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 <david.beckett@netronome.com>
Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com>
Acked-by: Alexei Starovoitov <ast@kernel.org>
Acked-by: Daniel Borkmann <daniel@iogearbox.net>
Signed-off-by: David S. Miller <davem@davemloft.net>
This commit is contained in:
Jakub Kicinski 2017-10-04 20:10:05 -07:00 committed by David S. Miller
parent 71bb428fe2
commit ff69c21a85
5 changed files with 263 additions and 0 deletions

View File

@ -0,0 +1,34 @@
include ../../../scripts/Makefile.include
include ../../../scripts/utilities.mak
INSTALL ?= install
RM ?= rm -f
# Make the path relative to DESTDIR, not prefix
ifndef DESTDIR
prefix?=$(HOME)
endif
mandir ?= $(prefix)/share/man
man8dir = $(mandir)/man8
MAN8_RST = $(wildcard *.rst)
_DOC_MAN8 = $(patsubst %.rst,%.8,$(MAN8_RST))
DOC_MAN8 = $(addprefix $(OUTPUT),$(_DOC_MAN8))
man: man8
man8: $(DOC_MAN8)
$(OUTPUT)%.8: %.rst
rst2man $< > $@
clean:
$(call QUIET_CLEAN, Documentation) $(RM) $(DOC_MAN8)
install: man
$(call QUIET_INSTALL, Documentation-man) \
$(INSTALL) -d -m 755 $(DESTDIR)$(man8dir); \
$(INSTALL) -m 644 $(DOC_MAN8) $(DESTDIR)$(man8dir);
.PHONY: man man8 clean install
.DEFAULT_GOAL := man

View File

@ -0,0 +1,110 @@
================
bpftool-map
================
-------------------------------------------------------------------------------
tool for inspection and simple manipulation of eBPF maps
-------------------------------------------------------------------------------
:Manual section: 8
SYNOPSIS
========
**bpftool** **map** *COMMAND*
*COMMANDS* :=
{ show | dump | update | lookup | getnext | delete | pin | help }
MAP COMMANDS
=============
| **bpftool** map show [*MAP*]
| **bpftool** map dump *MAP*
| **bpftool** map update *MAP* key *BYTES* value *VALUE* [*UPDATE_FLAGS*]
| **bpftool** map lookup *MAP* key *BYTES*
| **bpftool** map getnext *MAP* [key *BYTES*]
| **bpftool** map delete *MAP* key *BYTES*
| **bpftool** map pin *MAP* *FILE*
| **bpftool** map help
|
| *MAP* := { id MAP_ID | pinned FILE }
| *VALUE* := { BYTES | MAP | PROGRAM }
| *UPDATE_FLAGS* := { any | exist | noexist }
DESCRIPTION
===========
**bpftool map show** [*MAP*]
Show information about loaded maps. If *MAP* is specified
show information only about given map, otherwise list all
maps currently loaded on the system.
Output will start with map ID followed by map type and
zero or more named attributes (depending on kernel version).
**bpftool map dump** *MAP*
Dump all entries in a given *MAP*.
**bpftool map update** *MAP* **key** *BYTES* **value** *VALUE* [*UPDATE_FLAGS*]
Update map entry for a given *KEY*.
*UPDATE_FLAGS* can be one of: **any** update existing entry
or add if doesn't exit; **exist** update only if entry already
exists; **noexist** update only if entry doesn't exist.
**bpftool map lookup** *MAP* **key** *BYTES*
Lookup **key** in the map.
**bpftool map getnext** *MAP* [**key** *BYTES*]
Get next key. If *key* is not specified, get first key.
**bpftool map delete** *MAP* **key** *BYTES*
Remove entry from the map.
**bpftool map pin** *MAP* *FILE*
Pin map *MAP* as *FILE*.
Note: *FILE* must be located in *bpffs* mount.
**bpftool map help**
Print short help message.
EXAMPLES
========
**# bpftool map show**
::
10: hash name some_map flags 0x0
key 4B value 8B max_entries 2048 memlock 167936B
**# bpftool map update id 10 key 13 00 07 00 value 02 00 00 00 01 02 03 04**
**# bpftool map lookup id 10 key 0 1 2 3**
::
key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
**# bpftool map dump id 10**
::
key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
key: 0d 00 07 00 value: 02 00 00 00 01 02 03 04
Found 2 elements
**# bpftool map getnext id 10 key 0 1 2 3**
::
key:
00 01 02 03
next key:
0d 00 07 00
|
| **# mount -t bpf none /sys/fs/bpf/**
| **# bpftool map pin id 10 /sys/fs/bpf/map**
| **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00**
SEE ALSO
========
**bpftool**\ (8), **bpftool-prog**\ (8)

View File

@ -0,0 +1,79 @@
================
bpftool-prog
================
-------------------------------------------------------------------------------
tool for inspection and simple manipulation of eBPF progs
-------------------------------------------------------------------------------
:Manual section: 8
SYNOPSIS
========
| **bpftool** prog show [*PROG*]
| **bpftool** prog dump xlated *PROG* file *FILE*
| **bpftool** prog dump jited *PROG* [file *FILE*] [opcodes]
| **bpftool** prog pin *PROG* *FILE*
| **bpftool** prog help
|
| *PROG* := { id *PROG_ID* | pinned *FILE* | tag *PROG_TAG* }
DESCRIPTION
===========
**bpftool prog show** [*PROG*]
Show information about loaded programs. If *PROG* is
specified show information only about given program, otherwise
list all programs currently loaded on the system.
Output will start with program ID followed by program type and
zero or more named attributes (depending on kernel version).
**bpftool prog dump xlated** *PROG* **file** *FILE*
Dump eBPF instructions of the program from the kernel to a
file.
**bpftool prog dump jited** *PROG* [**file** *FILE*] [**opcodes**]
Dump jited image (host machine code) of the program.
If *FILE* is specified image will be written to a file,
otherwise it will be disassembled and printed to stdout.
**opcodes** controls if raw opcodes will be printed.
**bpftool prog pin** *PROG* *FILE*
Pin program *PROG* as *FILE*.
Note: *FILE* must be located in *bpffs* mount.
**bpftool prog help**
Print short help message.
EXAMPLES
========
**# bpftool prog show**
::
10: xdp name some_prog tag 00:5a:3d:21:23:62:0c:8b
loaded_at Sep 29/20:11 uid 0
xlated 528B jited 370B memlock 4096B map_ids 10
|
| **# bpftool prog dump xlated id 10 file /tmp/t**
| **# ls -l /tmp/t**
| -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
|
| **# bpftool prog dum jited pinned /sys/fs/bpf/prog**
::
push %rbp
mov %rsp,%rbp
sub $0x228,%rsp
sub $0x28,%rbp
mov %rbx,0x0(%rbp)
SEE ALSO
========
**bpftool**\ (8), **bpftool-map**\ (8)

View File

@ -0,0 +1,34 @@
================
BPFTOOL
================
-------------------------------------------------------------------------------
tool for inspection and simple manipulation of eBPF programs and maps
-------------------------------------------------------------------------------
:Manual section: 8
SYNOPSIS
========
**bpftool** *OBJECT* { *COMMAND* | help }
**bpftool** batch file *FILE*
*OBJECT* := { **map** | **program** }
*MAP-COMMANDS* :=
{ show | dump | update | lookup | getnext | delete | pin | help }
*PROG-COMMANDS* := { show | dump jited | dump xlated | pin | help }
DESCRIPTION
===========
*bpftool* allows for inspection and simple modification of BPF objects
on the system.
Note that format of the output of all tools is not guaranteed to be
stable and should not be depended upon.
SEE ALSO
========
**bpftool-map**\ (8), **bpftool-prog**\ (8)

View File

@ -74,6 +74,12 @@ clean: $(LIBBPF)-clean
install:
install $(OUTPUT)bpftool $(prefix)/sbin/bpftool
doc:
$(Q)$(MAKE) -C Documentation/
doc-install:
$(Q)$(MAKE) -C Documentation/ install
FORCE:
.PHONY: all clean FORCE