Commit f7b68543 authored by Rameez Rehman's avatar Rameez Rehman Committed by Daniel Borkmann
Browse files

bpftool: Use simpler indentation in source rST for documentation 



The rST manual pages for bpftool would use a mix of tabs and spaces for
indentation. While this is the norm in C code, this is rather unusual
for rST documents, and over time we've seen many contributors use a
wrong level of indentation for documentation update.

Let's fix bpftool's indentation in docs once and for all:

- Let's use spaces, that are more common in rST files.
- Remove one level of indentation for the synopsis, the command
  description, and the "see also" section. As a result, all sections
  start with the same indentation level in the generated man page.
- Rewrap the paragraphs after the changes.

There is no content change in this patch, only indentation and
rewrapping changes. The wrapping in the generated source files for the
manual pages is changed, but the pages displayed with "man" remain the
same, apart from the adjusted indentation level on relevant sections.

[ Quentin: rebased on bpf-next, removed indent level for command
  description and options, updated synopsis, command summary, and "see
  also" sections. ]

Signed-off-by: default avatarRameez Rehman <rameezrehman408@hotmail.com>
Signed-off-by: default avatarQuentin Monnet <qmo@kernel.org>
Signed-off-by: default avatarDaniel Borkmann <daniel@iogearbox.net>
Link: https://lore.kernel.org/bpf/20240331200346.29118-2-qmo@kernel.org
parent 623bdd58

tools/bpf/bpftool/Documentation/Makefile

+3 −3
Original line number Diff line number Diff line
@@ -31,9 +31,9 @@ see_also = $(subst " ",, \ 
	"\n" \

	"SEE ALSO\n" \

	"========\n" \

	"\t**bpf**\ (2),\n" \

	"\t**bpf-helpers**\\ (7)" \

	$(foreach page,$(call list_pages,$(1)),",\n\t**$(page)**\\ (8)") \

	"**bpf**\ (2),\n" \

	"**bpf-helpers**\\ (7)" \

	$(foreach page,$(call list_pages,$(1)),",\n**$(page)**\\ (8)") \

	"\n")



$(OUTPUT)%.8: %.rst

tools/bpf/bpftool/Documentation/bpftool-btf.rst

+49 −55
Original line number Diff line number Diff line
@@ -35,40 +35,35 @@ BTF COMMANDS 
DESCRIPTION

===========

**bpftool btf { show | list }** [**id** *BTF_ID*]

		  Show information about loaded BTF objects. If a BTF ID is

		  specified, show information only about given BTF object,

		  otherwise list all BTF objects currently loaded on the

		  system.

    Show information about loaded BTF objects. If a BTF ID is specified, show

    information only about given BTF object, otherwise list all BTF objects

    currently loaded on the system.



		  Since Linux 5.8 bpftool is able to discover information about

		  processes that hold open file descriptors (FDs) against BTF

		  objects. On such kernels bpftool will automatically emit this

		  information as well.

    Since Linux 5.8 bpftool is able to discover information about processes

    that hold open file descriptors (FDs) against BTF objects. On such kernels

    bpftool will automatically emit this information as well.



**bpftool btf dump** *BTF_SRC*

    Dump BTF entries from a given *BTF_SRC*.



		  When **id** is specified, BTF object with that ID will be

		  loaded and all its BTF types emitted.

    When **id** is specified, BTF object with that ID will be loaded and all

    its BTF types emitted.



		  When **map** is provided, it's expected that map has

		  associated BTF object with BTF types describing key and

		  value. It's possible to select whether to dump only BTF

		  type(s) associated with key (**key**), value (**value**),

		  both key and value (**kv**), or all BTF types present in

		  associated BTF object (**all**). If not specified, **kv**

		  is assumed.

    When **map** is provided, it's expected that map has associated BTF object

    with BTF types describing key and value. It's possible to select whether to

    dump only BTF type(s) associated with key (**key**), value (**value**),

    both key and value (**kv**), or all BTF types present in associated BTF

    object (**all**). If not specified, **kv** is assumed.



		  When **prog** is provided, it's expected that program has

		  associated BTF object with BTF types.

    When **prog** is provided, it's expected that program has associated BTF

    object with BTF types.



		  When specifying *FILE*, an ELF file is expected, containing

		  .BTF section with well-defined BTF binary format data,

		  typically produced by clang or pahole.

    When specifying *FILE*, an ELF file is expected, containing .BTF section

    with well-defined BTF binary format data, typically produced by clang or

    pahole.



		  **format** option can be used to override default (raw)

		  output format. Raw (**raw**) or C-syntax (**c**) output

		  formats are supported.

    **format** option can be used to override default (raw) output format. Raw

    (**raw**) or C-syntax (**c**) output formats are supported.



**bpftool btf help**

    Print short help message.
@@ -78,18 +73,17 @@ OPTIONS 
.. include:: common_options.rst



-B, --base-btf *FILE*

		  Pass a base BTF object. Base BTF objects are typically used

		  with BTF objects for kernel modules. To avoid duplicating

		  all kernel symbols required by modules, BTF objects for

		  modules are "split", they are built incrementally on top of

		  the kernel (vmlinux) BTF object. So the base BTF reference

		  should usually point to the kernel BTF.



		  When the main BTF object to process (for example, the

		  module BTF to dump) is passed as a *FILE*, bpftool attempts

		  to autodetect the path for the base object, and passing

		  this option is optional. When the main BTF object is passed

		  through other handles, this option becomes necessary.

    Pass a base BTF object. Base BTF objects are typically used with BTF

    objects for kernel modules. To avoid duplicating all kernel symbols

    required by modules, BTF objects for modules are "split", they are

    built incrementally on top of the kernel (vmlinux) BTF object. So the

    base BTF reference should usually point to the kernel BTF.



    When the main BTF object to process (for example, the module BTF to

    dump) is passed as a *FILE*, bpftool attempts to autodetect the path

    for the base object, and passing this option is optional. When the main

    BTF object is passed through other handles, this option becomes

    necessary.



EXAMPLES

========

tools/bpf/bpftool/Documentation/bpftool-cgroup.rst

+110 −114
Original line number Diff line number Diff line
@@ -52,46 +52,43 @@ DESCRIPTION 
**bpftool cgroup { show | list }** *CGROUP* [**effective**]

    List all programs attached to the cgroup *CGROUP*.



		  Output will start with program ID followed by attach type,

		  attach flags and program name.

    Output will start with program ID followed by attach type, attach flags and

    program name.



		  If **effective** is specified retrieve effective programs that

		  will execute for events within a cgroup. This includes

		  inherited along with attached ones.

    If **effective** is specified retrieve effective programs that will execute

    for events within a cgroup. This includes inherited along with attached

    ones.



**bpftool cgroup tree** [*CGROUP_ROOT*] [**effective**]

		  Iterate over all cgroups in *CGROUP_ROOT* and list all

		  attached programs. If *CGROUP_ROOT* is not specified,

		  bpftool uses cgroup v2 mountpoint.

    Iterate over all cgroups in *CGROUP_ROOT* and list all attached programs.

    If *CGROUP_ROOT* is not specified, bpftool uses cgroup v2 mountpoint.



		  The output is similar to the output of cgroup show/list

		  commands: it starts with absolute cgroup path, followed by

		  program ID, attach type, attach flags and program name.

    The output is similar to the output of cgroup show/list commands: it starts

    with absolute cgroup path, followed by program ID, attach type, attach

    flags and program name.



		  If **effective** is specified retrieve effective programs that

		  will execute for events within a cgroup. This includes

		  inherited along with attached ones.

    If **effective** is specified retrieve effective programs that will execute

    for events within a cgroup. This includes inherited along with attached

    ones.



**bpftool cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*]

		  Attach program *PROG* to the cgroup *CGROUP* with attach type

		  *ATTACH_TYPE* and optional *ATTACH_FLAGS*.

    Attach program *PROG* to the cgroup *CGROUP* with attach type *ATTACH_TYPE*

    and optional *ATTACH_FLAGS*.



		  *ATTACH_FLAGS* can be one of: **override** if a sub-cgroup installs

		  some bpf program, the program in this cgroup yields to sub-cgroup

		  program; **multi** if a sub-cgroup installs some bpf program,

		  that cgroup program gets run in addition to the program in this

		  cgroup.

    *ATTACH_FLAGS* can be one of: **override** if a sub-cgroup installs some

    bpf program, the program in this cgroup yields to sub-cgroup program;

    **multi** if a sub-cgroup installs some bpf program, that cgroup program

    gets run in addition to the program in this cgroup.



		  Only one program is allowed to be attached to a cgroup with

		  no attach flags or the **override** flag. Attaching another

		  program will release old program and attach the new one.

    Only one program is allowed to be attached to a cgroup with no attach flags

    or the **override** flag. Attaching another program will release old

    program and attach the new one.



		  Multiple programs are allowed to be attached to a cgroup with

		  **multi**. They are executed in FIFO order (those that were

		  attached first, run first).

    Multiple programs are allowed to be attached to a cgroup with **multi**.

    They are executed in FIFO order (those that were attached first, run

    first).



		  Non-default *ATTACH_FLAGS* are supported by kernel version 4.14

		  and later.

    Non-default *ATTACH_FLAGS* are supported by kernel version 4.14 and later.



    *ATTACH_TYPE* can be on of:

    **ingress** ingress path of the inet socket (since 4.10);
@@ -106,18 +103,18 @@ DESCRIPTION 
    **connect4** call to connect(2) for an inet4 socket (since 4.17);

    **connect6** call to connect(2) for an inet6 socket (since 4.17);

    **connect_unix** call to connect(2) for a unix socket (since 6.7);

		  **sendmsg4** call to sendto(2), sendmsg(2), sendmmsg(2) for an

		  unconnected udp4 socket (since 4.18);

		  **sendmsg6** call to sendto(2), sendmsg(2), sendmmsg(2) for an

		  unconnected udp6 socket (since 4.18);

		  **sendmsg_unix** call to sendto(2), sendmsg(2), sendmmsg(2) for

		  an unconnected unix socket (since 6.7);

		  **recvmsg4** call to recvfrom(2), recvmsg(2), recvmmsg(2) for

		  an unconnected udp4 socket (since 5.2);

		  **recvmsg6** call to recvfrom(2), recvmsg(2), recvmmsg(2) for

		  an unconnected udp6 socket (since 5.2);

		  **recvmsg_unix** call to recvfrom(2), recvmsg(2), recvmmsg(2) for

		  an unconnected unix socket (since 6.7);

    **sendmsg4** call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected

    udp4 socket (since 4.18);

    **sendmsg6** call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected

    udp6 socket (since 4.18);

    **sendmsg_unix** call to sendto(2), sendmsg(2), sendmmsg(2) for an

    unconnected unix socket (since 6.7);

    **recvmsg4** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an

    unconnected udp4 socket (since 5.2);

    **recvmsg6** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an

    unconnected udp6 socket (since 5.2);

    **recvmsg_unix** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an

    unconnected unix socket (since 6.7);

    **sysctl** sysctl access (since 5.2);

    **getsockopt** call to getsockopt (since 5.3);

    **setsockopt** call to setsockopt (since 5.3);
@@ -130,8 +127,7 @@ DESCRIPTION 
    **sock_release** closing an userspace inet socket (since 5.9).



**bpftool cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG*

		  Detach *PROG* from the cgroup *CGROUP* and attach type

		  *ATTACH_TYPE*.

    Detach *PROG* from the cgroup *CGROUP* and attach type *ATTACH_TYPE*.



**bpftool prog help**

    Print short help message.

tools/bpf/bpftool/Documentation/bpftool-feature.rst

+54 −61
Original line number Diff line number Diff line
@@ -33,54 +33,47 @@ FEATURE COMMANDS 
DESCRIPTION

===========

**bpftool feature probe** [**kernel**] [**full**] [**macros** [**prefix** *PREFIX*]]

		  Probe the running kernel and dump a number of eBPF-related

		  parameters, such as availability of the **bpf**\ () system call,

		  JIT status, eBPF program types availability, eBPF helper

		  functions availability, and more.



		  By default, bpftool **does not run probes** for

		  **bpf_probe_write_user**\ () and **bpf_trace_printk**\()

		  helpers which print warnings to kernel logs. To enable them

		  and run all probes, the **full** keyword should be used.



		  If the **macros** keyword (but not the **-j** option) is

		  passed, a subset of the output is dumped as a list of

		  **#define** macros that are ready to be included in a C

		  header file, for example. If, additionally, **prefix** is

		  used to define a *PREFIX*, the provided string will be used

		  as a prefix to the names of the macros: this can be used to

		  avoid conflicts on macro names when including the output of

		  this command as a header file.



		  Keyword **kernel** can be omitted. If no probe target is

		  specified, probing the kernel is the default behaviour.



		  When the **unprivileged** keyword is used, bpftool will dump

		  only the features available to a user who does not have the

		  **CAP_SYS_ADMIN** capability set. The features available in

		  that case usually represent a small subset of the parameters

		  supported by the system. Unprivileged users MUST use the

		  **unprivileged** keyword: This is to avoid misdetection if

		  bpftool is inadvertently run as non-root, for example. This

		  keyword is unavailable if bpftool was compiled without

		  libcap.

    Probe the running kernel and dump a number of eBPF-related parameters, such

    as availability of the **bpf**\ () system call, JIT status, eBPF program

    types availability, eBPF helper functions availability, and more.



    By default, bpftool **does not run probes** for **bpf_probe_write_user**\

    () and **bpf_trace_printk**\() helpers which print warnings to kernel logs.

    To enable them and run all probes, the **full** keyword should be used.



    If the **macros** keyword (but not the **-j** option) is passed, a subset

    of the output is dumped as a list of **#define** macros that are ready to

    be included in a C header file, for example. If, additionally, **prefix**

    is used to define a *PREFIX*, the provided string will be used as a prefix

    to the names of the macros: this can be used to avoid conflicts on macro

    names when including the output of this command as a header file.



    Keyword **kernel** can be omitted. If no probe target is specified, probing

    the kernel is the default behaviour.



    When the **unprivileged** keyword is used, bpftool will dump only the

    features available to a user who does not have the **CAP_SYS_ADMIN**

    capability set. The features available in that case usually represent a

    small subset of the parameters supported by the system. Unprivileged users

    MUST use the **unprivileged** keyword: This is to avoid misdetection if

    bpftool is inadvertently run as non-root, for example. This keyword is

    unavailable if bpftool was compiled without libcap.



**bpftool feature probe dev** *NAME* [**full**] [**macros** [**prefix** *PREFIX*]]

		  Probe network device for supported eBPF features and dump

		  results to the console.

    Probe network device for supported eBPF features and dump results to the

    console.



		  The keywords **full**, **macros** and **prefix** have the

		  same role as when probing the kernel.

    The keywords **full**, **macros** and **prefix** have the same role as when

    probing the kernel.



**bpftool feature list_builtins** *GROUP*

    List items known to bpftool. These can be BPF program types

    (**prog_types**), BPF map types (**map_types**), attach types

		  (**attach_types**), link types (**link_types**), or BPF helper

		  functions (**helpers**). The command does not probe the system, but

		  simply lists the elements that bpftool knows from compilation time,

		  as provided from libbpf (for all object types) or from the BPF UAPI

		  header (list of helpers). This can be used in scripts to iterate over

		  BPF types or helpers.

    (**attach_types**), link types (**link_types**), or BPF helper functions

    (**helpers**). The command does not probe the system, but simply lists the

    elements that bpftool knows from compilation time, as provided from libbpf

    (for all object types) or from the BPF UAPI header (list of helpers). This

    can be used in scripts to iterate over BPF types or helpers.



**bpftool feature help**

    Print short help message.

tools/bpf/bpftool/Documentation/bpftool-gen.rst

+158 −180

File changed.

Preview size limit exceeded, changes collapsed.