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! Best regards, Quentin -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
