From: Jonathan Corbet <corbet@lwn.net>
To: Joe Stringer <joe@wand.net.nz>, bpf@vger.kernel.org
Cc: Joe Stringer <joe@cilium.io>,
linux-man@vger.kernel.org, netdev@vger.kernel.org,
mtk.manpages@gmail.com, ast@kernel.org, brianvv@google.com,
daniel@iogearbox.net, daniel@zonque.org,
john.fastabend@gmail.com, ppenkov@google.com,
quentin@isovalent.com, sean@mess.org, yhs@fb.com,
linux-doc@vger.kernel.org
Subject: Re: [PATCH bpf-next 00/17] Improve BPF syscall command documentation
Date: Wed, 17 Feb 2021 10:32:49 -0700 [thread overview]
Message-ID: <871rdewqf2.fsf@meer.lwn.net> (raw)
In-Reply-To: <20210217010821.1810741-1-joe@wand.net.nz>
[CC += linux-doc]
Joe Stringer <joe@wand.net.nz> writes:
> From: Joe Stringer <joe@cilium.io>
>
> The state of bpf(2) manual pages today is not exactly ideal. For the
> most part, it was written several years ago and has not kept up with the
> pace of development in the kernel tree. For instance, out of a total of
> ~35 commands to the BPF syscall available today, when I pull the
> kernel-man-pages tree today I find just 6 documented commands: The very
> basics of map interaction and program load.
>
> In contrast, looking at bpf-helpers(7), I am able today to run one
> command[0] to fetch API documentation of the very latest eBPF helpers
> that have been added to the kernel. This documentation is up to date
> because kernel maintainers enforce documenting the APIs as part of
> the feature submission process. As far as I can tell, we rely on manual
> synchronization from the kernel tree to the kernel-man-pages tree to
> distribute these more widely, so all locations may not be completely up
> to date. That said, the documentation does in fact exist in the first
> place which is a major initial hurdle to overcome.
>
> Given the relative success of the process around bpf-helpers(7) to
> encourage developers to document their user-facing changes, in this
> patch series I explore applying this technique to bpf(2) as well.
So I am totally in favor of improving the BPF docs, this is great work.
That said, I am a bit less thrilled about creating a new, parallel
documentation-build system in the kernel. I don't think that BPF is so
special that it needs to do its own thing here.
In particular, I would love to have the bpf() syscall API information
incorporated into the userspace-api book with all the rest of the
user-space API docs. That could be done now by formatting your
information as a DOC: block.
If you started that way, you'd get the whole existing build system for
free. You would also have started down a path that could, some bright
shining day, lead to this kind of documentation for *all* of our system
calls. That would be a huge improvement in how we do things.
The troff output would still need implementation, but we'd like to have
that anyway. We used to create man pages for internal kernel APIs; that
was lost in the sphinx transition and hasn't been a priority since
people haven't been screaming, but it could still be nice to have it
back.
So...could I ask you to have a look at doing this within the kernel's
docs system instead of in addition to it? Even if it means digging into
scripts/kernel-doc, which isn't all that high on my list of Fun Things
To Do either? I'm willing to try to help, and maybe we can get some
other assistance too - I'm ever the optimist.
Thanks,
jon
next prev parent reply other threads:[~2021-02-17 17:34 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-02-17 1:08 [PATCH bpf-next 00/17] Improve BPF syscall command documentation Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 01/17] bpf: Import syscall arg documentation Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 02/17] bpf: Add minimal bpf() command documentation Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 03/17] bpf: Document BPF_F_LOCK in syscall commands Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 04/17] bpf: Document BPF_PROG_PIN syscall command Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 05/17] bpf: Document BPF_PROG_ATTACH " Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 06/17] bpf: Document BPF_PROG_TEST_RUN " Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 07/17] bpf: Document BPF_PROG_QUERY " Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 08/17] bpf: Document BPF_MAP_*_BATCH syscall commands Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 09/17] scripts/bpf: Rename bpf_helpers_doc.py -> bpf_doc.py Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 10/17] scripts/bpf: Abstract eBPF API target parameter Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 11/17] scripts/bpf: Add syscall commands printer Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 12/17] tools/bpf: Rename Makefile.{helpers,docs} Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 13/17] tools/bpf: Templatize man page generation Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 14/17] tools/bpf: Build bpf-sycall.2 in Makefile.docs Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 15/17] selftests/bpf: Add docs target Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 16/17] docs/bpf: Add bpf() syscall command reference Joe Stringer
2021-02-17 1:08 ` [PATCH bpf-next 17/17] tools: Sync uapi bpf.h header with latest changes Joe Stringer
2021-02-17 13:55 ` [PATCH bpf-next 00/17] Improve BPF syscall command documentation Toke Høiland-Jørgensen
2021-02-18 4:08 ` Joe Stringer
2021-02-18 11:33 ` Toke Høiland-Jørgensen
2021-02-17 17:32 ` Jonathan Corbet [this message]
2021-02-18 4:22 ` Joe Stringer
2021-02-18 19:26 ` Jonathan Corbet
2021-02-18 21:53 ` Joe Stringer
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=871rdewqf2.fsf@meer.lwn.net \
--to=corbet@lwn.net \
--cc=ast@kernel.org \
--cc=bpf@vger.kernel.org \
--cc=brianvv@google.com \
--cc=daniel@iogearbox.net \
--cc=daniel@zonque.org \
--cc=joe@cilium.io \
--cc=joe@wand.net.nz \
--cc=john.fastabend@gmail.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-man@vger.kernel.org \
--cc=mtk.manpages@gmail.com \
--cc=netdev@vger.kernel.org \
--cc=ppenkov@google.com \
--cc=quentin@isovalent.com \
--cc=sean@mess.org \
--cc=yhs@fb.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).