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

bpf: Document BPF_PROG_PIN syscall command 



Commit b2197755 ("bpf: add support for persistent maps/progs")
contains the original implementation and git logs, used as reference for
this documentation.

Also pull in the filename restriction as documented in commit 6d8cb045
("bpf: comment why dots in filenames under BPF virtual FS are not allowed")

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-5-joe@cilium.io
parent 6690523b

include/uapi/linux/bpf.h

+29 −7
Original line number Diff line number Diff line
@@ -219,6 +219,22 @@ union bpf_iter_link_info { 
 *		Pin an eBPF program or map referred by the specified *bpf_fd*

 *		to the provided *pathname* on the filesystem.

 *

 *		The *pathname* argument must not contain a dot (".").

 *

 *		On success, *pathname* retains a reference to the eBPF object,

 *		preventing deallocation of the object when the original

 *		*bpf_fd* is closed. This allow the eBPF object to live beyond

 *		**close**\ (\ *bpf_fd*\ ), and hence the lifetime of the parent

 *		process.

 *

 *		Applying **unlink**\ (2) or similar calls to the *pathname*

 *		unpins the object from the filesystem, removing the reference.

 *		If no other file descriptors or filesystem nodes refer to the

 *		same object, it will be deallocated (see NOTES).

 *

 *		The filesystem type for the parent directory of *pathname* must

 *		be **BPF_FS_MAGIC**.

 *

 *	Return

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

 *		is set appropriately.
@@ -584,13 +600,19 @@ union bpf_iter_link_info { 
 *

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

 *

 *	* After **fork**\ (2), the child inherits file descriptors

 *	  referring to the same eBPF objects.

 *	* File descriptors referring to eBPF objects can be transferred over

 *	  **unix**\ (7) domain sockets.

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

 *	  usual way, using **dup**\ (2) and similar calls.

 *	* File descriptors referring to eBPF objects can be pinned to the

 *	  filesystem using the **BPF_OBJ_PIN** command of **bpf**\ (2).

 *

 *	An eBPF object is deallocated only after all file descriptors referring

 *	to the object have been closed and no references remain pinned to the

 *	filesystem or attached (for example, bound to a program or device).

 */

enum bpf_cmd {

	BPF_MAP_CREATE,