From 7b203a3d6dc6c2b0a395fb06354570ff1f7b7524 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Sat, 22 Aug 2020 13:28:09 +0200 Subject: [PATCH] bpf-helpers.7: Resync with current kernel source Signed-off-by: Michael Kerrisk --- man7/bpf-helpers.7 | 497 ++++++--------------------------------------- 1 file changed, 65 insertions(+), 432 deletions(-) diff --git a/man7/bpf-helpers.7 b/man7/bpf-helpers.7 index c8b3c7710..de6c7a8ec 100644 --- a/man7/bpf-helpers.7 +++ b/man7/bpf-helpers.7 @@ -31,34 +31,63 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .\" Copyright (C) All BPF authors and contributors from 2014 to present. +. .\" See git log include/uapi/linux/bpf.h in kernel tree for details. -.\" +. +.\" +. .\" %%%LICENSE_START(VERBATIM) +. .\" Permission is granted to make and distribute verbatim copies of this +. .\" manual provided the copyright notice and this permission notice are +. .\" preserved on all copies. -.\" +. +.\" +. .\" Permission is granted to copy and distribute modified versions of this +. .\" manual under the conditions for verbatim copying, provided that the +. .\" entire resulting derived work is distributed under the terms of a +. .\" permission notice identical to this one. -.\" +. +.\" +. .\" Since the Linux kernel and libraries are constantly changing, this +. .\" manual page may be incorrect or out-of-date. The author(s) assume no +. .\" responsibility for errors or omissions, or for damages resulting from +. .\" the use of the information contained herein. The author(s) may not +. .\" have taken the same level of care in the production of this manual, +. .\" which is licensed free of charge, as they might when working +. .\" professionally. -.\" +. +.\" +. .\" Formatted or processed versions of this manual, if unaccompanied by +. .\" the source, must acknowledge the copyright and authors of this work. +. .\" %%%LICENSE_END -.\" +. +.\" +. .\" Please do not edit this file. It was generated from the documentation +. .\" located in file include/uapi/linux/bpf.h of the Linux kernel sources +. .\" (helpers description), and from scripts/bpf_helpers_doc.py in the same +. .\" repository (header and footer). +. .SH DESCRIPTION .sp The extended Berkeley Packet Filter (eBPF) subsystem consists in programs @@ -142,8 +171,8 @@ Delete entry with \fIkey\fP from \fImap\fP\&. For tracing programs, safely attempt to read \fIsize\fP bytes from kernel space address \fIunsafe_ptr\fP and store the data in \fIdst\fP\&. .sp -Generally, use \fBbpf_probe_read_user\fP() or -\fBbpf_probe_read_kernel\fP() instead. +Generally, use bpf_probe_read_user() or bpf_probe_read_kernel() +instead. .TP .B Return 0 on success, or a negative error in case of failure. @@ -154,8 +183,6 @@ Generally, use \fBbpf_probe_read_user\fP() or .TP .B Description Return the time elapsed since system boot, in nanoseconds. -Does not include time the system was suspended. -See: \fBclock_gettime\fP(\fBCLOCK_MONOTONIC\fP) .TP .B Return Current \fIktime\fP\&. @@ -1230,11 +1257,11 @@ direct packet access. .TP .B Description Copy a NUL terminated string from an unsafe kernel address -\fIunsafe_ptr\fP to \fIdst\fP\&. See \fBbpf_probe_read_kernel_str\fP() for +\fIunsafe_ptr\fP to \fIdst\fP\&. See bpf_probe_read_kernel_str() for more details. .sp -Generally, use \fBbpf_probe_read_user_str\fP() or -\fBbpf_probe_read_kernel_str\fP() instead. +Generally, use bpf_probe_read_user_str() or bpf_probe_read_kernel_str() +instead. .TP .B Return On success, the strictly positive length of the string, @@ -1274,7 +1301,7 @@ A 8\-byte long non\-decreasing number. .INDENT 7.0 .TP .B Description -Equivalent to \fBbpf_get_socket_cookie\fP() helper that accepts +Equivalent to bpf_get_socket_cookie() helper that accepts \fIskb\fP, but gets socket from \fBstruct bpf_sock_ops\fP context. .TP .B Return @@ -1303,7 +1330,7 @@ to value \fIhash\fP\&. 0 .UNINDENT .TP -.B \fBint bpf_setsockopt(void *\fP\fIbpf_socket\fP\fB, int\fP \fIlevel\fP\fB, int\fP \fIoptname\fP\fB, void *\fP\fIoptval\fP\fB, int\fP \fIoptlen\fP\fB)\fP +.B \fBint bpf_setsockopt(struct bpf_sock_ops *\fP\fIbpf_socket\fP\fB, int\fP \fIlevel\fP\fB, int\fP \fIoptname\fP\fB, void *\fP\fIoptval\fP\fB, int\fP \fIoptlen\fP\fB)\fP .INDENT 7.0 .TP .B Description @@ -1313,15 +1340,6 @@ which the option resides and the name \fIoptname\fP of the option must be specified, see \fBsetsockopt(2)\fP for more information. The option value of length \fIoptlen\fP is pointed by \fIoptval\fP\&. .sp -\fIbpf_socket\fP should be one of the following: -.INDENT 7.0 -.IP \(bu 2 -\fBstruct bpf_sock_ops\fP for \fBBPF_PROG_TYPE_SOCK_OPS\fP\&. -.IP \(bu 2 -\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP -and \fBBPF_CGROUP_INET6_CONNECT\fP\&. -.UNINDENT -.sp This helper actually implements a subset of \fBsetsockopt()\fP\&. It supports the following \fIlevel\fPs: .INDENT 7.0 @@ -1350,15 +1368,6 @@ It supports the following \fIlevel\fPs: Grow or shrink the room for data in the packet associated to \fIskb\fP by \fIlen_diff\fP, and according to the selected \fImode\fP\&. .sp -By default, the helper will reset any offloaded checksum -indicator of the skb to CHECKSUM_NONE. This can be avoided -by the following flag: -.INDENT 7.0 -.IP \(bu 2 -\fBBPF_F_ADJ_ROOM_NO_CSUM_RESET\fP: Do not reset offloaded -checksum data of the skb to CHECKSUM_NONE. -.UNINDENT -.sp There are two supported modes at this time: .INDENT 7.0 .IP \(bu 2 @@ -1412,16 +1421,22 @@ support) as of this writing). .sp The lower two bits of \fIflags\fP are used as the return code if the map lookup fails. This is so that the return value can be -one of the XDP program return codes up to \fBXDP_TX\fP, as chosen -by the caller. Any higher bits in the \fIflags\fP argument must be +one of the XDP program return codes up to XDP_TX, as chosen by +the caller. Any higher bits in the \fIflags\fP argument must be unset. .sp -See also \fBbpf_redirect\fP(), which only supports redirecting -to an ifindex, but doesn\(aqt require a map to do so. +See also bpf_redirect(), which only supports redirecting to an +ifindex, but doesn\(aqt require a map to do so. .TP .B Return \fBXDP_REDIRECT\fP on success, or the value of the two lower bits -of the \fIflags\fP argument on error. +of the +.nf +** +.fi +flags* argument on error. +.IP "System Message: WARNING/2 (/tmp/bpf-helpers.rst:, line 1105)" +Inline strong start\-string without end\-string. .UNINDENT .TP .B \fBint bpf_sk_redirect_map(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u32\fP \fIkey\fP\fB, u64\fP \fIflags\fP\fB)\fP @@ -1550,7 +1565,7 @@ Where t_enabled is the time enabled for event and t_running is the time running for event since last normalization. The enabled and running times are accumulated since the perf event open. To achieve scaling factor between two invocations of an -eBPF program, users can use CPU id as the key (which is +eBPF program, users can can use CPU id as the key (which is typical for perf array usage model) to remember the previous value and do the calculation inside the eBPF program. .TP @@ -1573,7 +1588,7 @@ more details). 0 on success, or a negative error in case of failure. .UNINDENT .TP -.B \fBint bpf_getsockopt(void *\fP\fIbpf_socket\fP\fB, int\fP \fIlevel\fP\fB, int\fP \fIoptname\fP\fB, void *\fP\fIoptval\fP\fB, int\fP \fIoptlen\fP\fB)\fP +.B \fBint bpf_getsockopt(struct bpf_sock_ops *\fP\fIbpf_socket\fP\fB, int\fP \fIlevel\fP\fB, int\fP \fIoptname\fP\fB, void *\fP\fIoptval\fP\fB, int\fP \fIoptlen\fP\fB)\fP .INDENT 7.0 .TP .B Description @@ -1584,15 +1599,6 @@ must be specified, see \fBgetsockopt(2)\fP for more information. The retrieved value is stored in the structure pointed by \fIopval\fP and of length \fIoptlen\fP\&. .sp -\fIbpf_socket\fP should be one of the following: -.INDENT 7.0 -.IP \(bu 2 -\fBstruct bpf_sock_ops\fP for \fBBPF_PROG_TYPE_SOCK_OPS\fP\&. -.IP \(bu 2 -\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP -and \fBBPF_CGROUP_INET6_CONNECT\fP\&. -.UNINDENT -.sp This helper actually implements a subset of \fBgetsockopt()\fP\&. It supports the following \fIlevel\fPs: .INDENT 7.0 @@ -1618,7 +1624,7 @@ the return value of the probed function, and to set it to \fIrc\fP\&. The first argument is the context \fIregs\fP on which the kprobe works. .sp -This helper works by setting the PC (program counter) +This helper works by setting setting the PC (program counter) to an override function which is run in place of the original probed function. This means the probed function is not run at all. The replacement function just returns with the required @@ -1674,7 +1680,7 @@ callback: .INDENT 7.0 .TP .B \fBbpf_sock_ops_cb_flags_set(bpf_sock,\fP -\fBbpf_sock\->bpf_sock_ops_cb_flags & \(tiBPF_SOCK_OPS_RTO_CB_FLAG)\fP +\fBbpf_sock\->bpf_sock_ops_cb_flags & ~BPF_SOCK_OPS_RTO_CB_FLAG)\fP .UNINDENT .sp Here are some examples of where one could call such eBPF @@ -1826,11 +1832,10 @@ single IP address on a host that has multiple IP configured. .sp This helper works for IPv4 and IPv6, TCP and UDP sockets. The domain (\fIaddr\fP\fB\->sa_family\fP) must be \fBAF_INET\fP (or -\fBAF_INET6\fP). It\(aqs advised to pass zero port (\fBsin_port\fP -or \fBsin6_port\fP) which triggers IP_BIND_ADDRESS_NO_PORT\-like -behavior and lets the kernel efficiently pick up an unused -port as long as 4\-tuple is unique. Passing non\-zero port might -lead to degraded performance. +\fBAF_INET6\fP). Looking for a free port to bind to can be +expensive, therefore binding to port is not permitted by the +helper: \fIaddr\fP\fB\->sin_port\fP (or \fBsin6_port\fP, respectively) +must be set to zero. .TP .B Return 0 on success, or a negative error in case of failure. @@ -1841,8 +1846,8 @@ lead to degraded performance. .TP .B Description Adjust (move) \fIxdp_md\fP\fB\->data_end\fP by \fIdelta\fP bytes. It is -possible to both shrink and grow the packet tail. -Shrink done via \fIdelta\fP being a negative integer. +only possible to shrink the packet as of this writing, +therefore \fIdelta\fP must be a negative integer. .sp A call to this helper is susceptible to change the underlying packet buffer. Therefore, at load time, all checks on pointers @@ -2997,7 +3002,7 @@ void bpf_sys_open(struct pt_regs *ctx) .UNINDENT .UNINDENT .sp -In comparison, using \fBbpf_probe_read_user\fP() helper here +In comparison, using \fBbpf_probe_read_user()\fP helper here instead to read the string would require to estimate the length at compile time, and would often result in copying more memory than necessary. @@ -3018,7 +3023,7 @@ value. .TP .B Description Copy a NUL terminated string from an unsafe kernel address \fIunsafe_ptr\fP -to \fIdst\fP\&. Same semantics as with \fBbpf_probe_read_user_str\fP() apply. +to \fIdst\fP\&. Same semantics as with bpf_probe_read_user_str() apply. .TP .B Return On success, the strictly positive length of the string, including @@ -3029,7 +3034,7 @@ the trailing NUL character. On error, a negative value. .INDENT 7.0 .TP .B Description -Send out a tcp\-ack. \fItp\fP is the in\-kernel struct \fBtcp_sock\fP\&. +Send out a tcp\-ack. \fItp\fP is the in\-kernel struct tcp_sock. \fIrcv_nxt\fP is the ack_seq to be sent out. .TP .B Return @@ -3063,371 +3068,6 @@ Obtain the 64bit jiffies .B Return The 64 bit jiffies .UNINDENT -.TP -.B \fBint bpf_read_branch_records(struct bpf_perf_event_data *\fP\fIctx\fP\fB, void *\fP\fIbuf\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -For an eBPF program attached to a perf event, retrieve the -branch records (\fBstruct perf_branch_entry\fP) associated to \fIctx\fP -and store it in the buffer pointed by \fIbuf\fP up to size -\fIsize\fP bytes. -.TP -.B Return -On success, number of bytes written to \fIbuf\fP\&. On error, a -negative value. -.sp -The \fIflags\fP can be set to \fBBPF_F_GET_BRANCH_RECORDS_SIZE\fP to -instead return the number of bytes required to store all the -branch entries. If this flag is set, \fIbuf\fP may be NULL. -.sp -\fB\-EINVAL\fP if arguments invalid or \fBsize\fP not a multiple -of \fBsizeof\fP(\fBstruct perf_branch_entry\fP). -.sp -\fB\-ENOENT\fP if architecture does not support branch records. -.UNINDENT -.TP -.B \fBint bpf_get_ns_current_pid_tgid(u64\fP \fIdev\fP\fB, u64\fP \fIino\fP\fB, struct bpf_pidns_info *\fP\fInsdata\fP\fB, u32\fP \fIsize\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -Returns 0 on success, values for \fIpid\fP and \fItgid\fP as seen from the current -\fInamespace\fP will be returned in \fInsdata\fP\&. -.TP -.B Return -0 on success, or one of the following in case of failure: -.sp -\fB\-EINVAL\fP if dev and inum supplied don\(aqt match dev_t and inode number -with nsfs of current task, or if dev conversion to dev_t lost high bits. -.sp -\fB\-ENOENT\fP if pidns does not exists for the current task. -.UNINDENT -.TP -.B \fBint bpf_xdp_output(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB, void *\fP\fIdata\fP\fB, u64\fP \fIsize\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -Write raw \fIdata\fP blob into a special BPF perf event held by -\fImap\fP of type \fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. This perf -event must have the following attributes: \fBPERF_SAMPLE_RAW\fP -as \fBsample_type\fP, \fBPERF_TYPE_SOFTWARE\fP as \fBtype\fP, and -\fBPERF_COUNT_SW_BPF_OUTPUT\fP as \fBconfig\fP\&. -.sp -The \fIflags\fP are used to indicate the index in \fImap\fP for which -the value must be put, masked with \fBBPF_F_INDEX_MASK\fP\&. -Alternatively, \fIflags\fP can be set to \fBBPF_F_CURRENT_CPU\fP -to indicate that the index of the current CPU core should be -used. -.sp -The value to write, of \fIsize\fP, is passed through eBPF stack and -pointed by \fIdata\fP\&. -.sp -\fIctx\fP is a pointer to in\-kernel struct xdp_buff. -.sp -This helper is similar to \fBbpf_perf_eventoutput\fP() but -restricted to raw_tracepoint bpf programs. -.TP -.B Return -0 on success, or a negative error in case of failure. -.UNINDENT -.TP -.B \fBu64 bpf_get_netns_cookie(void *\fP\fIctx\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -Retrieve the cookie (generated by the kernel) of the network -namespace the input \fIctx\fP is associated with. The network -namespace cookie remains stable for its lifetime and provides -a global identifier that can be assumed unique. If \fIctx\fP is -NULL, then the helper returns the cookie for the initial -network namespace. The cookie itself is very similar to that -of \fBbpf_get_socket_cookie\fP() helper, but for network -namespaces instead of sockets. -.TP -.B Return -A 8\-byte long opaque number. -.UNINDENT -.TP -.B \fBu64 bpf_get_current_ancestor_cgroup_id(int\fP \fIancestor_level\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -Return id of cgroup v2 that is ancestor of the cgroup associated -with the current task at the \fIancestor_level\fP\&. The root cgroup -is at \fIancestor_level\fP zero and each step down the hierarchy -increments the level. If \fIancestor_level\fP == level of cgroup -associated with the current task, then return value will be the -same as that of \fBbpf_get_current_cgroup_id\fP(). -.sp -The helper is useful to implement policies based on cgroups -that are upper in hierarchy than immediate cgroup associated -with the current task. -.sp -The format of returned id and helper limitations are same as in -\fBbpf_get_current_cgroup_id\fP(). -.TP -.B Return -The id is returned or 0 in case the id could not be retrieved. -.UNINDENT -.TP -.B \fBint bpf_sk_assign(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_sock *\fP\fIsk\fP\fB, u64\fP \fIflags\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -Assign the \fIsk\fP to the \fIskb\fP\&. When combined with appropriate -routing configuration to receive the packet towards the socket, -will cause \fIskb\fP to be delivered to the specified socket. -Subsequent redirection of \fIskb\fP via \fBbpf_redirect\fP(), -\fBbpf_clone_redirect\fP() or other methods outside of BPF may -interfere with successful delivery to the socket. -.sp -This operation is only valid from TC ingress path. -.sp -The \fIflags\fP argument must be zero. -.TP -.B Return -0 on success, or a negative error in case of failure: -.sp -\fB\-EINVAL\fP if specified \fIflags\fP are not supported. -.sp -\fB\-ENOENT\fP if the socket is unavailable for assignment. -.sp -\fB\-ENETUNREACH\fP if the socket is unreachable (wrong netns). -.sp -\fB\-EOPNOTSUPP\fP if the operation is not supported, for example -a call from outside of TC ingress. -.sp -\fB\-ESOCKTNOSUPPORT\fP if the socket type is not supported -(reuseport). -.UNINDENT -.TP -.B \fBu64 bpf_ktime_get_boot_ns(void)\fP -.INDENT 7.0 -.TP -.B Description -Return the time elapsed since system boot, in nanoseconds. -Does include the time the system was suspended. -See: \fBclock_gettime\fP(\fBCLOCK_BOOTTIME\fP) -.TP -.B Return -Current \fIktime\fP\&. -.UNINDENT -.TP -.B \fBint bpf_seq_printf(struct seq_file *\fP\fIm\fP\fB, const char *\fP\fIfmt\fP\fB, u32\fP \fIfmt_size\fP\fB, const void *\fP\fIdata\fP\fB, u32\fP \fIdata_len\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -\fBbpf_seq_printf\fP() uses seq_file \fBseq_printf\fP() to print -out the format string. -The \fIm\fP represents the seq_file. The \fIfmt\fP and \fIfmt_size\fP are for -the format string itself. The \fIdata\fP and \fIdata_len\fP are format string -arguments. The \fIdata\fP are a \fBu64\fP array and corresponding format string -values are stored in the array. For strings and pointers where pointees -are accessed, only the pointer values are stored in the \fIdata\fP array. -The \fIdata_len\fP is the size of \fIdata\fP in bytes. -.sp -Formats \fB%s\fP, \fB%p{i,I}{4,6}\fP requires to read kernel memory. -Reading kernel memory may fail due to either invalid address or -valid address but requiring a major memory fault. If reading kernel memory -fails, the string for \fB%s\fP will be an empty string, and the ip -address for \fB%p{i,I}{4,6}\fP will be 0. Not returning error to -bpf program is consistent with what \fBbpf_trace_printk\fP() does for now. -.TP -.B Return -0 on success, or a negative error in case of failure: -.sp -\fB\-EBUSY\fP if per\-CPU memory copy buffer is busy, can try again -by returning 1 from bpf program. -.sp -\fB\-EINVAL\fP if arguments are invalid, or if \fIfmt\fP is invalid/unsupported. -.sp -\fB\-E2BIG\fP if \fIfmt\fP contains too many format specifiers. -.sp -\fB\-EOVERFLOW\fP if an overflow happened: The same object will be tried again. -.UNINDENT -.TP -.B \fBint bpf_seq_write(struct seq_file *\fP\fIm\fP\fB, const void *\fP\fIdata\fP\fB, u32\fP \fIlen\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -\fBbpf_seq_write\fP() uses seq_file \fBseq_write\fP() to write the data. -The \fIm\fP represents the seq_file. The \fIdata\fP and \fIlen\fP represent the -data to write in bytes. -.TP -.B Return -0 on success, or a negative error in case of failure: -.sp -\fB\-EOVERFLOW\fP if an overflow happened: The same object will be tried again. -.UNINDENT -.TP -.B \fBu64 bpf_sk_cgroup_id(struct bpf_sock *\fP\fIsk\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -Return the cgroup v2 id of the socket \fIsk\fP\&. -.sp -\fIsk\fP must be a non\-\fBNULL\fP pointer to a full socket, e.g. one -returned from \fBbpf_sk_lookup_xxx\fP(), -\fBbpf_sk_fullsock\fP(), etc. The format of returned id is -same as in \fBbpf_skb_cgroup_id\fP(). -.sp -This helper is available only if the kernel was compiled with -the \fBCONFIG_SOCK_CGROUP_DATA\fP configuration option. -.TP -.B Return -The id is returned or 0 in case the id could not be retrieved. -.UNINDENT -.TP -.B \fBu64 bpf_sk_ancestor_cgroup_id(struct bpf_sock *\fP\fIsk\fP\fB, int\fP \fIancestor_level\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -Return id of cgroup v2 that is ancestor of cgroup associated -with the \fIsk\fP at the \fIancestor_level\fP\&. The root cgroup is at -\fIancestor_level\fP zero and each step down the hierarchy -increments the level. If \fIancestor_level\fP == level of cgroup -associated with \fIsk\fP, then return value will be same as that -of \fBbpf_sk_cgroup_id\fP(). -.sp -The helper is useful to implement policies based on cgroups -that are upper in hierarchy than immediate cgroup associated -with \fIsk\fP\&. -.sp -The format of returned id and helper limitations are same as in -\fBbpf_sk_cgroup_id\fP(). -.TP -.B Return -The id is returned or 0 in case the id could not be retrieved. -.UNINDENT -.TP -.B \fBvoid *bpf_ringbuf_output(void *\fP\fIringbuf\fP\fB, void *\fP\fIdata\fP\fB, u64\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -Copy \fIsize\fP bytes from \fIdata\fP into a ring buffer \fIringbuf\fP\&. -If BPF_RB_NO_WAKEUP is specified in \fIflags\fP, no notification of -new data availability is sent. -IF BPF_RB_FORCE_WAKEUP is specified in \fIflags\fP, notification of -new data availability is sent unconditionally. -.TP -.B Return -0, on success; -< 0, on error. -.UNINDENT -.TP -.B \fBvoid *bpf_ringbuf_reserve(void *\fP\fIringbuf\fP\fB, u64\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -Reserve \fIsize\fP bytes of payload in a ring buffer \fIringbuf\fP\&. -.TP -.B Return -Valid pointer with \fIsize\fP bytes of memory available; NULL, -otherwise. -.UNINDENT -.TP -.B \fBvoid bpf_ringbuf_submit(void *\fP\fIdata\fP\fB, u64\fP \fIflags\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -Submit reserved ring buffer sample, pointed to by \fIdata\fP\&. -If BPF_RB_NO_WAKEUP is specified in \fIflags\fP, no notification of -new data availability is sent. -IF BPF_RB_FORCE_WAKEUP is specified in \fIflags\fP, notification of -new data availability is sent unconditionally. -.TP -.B Return -Nothing. Always succeeds. -.UNINDENT -.TP -.B \fBvoid bpf_ringbuf_discard(void *\fP\fIdata\fP\fB, u64\fP \fIflags\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -Discard reserved ring buffer sample, pointed to by \fIdata\fP\&. -If BPF_RB_NO_WAKEUP is specified in \fIflags\fP, no notification of -new data availability is sent. -IF BPF_RB_FORCE_WAKEUP is specified in \fIflags\fP, notification of -new data availability is sent unconditionally. -.TP -.B Return -Nothing. Always succeeds. -.UNINDENT -.TP -.B \fBu64 bpf_ringbuf_query(void *\fP\fIringbuf\fP\fB, u64\fP \fIflags\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -Query various characteristics of provided ring buffer. What -exactly is queries is determined by \fIflags\fP: -.IP "System Message: ERROR/3 (/tmp/bpf-helpers.rst:, line 2636)" -Unexpected indentation. -.INDENT 7.0 -.INDENT 3.5 -.INDENT 0.0 -.IP \(bu 2 -BPF_RB_AVAIL_DATA \- amount of data not yet consumed; -.IP \(bu 2 -BPF_RB_RING_SIZE \- the size of ring buffer; -.IP \(bu 2 -BPF_RB_CONS_POS \- consumer position (can wrap around); -.IP \(bu 2 -BPF_RB_PROD_POS \- producer(s) position (can wrap around); -.UNINDENT -.UNINDENT -.UNINDENT -.IP "System Message: WARNING/2 (/tmp/bpf-helpers.rst:, line 2640)" -Block quote ends without a blank line; unexpected unindent. -.sp -Data returned is just a momentary snapshots of actual values -and could be inaccurate, so this facility should be used to -power heuristics and for reporting, not to make 100% correct -calculation. -.TP -.B Return -Requested value, or 0, if flags are not recognized. -.UNINDENT -.TP -.B \fBint bpf_csum_level(struct sk_buff *\fP\fIskb\fP\fB, u64\fP \fIlevel\fP\fB)\fP -.INDENT 7.0 -.TP -.B Description -Change the skbs checksum level by one layer up or down, or -reset it entirely to none in order to have the stack perform -checksum validation. The level is applicable to the following -protocols: TCP, UDP, GRE, SCTP, FCOE. For example, a decap of -| ETH | IP | UDP | GUE | IP | TCP | into | ETH | IP | TCP | -through \fBbpf_skb_adjust_room\fP() helper with passing in -\fBBPF_F_ADJ_ROOM_NO_CSUM_RESET\fP flag would require one call -to \fBbpf_csum_level\fP() with \fBBPF_CSUM_LEVEL_DEC\fP since -the UDP header is removed. Similarly, an encap of the latter -into the former could be accompanied by a helper call to -\fBbpf_csum_level\fP() with \fBBPF_CSUM_LEVEL_INC\fP if the -skb is still intended to be processed in higher layers of the -stack instead of just egressing at tc. -.sp -There are three supported level settings at this time: -.INDENT 7.0 -.IP \(bu 2 -\fBBPF_CSUM_LEVEL_INC\fP: Increases skb\->csum_level for skbs -with CHECKSUM_UNNECESSARY. -.IP \(bu 2 -\fBBPF_CSUM_LEVEL_DEC\fP: Decreases skb\->csum_level for skbs -with CHECKSUM_UNNECESSARY. -.IP \(bu 2 -\fBBPF_CSUM_LEVEL_RESET\fP: Resets skb\->csum_level to 0 and -sets CHECKSUM_NONE to force checksum validation by the stack. -.IP \(bu 2 -\fBBPF_CSUM_LEVEL_QUERY\fP: No\-op, returns the current -skb\->csum_level. -.UNINDENT -.TP -.B Return -0 on success, or a negative error in case of failure. In the -case of \fBBPF_CSUM_LEVEL_QUERY\fP, the current skb\->csum_level -is returned or the error code \-EACCES in case the skb is not -subject to CHECKSUM_UNNECESSARY. -.UNINDENT .UNINDENT .SH EXAMPLES .sp @@ -3488,12 +3128,6 @@ of eBPF maps are used with a given helper function. .IP \(bu 2 \fIkernel/bpf/\fP directory contains other files in which additional helpers are defined (for cgroups, sockmaps, etc.). -.IP \(bu 2 -The bpftool utility can be used to probe the availability of helper functions -on the system (as well as supported program and map types, and a number of -other parameters). To do so, run \fBbpftool feature probe\fP (see -\fBbpftool\-feature\fP(8) for details). Add the \fBunprivileged\fP keyword to -list features available to unprivileged users. .UNINDENT .sp Compatibility between helper functions and program types can generally be found @@ -3513,7 +3147,6 @@ pointers for network processing are listed in function .SH SEE ALSO .sp \fBbpf\fP(2), -\fBbpftool\fP(8), \fBcgroups\fP(7), \fBip\fP(8), \fBperf_event_open\fP(2),