Synchronise the bpf.h header under tools, to report the fixes recently brought to the documentation for the BPF helpers.
Showing the changes to tools/include/uapi (1 of 1 file). Show all
Unified · Split
| @@ -675,8 +675,8 @@ union bpf_attr { · 674 unmodified lines | ||
| 675 | 675 | * For tracing programs, safely attempt to read *size* bytes from |
| 676 | 676 | * kernel space address *unsafe_ptr* and store the data in *dst*. |
| 677 | 677 | * |
| 678 | − * Generally, use bpf_probe_read_user() or bpf_probe_read_kernel() | |
| 679 | − * instead. | |
| 678 | + * Generally, use **bpf_probe_read_user**\ () or | |
| 679 | + * **bpf_probe_read_kernel**\ () instead. | |
| 680 | 680 | * Return |
| 681 | 681 | * 0 on success, or a negative error in case of failure. |
| 682 | 682 | * |
| @@ -684,7 +684,7 @@ union bpf_attr { · 1 unmodified line | ||
| 684 | 684 | * Description |
| 685 | 685 | * Return the time elapsed since system boot, in nanoseconds. |
| 686 | 686 | * Does not include time the system was suspended. |
| 687 | − * See: clock_gettime(CLOCK_MONOTONIC) | |
| 687 | + * See: **clock_gettime**\ (**CLOCK_MONOTONIC**) | |
| 688 | 688 | * Return |
| 689 | 689 | * Current *ktime*. |
| 690 | 690 | * |
| @@ -1543,11 +1543,11 @@ union bpf_attr { · 852 unmodified lines | ||
| 1543 | 1543 | * int bpf_probe_read_str(void *dst, u32 size, const void *unsafe_ptr) |
| 1544 | 1544 | * Description |
| 1545 | 1545 | * Copy a NUL terminated string from an unsafe kernel address |
| 1546 | − * *unsafe_ptr* to *dst*. See bpf_probe_read_kernel_str() for | |
| 1546 | + * *unsafe_ptr* to *dst*. See **bpf_probe_read_kernel_str**\ () for | |
| 1547 | 1547 | * more details. |
| 1548 | 1548 | * |
| 1549 | − * Generally, use bpf_probe_read_user_str() or bpf_probe_read_kernel_str() | |
| 1550 | − * instead. | |
| 1549 | + * Generally, use **bpf_probe_read_user_str**\ () or | |
| 1550 | + * **bpf_probe_read_kernel_str**\ () instead. | |
| 1551 | 1551 | * Return |
| 1552 | 1552 | * On success, the strictly positive length of the string, |
| 1553 | 1553 | * including the trailing NUL character. On error, a negative |
| @@ -1575,7 +1575,7 @@ union bpf_attr { · 21 unmodified lines | ||
| 1575 | 1575 | * |
| 1576 | 1576 | * u64 bpf_get_socket_cookie(struct bpf_sock_ops *ctx) |
| 1577 | 1577 | * Description |
| 1578 | − * Equivalent to bpf_get_socket_cookie() helper that accepts | |
| 1578 | + * Equivalent to **bpf_get_socket_cookie**\ () helper that accepts | |
| 1579 | 1579 | * *skb*, but gets socket from **struct bpf_sock_ops** context. |
| 1580 | 1580 | * Return |
| 1581 | 1581 | * A 8-byte long non-decreasing number. |
| @@ -1604,6 +1604,7 @@ union bpf_attr { · 22 unmodified lines | ||
| 1604 | 1604 | * The option value of length *optlen* is pointed by *optval*. |
| 1605 | 1605 | * |
| 1606 | 1606 | * *bpf_socket* should be one of the following: |
| 1607 | + * | |
| 1607 | 1608 | * * **struct bpf_sock_ops** for **BPF_PROG_TYPE_SOCK_OPS**. |
| 1608 | 1609 | * * **struct bpf_sock_addr** for **BPF_CGROUP_INET4_CONNECT** |
| 1609 | 1610 | * and **BPF_CGROUP_INET6_CONNECT**. |
| @@ -1672,12 +1673,12 @@ union bpf_attr { · 62 unmodified lines | ||
| 1672 | 1673 | * |
| 1673 | 1674 | * The lower two bits of *flags* are used as the return code if |
| 1674 | 1675 | * the map lookup fails. This is so that the return value can be |
| 1675 | − * one of the XDP program return codes up to XDP_TX, as chosen by | |
| 1676 | − * the caller. Any higher bits in the *flags* argument must be | |
| 1676 | + * one of the XDP program return codes up to **XDP_TX**, as chosen | |
| 1677 | + * by the caller. Any higher bits in the *flags* argument must be | |
| 1677 | 1678 | * unset. |
| 1678 | 1679 | * |
| 1679 | − * See also bpf_redirect(), which only supports redirecting to an | |
| 1680 | − * ifindex, but doesn't require a map to do so. | |
| 1680 | + * See also **bpf_redirect**\ (), which only supports redirecting | |
| 1681 | + * to an ifindex, but doesn't require a map to do so. | |
| 1681 | 1682 | * Return |
| 1682 | 1683 | * **XDP_REDIRECT** on success, or the value of the two lower bits |
| 1683 | 1684 | * of the *flags* argument on error. |
| @@ -1785,7 +1786,7 @@ union bpf_attr { · 101 unmodified lines | ||
| 1785 | 1786 | * the time running for event since last normalization. The |
| 1786 | 1787 | * enabled and running times are accumulated since the perf event |
| 1787 | 1788 | * open. To achieve scaling factor between two invocations of an |
| 1788 | − * eBPF program, users can can use CPU id as the key (which is | |
| 1789 | + * eBPF program, users can use CPU id as the key (which is | |
| 1789 | 1790 | * typical for perf array usage model) to remember the previous |
| 1790 | 1791 | * value and do the calculation inside the eBPF program. |
| 1791 | 1792 | * Return |
| @@ -1812,6 +1813,7 @@ union bpf_attr { · 20 unmodified lines | ||
| 1812 | 1813 | * *opval* and of length *optlen*. |
| 1813 | 1814 | * |
| 1814 | 1815 | * *bpf_socket* should be one of the following: |
| 1816 | + * | |
| 1815 | 1817 | * * **struct bpf_sock_ops** for **BPF_PROG_TYPE_SOCK_OPS**. |
| 1816 | 1818 | * * **struct bpf_sock_addr** for **BPF_CGROUP_INET4_CONNECT** |
| 1817 | 1819 | * and **BPF_CGROUP_INET6_CONNECT**. |
| @@ -1833,7 +1835,7 @@ union bpf_attr { · 15 unmodified lines | ||
| 1833 | 1835 | * The first argument is the context *regs* on which the kprobe |
| 1834 | 1836 | * works. |
| 1835 | 1837 | * |
| 1836 | − * This helper works by setting setting the PC (program counter) | |
| 1838 | + * This helper works by setting the PC (program counter) | |
| 1837 | 1839 | * to an override function which is run in place of the original |
| 1838 | 1840 | * probed function. This means the probed function is not run at |
| 1839 | 1841 | * all. The replacement function just returns with the required |
| @@ -2300,7 +2302,7 @@ union bpf_attr { · 460 unmodified lines | ||
| 2300 | 2302 | * **bpf_rc_keydown**\ () again with the same values, or calling |
| 2301 | 2303 | * **bpf_rc_repeat**\ (). |
| 2302 | 2304 | * |
| 2303 | − * Some protocols include a toggle bit, in case the button was | |
| 2305 | + * Some protocols include a toggle bit, in case the button was | |
| 2304 | 2306 | * released and pressed again between consecutive scancodes. |
| 2305 | 2307 | * |
| 2306 | 2308 | * The *ctx* should point to the lirc sample as passed into |
| @@ -2646,7 +2648,6 @@ union bpf_attr { · 339 unmodified lines | ||
| 2646 | 2648 | * |
| 2647 | 2649 | * *th* points to the start of the TCP header, while *th_len* |
| 2648 | 2650 | * contains **sizeof**\ (**struct tcphdr**). |
| 2649 | − * | |
| 2650 | 2651 | * Return |
| 2651 | 2652 | * 0 if *iph* and *th* are a valid SYN cookie ACK, or a negative |
| 2652 | 2653 | * error otherwise. |
| @@ -2829,7 +2830,6 @@ union bpf_attr { · 176 unmodified lines | ||
| 2829 | 2830 | * |
| 2830 | 2831 | * *th* points to the start of the TCP header, while *th_len* |
| 2831 | 2832 | * contains the length of the TCP header. |
| 2832 | − * | |
| 2833 | 2833 | * Return |
| 2834 | 2834 | * On success, lower 32 bits hold the generated SYN cookie in |
| 2835 | 2835 | * followed by 16 bits which hold the MSS value for that cookie, |
| @@ -2912,7 +2912,7 @@ union bpf_attr { · 76 unmodified lines | ||
| 2912 | 2912 | * // size, after checking its boundaries. |
| 2913 | 2913 | * } |
| 2914 | 2914 | * |
| 2915 | − * In comparison, using **bpf_probe_read_user()** helper here | |
| 2915 | + * In comparison, using **bpf_probe_read_user**\ () helper here | |
| 2916 | 2916 | * instead to read the string would require to estimate the length |
| 2917 | 2917 | * at compile time, and would often result in copying more memory |
| 2918 | 2918 | * than necessary. |
| @@ -2930,14 +2930,14 @@ union bpf_attr { · 11 unmodified lines | ||
| 2930 | 2930 | * int bpf_probe_read_kernel_str(void *dst, u32 size, const void *unsafe_ptr) |
| 2931 | 2931 | * Description |
| 2932 | 2932 | * Copy a NUL terminated string from an unsafe kernel address *unsafe_ptr* |
| 2933 | − * to *dst*. Same semantics as with bpf_probe_read_user_str() apply. | |
| 2933 | + * to *dst*. Same semantics as with **bpf_probe_read_user_str**\ () apply. | |
| 2934 | 2934 | * Return |
| 2935 | − * On success, the strictly positive length of the string, including | |
| 2935 | + * On success, the strictly positive length of the string, including | |
| 2936 | 2936 | * the trailing NUL character. On error, a negative value. |
| 2937 | 2937 | * |
| 2938 | 2938 | * int bpf_tcp_send_ack(void *tp, u32 rcv_nxt) |
| 2939 | 2939 | * Description |
| 2940 | − * Send out a tcp-ack. *tp* is the in-kernel struct tcp_sock. | |
| 2940 | + * Send out a tcp-ack. *tp* is the in-kernel struct **tcp_sock**. | |
| 2941 | 2941 | * *rcv_nxt* is the ack_seq to be sent out. |
| 2942 | 2942 | * Return |
| 2943 | 2943 | * 0 on success, or a negative error in case of failure. |
| @@ -2965,19 +2965,19 @@ union bpf_attr { · 21 unmodified lines | ||
| 2965 | 2965 | * int bpf_read_branch_records(struct bpf_perf_event_data *ctx, void *buf, u32 size, u64 flags) |
| 2966 | 2966 | * Description |
| 2967 | 2967 | * For an eBPF program attached to a perf event, retrieve the |
| 2968 | − * branch records (struct perf_branch_entry) associated to *ctx* | |
| 2969 | − * and store it in the buffer pointed by *buf* up to size | |
| 2968 | + * branch records (**struct perf_branch_entry**) associated to *ctx* | |
| 2969 | + * and store it in the buffer pointed by *buf* up to size | |
| 2970 | 2970 | * *size* bytes. |
| 2971 | 2971 | * Return |
| 2972 | 2972 | * On success, number of bytes written to *buf*. On error, a |
| 2973 | 2973 | * negative value. |
| 2974 | 2974 | * |
| 2975 | 2975 | * The *flags* can be set to **BPF_F_GET_BRANCH_RECORDS_SIZE** to |
| 2976 | − * instead return the number of bytes required to store all the | |
| 2976 | + * instead return the number of bytes required to store all the | |
| 2977 | 2977 | * branch entries. If this flag is set, *buf* may be NULL. |
| 2978 | 2978 | * |
| 2979 | 2979 | * **-EINVAL** if arguments invalid or **size** not a multiple |
| 2980 | − * of sizeof(struct perf_branch_entry). | |
| 2980 | + * of **sizeof**\ (**struct perf_branch_entry**\ ). | |
| 2981 | 2981 | * |
| 2982 | 2982 | * **-ENOENT** if architecture does not support branch records. |
| 2983 | 2983 | * |
| @@ -2985,8 +2985,8 @@ union bpf_attr { · 1 unmodified line | ||
| 2985 | 2985 | * Description |
| 2986 | 2986 | * Returns 0 on success, values for *pid* and *tgid* as seen from the current |
| 2987 | 2987 | * *namespace* will be returned in *nsdata*. |
| 2988 | − * | |
| 2989 | − * On failure, the returned value is one of the following: | |
| 2988 | + * Return | |
| 2989 | + * 0 on success, or one of the following in case of failure: | |
| 2990 | 2990 | * |
| 2991 | 2991 | * **-EINVAL** if dev and inum supplied don't match dev_t and inode number |
| 2992 | 2992 | * with nsfs of current task, or if dev conversion to dev_t lost high bits. |
| @@ -3025,8 +3025,8 @@ union bpf_attr { · 32 unmodified lines | ||
| 3025 | 3025 | * a global identifier that can be assumed unique. If *ctx* is |
| 3026 | 3026 | * NULL, then the helper returns the cookie for the initial |
| 3027 | 3027 | * network namespace. The cookie itself is very similar to that |
| 3028 | − * of bpf_get_socket_cookie() helper, but for network namespaces | |
| 3029 | − * instead of sockets. | |
| 3028 | + * of **bpf_get_socket_cookie**\ () helper, but for network | |
| 3029 | + * namespaces instead of sockets. | |
| 3030 | 3030 | * Return |
| 3031 | 3031 | * A 8-byte long opaque number. |
| 3032 | 3032 | * |
| @@ -3061,57 +3061,66 @@ union bpf_attr { · 28 unmodified lines | ||
| 3061 | 3061 | * |
| 3062 | 3062 | * The *flags* argument must be zero. |
| 3063 | 3063 | * Return |
| 3064 | − * 0 on success, or a negative errno in case of failure. | |
| 3064 | + * 0 on success, or a negative error in case of failure: | |
| 3065 | 3065 | * |
| 3066 | − * * **-EINVAL** Unsupported flags specified. | |
| 3067 | − * * **-ENOENT** Socket is unavailable for assignment. | |
| 3068 | − * * **-ENETUNREACH** Socket is unreachable (wrong netns). | |
| 3069 | − * * **-EOPNOTSUPP** Unsupported operation, for example a | |
| 3070 | − * call from outside of TC ingress. | |
| 3071 | − * * **-ESOCKTNOSUPPORT** Socket type not supported (reuseport). | |
| 3066 | + * **-EINVAL** if specified *flags* are not supported. | |
| 3067 | + * | |
| 3068 | + * **-ENOENT** if the socket is unavailable for assignment. | |
| 3069 | + * | |
| 3070 | + * **-ENETUNREACH** if the socket is unreachable (wrong netns). | |
| 3071 | + * | |
| 3072 | + * **-EOPNOTSUPP** if the operation is not supported, for example | |
| 3073 | + * a call from outside of TC ingress. | |
| 3074 | + * | |
| 3075 | + * **-ESOCKTNOSUPPORT** if the socket type is not supported | |
| 3076 | + * (reuseport). | |
| 3072 | 3077 | * |
| 3073 | 3078 | * u64 bpf_ktime_get_boot_ns(void) |
| 3074 | 3079 | * Description |
| 3075 | 3080 | * Return the time elapsed since system boot, in nanoseconds. |
| 3076 | 3081 | * Does include the time the system was suspended. |
| 3077 | − * See: clock_gettime(CLOCK_BOOTTIME) | |
| 3082 | + * See: **clock_gettime**\ (**CLOCK_BOOTTIME**) | |
| 3078 | 3083 | * Return |
| 3079 | 3084 | * Current *ktime*. |
| 3080 | 3085 | * |
| 3081 | 3086 | * int bpf_seq_printf(struct seq_file *m, const char *fmt, u32 fmt_size, const void *data, u32 data_len) |
| 3082 | 3087 | * Description |
| 3083 | − * seq_printf uses seq_file seq_printf() to print out the format string. | |
| 3088 | + * **bpf_seq_printf**\ () uses seq_file **seq_printf**\ () to print | |
| 3089 | + * out the format string. | |
| 3084 | 3090 | * The *m* represents the seq_file. The *fmt* and *fmt_size* are for |
| 3085 | 3091 | * the format string itself. The *data* and *data_len* are format string |
| 3086 | − * arguments. The *data* are a u64 array and corresponding format string | |
| 3092 | + * arguments. The *data* are a **u64** array and corresponding format string | |
| 3087 | 3093 | * values are stored in the array. For strings and pointers where pointees |
| 3088 | 3094 | * are accessed, only the pointer values are stored in the *data* array. |
| 3089 | − * The *data_len* is the *data* size in term of bytes. | |
| 3095 | + * The *data_len* is the size of *data* in bytes. | |
| 3090 | 3096 | * |
| 3091 | 3097 | * Formats **%s**, **%p{i,I}{4,6}** requires to read kernel memory. |
| 3092 | 3098 | * Reading kernel memory may fail due to either invalid address or |
| 3093 | 3099 | * valid address but requiring a major memory fault. If reading kernel memory |
| 3094 | 3100 | * fails, the string for **%s** will be an empty string, and the ip |
| 3095 | 3101 | * address for **%p{i,I}{4,6}** will be 0. Not returning error to |
| 3096 | − * bpf program is consistent with what bpf_trace_printk() does for now. | |
| 3102 | + * bpf program is consistent with what **bpf_trace_printk**\ () does for now. | |
| 3097 | 3103 | * Return |
| 3098 | − * 0 on success, or a negative errno in case of failure. | |
| 3104 | + * 0 on success, or a negative error in case of failure: | |
| 3105 | + * | |
| 3106 | + * **-EBUSY** if per-CPU memory copy buffer is busy, can try again | |
| 3107 | + * by returning 1 from bpf program. | |
| 3108 | + * | |
| 3109 | + * **-EINVAL** if arguments are invalid, or if *fmt* is invalid/unsupported. | |
| 3110 | + * | |
| 3111 | + * **-E2BIG** if *fmt* contains too many format specifiers. | |
| 3099 | 3112 | * |
| 3100 | − * * **-EBUSY** Percpu memory copy buffer is busy, can try again | |
| 3101 | − * by returning 1 from bpf program. | |
| 3102 | − * * **-EINVAL** Invalid arguments, or invalid/unsupported formats. | |
| 3103 | − * * **-E2BIG** Too many format specifiers. | |
| 3104 | − * * **-EOVERFLOW** Overflow happens, the same object will be tried again. | |
| 3113 | + * **-EOVERFLOW** if an overflow happened: The same object will be tried again. | |
| 3105 | 3114 | * |
| 3106 | 3115 | * int bpf_seq_write(struct seq_file *m, const void *data, u32 len) |
| 3107 | 3116 | * Description |
| 3108 | − * seq_write uses seq_file seq_write() to write the data. | |
| 3117 | + * **bpf_seq_write**\ () uses seq_file **seq_write**\ () to write the data. | |
| 3109 | 3118 | * The *m* represents the seq_file. The *data* and *len* represent the |
| 3110 | − * data to write in bytes. | |
| 3119 | + * data to write in bytes. | |
| 3111 | 3120 | * Return |
| 3112 | − * 0 on success, or a negative errno in case of failure. | |
| 3121 | + * 0 on success, or a negative error in case of failure: | |
| 3113 | 3122 | * |
| 3114 | − * * **-EOVERFLOW** Overflow happens, the same object will be tried again. | |
| 3123 | + * **-EOVERFLOW** if an overflow happened: The same object will be tried again. | |
| 3115 | 3124 | */ |
| 3116 | 3125 | #define __BPF_FUNC_MAPPER(FN) \ |
| 3117 | 3126 | FN(unspec), \ |