tools, bpftool: Minor fixes for documentation
authorQuentin Monnet <quentin@isovalent.com>
Mon, 11 May 2020 16:15:34 +0000 (17:15 +0100)
committerDaniel Borkmann <daniel@iogearbox.net>
Mon, 11 May 2020 19:20:50 +0000 (21:20 +0200)
Bring minor improvements to bpftool documentation. Fix or harmonise
formatting, update map types (including in interactive help), improve
description for "map create", fix a build warning due to a missing line
after the double-colon for the "bpftool prog profile" example,
complete/harmonise/sort the list of related bpftool man pages in
footers.

v2:
- Remove (instead of changing) mark-up on "value" in bpftool-map.rst,
  when it does not refer to something passed on the command line.
- Fix an additional typo ("hexadeximal") in the same file.

Signed-off-by: Quentin Monnet <quentin@isovalent.com>
Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
Link: https://lore.kernel.org/bpf/20200511161536.29853-3-quentin@isovalent.com
13 files changed:
tools/bpf/bpftool/Documentation/bpftool-btf.rst
tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
tools/bpf/bpftool/Documentation/bpftool-feature.rst
tools/bpf/bpftool/Documentation/bpftool-gen.rst
tools/bpf/bpftool/Documentation/bpftool-iter.rst
tools/bpf/bpftool/Documentation/bpftool-link.rst
tools/bpf/bpftool/Documentation/bpftool-map.rst
tools/bpf/bpftool/Documentation/bpftool-net.rst
tools/bpf/bpftool/Documentation/bpftool-perf.rst
tools/bpf/bpftool/Documentation/bpftool-prog.rst
tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst
tools/bpf/bpftool/Documentation/bpftool.rst
tools/bpf/bpftool/map.c

index 39615f8..ce3a724 100644 (file)
@@ -230,9 +230,14 @@ SEE ALSO
        **bpf**\ (2),
        **bpf-helpers**\ (7),
        **bpftool**\ (8),
-       **bpftool-map**\ (8),
-       **bpftool-prog**\ (8),
+       **bpftool-btf**\ (8),
        **bpftool-cgroup**\ (8),
        **bpftool-feature**\ (8),
+       **bpftool-gen**\ (8),
+       **bpftool-iter**\ (8),
+       **bpftool-link**\ (8),
+       **bpftool-map**\ (8),
        **bpftool-net**\ (8),
-       **bpftool-perf**\ (8)
+       **bpftool-perf**\ (8),
+       **bpftool-prog**\ (8),
+       **bpftool-struct_ops**\ (8)
index 06a28b0..e4d9da6 100644 (file)
@@ -20,7 +20,7 @@ SYNOPSIS
 CGROUP COMMANDS
 ===============
 
-|      **bpftool** **cgroup { show | list }** *CGROUP* [**effective**]
+|      **bpftool** **cgroup** { **show** | **list** } *CGROUP* [**effective**]
 |      **bpftool** **cgroup tree** [*CGROUP_ROOT*] [**effective**]
 |      **bpftool** **cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*]
 |      **bpftool** **cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG*
@@ -160,9 +160,13 @@ SEE ALSO
        **bpf**\ (2),
        **bpf-helpers**\ (7),
        **bpftool**\ (8),
-       **bpftool-prog**\ (8),
-       **bpftool-map**\ (8),
+       **bpftool-btf**\ (8),
        **bpftool-feature**\ (8),
+       **bpftool-gen**\ (8),
+       **bpftool-iter**\ (8),
+       **bpftool-link**\ (8),
+       **bpftool-map**\ (8),
        **bpftool-net**\ (8),
        **bpftool-perf**\ (8),
-       **bpftool-btf**\ (8)
+       **bpftool-prog**\ (8),
+       **bpftool-struct_ops**\ (8)
index 1fa755f..8609f06 100644 (file)
@@ -28,7 +28,7 @@ DESCRIPTION
 ===========
        **bpftool feature probe** [**kernel**] [**full**] [**macros** [**prefix** *PREFIX*]]
                  Probe the running kernel and dump a number of eBPF-related
-                 parameters, such as availability of the **bpf()** system call,
+                 parameters, such as availability of the **bpf**\ () system call,
                  JIT status, eBPF program types availability, eBPF helper
                  functions availability, and more.
 
@@ -93,9 +93,13 @@ SEE ALSO
        **bpf**\ (2),
        **bpf-helpers**\ (7),
        **bpftool**\ (8),
-       **bpftool-prog**\ (8),
-       **bpftool-map**\ (8),
+       **bpftool-btf**\ (8),
        **bpftool-cgroup**\ (8),
+       **bpftool-gen**\ (8),
+       **bpftool-iter**\ (8),
+       **bpftool-link**\ (8),
+       **bpftool-map**\ (8),
        **bpftool-net**\ (8),
        **bpftool-perf**\ (8),
-       **bpftool-btf**\ (8)
+       **bpftool-prog**\ (8),
+       **bpftool-struct_ops**\ (8)
index 94d9132..df85dbd 100644 (file)
@@ -14,7 +14,7 @@ SYNOPSIS
 
        *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] }
 
-       *COMMAND* := { **skeleton | **help** }
+       *COMMAND* := { **skeleton** | **help** }
 
 GEN COMMANDS
 =============
@@ -36,12 +36,12 @@ DESCRIPTION
                  etc. Skeleton eliminates the need to lookup mentioned
                  components by name. Instead, if skeleton instantiation
                  succeeds, they are populated in skeleton structure as valid
-                 libbpf types (e.g., struct bpf_map pointer) and can be
+                 libbpf types (e.g., **struct bpf_map** pointer) and can be
                  passed to existing generic libbpf APIs.
 
                  In addition to simple and reliable access to maps and
-                 programs, skeleton provides a storage for BPF links (struct
-                 bpf_link) for each BPF program within BPF object. When
+                 programs, skeleton provides a storage for BPF links (**struct
+                 bpf_link**) for each BPF program within BPF object. When
                  requested, supported BPF programs will be automatically
                  attached and resulting BPF links stored for further use by
                  user in pre-allocated fields in skeleton struct. For BPF
@@ -82,14 +82,14 @@ DESCRIPTION
 
                  - **example__open** and **example__open_opts**.
                    These functions are used to instantiate skeleton. It
-                   corresponds to libbpf's **bpf_object__open()** API.
+                   corresponds to libbpf's **bpf_object__open**\ () API.
                    **_opts** variants accepts extra **bpf_object_open_opts**
                    options.
 
                  - **example__load**.
                    This function creates maps, loads and verifies BPF
                    programs, initializes global data maps. It corresponds to
-                   libppf's **bpf_object__load** API.
+                   libppf's **bpf_object__load**\ () API.
 
                  - **example__open_and_load** combines **example__open** and
                    **example__load** invocations in one commonly used
@@ -296,10 +296,13 @@ SEE ALSO
        **bpf**\ (2),
        **bpf-helpers**\ (7),
        **bpftool**\ (8),
-       **bpftool-map**\ (8),
-       **bpftool-prog**\ (8),
+       **bpftool-btf**\ (8),
        **bpftool-cgroup**\ (8),
        **bpftool-feature**\ (8),
+       **bpftool-iter**\ (8),
+       **bpftool-link**\ (8),
+       **bpftool-map**\ (8),
        **bpftool-net**\ (8),
        **bpftool-perf**\ (8),
-       **bpftool-btf**\ (8)
+       **bpftool-prog**\ (8),
+       **bpftool-struct_ops**\ (8)
index 13b173d..8dce698 100644 (file)
@@ -22,7 +22,6 @@ ITER COMMANDS
 |
 |      *OBJ* := /a/file/of/bpf_iter_target.o
 
-
 DESCRIPTION
 ===========
        **bpftool iter pin** *OBJ* *PATH*
@@ -65,19 +64,18 @@ EXAMPLES
    Create a file-based bpf iterator from bpf_iter_netlink.o and pin it
    to /sys/fs/bpf/my_netlink
 
-
 SEE ALSO
 ========
        **bpf**\ (2),
        **bpf-helpers**\ (7),
        **bpftool**\ (8),
-       **bpftool-prog**\ (8),
-       **bpftool-map**\ (8),
-       **bpftool-link**\ (8),
+       **bpftool-btf**\ (8),
        **bpftool-cgroup**\ (8),
        **bpftool-feature**\ (8),
+       **bpftool-gen**\ (8),
+       **bpftool-link**\ (8),
+       **bpftool-map**\ (8),
        **bpftool-net**\ (8),
        **bpftool-perf**\ (8),
-       **bpftool-btf**\ (8)
-       **bpftool-gen**\ (8)
+       **bpftool-prog**\ (8),
        **bpftool-struct_ops**\ (8)
index ee6500d..0e43d7b 100644 (file)
@@ -109,10 +109,13 @@ SEE ALSO
        **bpf**\ (2),
        **bpf-helpers**\ (7),
        **bpftool**\ (8),
-       **bpftool-prog\ (8),
-       **bpftool-map**\ (8),
+       **bpftool-btf**\ (8),
        **bpftool-cgroup**\ (8),
        **bpftool-feature**\ (8),
+       **bpftool-gen**\ (8),
+       **bpftool-iter**\ (8),
+       **bpftool-map**\ (8),
        **bpftool-net**\ (8),
        **bpftool-perf**\ (8),
-       **bpftool-btf**\ (8)
+       **bpftool-prog**\ (8),
+       **bpftool-struct_ops**\ (8)
index cdeae8a..3110164 100644 (file)
@@ -21,7 +21,7 @@ SYNOPSIS
 MAP COMMANDS
 =============
 
-|      **bpftool** **map { show | list }**   [*MAP*]
+|      **bpftool** **map** { **show** | **list** }   [*MAP*]
 |      **bpftool** **map create**     *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* \
 |              **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*]
 |      **bpftool** **map dump**       *MAP*
@@ -49,7 +49,7 @@ MAP COMMANDS
 |              | **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps**
 |              | **devmap** | **devmap_hash** | **sockmap** | **cpumap** | **xskmap** | **sockhash**
 |              | **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage**
-|              | **queue** | **stack** }
+|              | **queue** | **stack** | **sk_storage** | **struct_ops** }
 
 DESCRIPTION
 ===========
@@ -66,6 +66,13 @@ DESCRIPTION
                  Create a new map with given parameters and pin it to *bpffs*
                  as *FILE*.
 
+                 *FLAGS* should be an integer which is the combination of
+                 desired flags, e.g. 1024 for **BPF_F_MMAPABLE** (see bpf.h
+                 UAPI header for existing flags).
+
+                 Keyword **dev** expects a network interface name, and is used
+                 to request hardware offload for the map.
+
        **bpftool map dump**    *MAP*
                  Dump all entries in a given *MAP*.  In case of **name**,
                  *MAP* may match several maps which will all be dumped.
@@ -78,7 +85,7 @@ DESCRIPTION
                  exists; **noexist** update only if entry doesn't exist.
 
                  If the **hex** keyword is provided in front of the bytes
-                 sequence, the bytes are parsed as hexadeximal values, even if
+                 sequence, the bytes are parsed as hexadecimal values, even if
                  no "0x" prefix is added. If the keyword is not provided, then
                  the bytes are parsed as decimal values, unless a "0x" prefix
                  (for hexadecimal) or a "0" prefix (for octal) is provided.
@@ -100,10 +107,10 @@ DESCRIPTION
                  extensions of *bpffs*.
 
        **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*]
-                 Read events from a BPF_MAP_TYPE_PERF_EVENT_ARRAY map.
+                 Read events from a **BPF_MAP_TYPE_PERF_EVENT_ARRAY** map.
 
                  Install perf rings into a perf event array map and dump
-                 output of any bpf_perf_event_output() call in the kernel.
+                 output of any **bpf_perf_event_output**\ () call in the kernel.
                  By default read the number of CPUs on the system and
                  install perf ring for each CPU in the corresponding index
                  in the array.
@@ -116,24 +123,24 @@ DESCRIPTION
                  receiving events if it installed its rings earlier.
 
        **bpftool map peek**  *MAP*
-                 Peek next **value** in the queue or stack.
+                 Peek next value in the queue or stack.
 
        **bpftool map push**  *MAP* **value** *VALUE*
-                 Push **value** onto the stack.
+                 Push *VALUE* onto the stack.
 
        **bpftool map pop**  *MAP*
-                 Pop and print **value** from the stack.
+                 Pop and print value from the stack.
 
        **bpftool map enqueue**  *MAP* **value** *VALUE*
-                 Enqueue **value** into the queue.
+                 Enqueue *VALUE* into the queue.
 
        **bpftool map dequeue**  *MAP*
-                 Dequeue and print **value** from the queue.
+                 Dequeue and print value from the queue.
 
        **bpftool map freeze**  *MAP*
                  Freeze the map as read-only from user space. Entries from a
                  frozen map can not longer be updated or deleted with the
-                 **bpf\ ()** system call. This operation is not reversible,
+                 **bpf**\ () system call. This operation is not reversible,
                  and the map remains immutable from user space until its
                  destruction. However, read and write permissions for BPF
                  programs to the map remain unchanged.
@@ -269,9 +276,13 @@ SEE ALSO
        **bpf**\ (2),
        **bpf-helpers**\ (7),
        **bpftool**\ (8),
-       **bpftool-prog**\ (8),
+       **bpftool-btf**\ (8),
        **bpftool-cgroup**\ (8),
        **bpftool-feature**\ (8),
+       **bpftool-gen**\ (8),
+       **bpftool-iter**\ (8),
+       **bpftool-link**\ (8),
        **bpftool-net**\ (8),
        **bpftool-perf**\ (8),
-       **bpftool-btf**\ (8)
+       **bpftool-prog**\ (8),
+       **bpftool-struct_ops**\ (8)
index 8651b00..aa74507 100644 (file)
@@ -20,7 +20,7 @@ SYNOPSIS
 NET COMMANDS
 ============
 
-|      **bpftool** **net { show | list }** [ **dev** *NAME* ]
+|      **bpftool** **net** { **show** | **list** } [ **dev** *NAME* ]
 |      **bpftool** **net attach** *ATTACH_TYPE* *PROG* **dev** *NAME* [ **overwrite** ]
 |      **bpftool** **net detach** *ATTACH_TYPE* **dev** *NAME*
 |      **bpftool** **net help**
@@ -194,9 +194,13 @@ SEE ALSO
        **bpf**\ (2),
        **bpf-helpers**\ (7),
        **bpftool**\ (8),
-       **bpftool-prog**\ (8),
-       **bpftool-map**\ (8),
+       **bpftool-btf**\ (8),
        **bpftool-cgroup**\ (8),
        **bpftool-feature**\ (8),
+       **bpftool-gen**\ (8),
+       **bpftool-iter**\ (8),
+       **bpftool-link**\ (8),
+       **bpftool-map**\ (8),
        **bpftool-perf**\ (8),
-       **bpftool-btf**\ (8)
+       **bpftool-prog**\ (8),
+       **bpftool-struct_ops**\ (8)
index e252bd0..9c592b7 100644 (file)
@@ -20,7 +20,7 @@ SYNOPSIS
 PERF COMMANDS
 =============
 
-|      **bpftool** **perf { show | list }**
+|      **bpftool** **perf** { **show** | **list** }
 |      **bpftool** **perf help**
 
 DESCRIPTION
@@ -85,9 +85,13 @@ SEE ALSO
        **bpf**\ (2),
        **bpf-helpers**\ (7),
        **bpftool**\ (8),
-       **bpftool-prog**\ (8),
-       **bpftool-map**\ (8),
+       **bpftool-btf**\ (8),
        **bpftool-cgroup**\ (8),
        **bpftool-feature**\ (8),
+       **bpftool-gen**\ (8),
+       **bpftool-iter**\ (8),
+       **bpftool-link**\ (8),
+       **bpftool-map**\ (8),
        **bpftool-net**\ (8),
-       **bpftool-btf**\ (8)
+       **bpftool-prog**\ (8),
+       **bpftool-struct_ops**\ (8)
index 9f19404..5948e9d 100644 (file)
@@ -21,11 +21,11 @@ SYNOPSIS
 PROG COMMANDS
 =============
 
-|      **bpftool** **prog { show | list }** [*PROG*]
+|      **bpftool** **prog** { **show** | **list** } [*PROG*]
 |      **bpftool** **prog dump xlated** *PROG* [{**file** *FILE* | **opcodes** | **visual** | **linum**}]
 |      **bpftool** **prog dump jited**  *PROG* [{**file** *FILE* | **opcodes** | **linum**}]
 |      **bpftool** **prog pin** *PROG* *FILE*
-|      **bpftool** **prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*]
+|      **bpftool** **prog** { **load** | **loadall** } *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*]
 |      **bpftool** **prog attach** *PROG* *ATTACH_TYPE* [*MAP*]
 |      **bpftool** **prog detach** *PROG* *ATTACH_TYPE* [*MAP*]
 |      **bpftool** **prog tracelog**
@@ -49,7 +49,7 @@ PROG COMMANDS
 |       *ATTACH_TYPE* := {
 |              **msg_verdict** | **stream_verdict** | **stream_parser** | **flow_dissector**
 |      }
-|      *METRIC* := {
+|      *METRICs* := {
 |              **cycles** | **instructions** | **l1d_loads** | **llc_misses**
 |      }
 
@@ -155,7 +155,7 @@ DESCRIPTION
        **bpftool prog tracelog**
                  Dump the trace pipe of the system to the console (stdout).
                  Hit <Ctrl+C> to stop printing. BPF programs can write to this
-                 trace pipe at runtime with the **bpf_trace_printk()** helper.
+                 trace pipe at runtime with the **bpf_trace_printk**\ () helper.
                  This should be used only for debugging purposes. For
                  streaming data from BPF programs to user space, one can use
                  perf events (see also **bpftool-map**\ (8)).
@@ -195,9 +195,9 @@ DESCRIPTION
 
        **bpftool prog profile** *PROG* [**duration** *DURATION*] *METRICs*
                  Profile *METRICs* for bpf program *PROG* for *DURATION*
-                 seconds or until user hits Ctrl-C. *DURATION* is optional.
+                 seconds or until user hits <Ctrl+C>. *DURATION* is optional.
                  If *DURATION* is not specified, the profiling will run up to
-                 UINT_MAX seconds.
+                 **UINT_MAX** seconds.
 
        **bpftool prog help**
                  Print short help message.
@@ -267,7 +267,7 @@ EXAMPLES
 
 |
 | **# bpftool prog dump xlated id 10 file /tmp/t**
-| **# ls -l /tmp/t**
+| **$ ls -l /tmp/t**
 
 ::
 
@@ -325,6 +325,7 @@ EXAMPLES
 | **# bpftool prog profile id 337 duration 10 cycles instructions llc_misses**
 
 ::
+
          51397 run_cnt
       40176203 cycles                                                 (83.05%)
       42518139 instructions    #   1.06 insns per cycle               (83.39%)
@@ -335,9 +336,13 @@ SEE ALSO
        **bpf**\ (2),
        **bpf-helpers**\ (7),
        **bpftool**\ (8),
-       **bpftool-map**\ (8),
+       **bpftool-btf**\ (8),
        **bpftool-cgroup**\ (8),
        **bpftool-feature**\ (8),
+       **bpftool-gen**\ (8),
+       **bpftool-iter**\ (8),
+       **bpftool-link**\ (8),
+       **bpftool-map**\ (8),
        **bpftool-net**\ (8),
        **bpftool-perf**\ (8),
-       **bpftool-btf**\ (8)
+       **bpftool-struct_ops**\ (8)
index f045cc8..d93cd1c 100644 (file)
@@ -105,12 +105,13 @@ SEE ALSO
        **bpf**\ (2),
        **bpf-helpers**\ (7),
        **bpftool**\ (8),
-       **bpftool-prog**\ (8),
-       **bpftool-map**\ (8),
+       **bpftool-btf**\ (8),
        **bpftool-cgroup**\ (8),
        **bpftool-feature**\ (8),
+       **bpftool-gen**\ (8),
+       **bpftool-iter**\ (8),
+       **bpftool-link**\ (8),
+       **bpftool-map**\ (8),
        **bpftool-net**\ (8),
        **bpftool-perf**\ (8),
-       **bpftool-btf**\ (8)
-       **bpftool-gen**\ (8)
-       
+       **bpftool-prog**\ (8)
index 34239fd..420d4d5 100644 (file)
@@ -75,11 +75,14 @@ SEE ALSO
 ========
        **bpf**\ (2),
        **bpf-helpers**\ (7),
-       **bpftool-prog**\ (8),
-       **bpftool-map**\ (8),
+       **bpftool-btf**\ (8),
        **bpftool-cgroup**\ (8),
        **bpftool-feature**\ (8),
+       **bpftool-gen**\ (8),
+       **bpftool-iter**\ (8),
+       **bpftool-link**\ (8),
+       **bpftool-map**\ (8),
        **bpftool-net**\ (8),
        **bpftool-perf**\ (8),
-       **bpftool-btf**\ (8),
-       **bpftool-gen**\ (8),
+       **bpftool-prog**\ (8),
+       **bpftool-struct_ops**\ (8)
index 693a632..85cbe9a 100644 (file)
@@ -1589,7 +1589,8 @@ static int do_help(int argc, char **argv)
                "                 percpu_array | stack_trace | cgroup_array | lru_hash |\n"
                "                 lru_percpu_hash | lpm_trie | array_of_maps | hash_of_maps |\n"
                "                 devmap | devmap_hash | sockmap | cpumap | xskmap | sockhash |\n"
-               "                 cgroup_storage | reuseport_sockarray | percpu_cgroup_storage }\n"
+               "                 cgroup_storage | reuseport_sockarray | percpu_cgroup_storage |\n"
+               "                 queue | stack | sk_storage | struct_ops }\n"
                "       " HELP_SPEC_OPTIONS "\n"
                "",
                bin_name, argv[-2], bin_name, argv[-2], bin_name, argv[-2],