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]>

Author: iamkafai

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