From: David Vernet <void@manifault.com>
To: Donald Hunter <donald.hunter@gmail.com>
Cc: bpf@vger.kernel.org, linux-doc@vger.kernel.org,
Alexei Starovoitov <ast@kernel.org>,
Daniel Borkmann <daniel@iogearbox.net>,
Andrii Nakryiko <andrii@kernel.org>,
Jonathan Corbet <corbet@lwn.net>
Subject: Re: [PATCH bpf-next v5] docs/bpf: Add table of BPF program types to libbpf docs
Date: Fri, 18 Nov 2022 17:55:26 -0600 [thread overview]
Message-ID: <Y3gbbqwwL7GUydzb@maniforge.lan> (raw)
In-Reply-To: <20221118152859.69645-1-donald.hunter@gmail.com>
On Fri, Nov 18, 2022 at 03:28:59PM +0000, Donald Hunter wrote:
> Extend the libbpf documentation with a table of program types,
> attach points and ELF section names.
>
> Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
> ---
This looks great, thanks for writing it up. Just left one suggestion
below.
Acked-by: David Vernet <void@manifault.com>
> Documentation/bpf/libbpf/index.rst | 3 +
> Documentation/bpf/libbpf/program_types.rst | 203 +++++++++++++++++++++
> Documentation/bpf/programs.rst | 3 +
> 3 files changed, 209 insertions(+)
> create mode 100644 Documentation/bpf/libbpf/program_types.rst
>
> diff --git a/Documentation/bpf/libbpf/index.rst b/Documentation/bpf/libbpf/index.rst
> index 3722537d1384..f9b3b252e28f 100644
> --- a/Documentation/bpf/libbpf/index.rst
> +++ b/Documentation/bpf/libbpf/index.rst
> @@ -1,5 +1,7 @@
> .. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
>
> +.. _libbpf:
> +
> libbpf
> ======
>
> @@ -7,6 +9,7 @@ libbpf
> :maxdepth: 1
>
> API Documentation <https://libbpf.readthedocs.io/en/latest/api.html>
> + program_types
> libbpf_naming_convention
> libbpf_build
>
> diff --git a/Documentation/bpf/libbpf/program_types.rst b/Documentation/bpf/libbpf/program_types.rst
> new file mode 100644
> index 000000000000..544e1597ff5f
> --- /dev/null
> +++ b/Documentation/bpf/libbpf/program_types.rst
> @@ -0,0 +1,203 @@
> +.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
> +
> +.. _program_types_and_elf:
> +
> +Program Types and ELF Sections
> +==============================
> +
> +The table below lists the program types, their attach types where relevant and the ELF section
> +names supported by libbpf for them. The ELF section names follow these rules:
> +
> +- ``type`` is an exact match, e.g. ``SEC("socket")``
> +- ``type+`` means it can be either exact ``SEC("type")`` or well-formed ``SEC("type/extras")``
> + with a '``/``' separator between ``type`` and ``extras``.
> +
> +When ``extras`` are specified, they provide details of how to auto-attach the BPF program. The
> +format of ``extras`` depends on the program type, e.g. ``SEC("tracepoint/<category>/<name>")``
> +for tracepoints or ``SEC("usdt/<path>:<provider>:<name>")`` for USDT probes. The extras are
> +described in more detail in the footnotes.
> +
> +
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| Program Type | Attach Type | ELF Section Name | Sleepable |
> ++===========================================+========================================+==================================+===========+
> +| ``BPF_PROG_TYPE_CGROUP_DEVICE`` | ``BPF_CGROUP_DEVICE`` | ``cgroup/dev`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_CGROUP_SKB`` | | ``cgroup/skb`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_INET_EGRESS`` | ``cgroup_skb/egress`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_INET_INGRESS`` | ``cgroup_skb/ingress`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_CGROUP_SOCKOPT`` | ``BPF_CGROUP_GETSOCKOPT`` | ``cgroup/getsockopt`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_SETSOCKOPT`` | ``cgroup/setsockopt`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_CGROUP_SOCK_ADDR`` | ``BPF_CGROUP_INET4_BIND`` | ``cgroup/bind4`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_INET4_CONNECT`` | ``cgroup/connect4`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_INET4_GETPEERNAME`` | ``cgroup/getpeername4`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_INET4_GETSOCKNAME`` | ``cgroup/getsockname4`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_INET6_BIND`` | ``cgroup/bind6`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_INET6_CONNECT`` | ``cgroup/connect6`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_INET6_GETPEERNAME`` | ``cgroup/getpeername6`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_INET6_GETSOCKNAME`` | ``cgroup/getsockname6`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_UDP4_RECVMSG`` | ``cgroup/recvmsg4`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_UDP4_SENDMSG`` | ``cgroup/sendmsg4`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_UDP6_RECVMSG`` | ``cgroup/recvmsg6`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_UDP6_SENDMSG`` | ``cgroup/sendmsg6`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_CGROUP_SOCK`` | ``BPF_CGROUP_INET4_POST_BIND`` | ``cgroup/post_bind4`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_INET6_POST_BIND`` | ``cgroup/post_bind6`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_INET_SOCK_CREATE`` | ``cgroup/sock_create`` | |
> ++ + +----------------------------------+-----------+
> +| | | ``cgroup/sock`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_CGROUP_INET_SOCK_RELEASE`` | ``cgroup/sock_release`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_CGROUP_SYSCTL`` | ``BPF_CGROUP_SYSCTL`` | ``cgroup/sysctl`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_EXT`` | | ``freplace+`` [#fentry]_ | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_FLOW_DISSECTOR`` | ``BPF_FLOW_DISSECTOR`` | ``flow_dissector`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_KPROBE`` | | ``kprobe+`` [#kprobe]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``kretprobe+`` [#kprobe]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``ksyscall+`` [#ksyscall]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``kretsyscall+`` [#ksyscall]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``uprobe+`` [#uprobe]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``uprobe.s+`` [#uprobe]_ | Yes |
> ++ + +----------------------------------+-----------+
> +| | | ``uretprobe+`` [#uprobe]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``uretprobe.s+`` [#uprobe]_ | Yes |
> ++ + +----------------------------------+-----------+
> +| | | ``usdt+`` [#usdt]_ | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_TRACE_KPROBE_MULTI`` | ``kprobe.multi+`` [#kpmulti]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``kretprobe.multi+`` [#kpmulti]_ | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_LIRC_MODE2`` | ``BPF_LIRC_MODE2`` | ``lirc_mode2`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_LSM`` | ``BPF_LSM_CGROUP`` | ``lsm_cgroup+`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_LSM_MAC`` | ``lsm+`` [#lsm]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``lsm.s+`` [#lsm]_ | Yes |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_LWT_IN`` | | ``lwt_in`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_LWT_OUT`` | | ``lwt_out`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_LWT_SEG6LOCAL`` | | ``lwt_seg6local`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_LWT_XMIT`` | | ``lwt_xmit`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_PERF_EVENT`` | | ``perf_event`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_RAW_TRACEPOINT_WRITABLE`` | | ``raw_tp.w+`` [#rawtp]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``raw_tracepoint.w+`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_RAW_TRACEPOINT`` | | ``raw_tp+`` [#rawtp]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``raw_tracepoint+`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_SCHED_ACT`` | | ``action`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_SCHED_CLS`` | | ``classifier`` | |
> ++ + +----------------------------------+-----------+
> +| | | ``tc`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_SK_LOOKUP`` | ``BPF_SK_LOOKUP`` | ``sk_lookup`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_SK_MSG`` | ``BPF_SK_MSG_VERDICT`` | ``sk_msg`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_SK_REUSEPORT`` | ``BPF_SK_REUSEPORT_SELECT_OR_MIGRATE`` | ``sk_reuseport/migrate`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_SK_REUSEPORT_SELECT`` | ``sk_reuseport`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_SK_SKB`` | | ``sk_skb`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_SK_SKB_STREAM_PARSER`` | ``sk_skb/stream_parser`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_SK_SKB_STREAM_VERDICT`` | ``sk_skb/stream_verdict`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_SOCKET_FILTER`` | | ``socket`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_SOCK_OPS`` | ``BPF_CGROUP_SOCK_OPS`` | ``sockops`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_STRUCT_OPS`` | | ``struct_ops+`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_SYSCALL`` | | ``syscall`` | Yes |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_TRACEPOINT`` | | ``tp+`` [#tp]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``tracepoint+`` [#tp]_ | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_TRACING`` | ``BPF_MODIFY_RETURN`` | ``fmod_ret+`` [#fentry]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``fmod_ret.s+`` [#fentry]_ | Yes |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_TRACE_FENTRY`` | ``fentry+`` [#fentry]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``fentry.s+`` [#fentry]_ | Yes |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_TRACE_FEXIT`` | ``fexit+`` [#fentry]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``fexit.s+`` [#fentry]_ | Yes |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_TRACE_ITER`` | ``iter+`` [#iter]_ | |
> ++ + +----------------------------------+-----------+
> +| | | ``iter.s+`` [#iter]_ | Yes |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_TRACE_RAW_TP`` | ``tp_btf+`` [#fentry]_ | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +| ``BPF_PROG_TYPE_XDP`` | ``BPF_XDP_CPUMAP`` | ``xdp.frags/cpumap`` | |
> ++ + +----------------------------------+-----------+
> +| | | ``xdp/cpumap`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_XDP_DEVMAP`` | ``xdp.frags/devmap`` | |
> ++ + +----------------------------------+-----------+
> +| | | ``xdp/devmap`` | |
> ++ +----------------------------------------+----------------------------------+-----------+
> +| | ``BPF_XDP`` | ``xdp.frags`` | |
> ++ + +----------------------------------+-----------+
> +| | | ``xdp`` | |
> ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+
> +
> +
> +.. rubric:: Footnotes
> +
> +.. [#fentry] The ``fentry`` attach format is ``fentry[.s]/<function>``.
> +.. [#kprobe] The ``kprobe`` attach format is ``kprobe/<function>[+<offset>]``. Valid
> + characters for ``function`` are ``a-zA-Z0-9_.`` and ``offset`` must be a valid
> + integer.
Perhaps "nonnegative integer" is slightly more precise here?
> +.. [#ksyscall] The ``ksyscall`` attach format is ``ksyscall/<syscall>``.
> +.. [#uprobe] The ``uprobe`` attach format is ``uprobe[.s]/<path>:<function>[+<offset>]``.
> +.. [#usdt] The ``usdt`` attach format is ``usdt/<path>:<provider>:<name>``.
> +.. [#kpmulti] The ``kprobe.multi`` attach format is ``kprobe.multi/<pattern>`` where ``pattern``
> + supports ``*`` and ``?`` wildcards. Valid characters for pattern are
> + ``a-zA-Z0-9_.*?``.
> +.. [#lsm] The ``lsm`` attachment format is ``lsm[.s]/<hook>``.
> +.. [#rawtp] The ``raw_tp`` attach format is ``raw_tracepoint[.w]/<tracepoint>``.
> +.. [#tp] The ``tracepoint`` attach format is ``tracepoint/<category>/<name>``.
> +.. [#iter] The ``iter`` attach format is ``iter[.s]/<struct-name>``.
> diff --git a/Documentation/bpf/programs.rst b/Documentation/bpf/programs.rst
> index 620eb667ac7a..c99000ab6d9b 100644
> --- a/Documentation/bpf/programs.rst
> +++ b/Documentation/bpf/programs.rst
> @@ -7,3 +7,6 @@ Program Types
> :glob:
>
> prog_*
> +
> +For a list of all program types, see :ref:`program_types_and_elf` in
> +the :ref:`libbpf` documentation.
> --
> 2.35.1
>
next prev parent reply other threads:[~2022-11-19 0:57 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-11-18 15:28 [PATCH bpf-next v5] docs/bpf: Add table of BPF program types to libbpf docs Donald Hunter
2022-11-18 23:55 ` David Vernet [this message]
2022-11-19 3:00 ` Bagas Sanjaya
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=Y3gbbqwwL7GUydzb@maniforge.lan \
--to=void@manifault.com \
--cc=andrii@kernel.org \
--cc=ast@kernel.org \
--cc=bpf@vger.kernel.org \
--cc=corbet@lwn.net \
--cc=daniel@iogearbox.net \
--cc=donald.hunter@gmail.com \
--cc=linux-doc@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.