Commit 62369db2 authored by Quentin Monnet's avatar Quentin Monnet Committed by Alexei Starovoitov

bpf: fix documentation for eBPF helpers

Another round of minor fixes for the documentation of the BPF helpers
located in the UAPI bpf.h header file. Changes include:

- Moving around description of some helpers, to keep the descriptions in
  the same order as helpers are declared (bpf_map_push_elem(), leftover
  from commit 90b1023f ("bpf: fix documentation for eBPF helpers"),
  bpf_rc_keydown(), and bpf_skb_ancestor_cgroup_id()).
- Fixing typos ("contex" -> "context").
- Harmonising return types ("void* " -> "void *", "uint64_t" -> "u64").
- Addition of the "bpf_" prefix to bpf_get_storage().
- Light additions of RST markup on some keywords.
- Empty line deletion between description and return value for
  bpf_tcp_sock().
- Edit for the description for bpf_skb_ecn_set_ce() (capital letters,
  acronym expansion, no effect if ECT not set, more details on return
  value).
Signed-off-by: default avatarQuentin Monnet <quentin.monnet@netronome.com>
Reviewed-by: default avatarJakub Kicinski <jakub.kicinski@netronome.com>
Signed-off-by: default avatarAlexei Starovoitov <ast@kernel.org>
parent cd70182e
...@@ -502,16 +502,6 @@ union bpf_attr { ...@@ -502,16 +502,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_push_elem(struct bpf_map *map, const void *value, u64 flags)
* Description
* Push an element *value* in *map*. *flags* is one of:
*
* **BPF_EXIST**
* If the queue/stack is full, the oldest element is removed to
* make room for this.
* 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
...@@ -1435,14 +1425,14 @@ union bpf_attr { ...@@ -1435,14 +1425,14 @@ union bpf_attr {
* u64 bpf_get_socket_cookie(struct bpf_sock_addr *ctx) * u64 bpf_get_socket_cookie(struct bpf_sock_addr *ctx)
* Description * Description
* Equivalent to bpf_get_socket_cookie() helper that accepts * Equivalent to bpf_get_socket_cookie() helper that accepts
* *skb*, but gets socket from **struct bpf_sock_addr** contex. * *skb*, but gets socket from **struct bpf_sock_addr** context.
* Return * Return
* A 8-byte long non-decreasing number. * A 8-byte long non-decreasing number.
* *
* u64 bpf_get_socket_cookie(struct bpf_sock_ops *ctx) * u64 bpf_get_socket_cookie(struct bpf_sock_ops *ctx)
* Description * Description
* Equivalent to bpf_get_socket_cookie() helper that accepts * Equivalent to bpf_get_socket_cookie() helper that accepts
* *skb*, but gets socket from **struct bpf_sock_ops** contex. * *skb*, but gets socket from **struct bpf_sock_ops** context.
* Return * Return
* A 8-byte long non-decreasing number. * A 8-byte long non-decreasing number.
* *
...@@ -2098,52 +2088,52 @@ union bpf_attr { ...@@ -2098,52 +2088,52 @@ 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_rc_keydown(void *ctx, u32 protocol, u64 scancode, u32 toggle) * int bpf_rc_repeat(void *ctx)
* Description * Description
* This helper is used in programs implementing IR decoding, to * This helper is used in programs implementing IR decoding, to
* report a successfully decoded key press with *scancode*, * report a successfully decoded repeat key message. This delays
* *toggle* value in the given *protocol*. The scancode will be * the generation of a key up event for previously generated
* translated to a keycode using the rc keymap, and reported as * key down event.
* an input key down event. After a period a key up event is
* generated. This period can be extended by calling either
* **bpf_rc_keydown**\ () again with the same values, or calling
* **bpf_rc_repeat**\ ().
* *
* Some protocols include a toggle bit, in case the button was * Some IR protocols like NEC have a special IR message for
* released and pressed again between consecutive scancodes. * repeating last button, for when a button is held down.
* *
* The *ctx* should point to the lirc sample as passed into * The *ctx* should point to the lirc sample as passed into
* the program. * the program.
* *
* The *protocol* is the decoded protocol number (see
* **enum rc_proto** for some predefined values).
*
* This helper is only available is the kernel was compiled with * This helper is only available is the kernel was compiled with
* the **CONFIG_BPF_LIRC_MODE2** configuration option set to * the **CONFIG_BPF_LIRC_MODE2** configuration option set to
* "**y**". * "**y**".
* Return * Return
* 0 * 0
* *
* int bpf_rc_repeat(void *ctx) * int bpf_rc_keydown(void *ctx, u32 protocol, u64 scancode, u32 toggle)
* Description * Description
* This helper is used in programs implementing IR decoding, to * This helper is used in programs implementing IR decoding, to
* report a successfully decoded repeat key message. This delays * report a successfully decoded key press with *scancode*,
* the generation of a key up event for previously generated * *toggle* value in the given *protocol*. The scancode will be
* key down event. * translated to a keycode using the rc keymap, and reported as
* an input key down event. After a period a key up event is
* generated. This period can be extended by calling either
* **bpf_rc_keydown**\ () again with the same values, or calling
* **bpf_rc_repeat**\ ().
* *
* Some IR protocols like NEC have a special IR message for * Some protocols include a toggle bit, in case the button was
* repeating last button, for when a button is held down. * released and pressed again between consecutive scancodes.
* *
* The *ctx* should point to the lirc sample as passed into * The *ctx* should point to the lirc sample as passed into
* the program. * the program.
* *
* The *protocol* is the decoded protocol number (see
* **enum rc_proto** for some predefined values).
*
* This helper is only available is the kernel was compiled with * This helper is only available is the kernel was compiled with
* the **CONFIG_BPF_LIRC_MODE2** configuration option set to * the **CONFIG_BPF_LIRC_MODE2** configuration option set to
* "**y**". * "**y**".
* Return * Return
* 0 * 0
* *
* uint64_t bpf_skb_cgroup_id(struct sk_buff *skb) * u64 bpf_skb_cgroup_id(struct sk_buff *skb)
* Description * Description
* Return the cgroup v2 id of the socket associated with the *skb*. * Return the cgroup v2 id of the socket associated with the *skb*.
* This is roughly similar to the **bpf_get_cgroup_classid**\ () * This is roughly similar to the **bpf_get_cgroup_classid**\ ()
...@@ -2159,30 +2149,12 @@ union bpf_attr { ...@@ -2159,30 +2149,12 @@ union bpf_attr {
* Return * Return
* The id is returned or 0 in case the id could not be retrieved. * The id is returned or 0 in case the id could not be retrieved.
* *
* u64 bpf_skb_ancestor_cgroup_id(struct sk_buff *skb, int ancestor_level)
* Description
* Return id of cgroup v2 that is ancestor of cgroup associated
* with the *skb* at the *ancestor_level*. The root cgroup is at
* *ancestor_level* zero and each step down the hierarchy
* increments the level. If *ancestor_level* == level of cgroup
* associated with *skb*, then return value will be same as that
* of **bpf_skb_cgroup_id**\ ().
*
* The helper is useful to implement policies based on cgroups
* that are upper in hierarchy than immediate cgroup associated
* with *skb*.
*
* The format of returned id and helper limitations are same as in
* **bpf_skb_cgroup_id**\ ().
* Return
* The id is returned or 0 in case the id could not be retrieved.
*
* u64 bpf_get_current_cgroup_id(void) * u64 bpf_get_current_cgroup_id(void)
* Return * Return
* A 64-bit integer containing the current cgroup id based * A 64-bit integer containing the current cgroup id based
* on the cgroup within which the current task is running. * on the cgroup within which the current task is running.
* *
* void* get_local_storage(void *map, u64 flags) * void *bpf_get_local_storage(void *map, u64 flags)
* Description * Description
* Get the pointer to the local storage area. * Get the pointer to the local storage area.
* The type and the size of the local storage is defined * The type and the size of the local storage is defined
...@@ -2209,6 +2181,24 @@ union bpf_attr { ...@@ -2209,6 +2181,24 @@ 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.
* *
* u64 bpf_skb_ancestor_cgroup_id(struct sk_buff *skb, int ancestor_level)
* Description
* Return id of cgroup v2 that is ancestor of cgroup associated
* with the *skb* at the *ancestor_level*. The root cgroup is at
* *ancestor_level* zero and each step down the hierarchy
* increments the level. If *ancestor_level* == level of cgroup
* associated with *skb*, then return value will be same as that
* of **bpf_skb_cgroup_id**\ ().
*
* The helper is useful to implement policies based on cgroups
* that are upper in hierarchy than immediate cgroup associated
* with *skb*.
*
* The format of returned id and helper limitations are same as in
* **bpf_skb_cgroup_id**\ ().
* Return
* The id is returned or 0 in case the id could not be retrieved.
*
* struct bpf_sock *bpf_sk_lookup_tcp(void *ctx, struct bpf_sock_tuple *tuple, u32 tuple_size, u64 netns, u64 flags) * struct bpf_sock *bpf_sk_lookup_tcp(void *ctx, struct bpf_sock_tuple *tuple, u32 tuple_size, u64 netns, u64 flags)
* Description * Description
* Look for TCP socket matching *tuple*, optionally in a child * Look for TCP socket matching *tuple*, optionally in a child
...@@ -2289,6 +2279,16 @@ union bpf_attr { ...@@ -2289,6 +2279,16 @@ 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_push_elem(struct bpf_map *map, const void *value, u64 flags)
* Description
* Push an element *value* in *map*. *flags* is one of:
*
* **BPF_EXIST**
* If the queue/stack is full, the oldest element is
* removed to make room for this.
* Return
* 0 on success, or a negative error in case of failure.
*
* int bpf_map_pop_elem(struct bpf_map *map, void *value) * int bpf_map_pop_elem(struct bpf_map *map, void *value)
* Description * Description
* Pop an element from *map*. * Pop an element from *map*.
...@@ -2346,33 +2346,35 @@ union bpf_attr { ...@@ -2346,33 +2346,35 @@ union bpf_attr {
* struct bpf_sock *bpf_sk_fullsock(struct bpf_sock *sk) * struct bpf_sock *bpf_sk_fullsock(struct bpf_sock *sk)
* Description * Description
* This helper gets a **struct bpf_sock** pointer such * This helper gets a **struct bpf_sock** pointer such
* that all the fields in bpf_sock can be accessed. * that all the fields in this **bpf_sock** can be accessed.
* Return * Return
* A **struct bpf_sock** pointer on success, or NULL in * A **struct bpf_sock** pointer on success, or **NULL** in
* case of failure. * case of failure.
* *
* struct bpf_tcp_sock *bpf_tcp_sock(struct bpf_sock *sk) * struct bpf_tcp_sock *bpf_tcp_sock(struct bpf_sock *sk)
* Description * Description
* This helper gets a **struct bpf_tcp_sock** pointer from a * This helper gets a **struct bpf_tcp_sock** pointer from a
* **struct bpf_sock** pointer. * **struct bpf_sock** pointer.
*
* Return * Return
* A **struct bpf_tcp_sock** pointer on success, or NULL in * A **struct bpf_tcp_sock** pointer on success, or **NULL** in
* case of failure. * case of failure.
* *
* int bpf_skb_ecn_set_ce(struct sk_buf *skb) * int bpf_skb_ecn_set_ce(struct sk_buf *skb)
* Description * Description
* Sets ECN of IP header to ce (congestion encountered) if * Set ECN (Explicit Congestion Notification) field of IP header
* current value is ect (ECN capable). Works with IPv6 and IPv4. * to **CE** (Congestion Encountered) if current value is **ECT**
* Return * (ECN Capable Transport). Otherwise, do nothing. Works with IPv6
* 1 if set, 0 if not set. * and IPv4.
* Return
* 1 if the **CE** flag is set (either by the current helper call
* or because it was already present), 0 if it is not set.
* *
* struct bpf_sock *bpf_get_listener_sock(struct bpf_sock *sk) * struct bpf_sock *bpf_get_listener_sock(struct bpf_sock *sk)
* Description * Description
* Return a **struct bpf_sock** pointer in TCP_LISTEN state. * Return a **struct bpf_sock** pointer in **TCP_LISTEN** state.
* bpf_sk_release() is unnecessary and not allowed. * **bpf_sk_release**\ () is unnecessary and not allowed.
* Return * Return
* A **struct bpf_sock** pointer on success, or NULL in * A **struct bpf_sock** pointer on success, or **NULL** in
* case of failure. * case of failure.
*/ */
#define __BPF_FUNC_MAPPER(FN) \ #define __BPF_FUNC_MAPPER(FN) \
......
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