History

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 90b1023f68c7 ("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).

Quentin Monnet committed 7 years ago

Commit 62369db1 parent cd701821 file · +65 −63Browse files

Showing the changes to include/uapi/linux (1 of 1 file). Show all

Unified · Split

include/uapi/linux/bpf.h+65−63
@@ -502,16 +502,6 @@ union bpf_attr { · 501 unmodified lines
502502 * Return
503503 * 0 on success, or a negative error in case of failure.
504504 *
505− * int bpf_map_push_elem(struct bpf_map *map, const void *value, u64 flags)
506− * Description
507− * Push an element *value* in *map*. *flags* is one of:
508− *
509− * **BPF_EXIST**
510− * If the queue/stack is full, the oldest element is removed to
511− * make room for this.
512− * Return
513− * 0 on success, or a negative error in case of failure.
514− *
515505 * int bpf_probe_read(void *dst, u32 size, const void *src)
516506 * Description
517507 * For tracing programs, safely attempt to read *size* bytes from
@@ -1435,14 +1425,14 @@ union bpf_attr { · 917 unmodified lines
14351425 * u64 bpf_get_socket_cookie(struct bpf_sock_addr *ctx)
14361426 * Description
14371427 * Equivalent to bpf_get_socket_cookie() helper that accepts
1438− * *skb*, but gets socket from **struct bpf_sock_addr** contex.
1428+ * *skb*, but gets socket from **struct bpf_sock_addr** context.
14391429 * Return
14401430 * A 8-byte long non-decreasing number.
14411431 *
14421432 * u64 bpf_get_socket_cookie(struct bpf_sock_ops *ctx)
14431433 * Description
14441434 * Equivalent to bpf_get_socket_cookie() helper that accepts
1445− * *skb*, but gets socket from **struct bpf_sock_ops** contex.
1435+ * *skb*, but gets socket from **struct bpf_sock_ops** context.
14461436 * Return
14471437 * A 8-byte long non-decreasing number.
14481438 *
@@ -2098,52 +2088,52 @@ union bpf_attr { · 649 unmodified lines
20982088 * Return
20992089 * 0 on success, or a negative error in case of failure.
21002090 *
2101− * int bpf_rc_keydown(void *ctx, u32 protocol, u64 scancode, u32 toggle)
2091+ * int bpf_rc_repeat(void *ctx)
21022092 * Description
21032093 * This helper is used in programs implementing IR decoding, to
2104− * report a successfully decoded key press with *scancode*,
2105− * *toggle* value in the given *protocol*. The scancode will be
2106− * translated to a keycode using the rc keymap, and reported as
2107− * an input key down event. After a period a key up event is
2108− * generated. This period can be extended by calling either
2109− * **bpf_rc_keydown**\ () again with the same values, or calling
2110− * **bpf_rc_repeat**\ ().
2094+ * report a successfully decoded repeat key message. This delays
2095+ * the generation of a key up event for previously generated
2096+ * key down event.
21112097 *
2112− * Some protocols include a toggle bit, in case the button was
2113− * released and pressed again between consecutive scancodes.
2098+ * Some IR protocols like NEC have a special IR message for
2099+ * repeating last button, for when a button is held down.
21142100 *
21152101 * The *ctx* should point to the lirc sample as passed into
21162102 * the program.
21172103 *
2118− * The *protocol* is the decoded protocol number (see
2119− * **enum rc_proto** for some predefined values).
2120− *
21212104 * This helper is only available is the kernel was compiled with
21222105 * the **CONFIG_BPF_LIRC_MODE2** configuration option set to
21232106 * "**y**".
21242107 * Return
21252108 * 0
21262109 *
2127− * int bpf_rc_repeat(void *ctx)
2110+ * int bpf_rc_keydown(void *ctx, u32 protocol, u64 scancode, u32 toggle)
21282111 * Description
21292112 * This helper is used in programs implementing IR decoding, to
2130− * report a successfully decoded repeat key message. This delays
2131− * the generation of a key up event for previously generated
2132− * key down event.
2113+ * report a successfully decoded key press with *scancode*,
2114+ * *toggle* value in the given *protocol*. The scancode will be
2115+ * translated to a keycode using the rc keymap, and reported as
2116+ * an input key down event. After a period a key up event is
2117+ * generated. This period can be extended by calling either
2118+ * **bpf_rc_keydown**\ () again with the same values, or calling
2119+ * **bpf_rc_repeat**\ ().
21332120 *
2134− * Some IR protocols like NEC have a special IR message for
2135− * repeating last button, for when a button is held down.
2121+ * Some protocols include a toggle bit, in case the button was
2122+ * released and pressed again between consecutive scancodes.
21362123 *
21372124 * The *ctx* should point to the lirc sample as passed into
21382125 * the program.
21392126 *
2127+ * The *protocol* is the decoded protocol number (see
2128+ * **enum rc_proto** for some predefined values).
2129+ *
21402130 * This helper is only available is the kernel was compiled with
21412131 * the **CONFIG_BPF_LIRC_MODE2** configuration option set to
21422132 * "**y**".
21432133 * Return
21442134 * 0
21452135 *
2146− * uint64_t bpf_skb_cgroup_id(struct sk_buff *skb)
2136+ * u64 bpf_skb_cgroup_id(struct sk_buff *skb)
21472137 * Description
21482138 * Return the cgroup v2 id of the socket associated with the *skb*.
21492139 * This is roughly similar to the **bpf_get_cgroup_classid**\ ()
@@ -2159,30 +2149,12 @@ union bpf_attr { · 9 unmodified lines
21592149 * Return
21602150 * The id is returned or 0 in case the id could not be retrieved.
21612151 *
2162− * u64 bpf_skb_ancestor_cgroup_id(struct sk_buff *skb, int ancestor_level)
2163− * Description
2164− * Return id of cgroup v2 that is ancestor of cgroup associated
2165− * with the *skb* at the *ancestor_level*. The root cgroup is at
2166− * *ancestor_level* zero and each step down the hierarchy
2167− * increments the level. If *ancestor_level* == level of cgroup
2168− * associated with *skb*, then return value will be same as that
2169− * of **bpf_skb_cgroup_id**\ ().
2170− *
2171− * The helper is useful to implement policies based on cgroups
2172− * that are upper in hierarchy than immediate cgroup associated
2173− * with *skb*.
2174− *
2175− * The format of returned id and helper limitations are same as in
2176− * **bpf_skb_cgroup_id**\ ().
2177− * Return
2178− * The id is returned or 0 in case the id could not be retrieved.
2179− *
21802152 * u64 bpf_get_current_cgroup_id(void)
21812153 * Return
21822154 * A 64-bit integer containing the current cgroup id based
21832155 * on the cgroup within which the current task is running.
21842156 *
2185− * void* get_local_storage(void *map, u64 flags)
2157+ * void *bpf_get_local_storage(void *map, u64 flags)
21862158 * Description
21872159 * Get the pointer to the local storage area.
21882160 * The type and the size of the local storage is defined
@@ -2209,6 +2181,24 @@ union bpf_attr { · 20 unmodified lines
22092181 * Return
22102182 * 0 on success, or a negative error in case of failure.
22112183 *
2184+ * u64 bpf_skb_ancestor_cgroup_id(struct sk_buff *skb, int ancestor_level)
2185+ * Description
2186+ * Return id of cgroup v2 that is ancestor of cgroup associated
2187+ * with the *skb* at the *ancestor_level*. The root cgroup is at
2188+ * *ancestor_level* zero and each step down the hierarchy
2189+ * increments the level. If *ancestor_level* == level of cgroup
2190+ * associated with *skb*, then return value will be same as that
2191+ * of **bpf_skb_cgroup_id**\ ().
2192+ *
2193+ * The helper is useful to implement policies based on cgroups
2194+ * that are upper in hierarchy than immediate cgroup associated
2195+ * with *skb*.
2196+ *
2197+ * The format of returned id and helper limitations are same as in
2198+ * **bpf_skb_cgroup_id**\ ().
2199+ * Return
2200+ * The id is returned or 0 in case the id could not be retrieved.
2201+ *
22122202 * struct bpf_sock *bpf_sk_lookup_tcp(void *ctx, struct bpf_sock_tuple *tuple, u32 tuple_size, u64 netns, u64 flags)
22132203 * Description
22142204 * Look for TCP socket matching *tuple*, optionally in a child
@@ -2289,6 +2279,16 @@ union bpf_attr { · 74 unmodified lines
22892279 * Return
22902280 * 0 on success, or a negative error in case of failure.
22912281 *
2282+ * int bpf_map_push_elem(struct bpf_map *map, const void *value, u64 flags)
2283+ * Description
2284+ * Push an element *value* in *map*. *flags* is one of:
2285+ *
2286+ * **BPF_EXIST**
2287+ * If the queue/stack is full, the oldest element is
2288+ * removed to make room for this.
2289+ * Return
2290+ * 0 on success, or a negative error in case of failure.
2291+ *
22922292 * int bpf_map_pop_elem(struct bpf_map *map, void *value)
22932293 * Description
22942294 * Pop an element from *map*.
@@ -2346,33 +2346,35 @@ union bpf_attr { · 51 unmodified lines
23462346 * struct bpf_sock *bpf_sk_fullsock(struct bpf_sock *sk)
23472347 * Description
23482348 * This helper gets a **struct bpf_sock** pointer such
2349− * that all the fields in bpf_sock can be accessed.
2349+ * that all the fields in this **bpf_sock** can be accessed.
23502350 * Return
2351− * A **struct bpf_sock** pointer on success, or NULL in
2351+ * A **struct bpf_sock** pointer on success, or **NULL** in
23522352 * case of failure.
23532353 *
23542354 * struct bpf_tcp_sock *bpf_tcp_sock(struct bpf_sock *sk)
23552355 * Description
23562356 * This helper gets a **struct bpf_tcp_sock** pointer from a
23572357 * **struct bpf_sock** pointer.
2358− *
23592358 * Return
2360− * A **struct bpf_tcp_sock** pointer on success, or NULL in
2359+ * A **struct bpf_tcp_sock** pointer on success, or **NULL** in
23612360 * case of failure.
23622361 *
23632362 * int bpf_skb_ecn_set_ce(struct sk_buf *skb)
2364− * Description
2365− * Sets ECN of IP header to ce (congestion encountered) if
2366− * current value is ect (ECN capable). Works with IPv6 and IPv4.
2367− * Return
2368− * 1 if set, 0 if not set.
2363+ * Description
2364+ * Set ECN (Explicit Congestion Notification) field of IP header
2365+ * to **CE** (Congestion Encountered) if current value is **ECT**
2366+ * (ECN Capable Transport). Otherwise, do nothing. Works with IPv6
2367+ * and IPv4.
2368+ * Return
2369+ * 1 if the **CE** flag is set (either by the current helper call
2370+ * or because it was already present), 0 if it is not set.
23692371 *
23702372 * struct bpf_sock *bpf_get_listener_sock(struct bpf_sock *sk)
23712373 * Description
2372− * Return a **struct bpf_sock** pointer in TCP_LISTEN state.
2373− * bpf_sk_release() is unnecessary and not allowed.
2374+ * Return a **struct bpf_sock** pointer in **TCP_LISTEN** state.
2375+ * **bpf_sk_release**\ () is unnecessary and not allowed.
23742376 * Return
2375− * A **struct bpf_sock** pointer on success, or NULL in
2377+ * A **struct bpf_sock** pointer on success, or **NULL** in
23762378 * case of failure.
23772379 */
23782380 #define __BPF_FUNC_MAPPER(FN) \