bpf: Minor fixes to BPF helpers documentation

 * 		For tracing programs, safely attempt to read *size* bytes from

 * 		kernel space address *unsafe_ptr* and store the data in *dst*.

 *

 * 		Generally, use bpf_probe_read_user() or bpf_probe_read_kernel()

 * 		instead.

 * 		Generally, use **bpf_probe_read_user**\ () or

 * 		**bpf_probe_read_kernel**\ () instead.

 * 	Return

 * 		0 on success, or a negative error in case of failure.

 *

 * 	Description

 * 		Return the time elapsed since system boot, in nanoseconds.

 * 		Does not include time the system was suspended.

 * 		See: clock_gettime(CLOCK_MONOTONIC)

 * 		See: **clock_gettime**\ (**CLOCK_MONOTONIC**)

 * 	Return

 * 		Current *ktime*.

 *

 * int bpf_probe_read_str(void *dst, u32 size, const void *unsafe_ptr)

 * 	Description

 * 		Copy a NUL terminated string from an unsafe kernel address

 * 		*unsafe_ptr* to *dst*. See bpf_probe_read_kernel_str() for

 * 		*unsafe_ptr* to *dst*. See **bpf_probe_read_kernel_str**\ () for

 * 		more details.

 *

 * 		Generally, use bpf_probe_read_user_str() or bpf_probe_read_kernel_str()

 * 		instead.

 * 		Generally, use **bpf_probe_read_user_str**\ () or

 * 		**bpf_probe_read_kernel_str**\ () instead.

 * 	Return

 * 		On success, the strictly positive length of the string,

 * 		including the trailing NUL character. On error, a negative

 *

 * u64 bpf_get_socket_cookie(struct bpf_sock_ops *ctx)

 * 	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** context.

 * 	Return

 * 		A 8-byte long non-decreasing number.

 * 		The option value of length *optlen* is pointed by *optval*.

 *

 * 		*bpf_socket* should be one of the following:

 *

 * 		* **struct bpf_sock_ops** for **BPF_PROG_TYPE_SOCK_OPS**.

 * 		* **struct bpf_sock_addr** for **BPF_CGROUP_INET4_CONNECT**

 * 		  and **BPF_CGROUP_INET6_CONNECT**.

 *

 * 		The lower two bits of *flags* 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 XDP_TX, as chosen by

 * 		the caller. Any higher bits in the *flags* argument must be

 * 		one of the XDP program return codes up to **XDP_TX**, as chosen

 * 		by the caller. Any higher bits in the *flags* argument must be

 * 		unset.

 *

 * 		See also bpf_redirect(), which only supports redirecting to an

 * 		ifindex, but doesn't require a map to do so.

 * 		See also **bpf_redirect**\ (), which only supports redirecting

 * 		to an ifindex, but doesn't require a map to do so.

 * 	Return

 * 		**XDP_REDIRECT** on success, or the value of the two lower bits

 * 		of the *flags* argument on error.

 * 		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 can use CPU id as the key (which is

 * 		eBPF program, users 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.

 * 	Return

 * 		*opval* and of length *optlen*.

 *

 * 		*bpf_socket* should be one of the following:

 *

 * 		* **struct bpf_sock_ops** for **BPF_PROG_TYPE_SOCK_OPS**.

 * 		* **struct bpf_sock_addr** for **BPF_CGROUP_INET4_CONNECT**

 * 		  and **BPF_CGROUP_INET6_CONNECT**.

 * 		The first argument is the context *regs* on which the kprobe

 * 		works.

 *

 * 		This helper works by setting setting the PC (program counter)

 * 		This helper works by 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

 *

 * 		*th* points to the start of the TCP header, while *th_len*

 * 		contains **sizeof**\ (**struct tcphdr**).

 *

 * 	Return

 * 		0 if *iph* and *th* are a valid SYN cookie ACK, or a negative

 * 		error otherwise.

 *

 *		*th* points to the start of the TCP header, while *th_len*

 *		contains the length of the TCP header.

 *

 *	Return

 *		On success, lower 32 bits hold the generated SYN cookie in

 *		followed by 16 bits which hold the MSS value for that cookie,

 * 				// size, after checking its boundaries.

 * 			}

 *

 * 		In comparison, using **bpf_probe_read_user()** helper here

 * 		In comparison, using **bpf_probe_read_user**\ () 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.

 * int bpf_probe_read_kernel_str(void *dst, u32 size, const void *unsafe_ptr)

 * 	Description

 * 		Copy a NUL terminated string from an unsafe kernel address *unsafe_ptr*

 * 		to *dst*. Same semantics as with bpf_probe_read_user_str() apply.

 * 		to *dst*. Same semantics as with **bpf_probe_read_user_str**\ () apply.

 * 	Return

 * 		On success, the strictly positive length of the string, including

 * 		the trailing NUL character. On error, a negative value.

 *

 * int bpf_tcp_send_ack(void *tp, u32 rcv_nxt)

 *	Description

 *		Send out a tcp-ack. *tp* is the in-kernel struct tcp_sock.

 *		Send out a tcp-ack. *tp* is the in-kernel struct **tcp_sock**.

 *		*rcv_nxt* is the ack_seq to be sent out.

 *	Return

 *		0 on success, or a negative error in case of failure.

 * int bpf_read_branch_records(struct bpf_perf_event_data *ctx, void *buf, u32 size, u64 flags)

 *	Description

 *		For an eBPF program attached to a perf event, retrieve the

 *		branch records (struct perf_branch_entry) associated to *ctx*

 *		branch records (**struct perf_branch_entry**) associated to *ctx*

 *		and store it in the buffer pointed by *buf* up to size

 *		*size* bytes.

 *	Return

 *		branch entries. If this flag is set, *buf* may be NULL.

 *

 *		**-EINVAL** if arguments invalid or **size** not a multiple

 *		of sizeof(struct perf_branch_entry).

 *		of **sizeof**\ (**struct perf_branch_entry**\ ).

 *

 *		**-ENOENT** if architecture does not support branch records.

 *

 *	Description

 *		Returns 0 on success, values for *pid* and *tgid* as seen from the current

 *		*namespace* will be returned in *nsdata*.

 *

 *		On failure, the returned value is one of the following:

 *	Return

 *		0 on success, or one of the following in case of failure:

 *

 *		**-EINVAL** if dev and inum supplied don't match dev_t and inode number

 *              with nsfs of current task, or if dev conversion to dev_t lost high bits.

 * 		a global identifier that can be assumed unique. If *ctx* is

 * 		NULL, then the helper returns the cookie for the initial

 * 		network namespace. The cookie itself is very similar to that

 * 		of bpf_get_socket_cookie() helper, but for network namespaces

 * 		instead of sockets.

 * 		of **bpf_get_socket_cookie**\ () helper, but for network

 * 		namespaces instead of sockets.

 * 	Return

 * 		A 8-byte long opaque number.

 *

 *

 *		The *flags* argument must be zero.

 *	Return

 *		0 on success, or a negative errno in case of failure.

 *		0 on success, or a negative error in case of failure:

 *

 *		* **-EINVAL**		Unsupported flags specified.

 *		* **-ENOENT**		Socket is unavailable for assignment.

 *		* **-ENETUNREACH**	Socket is unreachable (wrong netns).

 *		* **-EOPNOTSUPP**	Unsupported operation, for example a

 *					call from outside of TC ingress.

 *		* **-ESOCKTNOSUPPORT**	Socket type not supported (reuseport).

 *		**-EINVAL** if specified *flags* are not supported.

 *

 *		**-ENOENT** if the socket is unavailable for assignment.

 *

 *		**-ENETUNREACH** if the socket is unreachable (wrong netns).

 *

 *		**-EOPNOTSUPP** if the operation is not supported, for example

 *		a call from outside of TC ingress.

 *

 *		**-ESOCKTNOSUPPORT** if the socket type is not supported

 *		(reuseport).

 *

 * u64 bpf_ktime_get_boot_ns(void)

 * 	Description

 * 		Return the time elapsed since system boot, in nanoseconds.

 * 		Does include the time the system was suspended.

 * 		See: clock_gettime(CLOCK_BOOTTIME)

 * 		See: **clock_gettime**\ (**CLOCK_BOOTTIME**)

 * 	Return

 * 		Current *ktime*.

 *

 * int bpf_seq_printf(struct seq_file *m, const char *fmt, u32 fmt_size, const void *data, u32 data_len)

 * 	Description

 * 		seq_printf uses seq_file seq_printf() to print out the format string.

 * 		**bpf_seq_printf**\ () uses seq_file **seq_printf**\ () to print

 * 		out the format string.

 * 		The *m* represents the seq_file. The *fmt* and *fmt_size* are for

 * 		the format string itself. The *data* and *data_len* are format string

 * 		arguments. The *data* are a u64 array and corresponding format string

 * 		arguments. The *data* are a **u64** 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 *data* array.

 * 		The *data_len* is the *data* size in term of bytes.

 * 		The *data_len* is the size of *data* in bytes.

 *

 *		Formats **%s**, **%p{i,I}{4,6}** 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 **%s** will be an empty string, and the ip

 *		address for **%p{i,I}{4,6}** will be 0. Not returning error to

 *		bpf program is consistent with what bpf_trace_printk() does for now.

 *		bpf program is consistent with what **bpf_trace_printk**\ () does for now.

 * 	Return

 * 		0 on success, or a negative errno in case of failure.

 * 		0 on success, or a negative error in case of failure:

 *

 *		* **-EBUSY**		Percpu memory copy buffer is busy, can try again

 *		**-EBUSY** if per-CPU memory copy buffer is busy, can try again

 *		by returning 1 from bpf program.

 *		* **-EINVAL**		Invalid arguments, or invalid/unsupported formats.

 *		* **-E2BIG**		Too many format specifiers.

 *		* **-EOVERFLOW**	Overflow happens, the same object will be tried again.

 *

 *		**-EINVAL** if arguments are invalid, or if *fmt* is invalid/unsupported.

 *

 *		**-E2BIG** if *fmt* contains too many format specifiers.

 *

 *		**-EOVERFLOW** if an overflow happened: The same object will be tried again.

 *

 * int bpf_seq_write(struct seq_file *m, const void *data, u32 len)

 * 	Description

 * 		seq_write uses seq_file seq_write() to write the data.

 * 		**bpf_seq_write**\ () uses seq_file **seq_write**\ () to write the data.

 * 		The *m* represents the seq_file. The *data* and *len* represent the

 * 		data to write in bytes.

 * 	Return

 * 		0 on success, or a negative errno in case of failure.

 * 		0 on success, or a negative error in case of failure:

 *

 *		* **-EOVERFLOW**	Overflow happens, the same object will be tried again.

 *		**-EOVERFLOW** if an overflow happened: The same object will be tried again.

 */

#define __BPF_FUNC_MAPPER(FN)		\

	FN(unspec),			\

  of eBPF maps are used with a given helper function.

* *kernel/bpf/* directory contains other files in which additional helpers are

  defined (for cgroups, sockmaps, etc.).

* 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 **bpftool feature probe** (see

  **bpftool-feature**\ (8) for details). Add the **unprivileged** keyword to

  list features available to unprivileged users.

Compatibility between helper functions and program types can generally be found

in the files where helper functions are defined. Look for the **struct

========

**bpf**\ (2),

**bpftool**\ (8),

**cgroups**\ (7),

**ip**\ (8),

**perf_event_open**\ (2),