Skip to content

Commit ff69c21

Browse files
Jakub Kicinskidavem330
Jakub Kicinski
authored and
davem330
committed
tools: bpftool: add documentation
Add documentation for bpftool. Separate files for each subcommand. Use rst format. Documentation is compiled into man pages using rst2man. Signed-off-by: David Beckett <[email protected]> Signed-off-by: Jakub Kicinski <[email protected]> Acked-by: Alexei Starovoitov <[email protected]> Acked-by: Daniel Borkmann <[email protected]> Signed-off-by: David S. Miller <[email protected]>
1 parent 71bb428 commit ff69c21

File tree

5 files changed

+263
-0
lines changed

5 files changed

+263
-0
lines changed

‎tools/bpf/bpftool/Documentation/Makefile

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
include ../../../scripts/Makefile.include
2+
include ../../../scripts/utilities.mak
3+
4+
INSTALL ?= install
5+
RM ?= rm -f
6+
7+
# Make the path relative to DESTDIR, not prefix
8+
ifndef DESTDIR
9+
prefix?=$(HOME)
10+
endif
11+
mandir ?= $(prefix)/share/man
12+
man8dir = $(mandir)/man8
13+
14+
MAN8_RST = $(wildcard *.rst)
15+
16+
_DOC_MAN8 = $(patsubst %.rst,%.8,$(MAN8_RST))
17+
DOC_MAN8 = $(addprefix $(OUTPUT),$(_DOC_MAN8))
18+
19+
man: man8
20+
man8: $(DOC_MAN8)
21+
22+
$(OUTPUT)%.8: %.rst
23+
rst2man $< > $@
24+
25+
clean:
26+
$(call QUIET_CLEAN, Documentation) $(RM) $(DOC_MAN8)
27+
28+
install: man
29+
$(call QUIET_INSTALL, Documentation-man) \
30+
$(INSTALL) -d -m 755 $(DESTDIR)$(man8dir); \
31+
$(INSTALL) -m 644 $(DOC_MAN8) $(DESTDIR)$(man8dir);
32+
33+
.PHONY: man man8 clean install
34+
.DEFAULT_GOAL := man

‎tools/bpf/bpftool/Documentation/bpftool-map.rst

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
================
2+
bpftool-map
3+
================
4+
-------------------------------------------------------------------------------
5+
tool for inspection and simple manipulation of eBPF maps
6+
-------------------------------------------------------------------------------
7+
8+
:Manual section: 8
9+
10+
SYNOPSIS
11+
========
12+
13+
**bpftool** **map** *COMMAND*
14+
15+
*COMMANDS* :=
16+
{ show | dump | update | lookup | getnext | delete | pin | help }
17+
18+
MAP COMMANDS
19+
=============
20+
21+
| **bpftool** map show [*MAP*]
22+
| **bpftool** map dump *MAP*
23+
| **bpftool** map update *MAP* key *BYTES* value *VALUE* [*UPDATE_FLAGS*]
24+
| **bpftool** map lookup *MAP* key *BYTES*
25+
| **bpftool** map getnext *MAP* [key *BYTES*]
26+
| **bpftool** map delete *MAP* key *BYTES*
27+
| **bpftool** map pin *MAP* *FILE*
28+
| **bpftool** map help
29+
|
30+
| *MAP* := { id MAP_ID | pinned FILE }
31+
| *VALUE* := { BYTES | MAP | PROGRAM }
32+
| *UPDATE_FLAGS* := { any | exist | noexist }
33+
34+
DESCRIPTION
35+
===========
36+
**bpftool map show** [*MAP*]
37+
Show information about loaded maps. If *MAP* is specified
38+
show information only about given map, otherwise list all
39+
maps currently loaded on the system.
40+
41+
Output will start with map ID followed by map type and
42+
zero or more named attributes (depending on kernel version).
43+
44+
**bpftool map dump** *MAP*
45+
Dump all entries in a given *MAP*.
46+
47+
**bpftool map update** *MAP* **key** *BYTES* **value** *VALUE* [*UPDATE_FLAGS*]
48+
Update map entry for a given *KEY*.
49+
50+
*UPDATE_FLAGS* can be one of: **any** update existing entry
51+
or add if doesn't exit; **exist** update only if entry already
52+
exists; **noexist** update only if entry doesn't exist.
53+
54+
**bpftool map lookup** *MAP* **key** *BYTES*
55+
Lookup **key** in the map.
56+
57+
**bpftool map getnext** *MAP* [**key** *BYTES*]
58+
Get next key. If *key* is not specified, get first key.
59+
60+
**bpftool map delete** *MAP* **key** *BYTES*
61+
Remove entry from the map.
62+
63+
**bpftool map pin** *MAP* *FILE*
64+
Pin map *MAP* as *FILE*.
65+
66+
Note: *FILE* must be located in *bpffs* mount.
67+
68+
**bpftool map help**
69+
Print short help message.
70+
71+
EXAMPLES
72+
========
73+
**# bpftool map show**
74+
::
75+
76+
10: hash name some_map flags 0x0
77+
key 4B value 8B max_entries 2048 memlock 167936B
78+
79+
**# bpftool map update id 10 key 13 00 07 00 value 02 00 00 00 01 02 03 04**
80+
81+
**# bpftool map lookup id 10 key 0 1 2 3**
82+
83+
::
84+
85+
key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
86+
87+
88+
**# bpftool map dump id 10**
89+
::
90+
91+
key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
92+
key: 0d 00 07 00 value: 02 00 00 00 01 02 03 04
93+
Found 2 elements
94+
95+
**# bpftool map getnext id 10 key 0 1 2 3**
96+
::
97+
98+
key:
99+
00 01 02 03
100+
next key:
101+
0d 00 07 00
102+
103+
|
104+
| **# mount -t bpf none /sys/fs/bpf/**
105+
| **# bpftool map pin id 10 /sys/fs/bpf/map**
106+
| **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00**
107+
108+
SEE ALSO
109+
========
110+
**bpftool**\ (8), **bpftool-prog**\ (8)

‎tools/bpf/bpftool/Documentation/bpftool-prog.rst

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
================
2+
bpftool-prog
3+
================
4+
-------------------------------------------------------------------------------
5+
tool for inspection and simple manipulation of eBPF progs
6+
-------------------------------------------------------------------------------
7+
8+
:Manual section: 8
9+
10+
SYNOPSIS
11+
========
12+
13+
| **bpftool** prog show [*PROG*]
14+
| **bpftool** prog dump xlated *PROG* file *FILE*
15+
| **bpftool** prog dump jited *PROG* [file *FILE*] [opcodes]
16+
| **bpftool** prog pin *PROG* *FILE*
17+
| **bpftool** prog help
18+
|
19+
| *PROG* := { id *PROG_ID* | pinned *FILE* | tag *PROG_TAG* }
20+
21+
DESCRIPTION
22+
===========
23+
**bpftool prog show** [*PROG*]
24+
Show information about loaded programs. If *PROG* is
25+
specified show information only about given program, otherwise
26+
list all programs currently loaded on the system.
27+
28+
Output will start with program ID followed by program type and
29+
zero or more named attributes (depending on kernel version).
30+
31+
**bpftool prog dump xlated** *PROG* **file** *FILE*
32+
Dump eBPF instructions of the program from the kernel to a
33+
file.
34+
35+
**bpftool prog dump jited** *PROG* [**file** *FILE*] [**opcodes**]
36+
Dump jited image (host machine code) of the program.
37+
If *FILE* is specified image will be written to a file,
38+
otherwise it will be disassembled and printed to stdout.
39+
40+
**opcodes** controls if raw opcodes will be printed.
41+
42+
**bpftool prog pin** *PROG* *FILE*
43+
Pin program *PROG* as *FILE*.
44+
45+
Note: *FILE* must be located in *bpffs* mount.
46+
47+
**bpftool prog help**
48+
Print short help message.
49+
50+
EXAMPLES
51+
========
52+
**# bpftool prog show**
53+
::
54+
55+
10: xdp name some_prog tag 00:5a:3d:21:23:62:0c:8b
56+
loaded_at Sep 29/20:11 uid 0
57+
xlated 528B jited 370B memlock 4096B map_ids 10
58+
59+
|
60+
| **# bpftool prog dump xlated id 10 file /tmp/t**
61+
| **# ls -l /tmp/t**
62+
| -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
63+
64+
|
65+
| **# bpftool prog dum jited pinned /sys/fs/bpf/prog**
66+
67+
::
68+
69+
push %rbp
70+
mov %rsp,%rbp
71+
sub $0x228,%rsp
72+
sub $0x28,%rbp
73+
mov %rbx,0x0(%rbp)
74+
75+
76+
77+
SEE ALSO
78+
========
79+
**bpftool**\ (8), **bpftool-map**\ (8)

‎tools/bpf/bpftool/Documentation/bpftool.rst

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
================
2+
BPFTOOL
3+
================
4+
-------------------------------------------------------------------------------
5+
tool for inspection and simple manipulation of eBPF programs and maps
6+
-------------------------------------------------------------------------------
7+
8+
:Manual section: 8
9+
10+
SYNOPSIS
11+
========
12+
13+
**bpftool** *OBJECT* { *COMMAND* | help }
14+
15+
**bpftool** batch file *FILE*
16+
17+
*OBJECT* := { **map** | **program** }
18+
19+
*MAP-COMMANDS* :=
20+
{ show | dump | update | lookup | getnext | delete | pin | help }
21+
22+
*PROG-COMMANDS* := { show | dump jited | dump xlated | pin | help }
23+
24+
DESCRIPTION
25+
===========
26+
*bpftool* allows for inspection and simple modification of BPF objects
27+
on the system.
28+
29+
Note that format of the output of all tools is not guaranteed to be
30+
stable and should not be depended upon.
31+
32+
SEE ALSO
33+
========
34+
**bpftool-map**\ (8), **bpftool-prog**\ (8)

‎tools/bpf/bpftool/Makefile

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,12 @@ clean: $(LIBBPF)-clean
7474
install:
7575
install $(OUTPUT)bpftool $(prefix)/sbin/bpftool
7676

77+
doc:
78+
$(Q)$(MAKE) -C Documentation/
79+
80+
doc-install:
81+
$(Q)$(MAKE) -C Documentation/ install
82+
7783
FORCE:
7884

7985
.PHONY: all clean FORCE

0 commit comments

Comments
 (0)