[PATCH v5 38/39] ml/cnxk: add user guide for marvell cnxk ml driver

[Srikanth Yalavarthi <syalavarthi@marvell.com>]

Added user guide for Marvell cnxk ML driver for Marvell Octeon
cnxk Soc family. Added details about device initialization,
debug options and runtime device args supported by the driver.

Signed-off-by: Srikanth Yalavarthi <syalavarthi@marvell.com>
---
 MAINTAINERS                 |   1 +
 doc/guides/index.rst        |   1 +
 doc/guides/mldevs/cnxk.rst  | 238 ++++++++++++++++++++++++++++++++++++
 doc/guides/mldevs/index.rst |  14 +++
 4 files changed, 254 insertions(+)
 create mode 100644 doc/guides/mldevs/cnxk.rst
 create mode 100644 doc/guides/mldevs/index.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 8e9d6dc946..65153948d2 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1442,6 +1442,7 @@ M: Srikanth Yalavarthi <syalavarthi@marvell.com>
 F: drivers/common/cnxk/hw/ml.h
 F: drivers/common/cnxk/roc_ml*
 F: drivers/ml/cnxk/
+F: doc/guides/mldevs/cnxk.rst
 
 
 Packet processing
diff --git a/doc/guides/index.rst b/doc/guides/index.rst
index 5eb5bd9c9a..0bd729530a 100644
--- a/doc/guides/index.rst
+++ b/doc/guides/index.rst
@@ -26,6 +26,7 @@ DPDK documentation
    eventdevs/index
    rawdevs/index
    mempool/index
+   mldevs/index
    platform/index
    contributing/index
    rel_notes/index
diff --git a/doc/guides/mldevs/cnxk.rst b/doc/guides/mldevs/cnxk.rst
new file mode 100644
index 0000000000..da40336299
--- /dev/null
+++ b/doc/guides/mldevs/cnxk.rst
@@ -0,0 +1,238 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright (c) 2022 Marvell.
+
+Marvell cnxk Machine Learning Poll Mode Driver
+==============================================
+
+The cnxk ML poll mode driver provides support for offloading Machine
+Learning inference operations to Machine Learning accelerator units
+on the **Marvell OCTEON cnxk** SoC family.
+
+The cnxk ML PMD code is organized into multiple files with all file names
+starting with cn10k, providing support for CN106XX and CN106XXS.
+
+More information about OCTEON cnxk SoCs may be obtained from `<https://www.marvell.com>`_
+
+Supported OCTEON cnxk SoCs
+--------------------------
+
+- CN106XX
+- CN106XXS
+
+Features
+--------
+
+The OCTEON cnxk ML PMD provides support for the following set of operations:
+
+Slow-path device and ML model handling:
+
+* ``Device probing, configuration and close``
+* ``Device start / stop``
+* ``Model loading and unloading``
+* ``Model start / stop``
+* ``Data quantization and dequantization``
+
+Fast-path Inference:
+
+* ``Inference execution``
+* ``Error handling``
+
+
+Installation
+------------
+
+The OCTEON cnxk ML PMD may be compiled natively on an OCTEON cnxk platform
+or cross-compiled on an x86 platform.
+
+Refer to :doc:`../platform/cnxk` for instructions to build your DPDK
+application.
+
+
+Initialization
+--------------
+
+``CN10K Initialization``
+
+List the ML PF devices available on cn10k platform:
+
+.. code-block:: console
+
+    lspci -d:a092
+
+``a092`` is the ML device PF id. You should see output similar to:
+
+.. code-block:: console
+
+    0000:00:10.0 System peripheral: Cavium, Inc. Device a092
+
+Bind the ML PF device to the vfio_pci driver:
+
+.. code-block:: console
+
+    cd <dpdk directory>
+    ./usertools/dpdk-devbind.py -u 0000:00:10.0
+    ./usertools/dpdk-devbind.py -b vfio-pci 0000:00:10.0
+
+Runtime Config Options
+----------------------
+
+- ``Firmware file path`` (default ``/lib/firmware/mlip-fw.bin``)
+
+   Path to the firmware binary to be loaded during device configuration.
+   The ``fw_path`` ``devargs`` parameter can be used by the user to load
+   ML firmware from a custom path.
+
+   For example::
+
+      -a 0000:00:10.0,fw_path="/home/user/ml_fw.bin"
+
+   With the above configuration, driver loads the firmware from the path
+   "/home/user/ml_fw.bin".
+
+- ``Enable DPE warnings`` (default ``1``)
+
+   ML firmware can be configured during load to handle the DPE errors reported
+   by ML inference engine. When enabled, firmware would mask the DPE non-fatal
+   hardware errors as warnings. The parameter ``enable_dpe_warnings`` ``devargs``
+   is used fo this configuration.
+
+   For example::
+
+      -a 0000:00:10.0,enable_dpe_warnings=0
+
+   With the above configuration, DPE non-fatal errors reported by HW are
+   considered as errors.
+
+
+- ``Model data caching`` (default ``1``)
+
+   Enable caching model data on ML ACC cores. Enabling this option executes a
+   dummy inference request in synchronous mode during model start stage. Caching
+   of model data improves the inferencing throughput / latency for the model.
+   The parameter ``cache_model_data`` ``devargs`` is used to enable data caching.
+
+   For example::
+
+      -a 0000:00:10.0,cache_model_data=0
+
+   With the above configuration, model data caching is disabled.
+
+
+- ``OCM allocation mode`` (default ``lowest``)
+
+   Option to specify the method to be used while allocating OCM memory for a
+   model during model start. Two modes are supported by the driver. The
+   parameter ``ocm_alloc_mode`` ``devargs`` is used to select the OCM
+   allocation mode.
+
+   ``lowest`` - Allocate OCM for the model from first available free slot. Search
+   for the free slot is done starting from the lowest tile ID and lowest page ID.
+   ``largest`` - Allocate OCM for the model from the slot with largest amount of
+   free space.
+
+   For example::
+
+      -a 0000:00:10.0,ocm_alloc_mode=lowest
+
+   With the above configuration, OCM allocation fo the model would be done from
+   the first available free slot / from the lowest possible tile ID.
+
+
+- ``Enable hardware queue lock`` (default ``0``)
+
+   Option to select the job request enqueue function to used to queue the requests
+   to hardware queue. The parameter ``hw_queue_lock`` ``devargs`` is used to select
+   the enqueue function.
+
+   ``0`` - Disable (default), use lock free version of hardware enqueue function
+   for job queuing in enqueue burst operation. To avoid race condition in request
+   queuing to hardware, disabling hw_queue_lock restricts the number of queue-pairs
+   supported by cnxk driver to 1.
+   ``1`` - Enable, use spin-lock version of hardware enqueue function for job queuing.
+   Enabling spinlock version would disable restrictions on the number of queue-pairs
+   that can be supported by the driver.
+
+   For example::
+
+      -a 0000:00:10.0,hw_queue_lock=1
+
+   With the above configuration, spinlock version of hardware enqueue function is used
+   in the fast path enqueue burst operation.
+
+
+- ``Polling memory location`` (default ``ddr``)
+
+   ML cnxk driver provides the option to select the memory location to be used
+   for polling to check the inference request completion. Driver supports using
+   the either DDR address space (``ddr``) or ML registers (``register``) as
+   polling locations. The parameter ``poll_mem`` ``devargs`` is used to specify
+   the poll location.
+
+   For example::
+
+      -a 0000:00:10.0,poll_mem="register"
+
+   With the above configuration, ML cnxk driver is configured to use ML registers
+   for polling in fastpath requests.
+
+
+Debugging Options
+-----------------
+
+.. _table_octeon_cnxk_ml_debug_options:
+
+.. table:: OCTEON cnxk ML PMD debug options
+
+    +---+------------+-------------------------------------------------------+
+    | # | Component  | EAL log command                                       |
+    +===+============+=======================================================+
+    | 1 | ML         | --log-level='pmd\.ml\.cnxk,8'                         |
+    +---+------------+-------------------------------------------------------+
+
+
+Extended stats
+--------------
+
+Marvell cnxk ML PMD supports reporting the inference latencies through extended
+stats. The PMD supports the below list of 6 extended stats types per each model.
+Total number of extended stats would be equal to 6 x number of models loaded.
+
+.. _table_octeon_cnxk_ml_xstats_names:
+
+.. table:: OCTEON cnxk ML PMD xstats names
+
+    +---+---------------------+----------------------------------------------+
+    | # | Type                | Description                                  |
+    +===+=====================+==============================================+
+    | 1 | Avg-HW-Latency      | Average hardware latency                     |
+    +---+---------------------+----------------------------------------------+
+    | 2 | Min-HW-Latency      | Minimum hardware latency                     |
+    +---+---------------------+----------------------------------------------+
+    | 3 | Max-HW-Latency      | Maximum hardware latency                     |
+    +---+---------------------+----------------------------------------------+
+    | 4 | Avg-HW-Latency      | Average firmware latency                     |
+    +---+---------------------+----------------------------------------------+
+    | 5 | Avg-HW-Latency      | Minimum firmware latency                     |
+    +---+---------------------+----------------------------------------------+
+    | 6 | Avg-HW-Latency      | Maximum firmware latency                     |
+    +---+---------------------+----------------------------------------------+
+
+Latency values reported by the PMD through xstats can have units, either in
+cycles or nano seconds. The units of the latency is determined during DPDK
+initialization and would depend on the availability of SCLK. Latencies are
+reported in nao seconds when the SCLK is available and in cycles otherwise.
+Application needs to initialize at least one RVU for the clock to be available.
+
+xstats names are dynamically generated by the PMD and would have the format
+"Model-<model_id>-Type-<units>".
+
+For example::
+   Model-1-Avg-FW-Latency-ns
+
+The above xstat name would report average firmware latency in nano seconds for
+model with model ID 1.
+
+Number of xstats made available by the PMD change dynamically. The number would
+increase with loading a model and would decrease with unloading a model.
+Application needs to update the xstats map after a model is either loaded or
+unloaded.
diff --git a/doc/guides/mldevs/index.rst b/doc/guides/mldevs/index.rst
new file mode 100644
index 0000000000..f201e54175
--- /dev/null
+++ b/doc/guides/mldevs/index.rst
@@ -0,0 +1,14 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright (c) 2022 Marvell.
+
+Machine Learning Device Driver
+==============================
+
+The following are a list of ML device PMDs, which can be used from an
+application through the ML device API.
+
+.. toctree::
+    :maxdepth: 2
+    :numbered:
+
+    cnxk
-- 
2.17.1