1. 17 May, 2018 1 commit
    • Quentin Monnet's avatar
      bpf: change eBPF helper doc parsing script to allow for smaller indent · eeacb716
      Quentin Monnet authored
      Documentation for eBPF helpers can be parsed from bpf.h and eventually
      turned into a man page. Commit 6f96674d ("bpf: relax constraints on
      formatting for eBPF helper documentation") changed the script used to
      parse it, in order to allow for different indent style and to ease the
      work for writing documentation for future helpers.
      
      The script currently considers that the first tab can be replaced by 6
      to 8 spaces. But the documentation for bpf_fib_lookup() uses a mix of
      tabs (for the "Description" part) and of spaces ("Return" part), and
      only has 5 space long indent for the latter.
      
      We probably do not want to change the values accepted by the script each
      time a new helper gets a new indent style. However, it is worth noting
      that with those 5 spaces, the "Description" and "Return" part *look*
      aligned in the generated patch and in `git show`, so it is likely other
      helper authors will use the same length. Therefore, allow for helper
      documentation to use 5 spaces only for the first indent level.
      Signed-off-by: 's avatarQuentin Monnet <quentin.monnet@netronome.com>
      Signed-off-by: 's avatarDaniel Borkmann <daniel@iogearbox.net>
      eeacb716
  2. 02 May, 2018 1 commit
    • Quentin Monnet's avatar
      bpf: relax constraints on formatting for eBPF helper documentation · 6f96674d
      Quentin Monnet authored
      The Python script used to parse and extract eBPF helpers documentation
      from include/uapi/linux/bpf.h expects a very specific formatting for the
      descriptions (single dot represents a space, '>' stands for a tab):
      
          /*
           ...
           *.int bpf_helper(list of arguments)
           *.>    Description
           *.>    >       Start of description
           *.>    >       Another line of description
           *.>    >       And yet another line of description
           *.>    Return
           *.>    >       0 on success, or a negative error in case of failure
           ...
           */
      
      This is too strict, and painful for developers who wants to add
      documentation for new helpers. Worse, it is extremely difficult to check
      that the formatting is correct during reviews. Change the format
      expected by the script and make it more flexible. The script now works
      whether or not the initial space (right after the star) is present, and
      accepts both tabs and white spaces (or a combination of both) for
      indenting description sections and contents.
      
      Concretely, something like the following would now be supported:
      
          /*
           ...
           *int bpf_helper(list of arguments)
           *......Description
           *.>    >       Start of description...
           *>     >       Another line of description
           *..............And yet another line of description
           *>     Return
           *.>    ........0 on success, or a negative error in case of failure
           ...
           */
      
      While at it, remove unnecessary carets from each regex used with match()
      in the script. They are redundant, as match() tries to match from the
      beginning of the string by default.
      
      v2: Remove unnecessary caret when a regex is used with match().
      Signed-off-by: 's avatarQuentin Monnet <quentin.monnet@netronome.com>
      Signed-off-by: 's avatarDaniel Borkmann <daniel@iogearbox.net>
      6f96674d
  3. 26 Apr, 2018 1 commit
    • 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