Re: Edited draft of bpf(2) man page for review/enhancement

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

On 07/22/2015 07:43 PM, Alexei Starovoitov wrote:
> On 7/22/15 7:52 AM, Michael Kerrisk (man-pages) wrote:
>>> As Daniel said there is no spec for this C. It's a normal C where
>>> things like loops, global variables, vararg, floating point,
>>> struct passing and bunch of other things are not supported.
>>
>> I assume we're talking about the LLVM front-end, right?
> 
> yes. clang.
> There is a bpf backend for gcc, but it's bit rotting now.

Okay.

>> Am I correct that these kernel source files are examples of this restricted C:
>>
>> samples/bpf/tcbpf1_kern.c
>> samples/bpf/tracex2_kern.c
>> samples/bpf/tracex4_kern.c
>> samples/bpf/tracex1_kern.c
>> samples/bpf/tracex3_kern.c
>> samples/bpf/sockex1_kern.c
>> samples/bpf/sockex2_kern.c
> 
> yes.

Thanks.

>> And samples/bpf/Makefile shows the necessary LLVM incantation
>> to produce the BPF binaries, right?
> 
> yes.
> Now with llvm 3.7 coming out soon it's even simpler. Just:
> clang -O2 -target bpf -c file.c

Okay.

>> Anyway, I added the following text in NOTES:
>>
>>         eBPF objects (maps and programs) can  be  shared  between  pro‐
>>         cesses.   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.
>>
>> Is the above all correct?
> 
> yes. all correct.

Thanks.

>> This makes me curious: why was the BPF functionality not designed as
>> a *set* of system calls (as per these wrappers), rather than the existing
>> multiplexed call?
> 
> because new commands are much easier to add to existing syscall
> instead of adding new syscall for every new command.
> 
>> [[
>> If
>> .I key
>> is found, the operation returns zero and sets the
>> .I next_key
>> pointer to the key of the next element.
>> ]]
>>
>> right?
> 
> yes.

Thanks.

>>>>           BPF_MOV64_IMM(BPF_REG_1, 1),                /* r1 = 1 */
>>>>           BPF_XADD(BPF_DW, BPF_REG_0, BPF_REG_1, 0, 0),
>>>> .\" FIXME What does 'lock' in the line below mean?
>>>>                                   /* lock *(u64 *) r0 += r1 */
>>>
>>> it means that it's 'lock xadd' equivalent.
>>
>> Sorry -- you've assumed I'm cleverer than I am... :-}
>> I'm not wiser after that comment. What is 'lock xadd'?
> 
> I meant that it is == atomic64_add

Okay.

>> If you might have a chance to look at my questions above and
>> let me know your thoughts, then I could further edit the page
>> before sending out the next draft.
> 
> I think would be great to get some form of the man page out and
> work on it incrementally. Quite a few folks have asked for it.

I think another pass would be best done first. I'll try to be quicker.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/