[bpf-next,v1,1/2] docs: fix sphinx warnings for cpumap

Commit Message

Maryam Tahhan Nov. 22, 2022, 10:37 a.m. UTC

From: Maryam Tahhan <[e-mail]>

Sphinx version >=3.3 warns about duplicate function delcarations in the
CPUMAP documentation. This is because the function name is the same for
Kernel and Userspace 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.

Signed-off-by: Maryam Tahhan <[e-mail]>
---
 Documentation/bpf/map_cpumap.rst | 48 ++++++++++++++++++++------------
 1 file changed, 30 insertions(+), 18 deletions(-)

Comments

David Vernet Nov. 22, 2022, 3:19 p.m. UTC | #1

On Tue, Nov 22, 2022 at 10:37:37AM +0000, [e-mail] wrote:
> From: Maryam Tahhan <[e-mail]>
> 
> Sphinx version >=3.3 warns about duplicate function delcarations in the

s/delcarations/declarations

> CPUMAP documentation. This is because the function name is the same for
> Kernel and Userspace 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.
> 
> Signed-off-by: Maryam Tahhan <[e-mail]>

LGTM, just left one optionl nit below. Thanks for fixing this up.

Acked-by: David Vernet <[e-mail]>

> ---
>  Documentation/bpf/map_cpumap.rst | 48 ++++++++++++++++++++------------
>  1 file changed, 30 insertions(+), 18 deletions(-)
> 
> diff --git a/Documentation/bpf/map_cpumap.rst b/Documentation/bpf/map_cpumap.rst
> index 61a797a86342..e8d9f7abf26a 100644
> --- a/Documentation/bpf/map_cpumap.rst
> +++ b/Documentation/bpf/map_cpumap.rst
> @@ -30,15 +30,18 @@ Usage
>  
>  Kernel BPF
>  ----------
> -.. c:function::
> +bpf_redirect_map()
> +^^^^^^^^^^^^^^^^^^
> +.. code-block:: c
> +
>       long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags)
>  
> - Redirect the packet to the endpoint referenced by ``map`` at index ``key``.
> - For ``BPF_MAP_TYPE_CPUMAP`` this map contains references to CPUs.
> +Redirect the packet to the endpoint referenced by ``map`` at index ``key``.
> +For ``BPF_MAP_TYPE_CPUMAP`` this map contains references to CPUs.
>  
> - The lower two bits of ``flags`` are used as the return code if the map lookup
> - fails. This is so that the return value can be one of the XDP program return
> - codes up to ``XDP_TX``, as chosen by the caller.
> +The lower two bits of ``flags`` are used as the return code if the map lookup
> +fails. This is so that the return value can be one of the XDP program return
> +codes up to ``XDP_TX``, as chosen by the caller.
>  
>  Userspace
>  ---------

Feel free to ignore as this isn't really relevant to your change, but
while you're here would you mind please fixing this up as well:

s/Userspace/User space

> @@ -47,12 +50,15 @@ Userspace
>      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.
>  
> -.. c:function::
> +bpf_map_update_elem()
> +^^^^^^^^^^^^^^^^^^^^^
> +.. code-block:: c
> +
>      int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags);
>  
> - CPU entries can be added or updated using the ``bpf_map_update_elem()``
> - helper. This helper replaces existing elements atomically. The ``value`` parameter
> - can be ``struct bpf_cpumap_val``.
> +CPU entries can be added or updated using the ``bpf_map_update_elem()``
> +helper. This helper replaces existing elements atomically. The ``value`` parameter
> +can be ``struct bpf_cpumap_val``.
>  
>   .. code-block:: c
>  
> @@ -64,23 +70,29 @@ Userspace
>          } 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_NOEXIST: Create a new element only if it did not exist.
>    - BPF_EXIST: Update an existing element.
>  
> -.. c:function::
> +bpf_map_lookup_elem()
> +^^^^^^^^^^^^^^^^^^^^^
> +.. code-block:: c
> +
>      int bpf_map_lookup_elem(int fd, const void *key, void *value);
>  
> - CPU entries can be retrieved using the ``bpf_map_lookup_elem()``
> - helper.
> +CPU entries can be retrieved using the ``bpf_map_lookup_elem()``
> +helper.
> +
> +bpf_map_delete_elem()
> +^^^^^^^^^^^^^^^^^^^^^
> +.. code-block:: c
>  
> -.. c:function::
>      int bpf_map_delete_elem(int fd, const void *key);
>  
> - CPU entries can be deleted using the ``bpf_map_delete_elem()``
> - helper. This helper will return 0 on success, or negative error in case of
> - failure.
> +CPU entries can be deleted using the ``bpf_map_delete_elem()``
> +helper. This helper will return 0 on success, or negative error in case of
> +failure.
>  
>  Examples
>  ========
> -- 
> 2.34.1
>

Patch

diff --git a/Documentation/bpf/map_cpumap.rst b/Documentation/bpf/map_cpumap.rst
index 61a797a86342..e8d9f7abf26a 100644
--- a/Documentation/bpf/map_cpumap.rst
+++ b/Documentation/bpf/map_cpumap.rst
@@ -30,15 +30,18 @@  Usage
 
 Kernel BPF
 ----------
-.. c:function::
+bpf_redirect_map()
+^^^^^^^^^^^^^^^^^^
+.. code-block:: c
+
      long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags)
 
- Redirect the packet to the endpoint referenced by ``map`` at index ``key``.
- For ``BPF_MAP_TYPE_CPUMAP`` this map contains references to CPUs.
+Redirect the packet to the endpoint referenced by ``map`` at index ``key``.
+For ``BPF_MAP_TYPE_CPUMAP`` this map contains references to CPUs.
 
- The lower two bits of ``flags`` are used as the return code if the map lookup
- fails. This is so that the return value can be one of the XDP program return
- codes up to ``XDP_TX``, as chosen by the caller.
+The lower two bits of ``flags`` are used as the return code if the map lookup
+fails. This is so that the return value can be one of the XDP program return
+codes up to ``XDP_TX``, as chosen by the caller.
 
 Userspace
 ---------
@@ -47,12 +50,15 @@  Userspace
     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.
 
-.. c:function::
+bpf_map_update_elem()
+^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: c
+
     int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags);
 
- CPU entries can be added or updated using the ``bpf_map_update_elem()``
- helper. This helper replaces existing elements atomically. The ``value`` parameter
- can be ``struct bpf_cpumap_val``.
+CPU entries can be added or updated using the ``bpf_map_update_elem()``
+helper. This helper replaces existing elements atomically. The ``value`` parameter
+can be ``struct bpf_cpumap_val``.
 
  .. code-block:: c
 
@@ -64,23 +70,29 @@  Userspace
         } 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_NOEXIST: Create a new element only if it did not exist.
   - BPF_EXIST: Update an existing element.
 
-.. c:function::
+bpf_map_lookup_elem()
+^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: c
+
     int bpf_map_lookup_elem(int fd, const void *key, void *value);
 
- CPU entries can be retrieved using the ``bpf_map_lookup_elem()``
- helper.
+CPU entries can be retrieved using the ``bpf_map_lookup_elem()``
+helper.
+
+bpf_map_delete_elem()
+^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: c
 
-.. c:function::
     int bpf_map_delete_elem(int fd, const void *key);
 
- CPU entries can be deleted using the ``bpf_map_delete_elem()``
- helper. This helper will return 0 on success, or negative error in case of
- failure.
+CPU entries can be deleted using the ``bpf_map_delete_elem()``
+helper. This helper will return 0 on success, or negative error in case of
+failure.
 
 Examples
 ========