Commit c645eee4 authored by Maryam Tahhan's avatar Maryam Tahhan Committed by Daniel Borkmann

docs/bpf: Fix sphinx warnings for devmap

Sphinx version >=3.1 warns about duplicate function declarations in the
DEVMAP documentation. This is because the function name is the same for
kernel and user space BPF progs but the parameters and return types
they take is what differs. This patch moves from using the ``c:function::``
directive to using the ``code-block:: c`` directive. The patches also fix
the indentation for the text associated with the "new" code block delcarations.
The missing support of c:namespace-push:: and c:namespace-pop:: directives by
helper scripts for kernel documentation prevents using the ``c:function::``
directive with proper namespacing.
Signed-off-by: default avatarMaryam Tahhan <mtahhan@redhat.com>
Signed-off-by: default avatarDaniel Borkmann <daniel@iogearbox.net>
Link: https://lore.kernel.org/bpf/20221123092321.88558-3-mtahhan@redhat.com
parent 3685b0dc
...@@ -29,7 +29,10 @@ Usage ...@@ -29,7 +29,10 @@ Usage
===== =====
Kernel BPF Kernel BPF
---------- ----------
.. c:function:: bpf_redirect_map()
^^^^^^^^^^^^^^^^^^
.. code-block:: c
long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags) long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags)
Redirect the packet to the endpoint referenced by ``map`` at index ``key``. Redirect the packet to the endpoint referenced by ``map`` at index ``key``.
...@@ -56,26 +59,32 @@ lower bits of the ``flags`` argument if the map lookup fails. ...@@ -56,26 +59,32 @@ lower bits of the ``flags`` argument if the map lookup fails.
More information about redirection can be found :doc:`redirect` More information about redirection can be found :doc:`redirect`
.. c:function:: bpf_map_lookup_elem()
^^^^^^^^^^^^^^^^^^^^^
.. code-block:: c
void *bpf_map_lookup_elem(struct bpf_map *map, const void *key) void *bpf_map_lookup_elem(struct bpf_map *map, const void *key)
Net device entries can be retrieved using the ``bpf_map_lookup_elem()`` Net device entries can be retrieved using the ``bpf_map_lookup_elem()``
helper. helper.
Userspace User space
--------- ----------
.. note:: .. note::
DEVMAP entries can only be updated/deleted from user space and not DEVMAP entries can only be updated/deleted from user space and not
from an eBPF program. Trying to call these functions from a kernel eBPF from an eBPF program. Trying to call these functions from a kernel eBPF
program will result in the program failing to load and a verifier warning. program will result in the program failing to load and a verifier warning.
.. c:function:: bpf_map_update_elem()
^^^^^^^^^^^^^^^^^^^^^
.. code-block:: c
int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags); int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags);
Net device entries can be added or updated using the ``bpf_map_update_elem()`` Net device entries can be added or updated using the ``bpf_map_update_elem()``
helper. This helper replaces existing elements atomically. The ``value`` parameter helper. This helper replaces existing elements atomically. The ``value`` parameter
can be ``struct bpf_devmap_val`` or a simple ``int ifindex`` for backwards can be ``struct bpf_devmap_val`` or a simple ``int ifindex`` for backwards
compatibility. compatibility.
.. code-block:: c .. code-block:: c
...@@ -87,35 +96,42 @@ Userspace ...@@ -87,35 +96,42 @@ Userspace
} bpf_prog; } bpf_prog;
}; };
The ``flags`` argument can be one of the following: The ``flags`` argument can be one of the following:
- ``BPF_ANY``: Create a new element or update an existing element. - ``BPF_ANY``: Create a new element or update an existing element.
- ``BPF_NOEXIST``: Create a new element only if it did not exist. - ``BPF_NOEXIST``: Create a new element only if it did not exist.
- ``BPF_EXIST``: Update an existing element. - ``BPF_EXIST``: Update an existing element.
DEVMAPs can associate a program with a device entry by adding a ``bpf_prog.fd`` DEVMAPs can associate a program with a device entry by adding a ``bpf_prog.fd``
to ``struct bpf_devmap_val``. Programs are run after ``XDP_REDIRECT`` and have to ``struct bpf_devmap_val``. Programs are run after ``XDP_REDIRECT`` and have
access to both Rx device and Tx device. The program associated with the ``fd`` access to both Rx device and Tx device. The program associated with the ``fd``
must have type XDP with expected attach type ``xdp_devmap``. must have type XDP with expected attach type ``xdp_devmap``.
When a program is associated with a device index, the program is run on an When a program is associated with a device index, the program is run on an
``XDP_REDIRECT`` and before the buffer is added to the per-cpu queue. Examples ``XDP_REDIRECT`` and before the buffer is added to the per-cpu queue. Examples
of how to attach/use xdp_devmap progs can be found in the kernel selftests: of how to attach/use xdp_devmap progs can be found in the kernel selftests:
- ``tools/testing/selftests/bpf/prog_tests/xdp_devmap_attach.c`` - ``tools/testing/selftests/bpf/prog_tests/xdp_devmap_attach.c``
- ``tools/testing/selftests/bpf/progs/test_xdp_with_devmap_helpers.c`` - ``tools/testing/selftests/bpf/progs/test_xdp_with_devmap_helpers.c``
bpf_map_lookup_elem()
^^^^^^^^^^^^^^^^^^^^^
.. code-block:: c
.. c:function:: .. c:function::
int bpf_map_lookup_elem(int fd, const void *key, void *value); int bpf_map_lookup_elem(int fd, const void *key, void *value);
Net device entries can be retrieved using the ``bpf_map_lookup_elem()`` Net device entries can be retrieved using the ``bpf_map_lookup_elem()``
helper. helper.
bpf_map_delete_elem()
^^^^^^^^^^^^^^^^^^^^^
.. code-block:: c
.. c:function:: .. c:function::
int bpf_map_delete_elem(int fd, const void *key); int bpf_map_delete_elem(int fd, const void *key);
Net device entries can be deleted using the ``bpf_map_delete_elem()`` Net device entries can be deleted using the ``bpf_map_delete_elem()``
helper. This helper will return 0 on success, or negative error in case of helper. This helper will return 0 on success, or negative error in case of
failure. failure.
Examples Examples
======== ========
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment