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

bpf: Add minimal bpf() command documentation 



Introduce high-level descriptions of the intent and return codes of the
bpf() syscall commands. Subsequent patches may further flesh out the
content to provide a more useful programming reference.

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-3-joe@cilium.io
parent 7799e4d9

include/uapi/linux/bpf.h

+368 −0
Original line number Diff line number Diff line
@@ -204,6 +204,374 @@ union bpf_iter_link_info { 
 *		A new file descriptor (a nonnegative integer), or -1 if an

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

 *

 * BPF_OBJ_PIN

 *	Description

 *		Pin an eBPF program or map referred by the specified *bpf_fd*

 *		to the provided *pathname* on the filesystem.

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_OBJ_GET

 *	Description

 *		Open a file descriptor for the eBPF object pinned to the

 *		specified *pathname*.

 *

 *	Return

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

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

 *

 * BPF_PROG_ATTACH

 *	Description

 *		Attach an eBPF program to a *target_fd* at the specified

 *		*attach_type* hook.

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_PROG_DETACH

 *	Description

 *		Detach the eBPF program associated with the *target_fd* at the

 *		hook specified by *attach_type*. The program must have been

 *		previously attached using **BPF_PROG_ATTACH**.

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_PROG_TEST_RUN

 *	Description

 *		Run an eBPF program a number of times against a provided

 *		program context and return the modified program context and

 *		duration of the test run.

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_PROG_GET_NEXT_ID

 *	Description

 *		Fetch the next eBPF program currently loaded into the kernel.

 *

 *		Looks for the eBPF program with an id greater than *start_id*

 *		and updates *next_id* on success. If no other eBPF programs

 *		remain with ids higher than *start_id*, returns -1 and sets

 *		*errno* to **ENOENT**.

 *

 *	Return

 *		Returns zero on success. On error, or when no id remains, -1

 *		is returned and *errno* is set appropriately.

 *

 * BPF_MAP_GET_NEXT_ID

 *	Description

 *		Fetch the next eBPF map currently loaded into the kernel.

 *

 *		Looks for the eBPF map with an id greater than *start_id*

 *		and updates *next_id* on success. If no other eBPF maps

 *		remain with ids higher than *start_id*, returns -1 and sets

 *		*errno* to **ENOENT**.

 *

 *	Return

 *		Returns zero on success. On error, or when no id remains, -1

 *		is returned and *errno* is set appropriately.

 *

 * BPF_PROG_GET_FD_BY_ID

 *	Description

 *		Open a file descriptor for the eBPF program corresponding to

 *		*prog_id*.

 *

 *	Return

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

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

 *

 * BPF_MAP_GET_FD_BY_ID

 *	Description

 *		Open a file descriptor for the eBPF map corresponding to

 *		*map_id*.

 *

 *	Return

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

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

 *

 * BPF_OBJ_GET_INFO_BY_FD

 *	Description

 *		Obtain information about the eBPF object corresponding to

 *		*bpf_fd*.

 *

 *		Populates up to *info_len* bytes of *info*, which will be in

 *		one of the following formats depending on the eBPF object type

 *		of *bpf_fd*:

 *

 *		* **struct bpf_prog_info**

 *		* **struct bpf_map_info**

 *		* **struct bpf_btf_info**

 *		* **struct bpf_link_info**

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_PROG_QUERY

 *	Description

 *		Obtain information about eBPF programs associated with the

 *		specified *attach_type* hook.

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_RAW_TRACEPOINT_OPEN

 *	Description

 *		Attach an eBPF program to a tracepoint *name* to access kernel

 *		internal arguments of the tracepoint in their raw form.

 *

 *		The *prog_fd* must be a valid file descriptor associated with

 *		a loaded eBPF program of type **BPF_PROG_TYPE_RAW_TRACEPOINT**.

 *

 *		No ABI guarantees are made about the content of tracepoint

 *		arguments exposed to the corresponding eBPF program.

 *

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

 *		**BPF_RAW_TRACEPOINT_OPEN** 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_BTF_LOAD

 *	Description

 *		Verify and load BPF Type Format (BTF) metadata into the kernel,

 *		returning a new file descriptor associated with the metadata.

 *		BTF is described in more detail at

 *		https://www.kernel.org/doc/html/latest/bpf/btf.html.

 *

 *		The *btf* parameter must point to valid memory providing

 *		*btf_size* bytes of BTF binary metadata.

 *

 *		The returned file descriptor can be passed to other **bpf**\ ()

 *		subcommands such as **BPF_PROG_LOAD** or **BPF_MAP_CREATE** to

 *		associate the BTF with those objects.

 *

 *		Similar to **BPF_PROG_LOAD**, **BPF_BTF_LOAD** has optional

 *		parameters to specify a *btf_log_buf*, *btf_log_size* and

 *		*btf_log_level* which allow the kernel to return freeform log

 *		output regarding the BTF verification process.

 *

 *	Return

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

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

 *

 * BPF_BTF_GET_FD_BY_ID

 *	Description

 *		Open a file descriptor for the BPF Type Format (BTF)

 *		corresponding to *btf_id*.

 *

 *	Return

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

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

 *

 * BPF_TASK_FD_QUERY

 *	Description

 *		Obtain information about eBPF programs associated with the

 *		target process identified by *pid* and *fd*.

 *

 *		If the *pid* and *fd* are associated with a tracepoint, kprobe

 *		or uprobe perf event, then the *prog_id* and *fd_type* will

 *		be populated with the eBPF program id and file descriptor type

 *		of type **bpf_task_fd_type**. If associated with a kprobe or

 *		uprobe, the  *probe_offset* and *probe_addr* will also be

 *		populated. Optionally, if *buf* is provided, then up to

 *		*buf_len* bytes of *buf* will be populated with the name of

 *		the tracepoint, kprobe or uprobe.

 *

 *		The resulting *prog_id* may be introspected in deeper detail

 *		using **BPF_PROG_GET_FD_BY_ID** and **BPF_OBJ_GET_INFO_BY_FD**.

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_MAP_LOOKUP_AND_DELETE_ELEM

 *	Description

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

 *		by the file descriptor *fd*, and if found, delete the element.

 *

 *		The **BPF_MAP_TYPE_QUEUE** and **BPF_MAP_TYPE_STACK** map types

 *		implement this command as a "pop" operation, deleting the top

 *		element rather than one corresponding to *key*.

 *		The *key* and *key_len* parameters should be zeroed when

 *		issuing this operation for these map types.

 *

 *		This command is only valid for the following map types:

 *		* **BPF_MAP_TYPE_QUEUE**

 *		* **BPF_MAP_TYPE_STACK**

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_MAP_FREEZE

 *	Description

 *		Freeze the permissions of the specified map.

 *

 *		Write permissions may be frozen by passing zero *flags*.

 *		Upon success, no future syscall invocations may alter the

 *		map state of *map_fd*. Write operations from eBPF programs

 *		are still possible for a frozen map.

 *

 *		Not supported for maps of type **BPF_MAP_TYPE_STRUCT_OPS**.

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_BTF_GET_NEXT_ID

 *	Description

 *		Fetch the next BPF Type Format (BTF) object currently loaded

 *		into the kernel.

 *

 *		Looks for the BTF object with an id greater than *start_id*

 *		and updates *next_id* on success. If no other BTF objects

 *		remain with ids higher than *start_id*, returns -1 and sets

 *		*errno* to **ENOENT**.

 *

 *	Return

 *		Returns zero on success. On error, or when no id remains, -1

 *		is returned and *errno* is set appropriately.

 *

 * BPF_MAP_LOOKUP_BATCH

 *	Description

 *		Iterate and fetch multiple elements in a map.

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_MAP_LOOKUP_AND_DELETE_BATCH

 *	Description

 *		Iterate and delete multiple elements in a map.

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_MAP_UPDATE_BATCH

 *	Description

 *		Iterate and update multiple elements in a map.

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_MAP_DELETE_BATCH

 *	Description

 *		Iterate and delete multiple elements in a map.

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_LINK_CREATE

 *	Description

 *		Attach an eBPF program to a *target_fd* at the specified

 *		*attach_type* hook and return a file descriptor handle for

 *		managing the link.

 *

 *	Return

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

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

 *

 * BPF_LINK_UPDATE

 *	Description

 *		Update the eBPF program in the specified *link_fd* to

 *		*new_prog_fd*.

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_LINK_GET_FD_BY_ID

 *	Description

 *		Open a file descriptor for the eBPF Link corresponding to

 *		*link_id*.

 *

 *	Return

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

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

 *

 * BPF_LINK_GET_NEXT_ID

 *	Description

 *		Fetch the next eBPF link currently loaded into the kernel.

 *

 *		Looks for the eBPF link with an id greater than *start_id*

 *		and updates *next_id* on success. If no other eBPF links

 *		remain with ids higher than *start_id*, returns -1 and sets

 *		*errno* to **ENOENT**.

 *

 *	Return

 *		Returns zero on success. On error, or when no id remains, -1

 *		is returned and *errno* is set appropriately.

 *

 * BPF_ENABLE_STATS

 *	Description

 *		Enable eBPF runtime statistics gathering.

 *

 *		Runtime statistics gathering for the eBPF runtime is disabled

 *		by default to minimize the corresponding performance overhead.

 *		This command enables statistics globally.

 *

 *		Multiple programs may independently enable statistics.

 *		After gathering the desired statistics, eBPF runtime statistics

 *		may be disabled again by calling **close**\ (2) for the file

 *		descriptor returned by this function. Statistics will only be

 *		disabled system-wide when all outstanding file descriptors

 *		returned by prior calls for this subcommand are closed.

 *

 *	Return

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

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

 *

 * BPF_ITER_CREATE

 *	Description

 *		Create an iterator on top of the specified *link_fd* (as

 *		previously created using **BPF_LINK_CREATE**) and return a

 *		file descriptor that can be used to trigger the iteration.

 *

 *		If the resulting file descriptor is pinned to the filesystem

 *		using  **BPF_OBJ_PIN**, then subsequent **read**\ (2) syscalls

 *		for that path will trigger the iterator to read kernel state

 *		using the eBPF program attached to *link_fd*.

 *

 *	Return

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

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

 *

 * BPF_LINK_DETACH

 *	Description

 *		Forcefully detach the specified *link_fd* from its

 *		corresponding attachment point.

 *

 *	Return

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

 *		is set appropriately.

 *

 * BPF_PROG_BIND_MAP

 *	Description

 *		Bind a map to the lifetime of an eBPF program.

 *

 *		The map identified by *map_fd* is bound to the program

 *		identified by *prog_fd* and only released when *prog_fd* is

 *		released. This may be used in cases where metadata should be

 *		associated with a program which otherwise does not contain any

 *		references to the map (for example, embedded in the eBPF

 *		program instructions).

 *

 *	Return

 *		Returns zero on success. On error, -1 is returned and *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