bpf: Document BPF_PROG_PIN syscall command

Commit b2197755b263 ("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 6d8cb045cde6
("bpf: comment why dots in filenames under BPF virtual FS are not allowed")

Signed-off-by: Joe Stringer <joe@cilium.io>
Signed-off-by: Alexei Starovoitov <ast@kernel.org>
Reviewed-by: Quentin Monnet <quentin@isovalent.com>
Acked-by: Toke Høiland-Jørgensen <toke@redhat.com>
Acked-by: Yonghong Song <yhs@fb.com>
Link: https://lore.kernel.org/bpf/20210302171947.2268128-5-joe@cilium.io

diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index eb9f059f0569fe45d49695c2de0bae778947af0d..6946dde90c5672e0099a162c2d98f51398cd493f 100644 (file)
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -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,