man/bps: Add a man page for introspection/bps.c

This patch adds a man page for bps.c and also introduces
bps in README.md

Signed-off-by: Martin KaFai Lau <[email protected]>

README.md

@@ -171,6 +171,12 @@ Examples:
 - examples/networking/[tunnel_monitor/](examples/networking/tunnel_monitor): Efficiently monitor traffic flows. [Example video](https://www.youtube.com/watch?v=yYy3Cwce02k).
 - examples/networking/vlan_learning/[vlan_learning.py](examples/networking/vlan_learning/vlan_learning.py) examples/[vlan_learning.c](examples/networking/vlan_learning/vlan_learning.c): Demux Ethernet traffic into worker veth+namespaces.
 
+### BPF Introspection:
+
+Tools that help to introspect BPF programs.
+
+- introspection/[bps.c](introspection/bps.c): List all BPF programs loaded into the kernel. 'ps' for BPF programs. [Examples](introspection/bps_example.txt).
+
 ## Motivation
 
 BPF guarantees that the programs loaded into the kernel cannot crash, and

introspection/bps_example.txt

@@ -0,0 +1,22 @@
+* List all BPF programs *
+# bps
+ BID TYPE UID #MAPS LoadTime NAME
+ 82 kprobe 0 1 Oct19/23:52 map_perf_test
+ 83 kprobe 0 1 Oct19/23:52 map_perf_test
+ 84 kprobe 0 1 Oct19/23:52 map_perf_test
+ 85 kprobe 0 1 Oct19/23:52 map_perf_test
+ 86 kprobe 0 4 Oct19/23:52 map_perf_test
+ 87 kprobe 0 1 Oct19/23:52 map_perf_test
+ 88 kprobe 0 1 Oct19/23:52 map_perf_test
+ 89 kprobe 0 1 Oct19/23:52 map_perf_test
+
+* List a particular BPF program and its maps *
+# bps 86
+ BID TYPE UID #MAPS LoadTime NAME
+ 86 kprobe 0 4 Oct19/23:52 map_perf_test
+
+MID TYPE FLAGS KeySz ValueSz MaxEnts NAME
+120 lru hash 0x0 4 8 10000 lru_hash_map
+129 lru hash 0x0 4 8 43 lru_hash_lookup
+123 array of maps 0x0 4 4 1024 array_of_lru_ha
+121 lru hash 0x2 4

man/man8/bps.8

@@ -0,0 +1,87 @@
+.TH bps 8 "2017-10-19" "USER COMMANDS"
+.SH NAME
+bps \- List all BPF programs. 'ps' for BPF programs.
+.SH SYNOPSIS
+.B bps [bpf-prog-id]
+.SH DESCRIPTION
+.B bps
+lists all BPF programs loaded into the kernel. It is similar
+to the ps command but for the BPF programs.
+
+Each loaded bpf program is identified by an unique integer (i.e.
+.B bpf-prog-id
+or simply BID). If
+a
+.B bpf-prog-id
+is specified, the maps used by
+.B bpf-prog-id
+will also be listed.
+
+.SH EXAMPLES
+.TP
+List all BPF programs loaded into the kernel:
+.B bps
+.TP
+Show the details and maps of BID 6:
+.B bps 6
+.SH BPF PROGRAM FIELDS
+.TP
+.B BID
+BPF program ID. It ends with '-' if it is not jitted.
+.TP
+.B TYPE
+The type of a BPF program. e.g. kprobe, tracepoint, xdp...etc.
+.TP
+.B UID
+The user ID that loaded the BPF program.
+.TP
+.B #MAPS
+Total number of maps used by a BPF program.
+.TP
+.B LoadTime
+When was the BPF program loaded?
+.TP
+.B NAME
+The name of a BPF program. The user space library (like
+.B bcc
+) usually
+uses the C function name of the original BPF's source code as
+the program name. It could be empty if the user space did not
+provide a name.
+
+.SH BPF MAP FIELDS
+.TP
+.B MID
+BPF map ID.
+.TP
+.B TYPE
+The type of a BPF map. e.g. hash, array, stack trace...etc.
+.TP
+.B FLAGS
+The flags used to create the BP map.
+.TP
+.B KeySz
+The key size of a BPF map.
+.TP
+.B ValueSz
+The value size of a BPF map.
+.TP
+.B MaxEnts
+The maximum number of entries of a map.
+.TP
+.B NAME
+The name of a BPF map. The user space library (like
+.B bcc
+) usually uses the C variable name of the BPF map as its name.
+It could be empty if the user space did not provide a name.
+
+.SH SOURCE
+This is from bcc.
+.IP
+https://github.com/iovisor/bcc
+.SH OS
+Linux
+.SH STABILITY
+Unstable - in development.
+.SH AUTHOR
+Martin Lau