[PATCH v1 1/1] doc: refactoring the guide for NTNIC PMD

[Serhii Iliushyk <sil-plv@napatech.com>]

Improve the doc formatting.

Signed-off-by: Serhii Iliushyk <sil-plv@napatech.com>
---
 doc/guides/nics/ntnic.rst | 262 ++++++++++++++++++++------------------
 1 file changed, 140 insertions(+), 122 deletions(-)

diff --git a/doc/guides/nics/ntnic.rst b/doc/guides/nics/ntnic.rst
index 01b6dca652..48f0e55c52 100644
--- a/doc/guides/nics/ntnic.rst
+++ b/doc/guides/nics/ntnic.rst
@@ -4,7 +4,7 @@
 NTNIC Poll Mode Driver
 ======================
 
-The NTNIC PMD provides poll mode driver support for Napatech smartNICs.
+The NTNIC PMD provides poll-mode driver (PMD) support for Napatech SmartNICs.
 
 
 Design
@@ -23,66 +23,66 @@ The physical ports are located behind PF0 as DPDK port 0 and 1.
 Supported NICs
 --------------
 
-- NT200A02 2x100G SmartNIC
+================== ================ ================================
+SmartNIC           total bandwidth  FPGA id
+================== ================ ================================
+**NT200A02**       2x100 Gb/s        9563 (Inline Flow Management)
+**NT400D11**       2x100 Gb/s        9569 (Inline Flow Management)
+**NT400D13**       2x100 Gb/s        9574 (Inline Flow Management)
+================== ================ ================================
 
-    - FPGA ID 9563 (Inline Flow Management)
+All information about Napatech SmartNICs can be found by links below:
 
-- NT400D11 2x100G SmartNIC
-
-    - FPGA ID 9569 (Inline Flow Management)
-
-- NT400D13 2x100G SmartNIC
-
-    - FPGA ID 9574 (Inline Flow Management)
-
-All information about NT200A02 and NT400D13 can be found by links below:
-
-- https://www.napatech.com/products/nt200a02-smartnic-inline/
-- https://www.napatech.com/products/nt400d11-smartnic-programmable/
-- https://www.napatech.com/products/nt400d13-smartnic-programmable/
-- https://www.napatech.com/support/resources/data-sheets/link-inline-software-for-napatech/
+- `NT200A02 <https://www.napatech.com/products/nt200a02-smartnic-inline/>`_
+- `NT400D11 <https://www.napatech.com/products/nt400d11-smartnic-programmable/>`_
+- `NT400D13 <https://www.napatech.com/products/nt400d13-smartnic-programmable/>`_
+- `Napatech FPGA-based SmartNICs <https://www.napatech.com/support/resources/data-sheets/link-inline-software-for-napatech/>`_
 
 
 Features
 --------
-
-- FW version
-- Speed capabilities
-- Link status (Link update only)
-- Unicast MAC filter
-- Multicast MAC filter
-- Promiscuous mode (Enable only. The device always run promiscuous mode)
-- Flow API support.
-- Support for multiple rte_flow groups.
-- Multiple TX and RX queues.
-- Scattered and gather for TX and RX.
-- Jumbo frame support.
-- Traffic mirroring.
-- VLAN filtering.
-- Packet modification: NAT, TTL decrement, DSCP tagging
-- Tunnel types: GTP.
-- Encapsulation and decapsulation of GTP data.
-- RX VLAN stripping via raw decap.
-- TX VLAN insertion via raw encap.
-- CAM and TCAM based matching.
-- Exact match of 140 million flows and policies.
-- Tunnel HW offload: Packet type, inner/outer RSS, IP and UDP checksum verification.
-- RSS hash
-- RSS key update
-- RSS based on VLAN or 5-tuple.
-- RSS using different combinations of fields: L3 only, L4 only or both,
-  and source only, destination only or both.
-- Several RSS hash keys, one for each flow type.
-- Default RSS operation with no hash key specification.
-- Port and queue statistics.
-- RMON statistics in extended stats.
-- Link state information.
-- Flow statistics
-- Flow aging support
-- Flow metering, including meter policy API.
-- Flow update. Update of the action list for specific flow
-- Asynchronous flow support
-- MTU update
+.. rst-class:: punchcard
+
+================================================================================================================ =======
+Supported Features                                                                                                Linux
+================================================================================================================ =======
+FW version                                                                                                          X
+Speed capabilities                                                                                                  X
+Link status (Link update only)                                                                                      X
+Unicast MAC filter                                                                                                  X
+Multicast MAC filter                                                                                                X
+Promiscuous mode (Enable only. The device always run promiscuous mode)                                              X
+Flow API support.                                                                                                   X
+Support for multiple rte_flow groups.                                                                               X
+Multiple TX and RX queues.                                                                                          X
+Scattered and gather for TX and RX.                                                                                 X
+Jumbo frame support.                                                                                                X
+Traffic mirroring.                                                                                                  X
+VLAN filtering.                                                                                                     X
+Packet modification: NAT, TTL decrement, DSCP tagging                                                               X
+Tunnel types: GTP.                                                                                                  X
+Encapsulation and decapsulation of GTP data.                                                                        X
+RX VLAN stripping via raw decap.                                                                                    X
+TX VLAN insertion via raw encap.                                                                                    X
+CAM and TCAM based matching.                                                                                        X
+Exact match of 140 million flows and policies.                                                                      X
+Tunnel HW offload: Packet type, inner/outer RSS, IP and UDP checksum verification.                                  X
+RSS hash                                                                                                            X
+RSS key update                                                                                                      X
+RSS based on VLAN or 5*tuple.                                                                                       X
+RSS using different combinations of fields: L3 only, L4 only or both, and source only, destination only or both.    X
+Several RSS hash keys, one for each flow type.                                                                      X
+Default RSS operation with no hash key specification.                                                               X
+Port and queue statistics.                                                                                          X
+RMON statistics in extended stats.                                                                                  X
+Link state information.                                                                                             X
+Flow statistics                                                                                                     X
+Flow aging support                                                                                                  X
+Flow metering, including meter policy API.                                                                          X
+Flow update. Update of the action list for specific flow                                                            X
+Asynchronous flow support                                                                                           X
+MTU update                                                                                                          X
+================================================================================================================ =======
 
 Limitations
 ~~~~~~~~~~~
@@ -103,76 +103,86 @@ Command line arguments
 
 Following standard DPDK command line arguments are used by the PMD:
 
-``-a``
-   Used to specifically define the NT adapter by PCI ID.
+NTNIC-specific arguments can be passed in the PCI device parameter list:
 
-``--iova-mode``
-   Must be set to ``pa`` for Physical Address mode.
-
-NTNIC specific arguments can be passed to the PMD in the PCI device parameter list::
+.. code-block:: console
 
-   <application> ... -a 0000:03:00.0[{,<NTNIC specific argument>}]
+      <application> ... -a 0000:03:00.0[{,<NTNIC specific argument>}]
 
-The NTNIC specific argument format is::
+   The NTNIC-specific argument format is
 
    <object>.<attribute>=[<object-ids>:]<value>
 
-Multiple arguments for the same device are separated by ‘,’ comma.
-<object-ids> can be a single value or a range.
+   Multiple arguments for the same device are separated by commas. The
+   ``<object-ids>`` field can be a single value or a range.
+
+- ``rxqs`` parameter [int]
 
-``rxqs`` parameter [int]
+   Number of Rx queues to use. Example:
 
-   Specify number of Rx queues to use::
+.. code-block:: console
 
       -a <domain>:<bus>:00.0,rxqs=4,txqs=4
 
    By default, the value is set to 1.
 
-``txqs`` parameter [int]
+- ``txqs`` parameter [int]
+
+   Number of Tx queues to use. Example:
 
-   Specify number of Tx queues to use::
+.. code-block:: console
 
       -a <domain>:<bus>:00.0,rxqs=4,txqs=4
 
    By default, the value is set to 1.
 
-``exception_path`` parameter [int]
+- ``exception_path`` parameter [int]
 
    Enable exception path for unmatched packets to go through queue 0.
 
-   To enable exception_path::
+   To enable exception_path:
+
+.. code-block:: console
 
       -a <domain>:<bus>:00.0,exception_path=1
 
    By default, the value is set to 0.
 
 Logging and Debugging
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 NTNIC supports several groups of logging
 that can be enabled with ``--log-level`` parameter:
 
 NTNIC
-   Logging info from the main PMD code. i.e. code that is related to DPDK::
+   Logging info from the main PMD code. i.e. code that is related to DPDK:
+
+   .. code-block:: console
 
       --log-level=pmd.net.ntnic.ntnic,8
 
 NTHW
-   Logging info from NTHW. i.e. code that is related to the FPGA and the adapter::
+   Logging info from NTHW. i.e. code that is related to the FPGA and the adapter:
+
+   .. code-block:: console
 
       --log-level=pmd.net.ntnic.nthw,8
 
 FILTER
-   Logging info from filter. i.e. code that is related to the binary filter::
+   Logging info from filter. i.e. code that is related to the binary filter:
+
+   .. code-block:: console
 
-        --log-level=pmd.net.ntnic.filter,8
+      --log-level=pmd.net.ntnic.filter,8
 
-To enable logging on all levels use wildcard in the following way::
+To enable logging on all levels use wildcard in the following way:
+
+.. code-block:: console
 
    --log-level=pmd.net.ntnic.*,8
 
 Flow Scanner
-------------
+~~~~~~~~~~~~
 
 Flow Scanner is DPDK mechanism that constantly and periodically scans
 the flow tables to check for aged-out flows.
@@ -202,46 +212,55 @@ There are list of characteristics that age timeout action has:
   and its aged-out status will be reverted;
 
 Service API
------------
+~~~~~~~~~~~
+
+The NTNIC PMD provides a service API that allows applications to configure
+and manage PMD services.
+
+Primary service functions:
+
+**nthw_service_add**, **nthw_service_del**, **nthw_service_get_info**
 
-**nthw_service_add**
-**nthw_service_del**
-**nthw_service_get_info**
+Services handle vital PMD functionality such as:
 
-The NTNIC PMD provides a service API that allows applications to configure services
+======================== =================================================
+Service name             Service purpose
+======================== =================================================
+**FLM Update**           create and destroy flows
+**Statistics**           collect statistics
+**Port event**           handle port events (aging, port load, flow load)
+**Adapter monitor**      monitor link state
+======================== =================================================
 
-The services are responsible for handling the vital functionality of the NTNIC PMD:
+Reserve service lcores via EAL options. Examples:
 
-- **FLM Update**: is responsible for creating and destroying flows;
-- **Statistics**: is responsible for collecting statistics;
-- **Port event**: is responsible for handling port events: aging, port load, and flow load;
-- **Adapter monitor** is responsible for link control;
+- ``-s SERVICE COREMASK`` — hexadecimal bitmask of cores to use as service cores
+- ``-S SERVICE CORELIST`` — list of cores to run services on
 
-**NOTE**: Use next EAL options to configure set service cores
-   * -s SERVICE COREMASK Hexadecimal bitmask of cores to be used as service cores;
-   * -S SERVICE CORELIST List of cores to run services on;
+   .. note::
 
-**NOTE**: **At least 5 lcores must be reserved** for the ntnic services by EAL options. above.
+      At least **five (5)** lcores must be reserved for NTNIC services.
 
-For example
+For example:
 
 .. code-block:: console
 
    dpdk-testpmd -S 8,9,10,11,12
 
-The PMD registers each service during initialization by function:
+
+The PMD registers each service during initialization with:
 
 .. code-block:: c
 
    int nthw_service_add(struct rte_service_spec *srv_spec, const enum rte_ntnic_service_tag tag)
 
-and unregistered by the PMD during deinitialization by the function:
+And unregister it during deinitialization with:
 
 .. code-block:: c
 
    int nthw_service_del(const enum rte_ntnic_service_tag tag)
 
-The service info may be retrieved by function:
+Retrieve service info can be done with `nthw_service_get_info`:
 
 .. code-block:: c
 
@@ -249,32 +268,19 @@ The service info may be retrieved by function:
 
 The service info includes the service ID, assigned lcore, and initialization state.
 
-Service API for user applications
----------------------------------
-**rte_pmd_ntnic_service_set_lcore**
-**rte_pmd_ntnic_service_get_id**
-
-The exported service API is available for applications to configure the services.
-
-By API function:
+Service API for applications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: c
+Exported functions:
 
-   int rte_pmd_ntnic_service_set_lcore(enum rte_ntnic_service_tag tag, uint32_t lcore_id)
+- ``rte_pmd_ntnic_service_set_lcore``
+- ``rte_pmd_ntnic_service_get_id``
 
-For example to assign lcores 8,9,10,11,12 to the services, the application can use:
+Set a service lcore with:
 
 .. code-block:: c
 
-   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_STAT, 8);
-   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_ADAPTER_MON, 9);
-   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_PORT_0_EVENT, 10);
-   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_PORT_1_EVENT,11);
-   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_FLM_UPDATE, 12);
-
-The API will automatically lcore to service core list and map the service to the lcore.
-
-.. note:: Use `rte_service_lcore_start` to start the lcore after mapping it to the service.
+   int rte_pmd_ntnic_service_set_lcore(enum rte_ntnic_service_tag tag, uint32_t lcore_id)
 
 Each service has its own tag to identify it.
 
@@ -289,26 +295,38 @@ Each service has its own tag to identify it.
       RTE_NTNIC_SERVICE_MAX
    };
 
-The application may use next API function to retrieve the service id:
+Example: assign lcores 8–12 to services
 
 .. code-block:: c
 
-  int rte_pmd_ntnic_service_get_id(enum rte_ntnic_service_tag tag);
+   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_STAT, 8);
+   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_ADAPTER_MON, 9);
+   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_PORT_0_EVENT, 10);
+   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_PORT_1_EVENT, 11);
+   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_FLM_UPDATE, 12);
 
+The API maps services to lcores and returns a service ID via:
 
-For example, to enable statistics for flm_update service, the application can use:
+.. code-block:: c
+
+  int rte_pmd_ntnic_service_get_id(enum rte_ntnic_service_tag tag);
+
+Example: enable statistics for the flm_update service
 
 .. code-block:: c
 
    int flm_update_id = rte_pmd_ntnic_service_get_id(RTE_NTNIC_SERVICE_FLM_UPDATE);
    rte_service_set_stats_enable(flm_update_id, 1);
 
-All other manipulations with the service can be done with the service ID and rte_service* API.
 
-To use the service API, an application must have included the header file:
+   .. note:: Use `rte_service_lcore_start` to start the lcore after mapping it to the service.
+
+All service operations use the service ID and the standard `rte_service*` APIs.
+
+To use the NTNIC service API include the header:
 
 .. code-block:: c
 
    #include <rte_pmd_ntnic.h>
 
-And linked with the library: `librte_net_ntnic.so` or `librte_net_ntnic.a` for static linking.
+Link with `librte_net_ntnic.so` or `librte_net_ntnic.a` for static linking.
-- 
2.45.0