linux.git/scripts/bpf_doc.py, branch v6.1.168

scripts/bpf_doc: Use silent mode when exec make cmd

2024-04-10T14:28:21+00:00

[ Upstream commit 5384cc0d1a88c27448a6a4e65b8abe6486de8012 ]

When getting kernel version via make, the result may be polluted by other
output, like directory change info. e.g.

  $ export MAKEFLAGS="-w"
  $ make kernelversion
  make: Entering directory '/home/net'
  6.8.0
  make: Leaving directory '/home/net'

This will distort the reStructuredText output and make latter rst2man
failed like:

  [...]
  bpf-helpers.rst:20: (WARNING/2) Field list ends without a blank line; unexpected unindent.
  [...]

Using silent mode would help. e.g.

  $ make -s --no-print-directory kernelversion
  6.8.0

Fixes: fd0a38f9c37d ("scripts/bpf: Set version attribute for bpf-helpers(7) man page")
Signed-off-by: Michael Hofmann 
Signed-off-by: Hangbin Liu 
Signed-off-by: Daniel Borkmann 
Reviewed-by: Quentin Monnet 
Acked-by: Alejandro Colomar 
Link: https://lore.kernel.org/bpf/20240315023443.2364442-1-liuhangbin@gmail.com
Signed-off-by: Sasha Levin

bpf, scripts: Correct GPL license name

2024-03-01T12:26:35+00:00

[ Upstream commit e37243b65d528a8a9f8b9a57a43885f8e8dfc15c ]

The bpf_doc script refers to the GPL as the "GNU Privacy License".
I strongly suspect that the author wanted to refer to the GNU General
Public License, under which the Linux kernel is released, as, to the
best of my knowledge, there is no license named "GNU Privacy License".
This patch corrects the license name in the script accordingly.

Fixes: 56a092c89505 ("bpf: add script and prepare bpf.h for new helpers documentation")
Signed-off-by: Gianmarco Lusvardi 
Signed-off-by: Daniel Borkmann 
Reviewed-by: Quentin Monnet 
Link: https://lore.kernel.org/bpf/20240213230544.930018-3-glusvardi@posteo.net
Signed-off-by: Sasha Levin

bpf/scripts: Assert helper enum value is aligned with comment order

2022-08-25T18:49:14+00:00

The helper value is ABI as defined by enum bpf_func_id.
As bpf_helper_defs.h is used for the userpace part, it must be consistent
with this enum.

Before this change the comments order was used by the bpf_doc script in
order to set the helper values defined in the helpers file.

When adding new helpers it is very puzzling when the userspace application
breaks in weird places if the comment is inserted instead of appended -
because the generated helper ABI is incorrect and shifted.

This commit sets the helper value to the enum value.

In addition it is currently the practice to have the comments appended
and kept in the same order as the enum. As such, add an assertion
validating the comment order is consistent with enum value.

In case a different comments ordering is desired, this assertion can
be lifted.

Signed-off-by: Eyal Birger 
Signed-off-by: Andrii Nakryiko 
Reviewed-by: Quentin Monnet 
Link: https://lore.kernel.org/bpf/20220824181043.1601429-1-eyal.birger@gmail.com

scripts/bpf: Set date attribute for bpf-helpers(7) man page

2022-08-23T20:51:04+00:00

The bpf-helpers(7) manual page shipped in the man-pages project is
generated from the documentation contained in the BPF UAPI header, in
the Linux repository, parsed by script/bpf_doc.py and then fed to
rst2man.

The man page should contain the date of last modification of the
documentation. This commit adds the relevant date when generating the
page.

Before:

    $ ./scripts/bpf_doc.py helpers | rst2man | grep '\.TH'
    .TH BPF-HELPERS 7 "" "Linux v5.19-14022-g30d2a4d74e11" ""

After:

    $ ./scripts/bpf_doc.py helpers | rst2man | grep '\.TH'
    .TH BPF-HELPERS 7 "2022-08-15" "Linux v5.19-14022-g30d2a4d74e11" ""

We get the version by using "git log" to look for the commit date of the
latest change to the section of the BPF header containing the
documentation. If the command fails, we just skip the date field. and
keep generating the page.

Reported-by: Alejandro Colomar 
Signed-off-by: Quentin Monnet 
Signed-off-by: Daniel Borkmann 
Reviewed-by: Alejandro Colomar 
Link: https://lore.kernel.org/bpf/20220823155327.98888-2-quentin@isovalent.com

scripts/bpf: Set version attribute for bpf-helpers(7) man page

2022-08-23T20:51:04+00:00

The bpf-helpers(7) manual page shipped in the man-pages project is
generated from the documentation contained in the BPF UAPI header, in
the Linux repository, parsed by script/bpf_doc.py and then fed to
rst2man.

After a recent update of that page [0], Alejandro reported that the
linter used to validate the man pages complains about the generated
document [1]. The header for the page is supposed to contain some
attributes that we do not set correctly with the script. This commit
updates the "project and version" field. We discussed the format of
those fields in [1] and [2].

Before:

    $ ./scripts/bpf_doc.py helpers | rst2man | grep '\.TH'
    .TH BPF-HELPERS 7 "" "" ""

After:

    $ ./scripts/bpf_doc.py helpers | rst2man | grep '\.TH'
    .TH BPF-HELPERS 7 "" "Linux v5.19-14022-g30d2a4d74e11" ""

We get the version from "git describe", but if unavailable, we fall back
on "make kernelversion". If none works, for example because neither git
nore make are installed, we just set the field to "Linux" and keep
generating the page.

[0] https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man7/bpf-helpers.7?id=19c7f78393f2b038e76099f87335ddf43a87f039
[1] https://lore.kernel.org/all/20220823084719.13613-1-quentin@isovalent.com/t/#m58a418a318642c6428e14ce9bb84eba5183b06e8
[2] https://lore.kernel.org/all/20220721110821.8240-1-alx.manpages@gmail.com/t/#m8e689a822e03f6e2530a0d6de9d128401916c5de

Reported-by: Alejandro Colomar 
Signed-off-by: Quentin Monnet 
Signed-off-by: Daniel Borkmann 
Reviewed-by: Alejandro Colomar 
Link: https://lore.kernel.org/bpf/20220823155327.98888-1-quentin@isovalent.com

bpf, docs: Use SPDX license identifier in bpf_doc.py

2022-07-21T22:28:14+00:00

The Linux man-pages project now uses SPDX tags, instead of the full
license text.

Signed-off-by: Alejandro Colomar 
Signed-off-by: Daniel Borkmann 
Link: https://www.kernel.org/doc/man-pages/licenses.html
Link: https://spdx.org/licenses/Linux-man-pages-copyleft.html
Link: https://lore.kernel.org/bpf/20220721110821.8240-1-alx.manpages@gmail.com

bpf: Add helpers to issue and check SYN cookies in XDP

2022-06-17T04:20:30+00:00

The new helpers bpf_tcp_raw_{gen,check}_syncookie_ipv{4,6} allow an XDP
program to generate SYN cookies in response to TCP SYN packets and to
check those cookies upon receiving the first ACK packet (the final
packet of the TCP handshake).

Unlike bpf_tcp_{gen,check}_syncookie these new helpers don't need a
listening socket on the local machine, which allows to use them together
with synproxy to accelerate SYN cookie generation.

Signed-off-by: Maxim Mikityanskiy 
Reviewed-by: Tariq Toukan 
Link: https://lore.kernel.org/r/20220615134847.3753567-4-maximmi@nvidia.com
Signed-off-by: Alexei Starovoitov

bpf: Add verifier support for dynptrs

2022-05-23T21:30:17+00:00

This patch adds the bulk of the verifier work for supporting dynamic
pointers (dynptrs) in bpf.

A bpf_dynptr is opaque to the bpf program. It is a 16-byte structure
defined internally as:

struct bpf_dynptr_kern {
    void *data;
    u32 size;
    u32 offset;
} __aligned(8);

The upper 8 bits of *size* is reserved (it contains extra metadata about
read-only status and dynptr type). Consequently, a dynptr only supports
memory less than 16 MB.

There are different types of dynptrs (eg malloc, ringbuf, ...). In this
patchset, the most basic one, dynptrs to a bpf program's local memory,
is added. For now only local memory that is of reg type PTR_TO_MAP_VALUE
is supported.

In the verifier, dynptr state information will be tracked in stack
slots. When the program passes in an uninitialized dynptr
(ARG_PTR_TO_DYNPTR | MEM_UNINIT), the stack slots corresponding
to the frame pointer where the dynptr resides at are marked
STACK_DYNPTR. For helper functions that take in initialized dynptrs (eg
bpf_dynptr_read + bpf_dynptr_write which are added later in this
patchset), the verifier enforces that the dynptr has been initialized
properly by checking that their corresponding stack slots have been
marked as STACK_DYNPTR.

The 6th patch in this patchset adds test cases that the verifier should
successfully reject, such as for example attempting to use a dynptr
after doing a direct write into it inside the bpf program.

Signed-off-by: Joanne Koong 
Signed-off-by: Andrii Nakryiko 
Acked-by: Andrii Nakryiko 
Acked-by: David Vernet 
Link: https://lore.kernel.org/bpf/20220523210712.3641569-2-joannelkoong@gmail.com

bpf: Add bpf_skc_to_mptcp_sock_proto

2022-05-20T22:29:00+00:00

This patch implements a new struct bpf_func_proto, named
bpf_skc_to_mptcp_sock_proto. Define a new bpf_id BTF_SOCK_TYPE_MPTCP,
and a new helper bpf_skc_to_mptcp_sock(), which invokes another new
helper bpf_mptcp_sock_from_subflow() in net/mptcp/bpf.c to get struct
mptcp_sock from a given subflow socket.

v2: Emit BTF type, add func_id checks in verifier.c and bpf_trace.c,
remove build check for CONFIG_BPF_JIT
v5: Drop EXPORT_SYMBOL (Martin)

Co-developed-by: Nicolas Rybowski 
Co-developed-by: Matthieu Baerts 
Signed-off-by: Nicolas Rybowski 
Signed-off-by: Matthieu Baerts 
Signed-off-by: Geliang Tang 
Signed-off-by: Mat Martineau 
Signed-off-by: Andrii Nakryiko 
Link: https://lore.kernel.org/bpf/20220519233016.105670-2-mathew.j.martineau@linux.intel.com

bpf/scripts: Raise an exception if the correct number of sycalls are not generated

2022-01-19T18:24:50+00:00

Currently the syscalls rst and subsequently man page are auto-generated
using function documentation present in bpf.h. If the documentation for the
syscall is missing or doesn't follow a specific format, then that syscall
is not dumped in the auto-generated rst.

This patch checks the number of syscalls documented within the header file
with those present as part of the enum bpf_cmd and raises an Exception if
they don't match. It is not needed with the currently documented upstream
syscalls, but can help in debugging when developing new syscalls when
there might be missing or misformatted documentation.

The function helper_number_check is moved to the Printer parent
class and renamed to elem_number_check as all the most derived children
classes are using this function now.

Signed-off-by: Usama Arif 
Signed-off-by: Andrii Nakryiko 
Reviewed-by: Quentin Monnet 
Link: https://lore.kernel.org/bpf/20220119114442.1452088-3-usama.arif@bytedance.com