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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20170208113613.520dd4e6@redhat.com>
Date:   Wed, 8 Feb 2017 11:36:13 +0100
From:   Jesper Dangaard Brouer <brouer@...hat.com>
To:     Jonathan Corbet <corbet@....net>
Cc:     netdev@...r.kernel.org, linux-doc@...r.kernel.org,
        Alexei Starovoitov <ast@...com>, alexander@...mayhu.com,
        linux-kernel@...r.kernel.org, quentin.monnet@...nd.com,
        Daniel Borkmann <borkmann@...earbox.net>, brouer@...hat.com
Subject: Re: [net-next PATCH 0/4] Documenting eBPF - extended Berkeley
 Packet Filter

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

> On Tue, 7 Feb 2017 21:51:49 +0100
> Jesper Dangaard Brouer <brouer@...hat.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