Edit user guide (#44)

Infrap4d user guide:

- Corrected several errors in the infrap4d user guide.

- Added subheadings to the command-line flags section.

Building krnlmon with Bazel:

- Corrected a number of errors.

- Changed "code" to "code-block", for consistency.

Building krnlmon with CMake:

- Changed "code" to "code-block", for consistency.

Signed-off-by: Derek Foster <[email protected]>

Author: ffoulkes

docs/executables/infrap4d/infrap4d.rst

@@ -22,38 +22,52 @@ Syntax
 
    infrap4d \
        [--help | --helpshort | --helpon MODULE] \
-       [options]
+       [--[no]detach] \
+       [--disable-krnlmon] \
+       [other options]
 
 infrap4d is located in the ``sbin`` directory of the install tree.
 
 
 Command-Line Flags
 ==================
 
+Flag prefix
+-----------
+
 A flag may be prefixed with either one or two hyphens.
-``-help`` is equivalent to ``--help``.
+``-help`` and ``--help`` are equivalent.
+
+Underscores vs. hyphens
+-----------------------
 
 Underscores and hyphens may be used interchangeably within the name
-of a flag. ``--disable_krnlmon`` is equivalent to ``--disable-krnlmon``.
+of a flag. ``--disable_krnlmon`` and ``--disable-krnlmon`` are equivalent.
 
-A Boolean value of *true* may be expressed as ``true``, ``yes``, ``on``,
+Boolean values
+--------------
+
+A Boolean value of **true** may be expressed as ``true``, ``yes``, ``on``,
 or ``1``, or by writing the flag name with no value. For example:
 
-.. code-block text
+.. code-block:: text
 
    -detach
    -detach=true
    -detach yes
 
-A Boolean value of *false* may be expressed as ``false``, ``no``, ``off``,
+A Boolean value of **false** may be expressed as ``false``, ``no``, ``off``,
 or ``0``, or by prefixing the flag name with ``no``. For example:
 
-.. code-block text
+.. code-block:: text
 
    -nodetach
    -detach=no
    -detach 0
 
+Documentation
+-------------
+
 Infrap4d uses the Google ``gflags`` library to process command-line flags.
 Technical documentation is available in
 `How to Use Gflags <https://gflags.github.io/gflags/>`_.
@@ -70,9 +84,12 @@ The most useful of these are:
   Displays just the flags that are specific to the main module
   (``infrap4d_main``).
 
-``helpon MODULE``
+``--helpon MODULE``
   Displays just the flags that are defined by the named module.
 
+  MODULE is the name of the source file in which the flags are defined,
+  without ``.cc`` suffix, e.g. ``logging`` or ``tdi_hal_flags``.
+
 ``--help``
   Displays the flags for all modules. The list is long.
 
@@ -88,7 +105,7 @@ Infrap4d Options
 These flags influence the way infrap4d starts up.
 They are defined by the ``infrap4d_main`` module.
 
-``--detached``
+``--detach``
   Run infrap4d in detached mode. type: Boolean. default: true.
 
   In detached mode, infrap4d runs as a separate process, as a daemon.
@@ -104,7 +121,7 @@ Other Options
 See :ref:`infrap4d_flags` for a complete list of flags supported by
 infrap4d.
 
-Verifying settings
+Verifying Settings
 ==================
 
 gflags processes all the flags on the command line before it displays
@@ -121,5 +138,5 @@ flags that have been set, as the following example demonstrates.
      -disable_krnlmon (Run infrap4d without krnlmon support) type: bool
       default: false currently: true
 
-gflags doesn't always do what you expect. This is a way to check for
-anomalies.
+gflags doesn't always do what you expect. This is a way to see the effect
+of the flags on the command line.

docs/maintainers/building-krnlmon-with-bazel.rst

@@ -41,11 +41,11 @@ specified before or after the target(s).
 ``--define target={dpdk|es2k}``
   Alternative to the ``--config`` flag.
 
-``--//flags:ovs={on|off}``
-  Whether to support OVSP4RT. Equivalent to the ``WITH_OVSP4RT`` cmake
-  variable or (in the negative) the ``--no-ovs`` helper script option.
+``--//flags:ovs={true|false}``
+  Whether to support OVSP4RT. Equivalent to the ``WITH_OVSP4RT={true|false}``
+  cmake variable or (in the negative) the ``--no-ovs`` helper script option.
 
-  Specify ``on``, ``true``, or ``1`` to enable support, and ``off``,
+  Specify ``yes``, ``true``, or ``1`` to enable support, and ``no``,
   ``false``, or ``0`` to disable it.
 
 Useful Targets
@@ -66,7 +66,7 @@ Build krnlmon for DPDK
 We are using the ``--define`` option and specifying it after the
 build target.
 
-.. code:: bash
+.. code-block:: bash
 
    bazel build //:krnlmon --define target=dpdk
 
@@ -76,7 +76,7 @@ Build for ES2K without OVS
 We are using ``--config`` instead of ``define`` and specifying the
 options before the target.
 
-.. code:: bash
+.. code-block:: bash
 
    bazel build --config es2k --//flags:ovs=no //:krnlmon
 
@@ -90,7 +90,7 @@ The ``dummy_krnlmon`` target links the krnlmon library with a dummy
 main program. This allows you to check for unresolved external symbols
 in the library.
 
-.. code:: bash
+.. code-block:: bash
 
    bazel build --config dpdk //:dummy_krnlmon
 
@@ -100,7 +100,7 @@ Check for RPATH issues
 You can check for RPATH problems by issuing the ``ldd`` comand and
 looking for missing libraries in its output.
 
-.. code:: bash
+.. code-block:: bash
 
    ldd bazel-bin/dummy_krnlmon
 
@@ -109,23 +109,23 @@ Run unit tests
 
 To build and run the unit tests for ES2K:
 
-.. code::bash
+.. code-block:: bash
 
    bazel test --config es2k //switchlink:all //switchsde:all
 
 Sample output:
 
-.. code:text
+.. code-block:: text
 
-INFO: Analyzed 23 targets (2 packages loaded, 92 targets configured).
-INFO: Found 18 targets and 5 test targets...
-INFO: Elapsed time: 2.372s, Critical Path: 1.79s
-INFO: 34 processes: 13 internal, 21 linux-sandbox.
-INFO: Build completed successfully, 34 total actions
-//switchlink:switchlink_address_test                             PASSED in 0.0s
-//switchlink:switchlink_link_test                                PASSED in 0.1s
-//switchlink:switchlink_neigh_test                               PASSED in 0.0s
-//switchlink:switchlink_route_test                               PASSED in 0.0s
-//switchsde:switchsde_test                                       PASSED in 0.1s
+   INFO: Analyzed 23 targets (2 packages loaded, 92 targets configured).
+   INFO: Found 18 targets and 5 test targets...
+   INFO: Elapsed time: 2.372s, Critical Path: 1.79s
+   INFO: 34 processes: 13 internal, 21 linux-sandbox.
+   INFO: Build completed successfully, 34 total actions
+   //switchlink:switchlink_address_test                           PASSED in 0.0s
+   //switchlink:switchlink_link_test                              PASSED in 0.1s
+   //switchlink:switchlink_neigh_test                             PASSED in 0.0s
+   //switchlink:switchlink_route_test                             PASSED in 0.0s
+   //switchsde:switchsde_test                                     PASSED in 0.1s
 
-Executed 5 out of 5 tests: 5 tests pass.
+   Executed 5 out of 5 tests: 5 tests pass.

docs/maintainers/building-krnlmon-with-cmake.rst

@@ -43,7 +43,7 @@ Integrated builds are usually done using the helper script ``make-all.sh``
 You will typically want to start by removing artifacts from previous
 builds:
 
-.. code:: text
+.. code-block:: text
 
    rm -fr build install
 
@@ -55,7 +55,7 @@ Full build
 
 To build all of P4 Control Plane, including krnlmon:
 
-.. code:: bash
+.. code-block:: bash
 
    ./make-all.sh --target=TARGET --rpath
 
@@ -64,7 +64,7 @@ where TARGET is ``dpdk`` or ``es2k``.
 Full build (no OVS)
 ~~~~~~~~~~~~~~~~~~~
 
-.. code:: bash
+.. code-block:: bash
 
    ./make-all.sh --target=TARGET --rpath --no-ovs
 
@@ -76,7 +76,7 @@ Krnlmon only
 
 To build just krnlmon:
 
-.. code:: bash
+.. code-block:: bash
 
    ./make-all.sh --target-TARGET --rpath --no-build
    cmake --build build -j4 --target krnlmon
@@ -97,7 +97,7 @@ Preparation
 You will generally want to begin by removing artifacts from previous
 builds:
 
-.. code:: bash
+.. code-block:: bash
 
    rm -fr build install
 
@@ -107,7 +107,7 @@ no effect on integrated builds.
 DPDK build
 ~~~~~~~~~~
 
-.. code:: bash
+.. code-block:: bash
 
    cmake -B build -C dpdk.cmake [options]
    cmake --build build -j4 --target install
@@ -128,7 +128,7 @@ You can also create your own configuration file and use it in place of
 ES2K build
 ^^^^^^^^^^
 
-.. code:: bash
+.. code-block:: bash
 
    cmake -B build -C es2k.cmake [options]
    cmake --build build -j4 --target install