[dpdk-dev] [PATCH v3 6/8] baseband/la12xx: add documentation support

[Hemant Agrawal]

This patch add documentation for LA12xx PMD.

Signed-off-by: Nipun Gupta <nipun.gupta at nxp.com>
Signed-off-by: Hemant Agrawal <hemant.agrawal at nxp.com>
---
 MAINTAINERS                            |   9 ++
 doc/guides/bbdevs/features/la12xx.ini  |  14 +++
 doc/guides/bbdevs/index.rst            |   1 +
 doc/guides/bbdevs/la12xx.rst           | 139 +++++++++++++++++++++++++
 doc/guides/rel_notes/release_21_05.rst |   5 +
 5 files changed, 168 insertions(+)
 create mode 100644 doc/guides/bbdevs/features/la12xx.ini
 create mode 100644 doc/guides/bbdevs/la12xx.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index e746ef1d32..24081fceb3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1289,6 +1289,15 @@ F: doc/guides/rawdevs/ntb.rst
 F: examples/ntb/
 F: doc/guides/sample_app_ug/ntb.rst
 
+Baseband Drivers
+-------------------
+
+NXP LA12xx
+M: Hemant Agrawal <hemant.agrawal at nxp.com>
+M: Nipun Gupta <nipun.gupta at nxp.com>
+F: drivers/baseband/la12xx/
+F: doc/guides/bbdevs/la12xx.rst
+F: doc/guides/bbdevs/features/la12xx.ini
 
 Packet processing
 -----------------
diff --git a/doc/guides/bbdevs/features/la12xx.ini b/doc/guides/bbdevs/features/la12xx.ini
new file mode 100644
index 0000000000..979d9dd224
--- /dev/null
+++ b/doc/guides/bbdevs/features/la12xx.ini
@@ -0,0 +1,14 @@
+;
+; Supported features of the 'la12xx' bbdev driver.
+;
+; Refer to default.ini for the full list of available PMD features.
+;
+[Features]
+Turbo Decoder (4G)     = N
+Turbo Encoder (4G)     = N
+LDPC Decoder (5G)      = Y
+LDPC Encoder (5G)      = Y
+LLR/HARQ Compression   = N
+External DDR Access    = Y
+HW Accelerated         = Y
+BBDEV API              = Y
diff --git a/doc/guides/bbdevs/index.rst b/doc/guides/bbdevs/index.rst
index 4445cbd1b0..cedd706fa6 100644
--- a/doc/guides/bbdevs/index.rst
+++ b/doc/guides/bbdevs/index.rst
@@ -14,3 +14,4 @@ Baseband Device Drivers
     fpga_lte_fec
     fpga_5gnr_fec
     acc100
+    la12xx
diff --git a/doc/guides/bbdevs/la12xx.rst b/doc/guides/bbdevs/la12xx.rst
new file mode 100644
index 0000000000..1cadd6f337
--- /dev/null
+++ b/doc/guides/bbdevs/la12xx.rst
@@ -0,0 +1,139 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright 2021 NXP
+
+NXP LA12xx Poll Mode Driver
+=======================================
+
+The BBDEV LA12xx poll mode driver (PMD) supports an implementation for
+offloading High Phy processing functions like LDPC Encode / Decode 5GNR wireless
+acceleration function, using PCI based LA12xx Software defined radio.
+
+More information can be found at `NXP Official Website
+<https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/layerscape-processors/layerscape-access-la1200-programmable-baseband-processor:LA1200>`_.
+
+Features
+--------
+
+LA12xx PMD supports the following features:
+
+- LDPC Encode in the DL
+- LDPC Decode in the UL
+- Maximum of 8 UL queues
+- Maximum of 8 DL queues
+- PCIe Gen-3 x8 Interface
+- MSI-X
+
+LA12xx PMD supports the following BBDEV capabilities:
+
+* For the LDPC encode operation:
+   - ``RTE_BBDEV_LDPC_CRC_24B_ATTACH`` :  set to attach CRC24B to CB(s)
+   - ``RTE_BBDEV_LDPC_RATE_MATCH`` :  if set then do not do Rate Match bypass
+
+* For the LDPC decode operation:
+   - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK`` :  check CRC24B from CB(s)
+   - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP`` :  drops CRC24B bits appended while decoding
+   - ``RTE_BBDEV_LDPC_DEC_SCATTER_GATHER`` :  supports scatter-gather for input/output data
+
+Installation
+------------
+
+Section 3 of the DPDK manual provides instructions on installing and compiling DPDK.
+
+DPDK requires hugepages to be configured as detailed in section 2 of the DPDK manual.
+
+Initialization
+--------------
+
+The device can be listed on the host console with:
+
+
+Use the following lspci command to get the multiple LA12xx processor ids. The
+device ID of the LA12xx baseband processor is "1c30".
+
+.. code-block:: console
+
+  sudo lspci -nn
+
+...
+0001:01:00.0 Power PC [0b20]: Freescale Semiconductor Inc Device [1957:1c30] (
+rev 10)
+...
+0002:01:00.0 Power PC [0b20]: Freescale Semiconductor Inc Device [1957:1c30] (
+rev 10)
+
+
+Prerequisites
+-------------
+
+Currently supported by DPDK:
+
+- NXP LA1224 BSP **1.0+**.
+- NXP LA1224 PCIe Modem card connected to ARM host.
+
+- Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
+
+* Use dev arg option ``modem=0`` to identify the modem instance for a given
+  device. This is required only if more than 1 modem cards are attached to host.
+  this is optional and the default value is 0.
+  e.g. ``--vdev=baseband_la12xx,modem=0``
+
+* Use dev arg option ``max_nb_queues=x`` to specify the maximum number of queues
+  to be used for communication with offload device i.e. modem. default is 16.
+  e.g. ``--vdev=baseband_la12xx,max_nb_queues=4``
+
+Enabling logs
+-------------
+
+For enabling logs, use the following EAL parameter:
+
+.. code-block:: console
+
+   ./your_bbdev_application <EAL args> --log-level=la12xx:<level>
+
+Using ``bb.la12xx`` as log matching criteria, all Baseband PMD logs can be
+enabled which are lower than logging ``level``.
+
+
+Test Application
+----------------
+
+BBDEV provides a test application, ``test-bbdev.py`` and range of test data for testing
+the functionality of LA12xx for FEC encode and decode, depending on the device
+capabilities. The test application is located under app->test-bbdev folder and has the
+following options:
+
+.. code-block:: console
+
+  "-p", "--testapp-path": specifies path to the bbdev test app.
+  "-e", "--eal-params"	: EAL arguments which are passed to the test app.
+  "-t", "--timeout"	: Timeout in seconds (default=300).
+  "-c", "--test-cases"	: Defines test cases to run. Run all if not specified.
+  "-v", "--test-vector"	: Test vector path (default=dpdk_path+/app/test-bbdev/test_vectors/bbdev_null.data).
+  "-n", "--num-ops"	: Number of operations to process on device (default=32).
+  "-b", "--burst-size"	: Operations enqueue/dequeue burst size (default=32).
+  "-s", "--snr"		: SNR in dB used when generating LLRs for bler tests.
+  "-s", "--iter_max"	: Number of iterations for LDPC decoder.
+  "-l", "--num-lcores"	: Number of lcores to run (default=16).
+  "-i", "--init-device" : Initialise PF device with default values.
+
+
+To execute the test application tool using simple decode or encode data,
+type one of the following:
+
+.. code-block:: console
+
+  ./test-bbdev.py -e="--vdev=baseband_la12xx,socket_id=0,max_nb_queues=8" -c validation -n 64 -b 1 -v ./ldpc_dec_default.data
+  ./test-bbdev.py -e="--vdev=baseband_la12xx,socket_id=0,max_nb_queues=8" -c validation -n 64 -b 1 -v ./ldpc_enc_default.data
+
+The test application ``test-bbdev.py``, supports the ability to configure the PF device with
+a default set of values, if the "-i" or "- -init-device" option is included. The default values
+are defined in test_bbdev_perf.c.
+
+
+Test Vectors
+~~~~~~~~~~~~
+
+In addition to the simple LDPC decoder and LDPC encoder tests, bbdev also provides
+a range of additional tests under the test_vectors folder, which may be useful. The results
+of these tests will depend on the LA12xx FEC capabilities which may cause some
+testcases to be skipped, but no failure should be reported.
diff --git a/doc/guides/rel_notes/release_21_05.rst b/doc/guides/rel_notes/release_21_05.rst
index 6f5858c8f6..61797e2a43 100644
--- a/doc/guides/rel_notes/release_21_05.rst
+++ b/doc/guides/rel_notes/release_21_05.rst
@@ -130,6 +130,11 @@ New Features
   * Added command to display Rx queue used descriptor count.
     ``show port (port_id) rxq (queue_id) desc used count``
 
+* **Added NXP LA12xx baseband PMD.**
+
+  Added a new baseband PMD driver for NXP LA12xx Software defined radio.
+
+  See the :doc:`../bbdevs/la12xx` for more details.
 
 Removed Items
 -------------
-- 
2.17.1