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

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

Hi Daniel,

On 07/22/2015 05:12 PM, Daniel Borkmann wrote:
> On 07/22/2015 04:49 PM, Michael Kerrisk (man-pages) wrote:
>> Hi Daniel,
>>
>> Sorry for the long delay in following up....
> 
> No worries, eBPF is quite some material. ;)
> 
>> On 05/27/2015 11:26 AM, Daniel Borkmann wrote:
>>> On 05/27/2015 10:43 AM, Michael Kerrisk (man-pages) wrote:
>>>> Hello Alexei,
>>>>
>>>> I took the draft 3 of the bpf(2) man page that you sent back in March
>>>> and did some substantial editing to clarify the language and add a
>>>> few technical details. Could you please check the revised  version
>>>> below, to ensure I did not inject any errors.
>>>>
>>>> I also added a number of FIXMEs for pieces of the page that need
>>>> further work. Could you take a look at these and let me know your
>>>> thoughts, please.
>>>
>>> That's great, thanks! Minor comments:
>>>
>>> ...
>>>> .TH BPF 2 2015-03-10 "Linux" "Linux Programmer's Manual"
>>>> .SH NAME
>>>> bpf - perform a command on an extended BPF map or program
>>>> .SH SYNOPSIS
>>>> .nf
>>>> .B #include <linux/bpf.h>
>>>> .sp
>>>> .BI "int bpf(int cmd, union bpf_attr *attr, unsigned int size);
>>>>
>>>> .SH DESCRIPTION
>>>> The
>>>> .BR bpf ()
>>>> system call performs a range of operations related to extended
>>>> Berkeley Packet Filters.
>>>> Extended BPF (or eBPF) is similar to
>>>> the original BPF (or classic BPF) used to filter network packets.
>>>> For both BPF and eBPF programs,
>>>> the kernel statically analyzes the programs before loading them,
>>>> in order to ensure that they cannot harm the running system.
>>>> .P
>>>> eBPF extends classic BPF in multiple ways including the ability to call
>>>> in-kernel helper functions (via the
>>>> .B BPF_CALL
>>>> opcode extension provided by eBPF)
>>>> and access shared data structures such as BPF maps.
>>>
>>> I would perhaps emphasize that maps can be shared among in-kernel
>>> eBPF programs, but also between kernel and user space.
>>
>> This is covered later in the page, under the "BPF maps" subheading.
>> Maybe you missed that? (Or did you think it doesn't suffice?)
> 
> Okay, I presume you mean:
> 
>    Maps are a generic data structure for storage of different types
>    and sharing data between the kernel and user-space programs.
> 
> Maybe, to emphasize both options a bit (not sure if it's better in
> my words, though):
> 
>    Maps are a generic data structure for storage of different types
>    and allow for sharing data among eBPF kernel programs, but also
>    between kernel and user-space applications.

Yes, that's better. I tweaked that a little and included it in the page.
Thanks.

>>>> The programs can be written in a restricted C that is compiled into
>>>> .\" FIXME In the next line, what is "a restricted C"? Where does
>>>> .\"       one get further information about it?
>>>
>>> So far only from the kernel samples directory and for tc classifier
>>> and action, from the tc man page and/or examples/bpf/ in the tc git
>>> tree.
>>
>> So, given that we are several weeks down the track, and things may have
>> changed, I'll re-ask the questions ;-) :
>>
>> * Is this restricted C documented anywhere?
> 
> Not (yet) that I'm aware of. We were thinking that short-mid term
> to polish the stuff that resides in the kernel documentation, that
> is, Documentation/networking/filter.txt, to get it in a better
> shape, which I presume, would also include a documentation on the
> restricted C. So far, examples are provided in the tc-bpf man page
> (see link below).
> 
> The set of available helper functions callable from eBPF resides
> under (enum bpf_func_id):
>    https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/bpf.h
> 

Yep, I did eventually find that on my own.

[...]

>>>> BPF maps are a generic data structure for storage of different data types.
>>>> A user process can create multiple maps (with key/value-pairs being
>>>> opaque bytes of data) and access them via file descriptors.
>>>> BPF programs can access maps from inside the kernel in parallel.
>>>> It's up to the user process and BPF program to decide what they store
>>>> inside maps.
>>>> .P
>>>> BPF programs are similar to kernel modules.
>>>> They are loaded by the user
>>>> process and automatically unloaded when the process exits.
>>>
>>> Generally that's true. Btw, in 4.1 kernel, tc(8) also got support for
>>> eBPF classifier and actions, and here it's slightly different: in tc,
>>> we load the programs, maps etc, and push down the eBPF program fd in
>>> order to let the kernel hold reference on the program itself.
>>>
>>> Thus, there, the program fd that the application owns is gone when the
>>> application terminates, but the eBPF program itself still lives on
>>> inside the kernel. But perhaps it's already too much detail to mention
>>> here ...
>>
>> Well, it should be documented somewhere....
> 
> Yep, fwiw some time ago I've hacked together a man page for tc:
> 
> https://git.kernel.org/cgit/linux/kernel/git/shemminger/iproute2.git/commit/?id=cbdd1e6921d21815e35d2a96526cfbad5ac98e09

I added a reference to that page (tc-bpff(8) under SEE ALSO.

[...]

>> I'll send out a new draft soon, but in the meantime hopefully you
>> or Alexei might have a chance to answer some open questions (see my
>> other mail to Alexei, which will be sent soon), so I can further edit
>> the page before sending it out.
> 
> Later on, we should also add a paragraph on eBPF tail calls, but one
> step at a time.

Yep, I have a FIXME for that.

Cheers,

Michael



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