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: 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-2-joe@cilium.io
Co-authored-by: Alexei Starovoitov <ast@kernel.org>
Co-authored-by: Michael Kerrisk <mtk.manpages@gmail.com>

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