Synchronise the bpf.h header under tools, to report the latest fixes and additions to the documentation for the BPF helpers.
Showing the changes to tools/include/uapi/linux (1 of 1 file). Show all
Unified · Split
| @@ -502,16 +502,6 @@ union bpf_attr { · 501 unmodified lines | ||
| 502 | 502 | * Return |
| 503 | 503 | * 0 on success, or a negative error in case of failure. |
| 504 | 504 | * |
| 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 | − * | |
| 515 | 505 | * int bpf_probe_read(void *dst, u32 size, const void *src) |
| 516 | 506 | * Description |
| 517 | 507 | * For tracing programs, safely attempt to read *size* bytes from |
| @@ -1435,14 +1425,14 @@ union bpf_attr { · 917 unmodified lines | ||
| 1435 | 1425 | * u64 bpf_get_socket_cookie(struct bpf_sock_addr *ctx) |
| 1436 | 1426 | * Description |
| 1437 | 1427 | * 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. | |
| 1439 | 1429 | * Return |
| 1440 | 1430 | * A 8-byte long non-decreasing number. |
| 1441 | 1431 | * |
| 1442 | 1432 | * u64 bpf_get_socket_cookie(struct bpf_sock_ops *ctx) |
| 1443 | 1433 | * Description |
| 1444 | 1434 | * 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. | |
| 1446 | 1436 | * Return |
| 1447 | 1437 | * A 8-byte long non-decreasing number. |
| 1448 | 1438 | * |
| @@ -2098,52 +2088,52 @@ union bpf_attr { · 649 unmodified lines | ||
| 2098 | 2088 | * Return |
| 2099 | 2089 | * 0 on success, or a negative error in case of failure. |
| 2100 | 2090 | * |
| 2101 | − * int bpf_rc_keydown(void *ctx, u32 protocol, u64 scancode, u32 toggle) | |
| 2091 | + * int bpf_rc_repeat(void *ctx) | |
| 2102 | 2092 | * Description |
| 2103 | 2093 | * 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. | |
| 2111 | 2097 | * |
| 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. | |
| 2114 | 2100 | * |
| 2115 | 2101 | * The *ctx* should point to the lirc sample as passed into |
| 2116 | 2102 | * the program. |
| 2117 | 2103 | * |
| 2118 | − * The *protocol* is the decoded protocol number (see | |
| 2119 | − * **enum rc_proto** for some predefined values). | |
| 2120 | − * | |
| 2121 | 2104 | * This helper is only available is the kernel was compiled with |
| 2122 | 2105 | * the **CONFIG_BPF_LIRC_MODE2** configuration option set to |
| 2123 | 2106 | * "**y**". |
| 2124 | 2107 | * Return |
| 2125 | 2108 | * 0 |
| 2126 | 2109 | * |
| 2127 | − * int bpf_rc_repeat(void *ctx) | |
| 2110 | + * int bpf_rc_keydown(void *ctx, u32 protocol, u64 scancode, u32 toggle) | |
| 2128 | 2111 | * Description |
| 2129 | 2112 | * 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**\ (). | |
| 2133 | 2120 | * |
| 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. | |
| 2136 | 2123 | * |
| 2137 | 2124 | * The *ctx* should point to the lirc sample as passed into |
| 2138 | 2125 | * the program. |
| 2139 | 2126 | * |
| 2127 | + * The *protocol* is the decoded protocol number (see | |
| 2128 | + * **enum rc_proto** for some predefined values). | |
| 2129 | + * | |
| 2140 | 2130 | * This helper is only available is the kernel was compiled with |
| 2141 | 2131 | * the **CONFIG_BPF_LIRC_MODE2** configuration option set to |
| 2142 | 2132 | * "**y**". |
| 2143 | 2133 | * Return |
| 2144 | 2134 | * 0 |
| 2145 | 2135 | * |
| 2146 | − * uint64_t bpf_skb_cgroup_id(struct sk_buff *skb) | |
| 2136 | + * u64 bpf_skb_cgroup_id(struct sk_buff *skb) | |
| 2147 | 2137 | * Description |
| 2148 | 2138 | * Return the cgroup v2 id of the socket associated with the *skb*. |
| 2149 | 2139 | * This is roughly similar to the **bpf_get_cgroup_classid**\ () |
| @@ -2159,30 +2149,12 @@ union bpf_attr { · 9 unmodified lines | ||
| 2159 | 2149 | * Return |
| 2160 | 2150 | * The id is returned or 0 in case the id could not be retrieved. |
| 2161 | 2151 | * |
| 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 | − * | |
| 2180 | 2152 | * u64 bpf_get_current_cgroup_id(void) |
| 2181 | 2153 | * Return |
| 2182 | 2154 | * A 64-bit integer containing the current cgroup id based |
| 2183 | 2155 | * on the cgroup within which the current task is running. |
| 2184 | 2156 | * |
| 2185 | − * void* get_local_storage(void *map, u64 flags) | |
| 2157 | + * void *bpf_get_local_storage(void *map, u64 flags) | |
| 2186 | 2158 | * Description |
| 2187 | 2159 | * Get the pointer to the local storage area. |
| 2188 | 2160 | * The type and the size of the local storage is defined |
| @@ -2209,6 +2181,24 @@ union bpf_attr { · 20 unmodified lines | ||
| 2209 | 2181 | * Return |
| 2210 | 2182 | * 0 on success, or a negative error in case of failure. |
| 2211 | 2183 | * |
| 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 | + * | |
| 2212 | 2202 | * struct bpf_sock *bpf_sk_lookup_tcp(void *ctx, struct bpf_sock_tuple *tuple, u32 tuple_size, u64 netns, u64 flags) |
| 2213 | 2203 | * Description |
| 2214 | 2204 | * Look for TCP socket matching *tuple*, optionally in a child |
| @@ -2289,6 +2279,16 @@ union bpf_attr { · 74 unmodified lines | ||
| 2289 | 2279 | * Return |
| 2290 | 2280 | * 0 on success, or a negative error in case of failure. |
| 2291 | 2281 | * |
| 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 | + * | |
| 2292 | 2292 | * int bpf_map_pop_elem(struct bpf_map *map, void *value) |
| 2293 | 2293 | * Description |
| 2294 | 2294 | * Pop an element from *map*. |
| @@ -2343,36 +2343,93 @@ union bpf_attr { · 48 unmodified lines | ||
| 2343 | 2343 | * Return |
| 2344 | 2344 | * 0 |
| 2345 | 2345 | * |
| 2346 | + * int bpf_spin_lock(struct bpf_spin_lock *lock) | |
| 2347 | + * Description | |
| 2348 | + * Acquire a spinlock represented by the pointer *lock*, which is | |
| 2349 | + * stored as part of a value of a map. Taking the lock allows to | |
| 2350 | + * safely update the rest of the fields in that value. The | |
| 2351 | + * spinlock can (and must) later be released with a call to | |
| 2352 | + * **bpf_spin_unlock**\ (\ *lock*\ ). | |
| 2353 | + * | |
| 2354 | + * Spinlocks in BPF programs come with a number of restrictions | |
| 2355 | + * and constraints: | |
| 2356 | + * | |
| 2357 | + * * **bpf_spin_lock** objects are only allowed inside maps of | |
| 2358 | + * types **BPF_MAP_TYPE_HASH** and **BPF_MAP_TYPE_ARRAY** (this | |
| 2359 | + * list could be extended in the future). | |
| 2360 | + * * BTF description of the map is mandatory. | |
| 2361 | + * * The BPF program can take ONE lock at a time, since taking two | |
| 2362 | + * or more could cause dead locks. | |
| 2363 | + * * Only one **struct bpf_spin_lock** is allowed per map element. | |
| 2364 | + * * When the lock is taken, calls (either BPF to BPF or helpers) | |
| 2365 | + * are not allowed. | |
| 2366 | + * * The **BPF_LD_ABS** and **BPF_LD_IND** instructions are not | |
| 2367 | + * allowed inside a spinlock-ed region. | |
| 2368 | + * * The BPF program MUST call **bpf_spin_unlock**\ () to release | |
| 2369 | + * the lock, on all execution paths, before it returns. | |
| 2370 | + * * The BPF program can access **struct bpf_spin_lock** only via | |
| 2371 | + * the **bpf_spin_lock**\ () and **bpf_spin_unlock**\ () | |
| 2372 | + * helpers. Loading or storing data into the **struct | |
| 2373 | + * bpf_spin_lock** *lock*\ **;** field of a map is not allowed. | |
| 2374 | + * * To use the **bpf_spin_lock**\ () helper, the BTF description | |
| 2375 | + * of the map value must be a struct and have **struct | |
| 2376 | + * bpf_spin_lock** *anyname*\ **;** field at the top level. | |
| 2377 | + * Nested lock inside another struct is not allowed. | |
| 2378 | + * * The **struct bpf_spin_lock** *lock* field in a map value must | |
| 2379 | + * be aligned on a multiple of 4 bytes in that value. | |
| 2380 | + * * Syscall with command **BPF_MAP_LOOKUP_ELEM** does not copy | |
| 2381 | + * the **bpf_spin_lock** field to user space. | |
| 2382 | + * * Syscall with command **BPF_MAP_UPDATE_ELEM**, or update from | |
| 2383 | + * a BPF program, do not update the **bpf_spin_lock** field. | |
| 2384 | + * * **bpf_spin_lock** cannot be on the stack or inside a | |
| 2385 | + * networking packet (it can only be inside of a map values). | |
| 2386 | + * * **bpf_spin_lock** is available to root only. | |
| 2387 | + * * Tracing programs and socket filter programs cannot use | |
| 2388 | + * **bpf_spin_lock**\ () due to insufficient preemption checks | |
| 2389 | + * (but this may change in the future). | |
| 2390 | + * * **bpf_spin_lock** is not allowed in inner maps of map-in-map. | |
| 2391 | + * Return | |
| 2392 | + * 0 | |
| 2393 | + * | |
| 2394 | + * int bpf_spin_unlock(struct bpf_spin_lock *lock) | |
| 2395 | + * Description | |
| 2396 | + * Release the *lock* previously locked by a call to | |
| 2397 | + * **bpf_spin_lock**\ (\ *lock*\ ). | |
| 2398 | + * Return | |
| 2399 | + * 0 | |
| 2400 | + * | |
| 2346 | 2401 | * struct bpf_sock *bpf_sk_fullsock(struct bpf_sock *sk) |
| 2347 | 2402 | * Description |
| 2348 | 2403 | * This helper gets a **struct bpf_sock** pointer such |
| 2349 | − * that all the fields in bpf_sock can be accessed. | |
| 2404 | + * that all the fields in this **bpf_sock** can be accessed. | |
| 2350 | 2405 | * Return |
| 2351 | − * A **struct bpf_sock** pointer on success, or NULL in | |
| 2406 | + * A **struct bpf_sock** pointer on success, or **NULL** in | |
| 2352 | 2407 | * case of failure. |
| 2353 | 2408 | * |
| 2354 | 2409 | * struct bpf_tcp_sock *bpf_tcp_sock(struct bpf_sock *sk) |
| 2355 | 2410 | * Description |
| 2356 | 2411 | * This helper gets a **struct bpf_tcp_sock** pointer from a |
| 2357 | 2412 | * **struct bpf_sock** pointer. |
| 2358 | − * | |
| 2359 | 2413 | * Return |
| 2360 | − * A **struct bpf_tcp_sock** pointer on success, or NULL in | |
| 2414 | + * A **struct bpf_tcp_sock** pointer on success, or **NULL** in | |
| 2361 | 2415 | * case of failure. |
| 2362 | 2416 | * |
| 2363 | 2417 | * 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. | |
| 2418 | + * Description | |
| 2419 | + * Set ECN (Explicit Congestion Notification) field of IP header | |
| 2420 | + * to **CE** (Congestion Encountered) if current value is **ECT** | |
| 2421 | + * (ECN Capable Transport). Otherwise, do nothing. Works with IPv6 | |
| 2422 | + * and IPv4. | |
| 2423 | + * Return | |
| 2424 | + * 1 if the **CE** flag is set (either by the current helper call | |
| 2425 | + * or because it was already present), 0 if it is not set. | |
| 2369 | 2426 | * |
| 2370 | 2427 | * struct bpf_sock *bpf_get_listener_sock(struct bpf_sock *sk) |
| 2371 | 2428 | * Description |
| 2372 | − * Return a **struct bpf_sock** pointer in TCP_LISTEN state. | |
| 2373 | − * bpf_sk_release() is unnecessary and not allowed. | |
| 2429 | + * Return a **struct bpf_sock** pointer in **TCP_LISTEN** state. | |
| 2430 | + * **bpf_sk_release**\ () is unnecessary and not allowed. | |
| 2374 | 2431 | * Return |
| 2375 | − * A **struct bpf_sock** pointer on success, or NULL in | |
| 2432 | + * A **struct bpf_sock** pointer on success, or **NULL** in | |
| 2376 | 2433 | * case of failure. |
| 2377 | 2434 | */ |
| 2378 | 2435 | #define __BPF_FUNC_MAPPER(FN) \ |