Skip to content

L
linux
Commit 90b1023f authored by Quentin Monnet's avatar Quentin Monnet Committed by Daniel Borkmann
Browse files
Options

bpf: fix documentation for eBPF helpers 

The missing indentation on the "Return" sections for bpf_map_pop_elem()
and bpf_map_peek_elem() helpers break RST and man pages generation. This
patch fixes them, and moves the description of those two helpers towards
the end of the list (even though they are somehow related to the three
first helpers for maps, the man page explicitly states that the helpers
are sorted in chronological order).

While at it, bring other minor formatting edits for eBPF helpers
documentation: mostly blank lines removal, RST formatting, or other
small nits for consistency.
Signed-off-by: default avatarQuentin Monnet <quentin.monnet@netronome.com>
Reviewed-by: default avatarJakub Kicinski <jakub.kicinski@netronome.com>
Signed-off-by: default avatarDaniel Borkmann <daniel@iogearbox.net>
parent e3da08d0
Hide whitespace changes
Inline Side-by-side
Showing with 45 additions and 45 deletions
include/uapi/linux/bpf.h
View file @ 90b1023f
...@@ -496,18 +496,6 @@ union bpf_attr { ...@@ -496,18 +496,6 @@ union bpf_attr {
* Return * Return
* 0 on success, or a negative error in case of failure. * 0 on success, or a negative error in case of failure.
* *
* int bpf_map_pop_elem(struct bpf_map *map, void *value)
* Description
* Pop an element from *map*.
* Return
* 0 on success, or a negative error in case of failure.
*
* int bpf_map_peek_elem(struct bpf_map *map, void *value)
* Description
* Get an element from *map* without removing it.
* Return
* 0 on success, or a negative error in case of failure.
*
* int bpf_probe_read(void *dst, u32 size, const void *src) * int bpf_probe_read(void *dst, u32 size, const void *src)
* Description * Description
* For tracing programs, safely attempt to read *size* bytes from * For tracing programs, safely attempt to read *size* bytes from
...@@ -1931,9 +1919,9 @@ union bpf_attr { ...@@ -1931,9 +1919,9 @@ union bpf_attr {
* is set to metric from route (IPv4/IPv6 only), and ifindex * is set to metric from route (IPv4/IPv6 only), and ifindex
* is set to the device index of the nexthop from the FIB lookup. * is set to the device index of the nexthop from the FIB lookup.
* *
* *plen* argument is the size of the passed in struct. * *plen* argument is the size of the passed in struct.
* *flags* argument can be a combination of one or more of the * *flags* argument can be a combination of one or more of the
* following values: * following values:
* *
* **BPF_FIB_LOOKUP_DIRECT** * **BPF_FIB_LOOKUP_DIRECT**
* Do a direct table lookup vs full lookup using FIB * Do a direct table lookup vs full lookup using FIB
...@@ -1942,9 +1930,9 @@ union bpf_attr { ...@@ -1942,9 +1930,9 @@ union bpf_attr {
* Perform lookup from an egress perspective (default is * Perform lookup from an egress perspective (default is
* ingress). * ingress).
* *
* *ctx* is either **struct xdp_md** for XDP programs or * *ctx* is either **struct xdp_md** for XDP programs or
* **struct sk_buff** tc cls_act programs. * **struct sk_buff** tc cls_act programs.
* Return * Return
* * < 0 if any input argument is invalid * * < 0 if any input argument is invalid
* * 0 on success (packet is forwarded, nexthop neighbor exists) * * 0 on success (packet is forwarded, nexthop neighbor exists)
* * > 0 one of **BPF_FIB_LKUP_RET_** codes explaining why the * * > 0 one of **BPF_FIB_LKUP_RET_** codes explaining why the
...@@ -2089,8 +2077,8 @@ union bpf_attr { ...@@ -2089,8 +2077,8 @@ union bpf_attr {
* translated to a keycode using the rc keymap, and reported as * translated to a keycode using the rc keymap, and reported as
* an input key down event. After a period a key up event is * an input key down event. After a period a key up event is
* generated. This period can be extended by calling either * generated. This period can be extended by calling either
* **bpf_rc_keydown** () again with the same values, or calling * **bpf_rc_keydown**\ () again with the same values, or calling
* **bpf_rc_repeat** (). * **bpf_rc_repeat**\ ().
* *
* Some protocols include a toggle bit, in case the button was * Some protocols include a toggle bit, in case the button was
* released and pressed again between consecutive scancodes. * released and pressed again between consecutive scancodes.
...@@ -2173,21 +2161,22 @@ union bpf_attr { ...@@ -2173,21 +2161,22 @@ union bpf_attr {
* The *flags* meaning is specific for each map type, * The *flags* meaning is specific for each map type,
* and has to be 0 for cgroup local storage. * and has to be 0 for cgroup local storage.
* *
* Depending on the bpf program type, a local storage area * Depending on the BPF program type, a local storage area
* can be shared between multiple instances of the bpf program, * can be shared between multiple instances of the BPF program,
* running simultaneously. * running simultaneously.
* *
* A user should care about the synchronization by himself. * A user should care about the synchronization by himself.
* For example, by using the BPF_STX_XADD instruction to alter * For example, by using the **BPF_STX_XADD** instruction to alter
* the shared data. * the shared data.
* Return * Return
* Pointer to the local storage area. * A pointer to the local storage area.
* *
* int bpf_sk_select_reuseport(struct sk_reuseport_md *reuse, struct bpf_map *map, void *key, u64 flags) * int bpf_sk_select_reuseport(struct sk_reuseport_md *reuse, struct bpf_map *map, void *key, u64 flags)
* Description * Description
* Select a SO_REUSEPORT sk from a BPF_MAP_TYPE_REUSEPORT_ARRAY map * Select a **SO_REUSEPORT** socket from a
* It checks the selected sk is matching the incoming * **BPF_MAP_TYPE_REUSEPORT_ARRAY** *map*.
* request in the skb. * It checks the selected socket is matching the incoming
* request in the socket buffer.
* Return * Return
* 0 on success, or a negative error in case of failure. * 0 on success, or a negative error in case of failure.
* *
...@@ -2195,7 +2184,7 @@ union bpf_attr { ...@@ -2195,7 +2184,7 @@ union bpf_attr {
* Description * Description
* Look for TCP socket matching *tuple*, optionally in a child * Look for TCP socket matching *tuple*, optionally in a child
* network namespace *netns*. The return value must be checked, * network namespace *netns*. The return value must be checked,
* and if non-NULL, released via **bpf_sk_release**\ (). * and if non-**NULL**, released via **bpf_sk_release**\ ().
* *
* The *ctx* should point to the context of the program, such as * The *ctx* should point to the context of the program, such as
* the skb or socket (depending on the hook in use). This is used * the skb or socket (depending on the hook in use). This is used
...@@ -2221,15 +2210,15 @@ union bpf_attr { ...@@ -2221,15 +2210,15 @@ union bpf_attr {
* This helper is available only if the kernel was compiled with * This helper is available only if the kernel was compiled with
* **CONFIG_NET** configuration option. * **CONFIG_NET** configuration option.
* Return * Return
* Pointer to *struct bpf_sock*, or NULL in case of failure. * A pointer to *struct bpf_sock*, or **NULL** in case of failure.
* For sockets with reuseport option, *struct bpf_sock* * For sockets with reuseport option, **struct bpf_sock**
* return is from reuse->socks[] using hash of the packet. * return is from **reuse->socks**\ [] using hash of the packet.
* *
* struct bpf_sock *bpf_sk_lookup_udp(void *ctx, struct bpf_sock_tuple *tuple, u32 tuple_size, u32 netns, u64 flags) * struct bpf_sock *bpf_sk_lookup_udp(void *ctx, struct bpf_sock_tuple *tuple, u32 tuple_size, u32 netns, u64 flags)
* Description * Description
* Look for UDP socket matching *tuple*, optionally in a child * Look for UDP socket matching *tuple*, optionally in a child
* network namespace *netns*. The return value must be checked, * network namespace *netns*. The return value must be checked,
* and if non-NULL, released via **bpf_sk_release**\ (). * and if non-**NULL**, released via **bpf_sk_release**\ ().
* *
* The *ctx* should point to the context of the program, such as * The *ctx* should point to the context of the program, such as
* the skb or socket (depending on the hook in use). This is used * the skb or socket (depending on the hook in use). This is used
...@@ -2255,46 +2244,57 @@ union bpf_attr { ...@@ -2255,46 +2244,57 @@ union bpf_attr {
* This helper is available only if the kernel was compiled with * This helper is available only if the kernel was compiled with
* **CONFIG_NET** configuration option. * **CONFIG_NET** configuration option.
* Return * Return
* Pointer to *struct bpf_sock*, or NULL in case of failure. * A pointer to **struct bpf_sock**, or **NULL** in case of
* For sockets with reuseport option, *struct bpf_sock* * failure. For sockets with reuseport option, **struct bpf_sock**
* return is from reuse->socks[] using hash of the packet. * return is from **reuse->socks**\ [] using hash of the packet.
* *
* int bpf_sk_release(struct bpf_sock *sk) * int bpf_sk_release(struct bpf_sock *sock)
* Description * Description
* Release the reference held by *sock*. *sock* must be a non-NULL * Release the reference held by *sock*. *sock* must be a
* pointer that was returned from bpf_sk_lookup_xxx\ (). * non-**NULL** pointer that was returned from
* **bpf_sk_lookup_xxx**\ ().
* Return * Return
* 0 on success, or a negative error in case of failure. * 0 on success, or a negative error in case of failure.
* *
* int bpf_map_pop_elem(struct bpf_map *map, void *value)
* Description
* Pop an element from *map*.
* Return
* 0 on success, or a negative error in case of failure.
*
* int bpf_map_peek_elem(struct bpf_map *map, void *value)
* Description
* Get an element from *map* without removing it.
* Return
* 0 on success, or a negative error in case of failure.
*
* int bpf_msg_push_data(struct sk_buff *skb, u32 start, u32 len, u64 flags) * int bpf_msg_push_data(struct sk_buff *skb, u32 start, u32 len, u64 flags)
* Description * Description
* For socket policies, insert *len* bytes into msg at offset * For socket policies, insert *len* bytes into *msg* at offset
* *start*. * *start*.
* *
* If a program of type **BPF_PROG_TYPE_SK_MSG** is run on a * If a program of type **BPF_PROG_TYPE_SK_MSG** is run on a
* *msg* it may want to insert metadata or options into the msg. * *msg* it may want to insert metadata or options into the *msg*.
* This can later be read and used by any of the lower layer BPF * This can later be read and used by any of the lower layer BPF
* hooks. * hooks.
* *
* This helper may fail if under memory pressure (a malloc * This helper may fail if under memory pressure (a malloc
* fails) in these cases BPF programs will get an appropriate * fails) in these cases BPF programs will get an appropriate
* error and BPF programs will need to handle them. * error and BPF programs will need to handle them.
*
* Return * Return
* 0 on success, or a negative error in case of failure. * 0 on success, or a negative error in case of failure.
* *
* int bpf_msg_pop_data(struct sk_msg_buff *msg, u32 start, u32 pop, u64 flags) * int bpf_msg_pop_data(struct sk_msg_buff *msg, u32 start, u32 pop, u64 flags)
* Description * Description
* Will remove *pop* bytes from a *msg* starting at byte *start*. * Will remove *pop* bytes from a *msg* starting at byte *start*.
* This may result in **ENOMEM** errors under certain situations if * This may result in **ENOMEM** errors under certain situations if
* an allocation and copy are required due to a full ring buffer. * an allocation and copy are required due to a full ring buffer.
* However, the helper will try to avoid doing the allocation * However, the helper will try to avoid doing the allocation
* if possible. Other errors can occur if input parameters are * if possible. Other errors can occur if input parameters are
* invalid either due to *start* byte not being valid part of msg * invalid either due to *start* byte not being valid part of *msg*
* payload and/or *pop* value being to large. * payload and/or *pop* value being to large.
*
* Return * Return
* 0 on success, or a negative erro in case of failure. * 0 on success, or a negative error in case of failure.
*/ */
#define __BPF_FUNC_MAPPER(FN) \ #define __BPF_FUNC_MAPPER(FN) \
FN(unspec), \ FN(unspec), \
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7