| Message ID | 20210302171947.2268128-2-joe@cilium.io (mailing list archive) |
|---|---|
| State | Accepted |
| Delegated to: | BPF |
| Headers | show |
| Series | Improve BPF syscall command documentation | expand |
| Context | Check | Description |
|---|---|---|
| netdev/cover_letter | success | Link |
| netdev/fixes_present | success | Link |
| netdev/patch_count | success | Link |
| netdev/tree_selection | success | Clearly marked for bpf-next |
| netdev/subject_prefix | success | Link |
| netdev/cc_maintainers | warning | 7 maintainers not CCed: yhs@fb.com netdev@vger.kernel.org john.fastabend@gmail.com kpsingh@kernel.org songliubraving@fb.com kafai@fb.com andrii@kernel.org |
| netdev/source_inline | success | Was 0 now: 0 |
| netdev/verify_signedoff | success | Link |
| netdev/module_param | success | Was 0 now: 0 |
| netdev/build_32bit | success | Errors and warnings before: 11835 this patch: 11835 |
| netdev/kdoc | success | Errors and warnings before: 0 this patch: 0 |
| netdev/verify_fixes | success | Link |
| netdev/checkpatch | warning | WARNING: Non-standard signature: Co-authored-by: |
| netdev/build_allmodconfig_warn | success | Errors and warnings before: 12482 this patch: 12482 |
| netdev/header_inline | success | Link |
| netdev/stable | success | Stable not CCed |
On 3/2/21 9:19 AM, Joe Stringer wrote: > 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. > > Acked-by: Toke Høiland-Jørgensen <toke@redhat.com> > Reviewed-by: Quentin Monnet <quentin@isovalent.com> > Co-authored-by: Alexei Starovoitov <ast@kernel.org> > Co-authored-by: Michael Kerrisk <mtk.manpages@gmail.com> > Signed-off-by: Joe Stringer <joe@cilium.io> Ack with one nit below. Acked-by: Yonghong Song <yhs@fb.com> > --- > include/uapi/linux/bpf.h | 122 ++++++++++++++++++++++++++++++++++++++- > 1 file changed, 121 insertions(+), 1 deletion(-) > > diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h > index b89af20cfa19..fb16c590e6d9 100644 > --- 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_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. if the object is pinned, the object will be live if the pinned file is not removed. The file description can refer to a link file descriptor or an iterator file descriptor which will (indirectly) hold a reference count to the program as well. It will be good we can clarify a little more in Patch #2 at NOTES section after other bpf syscall commands are introduced. > + */ > enum bpf_cmd { > BPF_MAP_CREATE, > BPF_MAP_LOOKUP_ELEM, >
On 3/3/21 11:38 AM, Yonghong Song wrote: > > > On 3/2/21 9:19 AM, Joe Stringer wrote: >> 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. >> >> Acked-by: Toke Høiland-Jørgensen <toke@redhat.com> >> Reviewed-by: Quentin Monnet <quentin@isovalent.com> >> Co-authored-by: Alexei Starovoitov <ast@kernel.org> >> Co-authored-by: Michael Kerrisk <mtk.manpages@gmail.com> >> Signed-off-by: Joe Stringer <joe@cilium.io> > > Ack with one nit below. > > Acked-by: Yonghong Song <yhs@fb.com> > >> --- >> include/uapi/linux/bpf.h | 122 ++++++++++++++++++++++++++++++++++++++- >> 1 file changed, 121 insertions(+), 1 deletion(-) >> >> diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h >> index b89af20cfa19..fb16c590e6d9 100644 >> --- 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_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. > > if the object is pinned, the object will be live if the pinned file is > not removed. The file description can refer to a link file descriptor or > an iterator file descriptor which will (indirectly) hold a reference > count to the program as well. It will be good we can clarify a little > more in Patch #2 at NOTES section after other bpf syscall commands are > introduced. Sorry. Looks like NOTES are properly updated in patch #4. So you can ignore this comment. > >> + */ >> enum bpf_cmd { >> BPF_MAP_CREATE, >> BPF_MAP_LOOKUP_ELEM, >>
diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h index b89af20cfa19..fb16c590e6d9 100644 --- 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,