Skip to content

Commit 0451298

Browse files
rameezrehman408qmonnet
rameezrehman408
authored and
qmonnet
committed
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: Rameez Rehman <[email protected]> Signed-off-by: Quentin Monnet <[email protected]> Signed-off-by: Daniel Borkmann <[email protected]> Link: https://lore.kernel.org/bpf/[email protected]
1 parent 9a40292 commit 0451298

14 files changed

+908
-991
lines changed

‎docs/Makefile

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,9 @@ see_also = $(subst " ",, \
3131
"\n" \
3232
"SEE ALSO\n" \
3333
"========\n" \
34-
"\t**bpf**\ (2),\n" \
35-
"\t**bpf-helpers**\\ (7)" \
36-
$(foreach page,$(call list_pages,$(1)),",\n\t**$(page)**\\ (8)") \
34+
"**bpf**\ (2),\n" \
35+
"**bpf-helpers**\\ (7)" \
36+
$(foreach page,$(call list_pages,$(1)),",\n**$(page)**\\ (8)") \
3737
"\n")
3838

3939
$(OUTPUT)%.8: %.rst

‎docs/bpftool-btf.rst

Lines changed: 49 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -14,82 +14,76 @@ tool for inspection of BTF data
1414
SYNOPSIS
1515
========
1616

17-
**bpftool** [*OPTIONS*] **btf** *COMMAND*
17+
**bpftool** [*OPTIONS*] **btf** *COMMAND*
1818

19-
*OPTIONS* := { |COMMON_OPTIONS| | { **-B** | **--base-btf** } }
19+
*OPTIONS* := { |COMMON_OPTIONS| | { **-B** | **--base-btf** } }
2020

21-
*COMMANDS* := { **dump** | **help** }
21+
*COMMANDS* := { **dump** | **help** }
2222

2323
BTF COMMANDS
2424
=============
2525

26-
| **bpftool** **btf** { **show** | **list** } [**id** *BTF_ID*]
27-
| **bpftool** **btf dump** *BTF_SRC* [**format** *FORMAT*]
28-
| **bpftool** **btf help**
26+
| **bpftool** **btf** { **show** | **list** } [**id** *BTF_ID*]
27+
| **bpftool** **btf dump** *BTF_SRC* [**format** *FORMAT*]
28+
| **bpftool** **btf help**
2929
|
30-
| *BTF_SRC* := { **id** *BTF_ID* | **prog** *PROG* | **map** *MAP* [{**key** | **value** | **kv** | **all**}] | **file** *FILE* }
31-
| *FORMAT* := { **raw** | **c** }
32-
| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
33-
| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
30+
| *BTF_SRC* := { **id** *BTF_ID* | **prog** *PROG* | **map** *MAP* [{**key** | **value** | **kv** | **all**}] | **file** *FILE* }
31+
| *FORMAT* := { **raw** | **c** }
32+
| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
33+
| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
3434
3535
DESCRIPTION
3636
===========
37-
**bpftool btf { show | list }** [**id** *BTF_ID*]
38-
Show information about loaded BTF objects. If a BTF ID is
39-
specified, show information only about given BTF object,
40-
otherwise list all BTF objects currently loaded on the
41-
system.
37+
**bpftool btf { show | list }** [**id** *BTF_ID*]
38+
Show information about loaded BTF objects. If a BTF ID is specified, show
39+
information only about given BTF object, otherwise list all BTF objects
40+
currently loaded on the system.
4241

43-
Since Linux 5.8 bpftool is able to discover information about
44-
processes that hold open file descriptors (FDs) against BTF
45-
objects. On such kernels bpftool will automatically emit this
46-
information as well.
42+
Since Linux 5.8 bpftool is able to discover information about processes
43+
that hold open file descriptors (FDs) against BTF objects. On such kernels
44+
bpftool will automatically emit this information as well.
4745

48-
**bpftool btf dump** *BTF_SRC*
49-
Dump BTF entries from a given *BTF_SRC*.
46+
**bpftool btf dump** *BTF_SRC*
47+
Dump BTF entries from a given *BTF_SRC*.
5048

51-
When **id** is specified, BTF object with that ID will be
52-
loaded and all its BTF types emitted.
49+
When **id** is specified, BTF object with that ID will be loaded and all
50+
its BTF types emitted.
5351

54-
When **map** is provided, it's expected that map has
55-
associated BTF object with BTF types describing key and
56-
value. It's possible to select whether to dump only BTF
57-
type(s) associated with key (**key**), value (**value**),
58-
both key and value (**kv**), or all BTF types present in
59-
associated BTF object (**all**). If not specified, **kv**
60-
is assumed.
52+
When **map** is provided, it's expected that map has associated BTF object
53+
with BTF types describing key and value. It's possible to select whether to
54+
dump only BTF type(s) associated with key (**key**), value (**value**),
55+
both key and value (**kv**), or all BTF types present in associated BTF
56+
object (**all**). If not specified, **kv** is assumed.
6157

62-
When **prog** is provided, it's expected that program has
63-
associated BTF object with BTF types.
58+
When **prog** is provided, it's expected that program has associated BTF
59+
object with BTF types.
6460

65-
When specifying *FILE*, an ELF file is expected, containing
66-
.BTF section with well-defined BTF binary format data,
67-
typically produced by clang or pahole.
61+
When specifying *FILE*, an ELF file is expected, containing .BTF section
62+
with well-defined BTF binary format data, typically produced by clang or
63+
pahole.
6864

69-
**format** option can be used to override default (raw)
70-
output format. Raw (**raw**) or C-syntax (**c**) output
71-
formats are supported.
65+
**format** option can be used to override default (raw) output format. Raw
66+
(**raw**) or C-syntax (**c**) output formats are supported.
7267

73-
**bpftool btf help**
74-
Print short help message.
68+
**bpftool btf help**
69+
Print short help message.
7570

7671
OPTIONS
7772
=======
78-
.. include:: common_options.rst
79-
80-
-B, --base-btf *FILE*
81-
Pass a base BTF object. Base BTF objects are typically used
82-
with BTF objects for kernel modules. To avoid duplicating
83-
all kernel symbols required by modules, BTF objects for
84-
modules are "split", they are built incrementally on top of
85-
the kernel (vmlinux) BTF object. So the base BTF reference
86-
should usually point to the kernel BTF.
87-
88-
When the main BTF object to process (for example, the
89-
module BTF to dump) is passed as a *FILE*, bpftool attempts
90-
to autodetect the path for the base object, and passing
91-
this option is optional. When the main BTF object is passed
92-
through other handles, this option becomes necessary.
73+
.. include:: common_options.rst
74+
75+
-B, --base-btf *FILE*
76+
Pass a base BTF object. Base BTF objects are typically used with BTF
77+
objects for kernel modules. To avoid duplicating all kernel symbols
78+
required by modules, BTF objects for modules are "split", they are
79+
built incrementally on top of the kernel (vmlinux) BTF object. So the
80+
base BTF reference should usually point to the kernel BTF.
81+
82+
When the main BTF object to process (for example, the module BTF to
83+
dump) is passed as a *FILE*, bpftool attempts to autodetect the path
84+
for the base object, and passing this option is optional. When the main
85+
BTF object is passed through other handles, this option becomes
86+
necessary.
9387

9488
EXAMPLES
9589
========

‎docs/bpftool-cgroup.rst

Lines changed: 110 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -14,134 +14,130 @@ tool for inspection and simple manipulation of eBPF progs
1414
SYNOPSIS
1515
========
1616

17-
**bpftool** [*OPTIONS*] **cgroup** *COMMAND*
17+
**bpftool** [*OPTIONS*] **cgroup** *COMMAND*
1818

19-
*OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } }
19+
*OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } }
2020

21-
*COMMANDS* :=
22-
{ **show** | **list** | **tree** | **attach** | **detach** | **help** }
21+
*COMMANDS* :=
22+
{ **show** | **list** | **tree** | **attach** | **detach** | **help** }
2323

2424
CGROUP COMMANDS
2525
===============
2626

27-
| **bpftool** **cgroup** { **show** | **list** } *CGROUP* [**effective**]
28-
| **bpftool** **cgroup tree** [*CGROUP_ROOT*] [**effective**]
29-
| **bpftool** **cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*]
30-
| **bpftool** **cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG*
31-
| **bpftool** **cgroup help**
27+
| **bpftool** **cgroup** { **show** | **list** } *CGROUP* [**effective**]
28+
| **bpftool** **cgroup tree** [*CGROUP_ROOT*] [**effective**]
29+
| **bpftool** **cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*]
30+
| **bpftool** **cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG*
31+
| **bpftool** **cgroup help**
3232
|
33-
| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
34-
| *ATTACH_TYPE* := { **cgroup_inet_ingress** | **cgroup_inet_egress** |
35-
| **cgroup_inet_sock_create** | **cgroup_sock_ops** |
36-
| **cgroup_device** | **cgroup_inet4_bind** | **cgroup_inet6_bind** |
37-
| **cgroup_inet4_post_bind** | **cgroup_inet6_post_bind** |
38-
| **cgroup_inet4_connect** | **cgroup_inet6_connect** |
39-
| **cgroup_unix_connect** | **cgroup_inet4_getpeername** |
40-
| **cgroup_inet6_getpeername** | **cgroup_unix_getpeername** |
41-
| **cgroup_inet4_getsockname** | **cgroup_inet6_getsockname** |
42-
| **cgroup_unix_getsockname** | **cgroup_udp4_sendmsg** |
43-
| **cgroup_udp6_sendmsg** | **cgroup_unix_sendmsg** |
44-
| **cgroup_udp4_recvmsg** | **cgroup_udp6_recvmsg** |
45-
| **cgroup_unix_recvmsg** | **cgroup_sysctl** |
46-
| **cgroup_getsockopt** | **cgroup_setsockopt** |
47-
| **cgroup_inet_sock_release** }
48-
| *ATTACH_FLAGS* := { **multi** | **override** }
33+
| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
34+
| *ATTACH_TYPE* := { **cgroup_inet_ingress** | **cgroup_inet_egress** |
35+
| **cgroup_inet_sock_create** | **cgroup_sock_ops** |
36+
| **cgroup_device** | **cgroup_inet4_bind** | **cgroup_inet6_bind** |
37+
| **cgroup_inet4_post_bind** | **cgroup_inet6_post_bind** |
38+
| **cgroup_inet4_connect** | **cgroup_inet6_connect** |
39+
| **cgroup_unix_connect** | **cgroup_inet4_getpeername** |
40+
| **cgroup_inet6_getpeername** | **cgroup_unix_getpeername** |
41+
| **cgroup_inet4_getsockname** | **cgroup_inet6_getsockname** |
42+
| **cgroup_unix_getsockname** | **cgroup_udp4_sendmsg** |
43+
| **cgroup_udp6_sendmsg** | **cgroup_unix_sendmsg** |
44+
| **cgroup_udp4_recvmsg** | **cgroup_udp6_recvmsg** |
45+
| **cgroup_unix_recvmsg** | **cgroup_sysctl** |
46+
| **cgroup_getsockopt** | **cgroup_setsockopt** |
47+
| **cgroup_inet_sock_release** }
48+
| *ATTACH_FLAGS* := { **multi** | **override** }
4949
5050
DESCRIPTION
5151
===========
52-
**bpftool cgroup { show | list }** *CGROUP* [**effective**]
53-
List all programs attached to the cgroup *CGROUP*.
54-
55-
Output will start with program ID followed by attach type,
56-
attach flags and program name.
57-
58-
If **effective** is specified retrieve effective programs that
59-
will execute for events within a cgroup. This includes
60-
inherited along with attached ones.
61-
62-
**bpftool cgroup tree** [*CGROUP_ROOT*] [**effective**]
63-
Iterate over all cgroups in *CGROUP_ROOT* and list all
64-
attached programs. If *CGROUP_ROOT* is not specified,
65-
bpftool uses cgroup v2 mountpoint.
66-
67-
The output is similar to the output of cgroup show/list
68-
commands: it starts with absolute cgroup path, followed by
69-
program ID, attach type, attach flags and program name.
70-
71-
If **effective** is specified retrieve effective programs that
72-
will execute for events within a cgroup. This includes
73-
inherited along with attached ones.
74-
75-
**bpftool cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*]
76-
Attach program *PROG* to the cgroup *CGROUP* with attach type
77-
*ATTACH_TYPE* and optional *ATTACH_FLAGS*.
78-
79-
*ATTACH_FLAGS* can be one of: **override** if a sub-cgroup installs
80-
some bpf program, the program in this cgroup yields to sub-cgroup
81-
program; **multi** if a sub-cgroup installs some bpf program,
82-
that cgroup program gets run in addition to the program in this
83-
cgroup.
84-
85-
Only one program is allowed to be attached to a cgroup with
86-
no attach flags or the **override** flag. Attaching another
87-
program will release old program and attach the new one.
88-
89-
Multiple programs are allowed to be attached to a cgroup with
90-
**multi**. They are executed in FIFO order (those that were
91-
attached first, run first).
92-
93-
Non-default *ATTACH_FLAGS* are supported by kernel version 4.14
94-
and later.
95-
96-
*ATTACH_TYPE* can be on of:
97-
**ingress** ingress path of the inet socket (since 4.10);
98-
**egress** egress path of the inet socket (since 4.10);
99-
**sock_create** opening of an inet socket (since 4.10);
100-
**sock_ops** various socket operations (since 4.12);
101-
**device** device access (since 4.15);
102-
**bind4** call to bind(2) for an inet4 socket (since 4.17);
103-
**bind6** call to bind(2) for an inet6 socket (since 4.17);
104-
**post_bind4** return from bind(2) for an inet4 socket (since 4.17);
105-
**post_bind6** return from bind(2) for an inet6 socket (since 4.17);
106-
**connect4** call to connect(2) for an inet4 socket (since 4.17);
107-
**connect6** call to connect(2) for an inet6 socket (since 4.17);
108-
**connect_unix** call to connect(2) for a unix socket (since 6.7);
109-
**sendmsg4** call to sendto(2), sendmsg(2), sendmmsg(2) for an
110-
unconnected udp4 socket (since 4.18);
111-
**sendmsg6** call to sendto(2), sendmsg(2), sendmmsg(2) for an
112-
unconnected udp6 socket (since 4.18);
113-
**sendmsg_unix** call to sendto(2), sendmsg(2), sendmmsg(2) for
114-
an unconnected unix socket (since 6.7);
115-
**recvmsg4** call to recvfrom(2), recvmsg(2), recvmmsg(2) for
116-
an unconnected udp4 socket (since 5.2);
117-
**recvmsg6** call to recvfrom(2), recvmsg(2), recvmmsg(2) for
118-
an unconnected udp6 socket (since 5.2);
119-
**recvmsg_unix** call to recvfrom(2), recvmsg(2), recvmmsg(2) for
120-
an unconnected unix socket (since 6.7);
121-
**sysctl** sysctl access (since 5.2);
122-
**getsockopt** call to getsockopt (since 5.3);
123-
**setsockopt** call to setsockopt (since 5.3);
124-
**getpeername4** call to getpeername(2) for an inet4 socket (since 5.8);
125-
**getpeername6** call to getpeername(2) for an inet6 socket (since 5.8);
126-
**getpeername_unix** call to getpeername(2) for a unix socket (since 6.7);
127-
**getsockname4** call to getsockname(2) for an inet4 socket (since 5.8);
128-
**getsockname6** call to getsockname(2) for an inet6 socket (since 5.8).
129-
**getsockname_unix** call to getsockname(2) for a unix socket (since 6.7);
130-
**sock_release** closing an userspace inet socket (since 5.9).
131-
132-
**bpftool cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG*
133-
Detach *PROG* from the cgroup *CGROUP* and attach type
134-
*ATTACH_TYPE*.
135-
136-
**bpftool prog help**
137-
Print short help message.
52+
**bpftool cgroup { show | list }** *CGROUP* [**effective**]
53+
List all programs attached to the cgroup *CGROUP*.
54+
55+
Output will start with program ID followed by attach type, attach flags and
56+
program name.
57+
58+
If **effective** is specified retrieve effective programs that will execute
59+
for events within a cgroup. This includes inherited along with attached
60+
ones.
61+
62+
**bpftool cgroup tree** [*CGROUP_ROOT*] [**effective**]
63+
Iterate over all cgroups in *CGROUP_ROOT* and list all attached programs.
64+
If *CGROUP_ROOT* is not specified, bpftool uses cgroup v2 mountpoint.
65+
66+
The output is similar to the output of cgroup show/list commands: it starts
67+
with absolute cgroup path, followed by program ID, attach type, attach
68+
flags and program name.
69+
70+
If **effective** is specified retrieve effective programs that will execute
71+
for events within a cgroup. This includes inherited along with attached
72+
ones.
73+
74+
**bpftool cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*]
75+
Attach program *PROG* to the cgroup *CGROUP* with attach type *ATTACH_TYPE*
76+
and optional *ATTACH_FLAGS*.
77+
78+
*ATTACH_FLAGS* can be one of: **override** if a sub-cgroup installs some
79+
bpf program, the program in this cgroup yields to sub-cgroup program;
80+
**multi** if a sub-cgroup installs some bpf program, that cgroup program
81+
gets run in addition to the program in this cgroup.
82+
83+
Only one program is allowed to be attached to a cgroup with no attach flags
84+
or the **override** flag. Attaching another program will release old
85+
program and attach the new one.
86+
87+
Multiple programs are allowed to be attached to a cgroup with **multi**.
88+
They are executed in FIFO order (those that were attached first, run
89+
first).
90+
91+
Non-default *ATTACH_FLAGS* are supported by kernel version 4.14 and later.
92+
93+
*ATTACH_TYPE* can be on of:
94+
**ingress** ingress path of the inet socket (since 4.10);
95+
**egress** egress path of the inet socket (since 4.10);
96+
**sock_create** opening of an inet socket (since 4.10);
97+
**sock_ops** various socket operations (since 4.12);
98+
**device** device access (since 4.15);
99+
**bind4** call to bind(2) for an inet4 socket (since 4.17);
100+
**bind6** call to bind(2) for an inet6 socket (since 4.17);
101+
**post_bind4** return from bind(2) for an inet4 socket (since 4.17);
102+
**post_bind6** return from bind(2) for an inet6 socket (since 4.17);
103+
**connect4** call to connect(2) for an inet4 socket (since 4.17);
104+
**connect6** call to connect(2) for an inet6 socket (since 4.17);
105+
**connect_unix** call to connect(2) for a unix socket (since 6.7);
106+
**sendmsg4** call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected
107+
udp4 socket (since 4.18);
108+
**sendmsg6** call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected
109+
udp6 socket (since 4.18);
110+
**sendmsg_unix** call to sendto(2), sendmsg(2), sendmmsg(2) for an
111+
unconnected unix socket (since 6.7);
112+
**recvmsg4** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an
113+
unconnected udp4 socket (since 5.2);
114+
**recvmsg6** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an
115+
unconnected udp6 socket (since 5.2);
116+
**recvmsg_unix** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an
117+
unconnected unix socket (since 6.7);
118+
**sysctl** sysctl access (since 5.2);
119+
**getsockopt** call to getsockopt (since 5.3);
120+
**setsockopt** call to setsockopt (since 5.3);
121+
**getpeername4** call to getpeername(2) for an inet4 socket (since 5.8);
122+
**getpeername6** call to getpeername(2) for an inet6 socket (since 5.8);
123+
**getpeername_unix** call to getpeername(2) for a unix socket (since 6.7);
124+
**getsockname4** call to getsockname(2) for an inet4 socket (since 5.8);
125+
**getsockname6** call to getsockname(2) for an inet6 socket (since 5.8).
126+
**getsockname_unix** call to getsockname(2) for a unix socket (since 6.7);
127+
**sock_release** closing an userspace inet socket (since 5.9).
128+
129+
**bpftool cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG*
130+
Detach *PROG* from the cgroup *CGROUP* and attach type *ATTACH_TYPE*.
131+
132+
**bpftool prog help**
133+
Print short help message.
138134

139135
OPTIONS
140136
=======
141-
.. include:: common_options.rst
137+
.. include:: common_options.rst
142138

143-
-f, --bpffs
144-
Show file names of pinned programs.
139+
-f, --bpffs
140+
Show file names of pinned programs.
145141

146142
EXAMPLES
147143
========

0 commit comments

Comments
 (0)