tools: bpftool: add documentation

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

================

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)

================

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)

================

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)

install:

	install $(OUTPUT)bpftool $(prefix)/sbin/bpftool

doc:

	$(Q)$(MAKE) -C Documentation/

doc-install:

	$(Q)$(MAKE) -C Documentation/ install

FORCE:

.PHONY: all clean FORCE