• Quentin Monnet's avatar
    bpf: add script and prepare bpf.h for new helpers documentation · 56a092c8
    Quentin Monnet authored
    Remove previous "overview" of eBPF helpers from user bpf.h header.
    Replace it by a comment explaining how to process the new documentation
    (to come in following patches) with a Python script to produce RST, then
    man page documentation.
    
    Also add the aforementioned Python script under scripts/. It is used to
    process include/uapi/linux/bpf.h and to extract helper descriptions, to
    turn it into a RST document that can further be processed with rst2man
    to produce a man page. The script takes one "--filename <path/to/file>"
    option. If the script is launched from scripts/ in the kernel root
    directory, it should be able to find the location of the header to
    parse, and "--filename <path/to/file>" is then optional. If it cannot
    find the file, then the option becomes mandatory. RST-formatted
    documentation is printed to standard output.
    
    Typical workflow for producing the final man page would be:
    
        $ ./scripts/bpf_helpers_doc.py \
                --filename include/uapi/linux/bpf.h > /tmp/bpf-helpers.rst
        $ rst2man /tmp/bpf-helpers.rst > /tmp/bpf-helpers.7
        $ man /tmp/bpf-helpers.7
    
    Note that the tool kernel-doc cannot be used to document eBPF helpers,
    whose signatures are not available directly in the header files
    (pre-processor directives are used to produce them at the beginning of
    the compilation process).
    
    v4:
    - Also remove overviews for newly added bpf_xdp_adjust_tail() and
      bpf_skb_get_xfrm_state().
    - Remove vague statement about what helpers are restricted to GPL
      programs in "LICENSE" section for man page footer.
    - Replace license boilerplate with SPDX tag for Python script.
    
    v3:
    - Change license for man page.
    - Remove "for safety reasons" from man page header text.
    - Change "packets metadata" to "packets" in man page header text.
    - Move and fix comment on helpers introducing no overhead.
    - Remove "NOTES" section from man page footer.
    - Add "LICENSE" section to man page footer.
    - Edit description of file include/uapi/linux/bpf.h in man page footer.
    Signed-off-by: 's avatarQuentin Monnet <quentin.monnet@netronome.com>
    Signed-off-by: 's avatarDaniel Borkmann <daniel@iogearbox.net>
    56a092c8
bpf_helpers_doc.py 15.4 KB