On Mon, Oct 02, 2017 at 04:11:30PM -0700, Jakub Kicinski wrote:
> 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.beck...@netronome.com>
> Signed-off-by: Jakub Kicinski <jakub.kicin...@netronome.com>
> ---
> tools/bpf/bpftool/Documentation/Makefile | 34 +++++++
> tools/bpf/bpftool/Documentation/bpftool-map.txt | 110
> +++++++++++++++++++++++
> tools/bpf/bpftool/Documentation/bpftool-prog.txt | 81 +++++++++++++++++
> tools/bpf/bpftool/Documentation/bpftool.txt | 34 +++++++
> tools/bpf/bpftool/Makefile | 6 ++
> 5 files changed, 265 insertions(+)
> create mode 100644 tools/bpf/bpftool/Documentation/Makefile
> create mode 100644 tools/bpf/bpftool/Documentation/bpftool-map.txt
> create mode 100644 tools/bpf/bpftool/Documentation/bpftool-prog.txt
> create mode 100644 tools/bpf/bpftool/Documentation/bpftool.txt
>
> diff --git a/tools/bpf/bpftool/Documentation/Makefile
> b/tools/bpf/bpftool/Documentation/Makefile
> new file mode 100644
> index 000000000000..ebd21ab2c6df
> --- /dev/null
> +++ b/tools/bpf/bpftool/Documentation/Makefile
> @@ -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_TXT = $(wildcard *.txt)
> +
> +_DOC_MAN8 = $(patsubst %.txt,%.8,$(MAN8_TXT))
> +DOC_MAN8 = $(addprefix $(OUTPUT),$(_DOC_MAN8))
> +
> +man: man8
> +man8: $(DOC_MAN8)
> +
> +$(OUTPUT)%.8: %.txt
> + 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
> diff --git a/tools/bpf/bpftool/Documentation/bpftool-map.txt
> b/tools/bpf/bpftool/Documentation/bpftool-map.txt
> new file mode 100644
> index 000000000000..ea82b9059a0a
> --- /dev/null
> +++ b/tools/bpf/bpftool/Documentation/bpftool-map.txt
> @@ -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)
> diff --git a/tools/bpf/bpftool/Documentation/bpftool-prog.txt
> b/tools/bpf/bpftool/Documentation/bpftool-prog.txt
> new file mode 100644
> index 000000000000..d632de0e0212
> --- /dev/null
> +++ b/tools/bpf/bpftool/Documentation/bpftool-prog.txt
> @@ -0,0 +1,81 @@
> +================
> +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
could you please remove ':' in the output to match what
show_fdinfo and kallsyms do ?
> + loaded_at:2024.771 uid:0
may be translate that to something human readable?
> + 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
> +
> +|
> +| **# mount -t bpf none /sys/fs/bpf/**
> +| **# bpftool prog pin id 10 /sys/fs/bpf/prog**
> +| **# bpftool prog dum jited pinned /sys/fs/bpf/prog**
> +
> +::
> +
> + push %rbp
> + mov %rsp,%rbp
> + sub $0x228,%rsp
> + sub $0x28,%rbp
> + mov %rbx,0x0(%rbp)
imo too many steps to dump disasm output.
Can it print it if we just say:
bpftool prog dump jited id 10
and
dump xlated
will pretty print them as verifier output as well?
All that can be changed later. Thanks for the doc.
Acked-by: Alexei Starovoitov <a...@kernel.org>
