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

[Yonghong Song <yhs@fb.com>]

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