Commit 7799e4d9 authored by Joe Stringer's avatar Joe Stringer Committed by Alexei Starovoitov
Browse files

bpf: Import syscall arg documentation 



These descriptions are present in the man-pages project from the
original submissions around 2015-2016. Import them so that they can be
kept up to date as developers extend the bpf syscall commands.

These descriptions follow the pattern used by scripts/bpf_helpers_doc.py
so that we can take advantage of the parser to generate more up-to-date
man page writing based upon these headers.

Some minor wording adjustments were made to make the descriptions
more consistent for the description / return format.

Signed-off-by: default avatarJoe Stringer <joe@cilium.io>
Signed-off-by: default avatarAlexei Starovoitov <ast@kernel.org>
Reviewed-by: default avatarQuentin Monnet <quentin@isovalent.com>
Acked-by: default avatarToke Høiland-Jørgensen <toke@redhat.com>
Acked-by: default avatarYonghong Song <yhs@fb.com>
Link: https://lore.kernel.org/bpf/20210302171947.2268128-2-joe@cilium.io



Co-authored-by: default avatarAlexei Starovoitov <ast@kernel.org>
Co-authored-by: default avatarMichael Kerrisk <mtk.manpages@gmail.com>
parent 13ec0216

include/uapi/linux/bpf.h

+121 −1
Original line number Diff line number Diff line
@@ -93,7 +93,127 @@ union bpf_iter_link_info { 
	} map;

};



/* BPF syscall commands, see bpf(2) man-page for details. */

/* BPF syscall commands, see bpf(2) man-page for more details. */

/**

 * DOC: eBPF Syscall Preamble

 *

 * The operation to be performed by the **bpf**\ () system call is determined

 * by the *cmd* argument. Each operation takes an accompanying argument,

 * provided via *attr*, which is a pointer to a union of type *bpf_attr* (see

 * below). The size argument is the size of the union pointed to by *attr*.

 */

/**

 * DOC: eBPF Syscall Commands

 *

 * BPF_MAP_CREATE

 *	Description

 *		Create a map and return a file descriptor that refers to the

 *		map. The close-on-exec file descriptor flag (see **fcntl**\ (2))

 *		is automatically enabled for the new file descriptor.

 *

 *		Applying **close**\ (2) to the file descriptor returned by

 *		**BPF_MAP_CREATE** will delete the map (but see NOTES).

 *

 *	Return

 *		A new file descriptor (a nonnegative integer), or -1 if an

 *		error occurred (in which case, *errno* is set appropriately).

 *

 * BPF_MAP_LOOKUP_ELEM

 *	Description

 *		Look up an element with a given *key* in the map referred to

 *		by the file descriptor *map_fd*.

 *

 *	Return

 *		Returns zero on success. On error, -1 is returned and *errno*

 *		is set appropriately.

 *

 * BPF_MAP_UPDATE_ELEM

 *	Description

 *		Create or update an element (key/value pair) in a specified map.

 *

 *		The *flags* argument should be specified as one of the

 *		following:

 *

 *		**BPF_ANY**

 *			Create a new element or update an existing element.

 *		**BPF_NOEXIST**

 *			Create a new element only if it did not exist.

 *		**BPF_EXIST**

 *			Update an existing element.

 *

 *	Return

 *		Returns zero on success. On error, -1 is returned and *errno*

 *		is set appropriately.

 *

 *		May set *errno* to **EINVAL**, **EPERM**, **ENOMEM**,

 *		**E2BIG**, **EEXIST**, or **ENOENT**.

 *

 *		**E2BIG**

 *			The number of elements in the map reached the

 *			*max_entries* limit specified at map creation time.

 *		**EEXIST**

 *			If *flags* specifies **BPF_NOEXIST** and the element

 *			with *key* already exists in the map.

 *		**ENOENT**

 *			If *flags* specifies **BPF_EXIST** and the element with

 *			*key* does not exist in the map.

 *

 * BPF_MAP_DELETE_ELEM

 *	Description

 *		Look up and delete an element by key in a specified map.

 *

 *	Return

 *		Returns zero on success. On error, -1 is returned and *errno*

 *		is set appropriately.

 *

 * BPF_MAP_GET_NEXT_KEY

 *	Description

 *		Look up an element by key in a specified map and return the key

 *		of the next element. Can be used to iterate over all elements

 *		in the map.

 *

 *	Return

 *		Returns zero on success. On error, -1 is returned and *errno*

 *		is set appropriately.

 *

 *		The following cases can be used to iterate over all elements of

 *		the map:

 *

 *		* If *key* is not found, the operation returns zero and sets

 *		  the *next_key* pointer to the key of the first element.

 *		* If *key* is found, the operation returns zero and sets the

 *		  *next_key* pointer to the key of the next element.

 *		* If *key* is the last element, returns -1 and *errno* is set

 *		  to **ENOENT**.

 *

 *		May set *errno* to **ENOMEM**, **EFAULT**, **EPERM**, or

 *		**EINVAL** on error.

 *

 * BPF_PROG_LOAD

 *	Description

 *		Verify and load an eBPF program, returning a new file

 *		descriptor associated with the program.

 *

 *		Applying **close**\ (2) to the file descriptor returned by

 *		**BPF_PROG_LOAD** will unload the eBPF program (but see NOTES).

 *

 *		The close-on-exec file descriptor flag (see **fcntl**\ (2)) is

 *		automatically enabled for the new file descriptor.

 *

 *	Return

 *		A new file descriptor (a nonnegative integer), or -1 if an

 *		error occurred (in which case, *errno* is set appropriately).

 *

 * NOTES

 *	eBPF objects (maps and programs) can be shared between processes.

 *	For example, after **fork**\ (2), the child inherits file descriptors

 *	referring to the same eBPF objects. In addition, file descriptors

 *	referring to eBPF objects can be transferred over UNIX domain sockets.

 *	File descriptors referring to eBPF objects can be duplicated in the

 *	usual way, using **dup**\ (2) and similar calls. An eBPF object is

 *	deallocated only after all file descriptors referring to the object

 *	have been closed.

 */

enum bpf_cmd {

	BPF_MAP_CREATE,

	BPF_MAP_LOOKUP_ELEM,