[PATCH bpf-next] bpf: clean up eBPF helpers documentation

[PATCH bpf-next] bpf: clean up eBPF helpers documentation

[Quentin Monnet]

These are minor edits for the eBPF helpers documentation in
include/uapi/linux/bpf.h.

The main fix consists in removing "BPF_FIB_LOOKUP_", because it ends
with a non-escaped underscore that gets interpreted by rst2man and
produces the following message in the resulting manual page:

    DOCUTILS SYSTEM MESSAGES
           System Message: ERROR/3 (/tmp/bpf-helpers.rst:, line 1514)
                  Unknown target name: "bpf_fib_lookup".

Other edits consist in:

- Improving formatting for flag values for "bpf_fib_lookup()" helper.
- Emphasising a parameter name in description of the return value for
  "bpf_get_stack()" helper.
- Removing unnecessary blank lines between "Description" and "Return"
  sections for the few helpers that would use it, for consistency.

Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com>
---
 include/uapi/linux/bpf.h | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index cc68787f2d97..3f556b35ac8d 100644
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -1010,7 +1010,6 @@ union bpf_attr {
  * 		::
  *
  * 			# sysctl kernel.perf_event_max_stack=<new value>
- *
  * 	Return
  * 		The positive or null stack id on success, or a negative error
  * 		in case of failure.
@@ -1821,10 +1820,9 @@ union bpf_attr {
  * 		::
  *
  * 			# sysctl kernel.perf_event_max_stack=<new value>
- *
  * 	Return
- * 		a non-negative value equal to or less than size on success, or
- * 		a negative error in case of failure.
+ * 		A non-negative value equal to or less than *size* on success,
+ * 		or a negative error in case of failure.
  *
  * int skb_load_bytes_relative(const struct sk_buff *skb, u32 offset, void *to, u32 len, u32 start_header)
  * 	Description
@@ -1845,7 +1843,6 @@ union bpf_attr {
  * 		in socket filters where *skb*\ **->data** does not always point
  * 		to the start of the mac header and where "direct packet access"
  * 		is not available.
- *
  * 	Return
  * 		0 on success, or a negative error in case of failure.
  *
@@ -1861,16 +1858,18 @@ union bpf_attr {
  *		rt_metric is set to metric from route.
  *
  *             *plen* argument is the size of the passed in struct.
- *             *flags* argument can be one or more BPF_FIB_LOOKUP_ flags:
+ *             *flags* argument can be a combination of one or more of the
+ *             following values:
  *
- *             **BPF_FIB_LOOKUP_DIRECT** means do a direct table lookup vs
- *             full lookup using FIB rules
- *             **BPF_FIB_LOOKUP_OUTPUT** means do lookup from an egress
- *             perspective (default is ingress)
+ *		**BPF_FIB_LOOKUP_DIRECT**
+ *			Do a direct table lookup vs full lookup using FIB
+ *			rules.
+ *		**BPF_FIB_LOOKUP_OUTPUT**
+ *			Perform lookup from an egress perspective (default is
+ *			ingress).
  *
  *             *ctx* is either **struct xdp_md** for XDP programs or
  *             **struct sk_buff** tc cls_act programs.
- *
  *     Return
  *             Egress device index on success, 0 if packet needs to continue
  *             up the stack for further processing or a negative error in case
-- 
2.14.1

Re: [PATCH bpf-next] bpf: clean up eBPF helpers documentation

[Song Liu]

On Tue, May 29, 2018 at 4:27 AM, Quentin Monnet
<quentin.monnet@netronome.com> wrote:
> These are minor edits for the eBPF helpers documentation in
> include/uapi/linux/bpf.h.
>
> The main fix consists in removing "BPF_FIB_LOOKUP_", because it ends
> with a non-escaped underscore that gets interpreted by rst2man and
> produces the following message in the resulting manual page:
>
>     DOCUTILS SYSTEM MESSAGES
>            System Message: ERROR/3 (/tmp/bpf-helpers.rst:, line 1514)
>                   Unknown target name: "bpf_fib_lookup".
>
> Other edits consist in:
>
> - Improving formatting for flag values for "bpf_fib_lookup()" helper.
> - Emphasising a parameter name in description of the return value for
>   "bpf_get_stack()" helper.
> - Removing unnecessary blank lines between "Description" and "Return"
>   sections for the few helpers that would use it, for consistency.
>
> Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com>
> ---
>  include/uapi/linux/bpf.h | 21 ++++++++++-----------
>  1 file changed, 10 insertions(+), 11 deletions(-)
>
> diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
> index cc68787f2d97..3f556b35ac8d 100644
> --- a/include/uapi/linux/bpf.h
> +++ b/include/uapi/linux/bpf.h
> @@ -1010,7 +1010,6 @@ union bpf_attr {
>   *             ::
>   *
>   *                     # sysctl kernel.perf_event_max_stack=<new value>
> - *
>   *     Return
>   *             The positive or null stack id on success, or a negative error
>   *             in case of failure.
> @@ -1821,10 +1820,9 @@ union bpf_attr {
>   *             ::
>   *
>   *                     # sysctl kernel.perf_event_max_stack=<new value>
> - *
>   *     Return
> - *             a non-negative value equal to or less than size on success, or
> - *             a negative error in case of failure.
> + *             A non-negative value equal to or less than *size* on success,
> + *             or a negative error in case of failure.
>   *
>   * int skb_load_bytes_relative(const struct sk_buff *skb, u32 offset, void *to, u32 len, u32 start_header)
>   *     Description
> @@ -1845,7 +1843,6 @@ union bpf_attr {
>   *             in socket filters where *skb*\ **->data** does not always point
>   *             to the start of the mac header and where "direct packet access"
>   *             is not available.
> - *
>   *     Return
>   *             0 on success, or a negative error in case of failure.
>   *
> @@ -1861,16 +1858,18 @@ union bpf_attr {
>   *             rt_metric is set to metric from route.
>   *
>   *             *plen* argument is the size of the passed in struct.
> - *             *flags* argument can be one or more BPF_FIB_LOOKUP_ flags:
> + *             *flags* argument can be a combination of one or more of the
> + *             following values:
>   *
> - *             **BPF_FIB_LOOKUP_DIRECT** means do a direct table lookup vs
> - *             full lookup using FIB rules
> - *             **BPF_FIB_LOOKUP_OUTPUT** means do lookup from an egress
> - *             perspective (default is ingress)
> + *             **BPF_FIB_LOOKUP_DIRECT**
> + *                     Do a direct table lookup vs full lookup using FIB
> + *                     rules.
> + *             **BPF_FIB_LOOKUP_OUTPUT**
> + *                     Perform lookup from an egress perspective (default is
> + *                     ingress).
>   *
>   *             *ctx* is either **struct xdp_md** for XDP programs or
>   *             **struct sk_buff** tc cls_act programs.
> - *
>   *     Return
>   *             Egress device index on success, 0 if packet needs to continue
>   *             up the stack for further processing or a negative error in case
> --
> 2.14.1
>

Please also apply the same changes to tools/include/uapi/linux/bpf.h.

Other than this, it looks to me.

Acked-by: Song Liu <songliubraving@fb.com>

Thanks,
Song

Re: [PATCH bpf-next] bpf: clean up eBPF helpers documentation

[Daniel Borkmann]

On 05/29/2018 08:27 PM, Song Liu wrote:
> On Tue, May 29, 2018 at 4:27 AM, Quentin Monnet
> <quentin.monnet@netronome.com> wrote:
>> These are minor edits for the eBPF helpers documentation in
>> include/uapi/linux/bpf.h.
>>
>> The main fix consists in removing "BPF_FIB_LOOKUP_", because it ends
>> with a non-escaped underscore that gets interpreted by rst2man and
>> produces the following message in the resulting manual page:
>>
>>     DOCUTILS SYSTEM MESSAGES
>>            System Message: ERROR/3 (/tmp/bpf-helpers.rst:, line 1514)
>>                   Unknown target name: "bpf_fib_lookup".
>>
>> Other edits consist in:
>>
>> - Improving formatting for flag values for "bpf_fib_lookup()" helper.
>> - Emphasising a parameter name in description of the return value for
>>   "bpf_get_stack()" helper.
>> - Removing unnecessary blank lines between "Description" and "Return"
>>   sections for the few helpers that would use it, for consistency.
>>
>> Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com>
[...]
> 
> Please also apply the same changes to tools/include/uapi/linux/bpf.h.

Just did while applying to bpf-next, thanks guys!

> Other than this, it looks to me.
> 
> Acked-by: Song Liu <songliubraving@fb.com>
> 
> Thanks,
> Song
> 

Re: [PATCH bpf-next] bpf: clean up eBPF helpers documentation

[Quentin Monnet]

On 29 May 2018 at 20:44, Daniel Borkmann <daniel@iogearbox.net> wrote:
> On 05/29/2018 08:27 PM, Song Liu wrote:
>> On Tue, May 29, 2018 at 4:27 AM, Quentin Monnet
>> <quentin.monnet@netronome.com> wrote:
>>> These are minor edits for the eBPF helpers documentation in
>>> include/uapi/linux/bpf.h.
>>>
>>> The main fix consists in removing "BPF_FIB_LOOKUP_", because it ends
>>> with a non-escaped underscore that gets interpreted by rst2man and
>>> produces the following message in the resulting manual page:
>>>
>>>     DOCUTILS SYSTEM MESSAGES
>>>            System Message: ERROR/3 (/tmp/bpf-helpers.rst:, line 1514)
>>>                   Unknown target name: "bpf_fib_lookup".
>>>
>>> Other edits consist in:
>>>
>>> - Improving formatting for flag values for "bpf_fib_lookup()" helper.
>>> - Emphasising a parameter name in description of the return value for
>>>   "bpf_get_stack()" helper.
>>> - Removing unnecessary blank lines between "Description" and "Return"
>>>   sections for the few helpers that would use it, for consistency.
>>>
>>> Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com>
> [...]
>>
>> Please also apply the same changes to tools/include/uapi/linux/bpf.h.

Ah, true, I forgot it... Thanks for the reminder.

> Just did while applying to bpf-next, thanks guys!
>
>> Other than this, it looks to me.
>>
>> Acked-by: Song Liu <songliubraving@fb.com>

Thanks a lot Song, Daniel!
Quentin