Hello Quentin, On 07/05/2018 03:30 PM, Quentin Monnet wrote: > 2018-05-30 12:25 UTC+0100 ~ Quentin Monnet <quentin.monnet@xxxxxxxxxxxxx> >> eBPF sub-system on Linux can use "helper functions", functions >> implemented in the kernel that can be called from within a eBPF program >> injected by a user on Linux. The kernel already supports a long list of >> such helpers (seventy-eight at this time, new ones are under review). >> Therefore, it is proposed to create a new manual page, separate from >> bpf(2), to document those helpers for people willing to develop new eBPF >> programs. >> >> Additionally, in an effort to keep this documentation in synchronisation >> with what is implemented in the kernel, it is further proposed to keep >> the documentation itself in the kernel sources, as comments in file >> "include/uapi/linux/bpf.h", and to generate the man page from there. >> In this way, there is a single location for documentation on helpers, >> and it accommodates both developers preferring reading the kernel UAPI >> headers and those relying on man pages. Furthermore, it should help >> enforce proper and reviewed documentation for eBPF helpers since the >> functions need to be enlisted in the __BPF_FUNC_MAPPER() in the BPF UAPI >> header. >> >> This patch adds the new man page, generated from kernel sources, to the >> man-pages repository. For each eBPF helper function, a description of >> the helper, of its arguments and of the return value is provided. The >> idea is that all future changes for this page should be redirected to >> the kernel file "include/uapi/linux/bpf.h" (usually updated through the >> bpf-next tree), and the modified page generated from there. >> >> Generating the page itself is a two-step process. First, the >> documentation is extracted from include/uapi/linux/bpf.h, and converted >> to a RST (reStructuredText-formatted) page, with the relevant script >> from Linux sources: >> >> $ ./scripts/bpf_helpers_doc.py > /tmp/bpf-helpers.rst >> >> The second step consists in turning the RST document into the final man >> page, with rst2man (from package python-docutils for Debian and >> derivatives): >> >> $ rst2man /tmp/bpf-helpers.rst > bpf-helpers.7 >> >> Known issues related to the inclusion of this automatically-generated >> page are: >> >> - All edits for this page submitted to the man-pages project will have >> to be redirected towards the bpf.h header from kernel sources, as >> explained above. >> - The use of rst2man introduces some inconsistencies with regard to >> other pages, some of them with negative effects, such as the use of >> ".sp" as a paragraph separator (known to render poorly for PS or PDF >> conversion of the pages). A post-processing tool could be used in the >> future. >> >> For those reasons the generated page is proposed to be merged as an >> "experiment", which could be revisited in the future, depending on how >> things go. >> >> The bpf.h file was taken at kernel commit 13a370b9d275 (that should be >> in Linux 4.18). >> >> v2: >> - Update contents from bpf.h (v1 used Linux commit 081023a31129). >> - Update commit log. >> >> Cc: Alexei Starovoitov <ast@xxxxxxxxxx> >> Cc: Daniel Borkmann <daniel@xxxxxxxxxxxxx> >> Signed-off-by: Quentin Monnet <quentin.monnet@xxxxxxxxxxxxx> >> Acked-by: Daniel Borkmann <daniel@xxxxxxxxxxxxx> > > Hi Michael, > > I got no answer for v2 of this patch about eBPF helpers documentation. >>From our discussion on v1, I remember you agreed to take the page, is > this still valid? > > If you changed your mind, I'll try to make the page available in another > way (maybe generate it along with the documentation for bpftool, shipped > with the kernel, and install it from there), although it would be nice > to have it rendered on man7.org one way or another. Please let me know! Sorry for the vary late reply... I've applied the scripts to kernel 4.19, to generate a version of the page that will be included in the next man-pages release. Changes are pushed to man-pages Git. Please let me know if anything is amiss. Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
