* [PATCH bpf 0/4] bpf: fix documentation for BPF helper functions
@ 2019-05-10 14:51 Quentin Monnet
2019-05-10 14:51 ` [PATCH bpf 1/4] bpf: fix script for generating man page on BPF helpers Quentin Monnet
` (4 more replies)
0 siblings, 5 replies; 6+ messages in thread
From: Quentin Monnet @ 2019-05-10 14:51 UTC (permalink / raw)
To: Daniel Borkmann, Alexei Starovoitov
Cc: bpf, netdev, oss-drivers, Quentin Monnet, Yonghong Song
Another round of fixes for the doc in the BPF UAPI header, which can be
turned into a manual page. First patch is the most important, as it fixes
parsing for the bpf_strtoul() helper doc. Following patches are formatting
fixes (nitpicks, mostly). The last one updates the copy of the header,
located under tools/.
Quentin Monnet (4):
bpf: fix script for generating man page on BPF helpers
bpf: fix recurring typo in documentation for BPF helpers
bpf: fix minor issues in documentation for BPF helpers.
tools: bpf: synchronise BPF UAPI header with tools
include/uapi/linux/bpf.h | 145 +++++++++++++++++++++--------------------
scripts/bpf_helpers_doc.py | 8 +--
tools/include/uapi/linux/bpf.h | 145 +++++++++++++++++++++--------------------
3 files changed, 154 insertions(+), 144 deletions(-)
--
2.14.1
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH bpf 1/4] bpf: fix script for generating man page on BPF helpers
2019-05-10 14:51 [PATCH bpf 0/4] bpf: fix documentation for BPF helper functions Quentin Monnet
@ 2019-05-10 14:51 ` Quentin Monnet
2019-05-10 14:51 ` [PATCH bpf 2/4] bpf: fix recurring typo in documentation for " Quentin Monnet
` (3 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Quentin Monnet @ 2019-05-10 14:51 UTC (permalink / raw)
To: Daniel Borkmann, Alexei Starovoitov
Cc: bpf, netdev, oss-drivers, Quentin Monnet, Yonghong Song
The script broke on parsing function prototype for bpf_strtoul(). This
is because the last argument for the function is a pointer to an
"unsigned long". The current version of the script only accepts "const"
and "struct", but not "unsigned", at the beginning of argument types
made of several words.
One solution could be to add "unsigned" to the list, but the issue could
come up again in the future (what about "long int"?). It turns out we do
not need to have such restrictions on the words: so let's simply accept
any series of words instead.
Reported-by: Yonghong Song <yhs@fb.com>
Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com>
Acked-by: Jakub Kicinski <jakub.kicinski@netronome.com>
---
scripts/bpf_helpers_doc.py | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/scripts/bpf_helpers_doc.py b/scripts/bpf_helpers_doc.py
index 5010a4d5bfba..894cc58c1a03 100755
--- a/scripts/bpf_helpers_doc.py
+++ b/scripts/bpf_helpers_doc.py
@@ -1,7 +1,7 @@
#!/usr/bin/python3
# SPDX-License-Identifier: GPL-2.0-only
#
-# Copyright (C) 2018 Netronome Systems, Inc.
+# Copyright (C) 2018-2019 Netronome Systems, Inc.
# In case user attempts to run with Python 2.
from __future__ import print_function
@@ -39,7 +39,7 @@ class Helper(object):
Break down helper function protocol into smaller chunks: return type,
name, distincts arguments.
"""
- arg_re = re.compile('((const )?(struct )?(\w+|...))( (\**)(\w+))?$')
+ arg_re = re.compile('((\w+ )*?(\w+|...))( (\**)(\w+))?$')
res = {}
proto_re = re.compile('(.+) (\**)(\w+)\(((([^,]+)(, )?){1,5})\)$')
@@ -54,8 +54,8 @@ class Helper(object):
capture = arg_re.match(a)
res['args'].append({
'type' : capture.group(1),
- 'star' : capture.group(6),
- 'name' : capture.group(7)
+ 'star' : capture.group(5),
+ 'name' : capture.group(6)
})
return res
--
2.14.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH bpf 2/4] bpf: fix recurring typo in documentation for BPF helpers
2019-05-10 14:51 [PATCH bpf 0/4] bpf: fix documentation for BPF helper functions Quentin Monnet
2019-05-10 14:51 ` [PATCH bpf 1/4] bpf: fix script for generating man page on BPF helpers Quentin Monnet
@ 2019-05-10 14:51 ` Quentin Monnet
2019-05-10 14:51 ` [PATCH bpf 3/4] bpf: fix minor issues " Quentin Monnet
` (2 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Quentin Monnet @ 2019-05-10 14:51 UTC (permalink / raw)
To: Daniel Borkmann, Alexei Starovoitov
Cc: bpf, netdev, oss-drivers, Quentin Monnet, Yonghong Song
"Underlaying packet buffer" should be an "underlying" one, in the
warning about invalidated data and data_end pointers. Through
copy-and-paste, the typo occurred no fewer than 19 times in the
documentation. Let's fix it.
Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com>
Acked-by: Jakub Kicinski <jakub.kicinski@netronome.com>
---
include/uapi/linux/bpf.h | 38 +++++++++++++++++++-------------------
1 file changed, 19 insertions(+), 19 deletions(-)
diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index 72336bac7573..989ef6b1c269 100644
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -629,7 +629,7 @@ union bpf_attr {
* **BPF_F_INVALIDATE_HASH** (set *skb*\ **->hash**, *skb*\
* **->swhash** and *skb*\ **->l4hash** to 0).
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -654,7 +654,7 @@ union bpf_attr {
* flexibility and can handle sizes larger than 2 or 4 for the
* checksum to update.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -686,7 +686,7 @@ union bpf_attr {
* flexibility and can handle sizes larger than 2 or 4 for the
* checksum to update.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -741,7 +741,7 @@ union bpf_attr {
* efficient, but it is handled through an action code where the
* redirection happens only after the eBPF program has returned.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -806,7 +806,7 @@ union bpf_attr {
* **ETH_P_8021Q** and **ETH_P_8021AD**, it is considered to
* be **ETH_P_8021Q**.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -818,7 +818,7 @@ union bpf_attr {
* Description
* Pop a VLAN header from the packet associated to *skb*.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1168,7 +1168,7 @@ union bpf_attr {
* All values for *flags* are reserved for future usage, and must
* be left at zero.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1281,7 +1281,7 @@ union bpf_attr {
* implicitly linearizes, unclones and drops offloads from the
* *skb*.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1317,7 +1317,7 @@ union bpf_attr {
* **bpf_skb_pull_data()** to effectively unclone the *skb* from
* the very beginning in case it is indeed cloned.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1369,7 +1369,7 @@ union bpf_attr {
* All values for *flags* are reserved for future usage, and must
* be left at zero.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1384,7 +1384,7 @@ union bpf_attr {
* can be used to prepare the packet for pushing or popping
* headers.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1531,7 +1531,7 @@ union bpf_attr {
* Use with ENCAP_L3/L4 flags to further specify the tunnel
* type; **len** is the length of the inner MAC header.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1610,7 +1610,7 @@ union bpf_attr {
* more flexibility as the user is free to store whatever meta
* data they need.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1852,7 +1852,7 @@ union bpf_attr {
* copied if necessary (i.e. if data was not linear and if start
* and end pointers do not point to the same chunk).
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1886,7 +1886,7 @@ union bpf_attr {
* only possible to shrink the packet as of this writing,
* therefore *delta* must be a negative integer.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -2072,7 +2072,7 @@ union bpf_attr {
* by bpf programs of types BPF_PROG_TYPE_LWT_IN and
* BPF_PROG_TYPE_LWT_XMIT.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -2087,7 +2087,7 @@ union bpf_attr {
* inside the outermost IPv6 Segment Routing Header can be
* modified through this helper.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -2103,7 +2103,7 @@ union bpf_attr {
* after the segments are accepted. *delta* can be as well
* positive (growing) as negative (shrinking).
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -2132,7 +2132,7 @@ union bpf_attr {
* encapsulation policy.
* Type of param: **struct ipv6_sr_hdr**.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
--
2.14.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH bpf 3/4] bpf: fix minor issues in documentation for BPF helpers.
2019-05-10 14:51 [PATCH bpf 0/4] bpf: fix documentation for BPF helper functions Quentin Monnet
2019-05-10 14:51 ` [PATCH bpf 1/4] bpf: fix script for generating man page on BPF helpers Quentin Monnet
2019-05-10 14:51 ` [PATCH bpf 2/4] bpf: fix recurring typo in documentation for " Quentin Monnet
@ 2019-05-10 14:51 ` Quentin Monnet
2019-05-10 14:51 ` [PATCH bpf 4/4] tools: bpf: synchronise BPF UAPI header with tools Quentin Monnet
2019-05-12 23:24 ` [PATCH bpf 0/4] bpf: fix documentation for BPF helper functions Daniel Borkmann
4 siblings, 0 replies; 6+ messages in thread
From: Quentin Monnet @ 2019-05-10 14:51 UTC (permalink / raw)
To: Daniel Borkmann, Alexei Starovoitov
Cc: bpf, netdev, oss-drivers, Quentin Monnet, Yonghong Song
This commit brings many minor fixes to the documentation for BPF helper
functions. Mostly, this is limited to formatting fixes and improvements.
In particular, fix broken formatting for bpf_skb_adjust_room().
Besides formatting, replace the mention of "bpf_fullsock()" (that is not
associated with any function or type exposed to the user) in the
description of bpf_sk_storage_get() by "full socket".
Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com>
Acked-by: Jakub Kicinski <jakub.kicinski@netronome.com>
---
include/uapi/linux/bpf.h | 103 +++++++++++++++++++++++++----------------------
1 file changed, 54 insertions(+), 49 deletions(-)
diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index 989ef6b1c269..63e0cf66f01a 100644
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -1518,18 +1518,18 @@ union bpf_attr {
* * **BPF_F_ADJ_ROOM_FIXED_GSO**: Do not adjust gso_size.
* Adjusting mss in this way is not allowed for datagrams.
*
- * * **BPF_F_ADJ_ROOM_ENCAP_L3_IPV4 **:
- * * **BPF_F_ADJ_ROOM_ENCAP_L3_IPV6 **:
+ * * **BPF_F_ADJ_ROOM_ENCAP_L3_IPV4**,
+ * **BPF_F_ADJ_ROOM_ENCAP_L3_IPV6**:
* Any new space is reserved to hold a tunnel header.
* Configure skb offsets and other fields accordingly.
*
- * * **BPF_F_ADJ_ROOM_ENCAP_L4_GRE **:
- * * **BPF_F_ADJ_ROOM_ENCAP_L4_UDP **:
+ * * **BPF_F_ADJ_ROOM_ENCAP_L4_GRE**,
+ * **BPF_F_ADJ_ROOM_ENCAP_L4_UDP**:
* Use with ENCAP_L3 flags to further specify the tunnel type.
*
- * * **BPF_F_ADJ_ROOM_ENCAP_L2(len) **:
+ * * **BPF_F_ADJ_ROOM_ENCAP_L2**\ (*len*):
* Use with ENCAP_L3/L4 flags to further specify the tunnel
- * type; **len** is the length of the inner MAC header.
+ * type; *len* is the length of the inner MAC header.
*
* A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
@@ -2061,16 +2061,16 @@ union bpf_attr {
* **BPF_LWT_ENCAP_IP**
* IP encapsulation (GRE/GUE/IPIP/etc). The outer header
* must be IPv4 or IPv6, followed by zero or more
- * additional headers, up to LWT_BPF_MAX_HEADROOM total
- * bytes in all prepended headers. Please note that
- * if skb_is_gso(skb) is true, no more than two headers
- * can be prepended, and the inner header, if present,
- * should be either GRE or UDP/GUE.
+ * additional headers, up to **LWT_BPF_MAX_HEADROOM**
+ * total bytes in all prepended headers. Please note that
+ * if **skb_is_gso**\ (*skb*) is true, no more than two
+ * headers can be prepended, and the inner header, if
+ * present, should be either GRE or UDP/GUE.
*
- * BPF_LWT_ENCAP_SEG6*** types can be called by bpf programs of
- * type BPF_PROG_TYPE_LWT_IN; BPF_LWT_ENCAP_IP type can be called
- * by bpf programs of types BPF_PROG_TYPE_LWT_IN and
- * BPF_PROG_TYPE_LWT_XMIT.
+ * **BPF_LWT_ENCAP_SEG6**\ \* types can be called by BPF programs
+ * of type **BPF_PROG_TYPE_LWT_IN**; **BPF_LWT_ENCAP_IP** type can
+ * be called by bpf programs of types **BPF_PROG_TYPE_LWT_IN** and
+ * **BPF_PROG_TYPE_LWT_XMIT**.
*
* A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
@@ -2126,11 +2126,11 @@ union bpf_attr {
* Type of *param*: **int**.
* **SEG6_LOCAL_ACTION_END_B6**
* End.B6 action: Endpoint bound to an SRv6 policy.
- * Type of param: **struct ipv6_sr_hdr**.
+ * Type of *param*: **struct ipv6_sr_hdr**.
* **SEG6_LOCAL_ACTION_END_B6_ENCAP**
* End.B6.Encap action: Endpoint bound to an SRv6
* encapsulation policy.
- * Type of param: **struct ipv6_sr_hdr**.
+ * Type of *param*: **struct ipv6_sr_hdr**.
*
* A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
@@ -2285,7 +2285,8 @@ union bpf_attr {
* Return
* Pointer to **struct bpf_sock**, or **NULL** in case of failure.
* For sockets with reuseport option, the **struct bpf_sock**
- * result is from **reuse->socks**\ [] using the hash of the tuple.
+ * result is from *reuse*\ **->socks**\ [] using the hash of the
+ * tuple.
*
* struct bpf_sock *bpf_sk_lookup_udp(void *ctx, struct bpf_sock_tuple *tuple, u32 tuple_size, u64 netns, u64 flags)
* Description
@@ -2321,7 +2322,8 @@ union bpf_attr {
* Return
* Pointer to **struct bpf_sock**, or **NULL** in case of failure.
* For sockets with reuseport option, the **struct bpf_sock**
- * result is from **reuse->socks**\ [] using the hash of the tuple.
+ * result is from *reuse*\ **->socks**\ [] using the hash of the
+ * tuple.
*
* int bpf_sk_release(struct bpf_sock *sock)
* Description
@@ -2490,31 +2492,34 @@ union bpf_attr {
* network namespace *netns*. The return value must be checked,
* and if non-**NULL**, released via **bpf_sk_release**\ ().
*
- * This function is identical to bpf_sk_lookup_tcp, except that it
- * also returns timewait or request sockets. Use bpf_sk_fullsock
- * or bpf_tcp_socket to access the full structure.
+ * This function is identical to **bpf_sk_lookup_tcp**\ (), except
+ * that it also returns timewait or request sockets. Use
+ * **bpf_sk_fullsock**\ () or **bpf_tcp_sock**\ () to access the
+ * full structure.
*
* This helper is available only if the kernel was compiled with
* **CONFIG_NET** configuration option.
* Return
* Pointer to **struct bpf_sock**, or **NULL** in case of failure.
* For sockets with reuseport option, the **struct bpf_sock**
- * result is from **reuse->socks**\ [] using the hash of the tuple.
+ * result is from *reuse*\ **->socks**\ [] using the hash of the
+ * tuple.
*
* int bpf_tcp_check_syncookie(struct bpf_sock *sk, void *iph, u32 iph_len, struct tcphdr *th, u32 th_len)
* Description
- * Check whether iph and th contain a valid SYN cookie ACK for
- * the listening socket in sk.
+ * Check whether *iph* and *th* contain a valid SYN cookie ACK for
+ * the listening socket in *sk*.
*
- * iph points to the start of the IPv4 or IPv6 header, while
- * iph_len contains sizeof(struct iphdr) or sizeof(struct ip6hdr).
+ * *iph* points to the start of the IPv4 or IPv6 header, while
+ * *iph_len* contains **sizeof**\ (**struct iphdr**) or
+ * **sizeof**\ (**struct ip6hdr**).
*
- * th points to the start of the TCP header, while th_len contains
- * sizeof(struct tcphdr).
+ * *th* points to the start of the TCP header, while *th_len*
+ * contains **sizeof**\ (**struct tcphdr**).
*
* Return
- * 0 if iph and th are a valid SYN cookie ACK, or a negative error
- * otherwise.
+ * 0 if *iph* and *th* are a valid SYN cookie ACK, or a negative
+ * error otherwise.
*
* int bpf_sysctl_get_name(struct bpf_sysctl *ctx, char *buf, size_t buf_len, u64 flags)
* Description
@@ -2592,17 +2597,17 @@ union bpf_attr {
* and save the result in *res*.
*
* The string may begin with an arbitrary amount of white space
- * (as determined by isspace(3)) followed by a single optional '-'
- * sign.
+ * (as determined by **isspace**\ (3)) followed by a single
+ * optional '**-**' sign.
*
* Five least significant bits of *flags* encode base, other bits
* are currently unused.
*
* Base must be either 8, 10, 16 or 0 to detect it automatically
- * similar to user space strtol(3).
+ * similar to user space **strtol**\ (3).
* Return
* Number of characters consumed on success. Must be positive but
- * no more than buf_len.
+ * no more than *buf_len*.
*
* **-EINVAL** if no valid digits were found or unsupported base
* was provided.
@@ -2616,16 +2621,16 @@ union bpf_attr {
* given base and save the result in *res*.
*
* The string may begin with an arbitrary amount of white space
- * (as determined by isspace(3)).
+ * (as determined by **isspace**\ (3)).
*
* Five least significant bits of *flags* encode base, other bits
* are currently unused.
*
* Base must be either 8, 10, 16 or 0 to detect it automatically
- * similar to user space strtoul(3).
+ * similar to user space **strtoul**\ (3).
* Return
* Number of characters consumed on success. Must be positive but
- * no more than buf_len.
+ * no more than *buf_len*.
*
* **-EINVAL** if no valid digits were found or unsupported base
* was provided.
@@ -2634,26 +2639,26 @@ union bpf_attr {
*
* void *bpf_sk_storage_get(struct bpf_map *map, struct bpf_sock *sk, void *value, u64 flags)
* Description
- * Get a bpf-local-storage from a sk.
+ * Get a bpf-local-storage from a *sk*.
*
* Logically, it could be thought of getting the value from
* a *map* with *sk* as the **key**. From this
* perspective, the usage is not much different from
- * **bpf_map_lookup_elem(map, &sk)** except this
- * helper enforces the key must be a **bpf_fullsock()**
- * and the map must be a BPF_MAP_TYPE_SK_STORAGE also.
+ * **bpf_map_lookup_elem**\ (*map*, **&**\ *sk*) except this
+ * helper enforces the key must be a full socket and the map must
+ * be a **BPF_MAP_TYPE_SK_STORAGE** also.
*
* Underneath, the value is stored locally at *sk* instead of
- * the map. The *map* is used as the bpf-local-storage **type**.
- * The bpf-local-storage **type** (i.e. the *map*) is searched
- * against all bpf-local-storages residing at sk.
+ * the *map*. The *map* is used as the bpf-local-storage
+ * "type". The bpf-local-storage "type" (i.e. the *map*) is
+ * searched against all bpf-local-storages residing at *sk*.
*
- * An optional *flags* (BPF_SK_STORAGE_GET_F_CREATE) can be
+ * An optional *flags* (**BPF_SK_STORAGE_GET_F_CREATE**) can be
* used such that a new bpf-local-storage will be
* created if one does not exist. *value* can be used
- * together with BPF_SK_STORAGE_GET_F_CREATE to specify
+ * together with **BPF_SK_STORAGE_GET_F_CREATE** to specify
* the initial value of a bpf-local-storage. If *value* is
- * NULL, the new bpf-local-storage will be zero initialized.
+ * **NULL**, the new bpf-local-storage will be zero initialized.
* Return
* A bpf-local-storage pointer is returned on success.
*
@@ -2662,7 +2667,7 @@ union bpf_attr {
*
* int bpf_sk_storage_delete(struct bpf_map *map, struct bpf_sock *sk)
* Description
- * Delete a bpf-local-storage from a sk.
+ * Delete a bpf-local-storage from a *sk*.
* Return
* 0 on success.
*
--
2.14.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH bpf 4/4] tools: bpf: synchronise BPF UAPI header with tools
2019-05-10 14:51 [PATCH bpf 0/4] bpf: fix documentation for BPF helper functions Quentin Monnet
` (2 preceding siblings ...)
2019-05-10 14:51 ` [PATCH bpf 3/4] bpf: fix minor issues " Quentin Monnet
@ 2019-05-10 14:51 ` Quentin Monnet
2019-05-12 23:24 ` [PATCH bpf 0/4] bpf: fix documentation for BPF helper functions Daniel Borkmann
4 siblings, 0 replies; 6+ messages in thread
From: Quentin Monnet @ 2019-05-10 14:51 UTC (permalink / raw)
To: Daniel Borkmann, Alexei Starovoitov
Cc: bpf, netdev, oss-drivers, Quentin Monnet, Yonghong Song
Synchronise the bpf.h header under tools, to report the fixes and
additions recently brought to the documentation for the BPF helpers.
Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com>
Acked-by: Jakub Kicinski <jakub.kicinski@netronome.com>
---
tools/include/uapi/linux/bpf.h | 145 +++++++++++++++++++++--------------------
1 file changed, 75 insertions(+), 70 deletions(-)
diff --git a/tools/include/uapi/linux/bpf.h b/tools/include/uapi/linux/bpf.h
index 72336bac7573..63e0cf66f01a 100644
--- a/tools/include/uapi/linux/bpf.h
+++ b/tools/include/uapi/linux/bpf.h
@@ -629,7 +629,7 @@ union bpf_attr {
* **BPF_F_INVALIDATE_HASH** (set *skb*\ **->hash**, *skb*\
* **->swhash** and *skb*\ **->l4hash** to 0).
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -654,7 +654,7 @@ union bpf_attr {
* flexibility and can handle sizes larger than 2 or 4 for the
* checksum to update.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -686,7 +686,7 @@ union bpf_attr {
* flexibility and can handle sizes larger than 2 or 4 for the
* checksum to update.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -741,7 +741,7 @@ union bpf_attr {
* efficient, but it is handled through an action code where the
* redirection happens only after the eBPF program has returned.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -806,7 +806,7 @@ union bpf_attr {
* **ETH_P_8021Q** and **ETH_P_8021AD**, it is considered to
* be **ETH_P_8021Q**.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -818,7 +818,7 @@ union bpf_attr {
* Description
* Pop a VLAN header from the packet associated to *skb*.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1168,7 +1168,7 @@ union bpf_attr {
* All values for *flags* are reserved for future usage, and must
* be left at zero.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1281,7 +1281,7 @@ union bpf_attr {
* implicitly linearizes, unclones and drops offloads from the
* *skb*.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1317,7 +1317,7 @@ union bpf_attr {
* **bpf_skb_pull_data()** to effectively unclone the *skb* from
* the very beginning in case it is indeed cloned.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1369,7 +1369,7 @@ union bpf_attr {
* All values for *flags* are reserved for future usage, and must
* be left at zero.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1384,7 +1384,7 @@ union bpf_attr {
* can be used to prepare the packet for pushing or popping
* headers.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1518,20 +1518,20 @@ union bpf_attr {
* * **BPF_F_ADJ_ROOM_FIXED_GSO**: Do not adjust gso_size.
* Adjusting mss in this way is not allowed for datagrams.
*
- * * **BPF_F_ADJ_ROOM_ENCAP_L3_IPV4 **:
- * * **BPF_F_ADJ_ROOM_ENCAP_L3_IPV6 **:
+ * * **BPF_F_ADJ_ROOM_ENCAP_L3_IPV4**,
+ * **BPF_F_ADJ_ROOM_ENCAP_L3_IPV6**:
* Any new space is reserved to hold a tunnel header.
* Configure skb offsets and other fields accordingly.
*
- * * **BPF_F_ADJ_ROOM_ENCAP_L4_GRE **:
- * * **BPF_F_ADJ_ROOM_ENCAP_L4_UDP **:
+ * * **BPF_F_ADJ_ROOM_ENCAP_L4_GRE**,
+ * **BPF_F_ADJ_ROOM_ENCAP_L4_UDP**:
* Use with ENCAP_L3 flags to further specify the tunnel type.
*
- * * **BPF_F_ADJ_ROOM_ENCAP_L2(len) **:
+ * * **BPF_F_ADJ_ROOM_ENCAP_L2**\ (*len*):
* Use with ENCAP_L3/L4 flags to further specify the tunnel
- * type; **len** is the length of the inner MAC header.
+ * type; *len* is the length of the inner MAC header.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1610,7 +1610,7 @@ union bpf_attr {
* more flexibility as the user is free to store whatever meta
* data they need.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1852,7 +1852,7 @@ union bpf_attr {
* copied if necessary (i.e. if data was not linear and if start
* and end pointers do not point to the same chunk).
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -1886,7 +1886,7 @@ union bpf_attr {
* only possible to shrink the packet as of this writing,
* therefore *delta* must be a negative integer.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -2061,18 +2061,18 @@ union bpf_attr {
* **BPF_LWT_ENCAP_IP**
* IP encapsulation (GRE/GUE/IPIP/etc). The outer header
* must be IPv4 or IPv6, followed by zero or more
- * additional headers, up to LWT_BPF_MAX_HEADROOM total
- * bytes in all prepended headers. Please note that
- * if skb_is_gso(skb) is true, no more than two headers
- * can be prepended, and the inner header, if present,
- * should be either GRE or UDP/GUE.
- *
- * BPF_LWT_ENCAP_SEG6*** types can be called by bpf programs of
- * type BPF_PROG_TYPE_LWT_IN; BPF_LWT_ENCAP_IP type can be called
- * by bpf programs of types BPF_PROG_TYPE_LWT_IN and
- * BPF_PROG_TYPE_LWT_XMIT.
- *
- * A call to this helper is susceptible to change the underlaying
+ * additional headers, up to **LWT_BPF_MAX_HEADROOM**
+ * total bytes in all prepended headers. Please note that
+ * if **skb_is_gso**\ (*skb*) is true, no more than two
+ * headers can be prepended, and the inner header, if
+ * present, should be either GRE or UDP/GUE.
+ *
+ * **BPF_LWT_ENCAP_SEG6**\ \* types can be called by BPF programs
+ * of type **BPF_PROG_TYPE_LWT_IN**; **BPF_LWT_ENCAP_IP** type can
+ * be called by bpf programs of types **BPF_PROG_TYPE_LWT_IN** and
+ * **BPF_PROG_TYPE_LWT_XMIT**.
+ *
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -2087,7 +2087,7 @@ union bpf_attr {
* inside the outermost IPv6 Segment Routing Header can be
* modified through this helper.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -2103,7 +2103,7 @@ union bpf_attr {
* after the segments are accepted. *delta* can be as well
* positive (growing) as negative (shrinking).
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -2126,13 +2126,13 @@ union bpf_attr {
* Type of *param*: **int**.
* **SEG6_LOCAL_ACTION_END_B6**
* End.B6 action: Endpoint bound to an SRv6 policy.
- * Type of param: **struct ipv6_sr_hdr**.
+ * Type of *param*: **struct ipv6_sr_hdr**.
* **SEG6_LOCAL_ACTION_END_B6_ENCAP**
* End.B6.Encap action: Endpoint bound to an SRv6
* encapsulation policy.
- * Type of param: **struct ipv6_sr_hdr**.
+ * Type of *param*: **struct ipv6_sr_hdr**.
*
- * A call to this helper is susceptible to change the underlaying
+ * A call to this helper is susceptible to change the underlying
* packet buffer. Therefore, at load time, all checks on pointers
* previously done by the verifier are invalidated and must be
* performed again, if the helper is used in combination with
@@ -2285,7 +2285,8 @@ union bpf_attr {
* Return
* Pointer to **struct bpf_sock**, or **NULL** in case of failure.
* For sockets with reuseport option, the **struct bpf_sock**
- * result is from **reuse->socks**\ [] using the hash of the tuple.
+ * result is from *reuse*\ **->socks**\ [] using the hash of the
+ * tuple.
*
* struct bpf_sock *bpf_sk_lookup_udp(void *ctx, struct bpf_sock_tuple *tuple, u32 tuple_size, u64 netns, u64 flags)
* Description
@@ -2321,7 +2322,8 @@ union bpf_attr {
* Return
* Pointer to **struct bpf_sock**, or **NULL** in case of failure.
* For sockets with reuseport option, the **struct bpf_sock**
- * result is from **reuse->socks**\ [] using the hash of the tuple.
+ * result is from *reuse*\ **->socks**\ [] using the hash of the
+ * tuple.
*
* int bpf_sk_release(struct bpf_sock *sock)
* Description
@@ -2490,31 +2492,34 @@ union bpf_attr {
* network namespace *netns*. The return value must be checked,
* and if non-**NULL**, released via **bpf_sk_release**\ ().
*
- * This function is identical to bpf_sk_lookup_tcp, except that it
- * also returns timewait or request sockets. Use bpf_sk_fullsock
- * or bpf_tcp_socket to access the full structure.
+ * This function is identical to **bpf_sk_lookup_tcp**\ (), except
+ * that it also returns timewait or request sockets. Use
+ * **bpf_sk_fullsock**\ () or **bpf_tcp_sock**\ () to access the
+ * full structure.
*
* This helper is available only if the kernel was compiled with
* **CONFIG_NET** configuration option.
* Return
* Pointer to **struct bpf_sock**, or **NULL** in case of failure.
* For sockets with reuseport option, the **struct bpf_sock**
- * result is from **reuse->socks**\ [] using the hash of the tuple.
+ * result is from *reuse*\ **->socks**\ [] using the hash of the
+ * tuple.
*
* int bpf_tcp_check_syncookie(struct bpf_sock *sk, void *iph, u32 iph_len, struct tcphdr *th, u32 th_len)
* Description
- * Check whether iph and th contain a valid SYN cookie ACK for
- * the listening socket in sk.
+ * Check whether *iph* and *th* contain a valid SYN cookie ACK for
+ * the listening socket in *sk*.
*
- * iph points to the start of the IPv4 or IPv6 header, while
- * iph_len contains sizeof(struct iphdr) or sizeof(struct ip6hdr).
+ * *iph* points to the start of the IPv4 or IPv6 header, while
+ * *iph_len* contains **sizeof**\ (**struct iphdr**) or
+ * **sizeof**\ (**struct ip6hdr**).
*
- * th points to the start of the TCP header, while th_len contains
- * sizeof(struct tcphdr).
+ * *th* points to the start of the TCP header, while *th_len*
+ * contains **sizeof**\ (**struct tcphdr**).
*
* Return
- * 0 if iph and th are a valid SYN cookie ACK, or a negative error
- * otherwise.
+ * 0 if *iph* and *th* are a valid SYN cookie ACK, or a negative
+ * error otherwise.
*
* int bpf_sysctl_get_name(struct bpf_sysctl *ctx, char *buf, size_t buf_len, u64 flags)
* Description
@@ -2592,17 +2597,17 @@ union bpf_attr {
* and save the result in *res*.
*
* The string may begin with an arbitrary amount of white space
- * (as determined by isspace(3)) followed by a single optional '-'
- * sign.
+ * (as determined by **isspace**\ (3)) followed by a single
+ * optional '**-**' sign.
*
* Five least significant bits of *flags* encode base, other bits
* are currently unused.
*
* Base must be either 8, 10, 16 or 0 to detect it automatically
- * similar to user space strtol(3).
+ * similar to user space **strtol**\ (3).
* Return
* Number of characters consumed on success. Must be positive but
- * no more than buf_len.
+ * no more than *buf_len*.
*
* **-EINVAL** if no valid digits were found or unsupported base
* was provided.
@@ -2616,16 +2621,16 @@ union bpf_attr {
* given base and save the result in *res*.
*
* The string may begin with an arbitrary amount of white space
- * (as determined by isspace(3)).
+ * (as determined by **isspace**\ (3)).
*
* Five least significant bits of *flags* encode base, other bits
* are currently unused.
*
* Base must be either 8, 10, 16 or 0 to detect it automatically
- * similar to user space strtoul(3).
+ * similar to user space **strtoul**\ (3).
* Return
* Number of characters consumed on success. Must be positive but
- * no more than buf_len.
+ * no more than *buf_len*.
*
* **-EINVAL** if no valid digits were found or unsupported base
* was provided.
@@ -2634,26 +2639,26 @@ union bpf_attr {
*
* void *bpf_sk_storage_get(struct bpf_map *map, struct bpf_sock *sk, void *value, u64 flags)
* Description
- * Get a bpf-local-storage from a sk.
+ * Get a bpf-local-storage from a *sk*.
*
* Logically, it could be thought of getting the value from
* a *map* with *sk* as the **key**. From this
* perspective, the usage is not much different from
- * **bpf_map_lookup_elem(map, &sk)** except this
- * helper enforces the key must be a **bpf_fullsock()**
- * and the map must be a BPF_MAP_TYPE_SK_STORAGE also.
+ * **bpf_map_lookup_elem**\ (*map*, **&**\ *sk*) except this
+ * helper enforces the key must be a full socket and the map must
+ * be a **BPF_MAP_TYPE_SK_STORAGE** also.
*
* Underneath, the value is stored locally at *sk* instead of
- * the map. The *map* is used as the bpf-local-storage **type**.
- * The bpf-local-storage **type** (i.e. the *map*) is searched
- * against all bpf-local-storages residing at sk.
+ * the *map*. The *map* is used as the bpf-local-storage
+ * "type". The bpf-local-storage "type" (i.e. the *map*) is
+ * searched against all bpf-local-storages residing at *sk*.
*
- * An optional *flags* (BPF_SK_STORAGE_GET_F_CREATE) can be
+ * An optional *flags* (**BPF_SK_STORAGE_GET_F_CREATE**) can be
* used such that a new bpf-local-storage will be
* created if one does not exist. *value* can be used
- * together with BPF_SK_STORAGE_GET_F_CREATE to specify
+ * together with **BPF_SK_STORAGE_GET_F_CREATE** to specify
* the initial value of a bpf-local-storage. If *value* is
- * NULL, the new bpf-local-storage will be zero initialized.
+ * **NULL**, the new bpf-local-storage will be zero initialized.
* Return
* A bpf-local-storage pointer is returned on success.
*
@@ -2662,7 +2667,7 @@ union bpf_attr {
*
* int bpf_sk_storage_delete(struct bpf_map *map, struct bpf_sock *sk)
* Description
- * Delete a bpf-local-storage from a sk.
+ * Delete a bpf-local-storage from a *sk*.
* Return
* 0 on success.
*
--
2.14.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH bpf 0/4] bpf: fix documentation for BPF helper functions
2019-05-10 14:51 [PATCH bpf 0/4] bpf: fix documentation for BPF helper functions Quentin Monnet
` (3 preceding siblings ...)
2019-05-10 14:51 ` [PATCH bpf 4/4] tools: bpf: synchronise BPF UAPI header with tools Quentin Monnet
@ 2019-05-12 23:24 ` Daniel Borkmann
4 siblings, 0 replies; 6+ messages in thread
From: Daniel Borkmann @ 2019-05-12 23:24 UTC (permalink / raw)
To: Quentin Monnet, Alexei Starovoitov
Cc: bpf, netdev, oss-drivers, Yonghong Song
On 05/10/2019 04:51 PM, Quentin Monnet wrote:
> Another round of fixes for the doc in the BPF UAPI header, which can be
> turned into a manual page. First patch is the most important, as it fixes
> parsing for the bpf_strtoul() helper doc. Following patches are formatting
> fixes (nitpicks, mostly). The last one updates the copy of the header,
> located under tools/.
>
> Quentin Monnet (4):
> bpf: fix script for generating man page on BPF helpers
> bpf: fix recurring typo in documentation for BPF helpers
> bpf: fix minor issues in documentation for BPF helpers.
> tools: bpf: synchronise BPF UAPI header with tools
>
> include/uapi/linux/bpf.h | 145 +++++++++++++++++++++--------------------
> scripts/bpf_helpers_doc.py | 8 +--
> tools/include/uapi/linux/bpf.h | 145 +++++++++++++++++++++--------------------
> 3 files changed, 154 insertions(+), 144 deletions(-)
>
Applied, thanks.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2019-05-12 23:24 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-05-10 14:51 [PATCH bpf 0/4] bpf: fix documentation for BPF helper functions Quentin Monnet
2019-05-10 14:51 ` [PATCH bpf 1/4] bpf: fix script for generating man page on BPF helpers Quentin Monnet
2019-05-10 14:51 ` [PATCH bpf 2/4] bpf: fix recurring typo in documentation for " Quentin Monnet
2019-05-10 14:51 ` [PATCH bpf 3/4] bpf: fix minor issues " Quentin Monnet
2019-05-10 14:51 ` [PATCH bpf 4/4] tools: bpf: synchronise BPF UAPI header with tools Quentin Monnet
2019-05-12 23:24 ` [PATCH bpf 0/4] bpf: fix documentation for BPF helper functions Daniel Borkmann
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).