Re: [PATCHv2 bpf-next 01/15] bpf: Import syscall arg documentation

[Yonghong Song <yhs@fb.com>]

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,
>