Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1575774 > unrolled thread

[net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet Filter

Back to article view | Back to linux.kernel

Contents

  [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet  Filter Jesper Dangaard Brouer <brouer@redhat.com> - 2017-02-07 15:40 +0100
    [net-next PATCH 1/4] doc/bpf: start eBPF documentation tree bpf/ Jesper Dangaard Brouer <brouer@redhat.com> - 2017-02-07 15:40 +0100
    Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley  Packet Filter Jonathan Corbet <corbet@lwn.net> - 2017-02-07 16:40 +0100
      Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley  Packet Filter Jesper Dangaard Brouer <brouer@redhat.com> - 2017-02-07 17:20 +0100
        Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley  Packet Filter Jonathan Corbet <corbet@lwn.net> - 2017-02-07 17:50 +0100
          Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley  Packet Filter Jesper Dangaard Brouer <brouer@redhat.com> - 2017-02-07 22:00 +0100
            Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley  Packet Filter Jonathan Corbet <corbet@lwn.net> - 2017-02-07 22:40 +0100
              Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley  Packet Filter Jesper Dangaard Brouer <brouer@redhat.com> - 2017-02-08 11:40 +0100
    Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet  Filter Daniel Borkmann <daniel@iogearbox.net> - 2017-02-07 17:50 +0100
      Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley  Packet Filter Jesper Dangaard Brouer <brouer@redhat.com> - 2017-02-07 22:30 +0100
        Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet  Filter Daniel Borkmann <daniel@iogearbox.net> - 2017-02-07 23:40 +0100

#1575774 — [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet Filter

Question: What kernel tree should this go into???

If going through Jonathan Corbet, will it appear sooner here???
 https://www.kernel.org/doc/html/latest/
If it will not appear sooner that way, then it's likely best to keep
it in sync with the tree that takes eBPF code changes.


This marks the beginning of user-facing developer documentation for
using eBPF (extended Berkeley Packet Filter) as part of the kernel
Documentation/ tree.

This documentation is also available here[1], as an intermidiate quick
way of prototyping and releasing the documentation.  The autoriative
and official version of the documentation is what gets included in the
kernel tree.  The docs at [2] will get updated based on what gets
accepted after the standard peer-review kernel process.

[1] http://prototype-kernel.readthedocs.io/en/latest/bpf/index.html
[2] https://github.com/netoptimizer/prototype-kernel/tree/master/kernel/Documentation

Thanks to the following people, who have already reviewed and fixed
earlier versions of this documentation on the IOvisor mailing-list:

 Alexander Alemayhu <alexander@alemayhu.com>
 Alexei Starovoitov <ast@fb.com>
 Daniel Borkmann <daniel@iogearbox.net>
 Quentin Monnet <quentin.monnet@6wind.com>


---

Jesper Dangaard Brouer (4):
      doc/bpf: start eBPF documentation tree bpf/
      doc/bpf: document interacting with eBPF maps
      doc/bpf: describes the different types of eBPF maps available
      doc/bpf: describe BCC the BPF Compiler Collection


 Documentation/bpf/bcc_tool_chain.rst  |   37 +++++
 Documentation/bpf/ebpf_maps.rst       |  256 +++++++++++++++++++++++++++++++++
 Documentation/bpf/ebpf_maps_types.rst |  119 +++++++++++++++
 Documentation/bpf/index.rst           |   68 +++++++++
 Documentation/index.rst               |    1 
 5 files changed, 481 insertions(+)
 create mode 100644 Documentation/bpf/bcc_tool_chain.rst
 create mode 100644 Documentation/bpf/ebpf_maps.rst
 create mode 100644 Documentation/bpf/ebpf_maps_types.rst
 create mode 100644 Documentation/bpf/index.rst

--

[toc] | [next] | [standalone]

#1575775 — [net-next PATCH 1/4] doc/bpf: start eBPF documentation tree bpf/

The learning curve for eBPF programs is hard.  The purpose of this
documentation (subtree) is to make it easier for developers to get
started using and writing eBPF programs.

Including bpf/index under section User-oriented documentation.

Thanks to Quentin Monnet <quentin.monnet@6wind.com> for improving
this document with areas eBFP is used in and early review.

Signed-off-by: Jesper Dangaard Brouer <brouer@redhat.com>
---
 Documentation/bpf/index.rst |   66 +++++++++++++++++++++++++++++++++++++++++++
 Documentation/index.rst     |    1 +
 2 files changed, 67 insertions(+)
 create mode 100644 Documentation/bpf/index.rst

diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst
new file mode 100644
index 000000000000..f262fe8f9f95
--- /dev/null
+++ b/Documentation/bpf/index.rst
@@ -0,0 +1,66 @@
+======================================
+eBPF - extended Berkeley Packet Filter
+======================================
+
+Introduction
+============
+
+The Berkeley Packet Filter (BPF) started (`article 1992`_) as a
+special-purpose virtual machine (register based filter evaluator) for
+filtering network packets, best known for its use in tcpdump. It is
+documented in the kernel tree, in the first part of:
+`Documentation/networking/filter.txt`_
+
+The extended BPF (eBPF) variant has become a universal in-kernel
+virtual machine, that has hooks all over the kernel.  The eBPF
+instruction set is quite different, see description in section "BPF
+kernel internals" of `Documentation/networking/filter.txt`_ or look at
+this `presentation by Alexei`_.
+
+Areas using eBPF:
+ * XDP - eXpress Data Path
+ * `Traffic control`_
+ * Sockets
+ * Firewalling (``xt_bpf`` module)
+ * Tracing
+ * Tracepoints
+ * kprobe (dynamic tracing of a kernel function call)
+ * cgroups
+
+Documentation
+=============
+
+The primary user documentation for extended BPF is in the man-page for
+the `bpf(2)`_ syscall.
+
+This documentation is focused on the kernel tree's `samples/bpf/`_ and
+`tools/lib/bpf/`_.  It is worth mentioning that other projects exist,
+like BCC_, that has a slightly different user-facing
+syntax, but is interfacing with the same kernel facilities as those
+covered by this documentation.
+
+.. toctree::
+   :maxdepth: 1
+
+.. links:
+
+.. _article 1992: http://www.tcpdump.org/papers/bpf-usenix93.pdf
+
+.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html
+
+.. _Documentation/networking/filter.txt:
+   https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/networking/filter.txt
+
+.. _presentation by Alexei:
+   http://www.slideshare.net/AlexeiStarovoitov/bpf-inkernel-virtual-machine
+
+.. _samples/bpf/:
+   https://github.com/torvalds/linux/blob/master/samples/bpf/
+
+.. _tools/lib/bpf/:
+   https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/tools/lib/bpf/
+
+.. _Traffic control: http://man7.org/linux/man-pages/man8/tc-bpf.8.html
+
+.. _BCC: https://github.com/iovisor/bcc
+
diff --git a/Documentation/index.rst b/Documentation/index.rst
index cb5d77699c60..dacf202febb8 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -23,6 +23,7 @@ trying to get it to work optimally on a given system.
    :maxdepth: 2
 
    admin-guide/index
+   bpf/index
 
 Introduction to kernel development
 ----------------------------------

[toc] | [prev] | [next] | [standalone]

#1575804 — Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet Filter

On Tue, 07 Feb 2017 15:30:11 +0100
Jesper Dangaard Brouer <brouer@redhat.com> wrote:

> Question: What kernel tree should this go into???
> 
> If going through Jonathan Corbet, will it appear sooner here???
>  https://www.kernel.org/doc/html/latest/
> If it will not appear sooner that way, then it's likely best to keep
> it in sync with the tree that takes eBPF code changes.

I've developed a fairly strong preference for carrying patches touching
index.rst; otherwise I spend a lot of time explaining merge conflicts to
Linus.

If the consensus is that this is ready to go, I expect I can squeeze it in
for 4.11.  I'm not too worried about regressions...:)

I haven't actually built it yet, but from a first look it seems like an
awfully good start.  The one thing that comes to mind is that I'm likely
to want to move it at some point.  I'd really like to start a separate
book for user-space developer documentation, and this would certainly
belong there.  That book doesn't exist yet, though, so I can't quite blame
you, hard as I might try, for not putting this document there.

Thanks,

jon

[toc] | [prev] | [next] | [standalone]

#1575833 — Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet Filter

On Tue, 7 Feb 2017 08:37:17 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> On Tue, 07 Feb 2017 15:30:11 +0100
> Jesper Dangaard Brouer <brouer@redhat.com> wrote:
> 
> > Question: What kernel tree should this go into???
> > 
> > If going through Jonathan Corbet, will it appear sooner here???
> >  https://www.kernel.org/doc/html/latest/

What about this question?  Or let me ask in another way, what tree is
https://www.kernel.org/doc/html/latest/ based on?


> > If it will not appear sooner that way, then it's likely best to keep
> > it in sync with the tree that takes eBPF code changes.  
> 
> I've developed a fairly strong preference for carrying patches touching
> index.rst; otherwise I spend a lot of time explaining merge conflicts to
> Linus.
> 
> If the consensus is that this is ready to go, I expect I can squeeze it in
> for 4.11.  I'm not too worried about regressions...:)
> 
> I haven't actually built it yet, but from a first look it seems like an
> awfully good start.  The one thing that comes to mind is that I'm likely
> to want to move it at some point.  I'd really like to start a separate
> book for user-space developer documentation, and this would certainly
> belong there.  That book doesn't exist yet, though, so I can't quite blame
> you, hard as I might try, for not putting this document there.

Yes, I was also wondering hard where to put it... and a book for
user-space developer documentation would likely be the right place, but
it was not there, as you mention ;-) 

I'm fine with moving it later under another "book". Linking to it as
HTML would still be the same right? (https://www.kernel.org/doc/html/latest/bpf/index.html)
And is the Documentation/bpf/ directory the correct place?

-- 
Best regards,
  Jesper Dangaard Brouer
  MSc.CS, Principal Kernel Engineer at Red Hat
  LinkedIn: http://www.linkedin.com/in/brouer

[toc] | [prev] | [next] | [standalone]

#1575879 — Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet Filter

On Tue, 7 Feb 2017 17:09:08 +0100
Jesper Dangaard Brouer <brouer@redhat.com> wrote:

> > > Question: What kernel tree should this go into???
> > > 
> > > If going through Jonathan Corbet, will it appear sooner here???
> > >  https://www.kernel.org/doc/html/latest/  
> 
> What about this question?  Or let me ask in another way, what tree is
> https://www.kernel.org/doc/html/latest/ based on?

I believe it's generated from the current -rc.  If this stuff goes into
4.11, it should show up there next week.

> Yes, I was also wondering hard where to put it... and a book for
> user-space developer documentation would likely be the right place, but
> it was not there, as you mention ;-) 
> 
> I'm fine with moving it later under another "book". Linking to it as
> HTML would still be the same right? (https://www.kernel.org/doc/html/latest/bpf/index.html)
> And is the Documentation/bpf/ directory the correct place?

Moving it would change the URL, of course.  If we want to avoid that, we
should try to come up with the proper placement from the outset.  And we
would want to move it; I really want to clean up the mess that is the
top-level directory.

How about if it goes into Documentation/userspace-guide/bpf ?  The
intermediate directory could just be empty for now, I'll put the book
structure into place later on.  Then the URL for the BPF guide itself
wouldn't change.

jon

[toc] | [prev] | [next] | [standalone]

#1576056 — Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet Filter

On Tue, 7 Feb 2017 09:46:08 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> On Tue, 7 Feb 2017 17:09:08 +0100
> Jesper Dangaard Brouer <brouer@redhat.com> wrote:
> 
> > > > Question: What kernel tree should this go into???
> > > > 
> > > > If going through Jonathan Corbet, will it appear sooner here???
> > > >  https://www.kernel.org/doc/html/latest/    
> > 
> > What about this question?  Or let me ask in another way, what tree is
> > https://www.kernel.org/doc/html/latest/ based on?  
> 
> I believe it's generated from the current -rc.  If this stuff goes into
> 4.11, it should show up there next week.
> 
> > Yes, I was also wondering hard where to put it... and a book for
> > user-space developer documentation would likely be the right place, but
> > it was not there, as you mention ;-) 
> > 
> > I'm fine with moving it later under another "book". Linking to it as
> > HTML would still be the same right? (https://www.kernel.org/doc/html/latest/bpf/index.html)
> > And is the Documentation/bpf/ directory the correct place?  
> 
> Moving it would change the URL, of course.  If we want to avoid that, we
> should try to come up with the proper placement from the outset.  And we
> would want to move it; I really want to clean up the mess that is the
> top-level directory.
> 
> How about if it goes into Documentation/userspace-guide/bpf ?  The
> intermediate directory could just be empty for now, I'll put the book
> structure into place later on.  Then the URL for the BPF guide itself
> wouldn't change.

I sounds like Daniel (see other email) have bigger plans for what
Documentation/BPF/ should contain.  E.g. consolidating
Documentation/networking/filter.txt which covers the cBPF/eBPF internals.
If that is the case (and I like the idea), then it goes beyond a
"userspace-guide".  And perhaps "BPF" is a "book" of its own?

And it seems Daniel is proposing capital-letters BPF for the directory
name "Documentation/BPF/"?  Any opinions on that? (I'm neutral)

-- 
Best regards,
  Jesper Dangaard Brouer
  MSc.CS, Principal Kernel Engineer at Red Hat
  LinkedIn: http://www.linkedin.com/in/brouer

[toc] | [prev] | [next] | [standalone]

#1576076 — Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet Filter

On Tue, 7 Feb 2017 21:51:49 +0100
Jesper Dangaard Brouer <brouer@redhat.com> wrote:

> I sounds like Daniel (see other email) have bigger plans for what
> Documentation/BPF/ should contain.  E.g. consolidating
> Documentation/networking/filter.txt which covers the cBPF/eBPF internals.
> If that is the case (and I like the idea), then it goes beyond a
> "userspace-guide".  And perhaps "BPF" is a "book" of its own?

One of the real problems with the kernel's documentation is that there is
really almost no thought given to who the audience is.  We have docs for
kernel developers, for system admins, for user-space developers, etc., and
it's all mixed up into one big jumble.

An objective of mine in launching into this whole project is to try to fix
that, so that people can readily find the documentation they need.  So I
don't think a single top-level directory, with a mix of user-space API
info and "internals", is the right direction to go.  The internals docs
should, IMO, go elsewhere, probably in the core-api manual.

See what I'm getting at here?

> And it seems Daniel is proposing capital-letters BPF for the directory
> name "Documentation/BPF/"?  Any opinions on that? (I'm neutral)

I think we should paint it green; otherwise I'm not too concerned about
this particular point...:)

Thanks,

jon

[toc] | [prev] | [next] | [standalone]

#1576422 — Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet Filter

On Tue, 7 Feb 2017 14:23:23 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> On Tue, 7 Feb 2017 21:51:49 +0100
> Jesper Dangaard Brouer <brouer@redhat.com> wrote:
> 
> > I sounds like Daniel (see other email) have bigger plans for what
> > Documentation/BPF/ should contain.  E.g. consolidating
> > Documentation/networking/filter.txt which covers the cBPF/eBPF internals.
> > If that is the case (and I like the idea), then it goes beyond a
> > "userspace-guide".  And perhaps "BPF" is a "book" of its own?  
> 
> One of the real problems with the kernel's documentation is that there is
> really almost no thought given to who the audience is.  We have docs for
> kernel developers, for system admins, for user-space developers, etc., and
> it's all mixed up into one big jumble.
> 
> An objective of mine in launching into this whole project is to try to fix
> that, so that people can readily find the documentation they need.  So I
> don't think a single top-level directory, with a mix of user-space API
> info and "internals", is the right direction to go.  The internals docs
> should, IMO, go elsewhere, probably in the core-api manual.
> 
> See what I'm getting at here?

First I was reluctant (as it would be "easier" just to cramp every eBPF
thing into one directory).  Thinking more about, I agree with you, and
I like your vision.  Focus on the target audience and avoid mixing
different target audience in the same document/book is the way forward.

My audience and objective is helping developers getting started using
eBPF, not core-developers on eBPF (like Daniel).  I do see that, if we
start mixing in too much "internals" then we loose sense of the
original target audience, and then they "exit" as they get "lost" in
details that does not concern them.

Separating BPF docs into different directories (or "books") will make
us think about the target audience.

I would like to propose directory structure:

 Documentation/user-guide/bpf/
 Documentation/core-api/bpf/


> > And it seems Daniel is proposing capital-letters BPF for the directory
> > name "Documentation/BPF/"?  Any opinions on that? (I'm neutral)  
> 
> I think we should paint it green; otherwise I'm not too concerned about
> this particular point...:)

True, bikeshedding...

-- 
Best regards,
  Jesper Dangaard Brouer
  MSc.CS, Principal Kernel Engineer at Red Hat
  LinkedIn: http://www.linkedin.com/in/brouer

[toc] | [prev] | [next] | [standalone]

#1575874

Hi Jesper,

On 02/07/2017 03:30 PM, Jesper Dangaard Brouer wrote:
> Question: What kernel tree should this go into???
>
> If going through Jonathan Corbet, will it appear sooner here???
>   https://www.kernel.org/doc/html/latest/
> If it will not appear sooner that way, then it's likely best to keep
> it in sync with the tree that takes eBPF code changes.

For initial parts, I don't have a preference (Jonathan has though,
so seems fine via docs tree then). If at some /later/ point in time
features come in along with doc updates (similar to test case updates),
probably best to route them via net-next.

> This marks the beginning of user-facing developer documentation for
> using eBPF (extended Berkeley Packet Filter) as part of the kernel
> Documentation/ tree.
>
> This documentation is also available here[1], as an intermidiate quick
> way of prototyping and releasing the documentation.  The autoriative
> and official version of the documentation is what gets included in the
> kernel tree.  The docs at [2] will get updated based on what gets
> accepted after the standard peer-review kernel process.

Thanks for your effort of writing a doc. Some high-level comments on
the set from my PoV first.

I think it's definitely the right direction to move everything BPF
related to Documentation/BPF/. Right now, there are a lot of different
places with different kind of documentation, f.e.:

* Documentation/networking/filter.txt
   Covers some cBPF/eBPF internals, tooling, etc; mostly technical,
   historically the central spot for BPF documentation. "filter" in
   filter.txt is long obsolete name, but looks like various sites,
   talks, blogs, etc still link to it. (At best, we should keep the
   file saying that the doc moved to Documentation/BPF/.)

* bpf(2) man page
   Has a good start, but right now is heavily behind the current user
   facing kernel code.

* include/uapi/linux/bpf.h
   Mostly relevant for helper function API description.

* netdev conference slides/proceedings
   Also contain mostly technical details on eBPF.

* https://github.com/iovisor/bpf-docs
   Non-exhaustive collection of various talks from different confs.

* https://qmonnet.github.io/whirl-offload/2016/09/01/dive-into-bpf/
   Even bigger and more complete list of documentation material.

* Various lwn articles ;), blog posts (f.e. from Brendan), etc.

Now, challenge is to bring the relevant parts together and logically
separated into Documentation/BPF/ and bpf(2) man page. I think everything
user API relevant would help most if it updates bpf(2) man page. That can
be explanation of different map types, interaction with maps, quirks, etc.

Eventually also helper functions. Right now they're all documented in
include/uapi/linux/bpf.h and that's okay as it ships along with the
kernel code, so they're in sync. Eventually, there should be some more
elaborate description of them, perhaps with tiny examples, in bpf(2)
as well, since it's part of the uapi and stable (helpers themselves at
least).

The Documentation/networking/filter.txt would need to be reworked a
bit and split into pieces for Documentation/BPF/, so we keep that as a
central place for the technical parts. Documentation/RCU/ is doing a
great job at that, and I would like to see Documentation/BPF/ being as
helpful for developers here. Part of that would be to add missing pieces
from the various available sources mentioned above or elsewhere, so
people can get a deeper understanding on internals beyond reading just
man page for the user API description; explaining concepts, etc. Part
of that can also be on the ELF loader bits, etc, no doubt.

On a quick glance on the remaining patches, it seems a mixture of quotes
from the bpf(2) man page, filter.txt along with sample code explanation and
lots of external links, part of them to https://git.kernel.org/cgit/linux/...,
http://lxr.free-electrons.com, http://man7.org, http://www.slideshare.net/,
https://github.com/torvalds/linux/..., etc. I would suggest that instead we
should make Documentation/BPF/ eventually as self-contained as possible
and the central place for the internals where others link to instead. It
might take a bit, but I think definitely worth it.

Regarding patches, could you split the parts that should go to bpf(2) off
and submit them to man page tree for inclusion? I think that would be
incredibly helpful. And the remaining internals to start a Documentation/BPF/
directory, even if initially just small (but will grow over time of
course)?

Thanks,
Daniel

> [1] http://prototype-kernel.readthedocs.io/en/latest/bpf/index.html
> [2] https://github.com/netoptimizer/prototype-kernel/tree/master/kernel/Documentation
>
> Thanks to the following people, who have already reviewed and fixed
> earlier versions of this documentation on the IOvisor mailing-list:
>
>   Alexander Alemayhu <alexander@alemayhu.com>
>   Alexei Starovoitov <ast@fb.com>
>   Daniel Borkmann <daniel@iogearbox.net>
>   Quentin Monnet <quentin.monnet@6wind.com>
>
>
> ---
>
> Jesper Dangaard Brouer (4):
>        doc/bpf: start eBPF documentation tree bpf/
>        doc/bpf: document interacting with eBPF maps
>        doc/bpf: describes the different types of eBPF maps available
>        doc/bpf: describe BCC the BPF Compiler Collection
>
>
>   Documentation/bpf/bcc_tool_chain.rst  |   37 +++++
>   Documentation/bpf/ebpf_maps.rst       |  256 +++++++++++++++++++++++++++++++++
>   Documentation/bpf/ebpf_maps_types.rst |  119 +++++++++++++++
>   Documentation/bpf/index.rst           |   68 +++++++++
>   Documentation/index.rst               |    1
>   5 files changed, 481 insertions(+)
>   create mode 100644 Documentation/bpf/bcc_tool_chain.rst
>   create mode 100644 Documentation/bpf/ebpf_maps.rst
>   create mode 100644 Documentation/bpf/ebpf_maps_types.rst
>   create mode 100644 Documentation/bpf/index.rst
>
> --
>

[toc] | [prev] | [next] | [standalone]

#1576074 — Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley Packet Filter

On Tue, 07 Feb 2017 17:43:38 +0100
Daniel Borkmann <daniel@iogearbox.net> wrote:

> Hi Jesper,
> 
> On 02/07/2017 03:30 PM, Jesper Dangaard Brouer wrote:
> > Question: What kernel tree should this go into???
> >
> > If going through Jonathan Corbet, will it appear sooner here???
> >   https://www.kernel.org/doc/html/latest/
> > If it will not appear sooner that way, then it's likely best to keep
> > it in sync with the tree that takes eBPF code changes.  
> 
> For initial parts, I don't have a preference (Jonathan has though,
> so seems fine via docs tree then). If at some /later/ point in time
> features come in along with doc updates (similar to test case updates),
> probably best to route them via net-next.
> 
> > This marks the beginning of user-facing developer documentation for
> > using eBPF (extended Berkeley Packet Filter) as part of the kernel
> > Documentation/ tree.
> >
> > This documentation is also available here[1], as an intermidiate quick
> > way of prototyping and releasing the documentation.  The autoriative
> > and official version of the documentation is what gets included in the
> > kernel tree.  The docs at [2] will get updated based on what gets
> > accepted after the standard peer-review kernel process.  
> 
> Thanks for your effort of writing a doc. Some high-level comments on
> the set from my PoV first.
> 
> I think it's definitely the right direction to move everything BPF
> related to Documentation/BPF/. Right now, there are a lot of different
> places with different kind of documentation, f.e.:

Agree that we need some in-kernel place to centralize bpf related
documentation, as it is too scattered at the moment.

> * Documentation/networking/filter.txt
>    Covers some cBPF/eBPF internals, tooling, etc; mostly technical,
>    historically the central spot for BPF documentation. "filter" in
>    filter.txt is long obsolete name, but looks like various sites,
>    talks, blogs, etc still link to it. (At best, we should keep the
>    file saying that the doc moved to Documentation/BPF/.)

Agree.
 
> * bpf(2) man page
>    Has a good start, but right now is heavily behind the current user
>    facing kernel code.

Yes, the man-page have proven to get out-of-sync.  This is one of the
reasons I prefer this in-kernel-tree documentation, as documentation
can follow the patchset submission, instead of being something
developers need to submit _after_ patches are accepted.

 
> * include/uapi/linux/bpf.h
>    Mostly relevant for helper function API description.
> 
> * netdev conference slides/proceedings
>    Also contain mostly technical details on eBPF.
> 
> * https://github.com/iovisor/bpf-docs
>    Non-exhaustive collection of various talks from different confs.
> 
> * https://qmonnet.github.io/whirl-offload/2016/09/01/dive-into-bpf/
>    Even bigger and more complete list of documentation material.
> 
> * Various lwn articles ;), blog posts (f.e. from Brendan), etc.
> 
> Now, challenge is to bring the relevant parts together and logically
> separated into Documentation/BPF/ and bpf(2) man page. I think everything
> user API relevant would help most if it updates bpf(2) man page. That can
> be explanation of different map types, interaction with maps, quirks, etc.

Sorry, but I disagree.  The man-page bpf(2) should only describe the
bpf syscall.  Details on map types should be documented in this
documentation.  Why, because this allow us to enforce documentation
of a new map type is included together with the code submission (else
it will never get documented).


> Eventually also helper functions. Right now they're all documented in
> include/uapi/linux/bpf.h and that's okay as it ships along with the
> kernel code, so they're in sync. Eventually, there should be some more
> elaborate description of them, perhaps with tiny examples, in bpf(2)
> as well, since it's part of the uapi and stable (helpers themselves at
> least).

IMHO descriptions for bpf helpers function does not belong in the
man-page for the bpf(2) syscall.  The bpf helpers are something that
gets used by the ebpf program code which runs kernel side.  (And again
the same argument about introducing new will not get updated in the man
page).


> The Documentation/networking/filter.txt would need to be reworked a
> bit and split into pieces for Documentation/BPF/, so we keep that as a
> central place for the technical parts. Documentation/RCU/ is doing a
> great job at that, and I would like to see Documentation/BPF/ being as
> helpful for developers here. Part of that would be to add missing
> pieces from the various available sources mentioned above or
> elsewhere, so people can get a deeper understanding on internals
> beyond reading just man page for the user API description; explaining
> concepts, etc. Part of that can also be on the ELF loader bits, etc,
> no doubt.

Agree
 
> On a quick glance on the remaining patches, it seems a mixture of
> quotes from the bpf(2) man page, filter.txt along with sample code
> explanation and lots of external links, part of them to
> https://git.kernel.org/cgit/linux/..., http://lxr.free-electrons.com,
> http://man7.org, http://www.slideshare.net/,
> https://github.com/torvalds/linux/..., etc. I would suggest that
> instead we should make Documentation/BPF/ eventually as
> self-contained as possible and the central place for the internals
> where others link to instead. It might take a bit, but I think
> definitely worth it.

In time it can be more self-contained, but as of this writing, as you
mention yourself, bpf doc resources are fragmented all over, thus the
obviously doc reflect that with many links.

> Regarding patches, could you split the parts that should go to bpf(2)
> off and submit them to man page tree for inclusion? I think that
> would be incredibly helpful. And the remaining internals to start a
> Documentation/BPF/ directory, even if initially just small (but will
> grow over time of course)?

As noted, I don't believe in populating the man page further is right
direction, sorry, and I've already argued why.


> > [1] http://prototype-kernel.readthedocs.io/en/latest/bpf/index.html
> > [2]
> > https://github.com/netoptimizer/prototype-kernel/tree/master/kernel/Documentation
> >
> > Thanks to the following people, who have already reviewed and fixed
> > earlier versions of this documentation on the IOvisor mailing-list:
> >
> >   Alexander Alemayhu <alexander@alemayhu.com>
> >   Alexei Starovoitov <ast@fb.com>
> >   Daniel Borkmann <daniel@iogearbox.net>
> >   Quentin Monnet <quentin.monnet@6wind.com>
> >
> >
> > ---
> >
> > Jesper Dangaard Brouer (4):
> >        doc/bpf: start eBPF documentation tree bpf/
> >        doc/bpf: document interacting with eBPF maps
> >        doc/bpf: describes the different types of eBPF maps available
> >        doc/bpf: describe BCC the BPF Compiler Collection
> >
> >
> >   Documentation/bpf/bcc_tool_chain.rst  |   37 +++++
> >   Documentation/bpf/ebpf_maps.rst       |  256
> > +++++++++++++++++++++++++++++++++
> > Documentation/bpf/ebpf_maps_types.rst |  119 +++++++++++++++
> > Documentation/bpf/index.rst           |   68 +++++++++
> > Documentation/index.rst               |    1 5 files changed, 481
> > insertions(+) create mode 100644
> > Documentation/bpf/bcc_tool_chain.rst create mode 100644
> > Documentation/bpf/ebpf_maps.rst create mode 100644
> > Documentation/bpf/ebpf_maps_types.rst create mode 100644
> > Documentation/bpf/index.rst
> >

-- 
Best regards,
  Jesper Dangaard Brouer
  MSc.CS, Principal Kernel Engineer at Red Hat
  LinkedIn: http://www.linkedin.com/in/brouer

[toc] | [prev] | [next] | [standalone]

#1576128

On 02/07/2017 10:19 PM, Jesper Dangaard Brouer wrote:
> On Tue, 07 Feb 2017 17:43:38 +0100
> Daniel Borkmann <daniel@iogearbox.net> wrote:
>
>> Hi Jesper,
>>
>> On 02/07/2017 03:30 PM, Jesper Dangaard Brouer wrote:
>>> Question: What kernel tree should this go into???
>>>
>>> If going through Jonathan Corbet, will it appear sooner here???
>>>    https://www.kernel.org/doc/html/latest/
>>> If it will not appear sooner that way, then it's likely best to keep
>>> it in sync with the tree that takes eBPF code changes.
>>
>> For initial parts, I don't have a preference (Jonathan has though,
>> so seems fine via docs tree then). If at some /later/ point in time
>> features come in along with doc updates (similar to test case updates),
>> probably best to route them via net-next.
>>
>>> This marks the beginning of user-facing developer documentation for
>>> using eBPF (extended Berkeley Packet Filter) as part of the kernel
>>> Documentation/ tree.
>>>
>>> This documentation is also available here[1], as an intermidiate quick
>>> way of prototyping and releasing the documentation.  The autoriative
>>> and official version of the documentation is what gets included in the
>>> kernel tree.  The docs at [2] will get updated based on what gets
>>> accepted after the standard peer-review kernel process.
>>
>> Thanks for your effort of writing a doc. Some high-level comments on
>> the set from my PoV first.
>>
>> I think it's definitely the right direction to move everything BPF
>> related to Documentation/BPF/. Right now, there are a lot of different
>> places with different kind of documentation, f.e.:
>
> Agree that we need some in-kernel place to centralize bpf related
> documentation, as it is too scattered at the moment.
>
>> * Documentation/networking/filter.txt
>>     Covers some cBPF/eBPF internals, tooling, etc; mostly technical,
>>     historically the central spot for BPF documentation. "filter" in
>>     filter.txt is long obsolete name, but looks like various sites,
>>     talks, blogs, etc still link to it. (At best, we should keep the
>>     file saying that the doc moved to Documentation/BPF/.)
>
> Agree.
>
>> * bpf(2) man page
>>     Has a good start, but right now is heavily behind the current user
>>     facing kernel code.
>
> Yes, the man-page have proven to get out-of-sync.  This is one of the
> reasons I prefer this in-kernel-tree documentation, as documentation
> can follow the patchset submission, instead of being something
> developers need to submit _after_ patches are accepted.
>
>
>> * include/uapi/linux/bpf.h
>>     Mostly relevant for helper function API description.
>>
>> * netdev conference slides/proceedings
>>     Also contain mostly technical details on eBPF.
>>
>> * https://github.com/iovisor/bpf-docs
>>     Non-exhaustive collection of various talks from different confs.
>>
>> * https://qmonnet.github.io/whirl-offload/2016/09/01/dive-into-bpf/
>>     Even bigger and more complete list of documentation material.
>>
>> * Various lwn articles ;), blog posts (f.e. from Brendan), etc.
>>
>> Now, challenge is to bring the relevant parts together and logically
>> separated into Documentation/BPF/ and bpf(2) man page. I think everything
>> user API relevant would help most if it updates bpf(2) man page. That can
>> be explanation of different map types, interaction with maps, quirks, etc.
>
> Sorry, but I disagree.  The man-page bpf(2) should only describe the
> bpf syscall.  Details on map types should be documented in this
> documentation.  Why, because this allow us to enforce documentation
> of a new map type is included together with the code submission (else
> it will never get documented).

But essential part of the syscall is to create new maps, interact with
them, etc so it's definitely relevant for the man page. The man page
has a couple of FIXMEs in its source that Michael Kerrisk added in the
course of reviewing and editing patches that were submitted; to give
one example related to this:

   [...]
   Currently, the following values are supported for
   .IR map_type :

   .in +4n
   .nf
   enum bpf_map_type {
     BPF_MAP_TYPE_UNSPEC,  /* Reserve 0 as invalid map type */
     BPF_MAP_TYPE_HASH,
     BPF_MAP_TYPE_ARRAY,
     BPF_MAP_TYPE_PROG_ARRAY,
   };
   .fi
   .in

   .I map_type
     selects one of the available map implementations in the kernel.
   .\" FIXME We need an explanation of why one might choose each of
   .\" these map implementations
   [...]

Thus, I think it makes sense to address these points there instead of
duplicating as a programmer guide in the kernel tree. Maps are not
added as frequently as helper calls, and neither require writing long
novels to document, so we could require submitters to send a patch there.
When it comes to deeper kernel internals that would not be appropriate
in man pages project, but need to be documented nevertheless (perhaps
a guide on what is necessary to implement new map types), they could
then go to the kernel documentation.

What I'm trying to say is that it makes sense to logically defragment
these bits that are relevant for man-page (since user/prog developer
specific) and for kernel doc tree (rather kernel developer specific),
so there's less duplication of efforts eventually.

>> Eventually also helper functions. Right now they're all documented in
>> include/uapi/linux/bpf.h and that's okay as it ships along with the
>> kernel code, so they're in sync. Eventually, there should be some more
>> elaborate description of them, perhaps with tiny examples, in bpf(2)
>> as well, since it's part of the uapi and stable (helpers themselves at
>> least).
>
> IMHO descriptions for bpf helpers function does not belong in the
> man-page for the bpf(2) syscall.  The bpf helpers are something that
> gets used by the ebpf program code which runs kernel side.  (And again
> the same argument about introducing new will not get updated in the man
> page).

But also here, the program runs in kernel space, sure, but people
writing programs are not necessarily the same that write kernel code
f.e. on netdev/lkml, or have a kernel source tree at hand. For helper
functions, the documentation is in-sync and part of include/uapi/linux/bpf.h
which gets shipped as kernel header anyway from distro side.

Man-pages get shipped as well, so they could contain additional infos
related to helpers, f.e. what helpers are tied to which program type,
etc; again, illustration from bpf.2 source:

   [...]
   .BR BPF_PROG_TYPE_KPROBE " (since Linux 4.1)
   .\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5
   [To be documented]
   .\" FIXME Document this program type
   .\"       Describe allowed helper functions for this program type
   .\"       Describe bpf_context for this program type
   .\"
   .\" FIXME We need text here to describe 'kern_version'
   [...]

>> The Documentation/networking/filter.txt would need to be reworked a
>> bit and split into pieces for Documentation/BPF/, so we keep that as a
>> central place for the technical parts. Documentation/RCU/ is doing a
>> great job at that, and I would like to see Documentation/BPF/ being as
>> helpful for developers here. Part of that would be to add missing
>> pieces from the various available sources mentioned above or
>> elsewhere, so people can get a deeper understanding on internals
>> beyond reading just man page for the user API description; explaining
>> concepts, etc. Part of that can also be on the ELF loader bits, etc,
>> no doubt.
>
> Agree
>
>> On a quick glance on the remaining patches, it seems a mixture of
>> quotes from the bpf(2) man page, filter.txt along with sample code
>> explanation and lots of external links, part of them to
>> https://git.kernel.org/cgit/linux/..., http://lxr.free-electrons.com,
>> http://man7.org, http://www.slideshare.net/,
>> https://github.com/torvalds/linux/..., etc. I would suggest that
>> instead we should make Documentation/BPF/ eventually as
>> self-contained as possible and the central place for the internals
>> where others link to instead. It might take a bit, but I think
>> definitely worth it.
>
> In time it can be more self-contained, but as of this writing, as you
> mention yourself, bpf doc resources are fragmented all over, thus the
> obviously doc reflect that with many links.
>
>> Regarding patches, could you split the parts that should go to bpf(2)
>> off and submit them to man page tree for inclusion? I think that
>> would be incredibly helpful. And the remaining internals to start a
>> Documentation/BPF/ directory, even if initially just small (but will
>> grow over time of course)?
>
> As noted, I don't believe in populating the man page further is right
> direction, sorry, and I've already argued why.
>
>
>>> [1] http://prototype-kernel.readthedocs.io/en/latest/bpf/index.html
>>> [2]
>>> https://github.com/netoptimizer/prototype-kernel/tree/master/kernel/Documentation
>>>
>>> Thanks to the following people, who have already reviewed and fixed
>>> earlier versions of this documentation on the IOvisor mailing-list:
>>>
>>>    Alexander Alemayhu <alexander@alemayhu.com>
>>>    Alexei Starovoitov <ast@fb.com>
>>>    Daniel Borkmann <daniel@iogearbox.net>
>>>    Quentin Monnet <quentin.monnet@6wind.com>
>>>
>>>
>>> ---
>>>
>>> Jesper Dangaard Brouer (4):
>>>         doc/bpf: start eBPF documentation tree bpf/
>>>         doc/bpf: document interacting with eBPF maps
>>>         doc/bpf: describes the different types of eBPF maps available
>>>         doc/bpf: describe BCC the BPF Compiler Collection
>>>
>>>
>>>    Documentation/bpf/bcc_tool_chain.rst  |   37 +++++
>>>    Documentation/bpf/ebpf_maps.rst       |  256
>>> +++++++++++++++++++++++++++++++++
>>> Documentation/bpf/ebpf_maps_types.rst |  119 +++++++++++++++
>>> Documentation/bpf/index.rst           |   68 +++++++++
>>> Documentation/index.rst               |    1 5 files changed, 481
>>> insertions(+) create mode 100644
>>> Documentation/bpf/bcc_tool_chain.rst create mode 100644
>>> Documentation/bpf/ebpf_maps.rst create mode 100644
>>> Documentation/bpf/ebpf_maps_types.rst create mode 100644
>>> Documentation/bpf/index.rst
>>>
>

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web