This patch adds documents and release notes
about compressdev and cryptodev.
Signed-off-by: Hanxiao Li <li.hanxiao@zte.com.cn>
---
doc/guides/compressdevs/features/zsda.ini | 15 ++
doc/guides/compressdevs/index.rst | 1 +
doc/guides/compressdevs/zsda.rst | 45 ++++
doc/guides/cryptodevs/features/zsda.ini | 53 +++++
doc/guides/cryptodevs/index.rst | 1 +
doc/guides/cryptodevs/zsda.rst | 260 ++++++++++++++++++++++
doc/guides/rel_notes/release_24_11.rst | 8 +
7 files changed, 383 insertions(+)
create mode 100644 doc/guides/compressdevs/features/zsda.ini
create mode 100644 doc/guides/compressdevs/zsda.rst
create mode 100644 doc/guides/cryptodevs/features/zsda.ini
create mode 100644 doc/guides/cryptodevs/zsda.rst
diff --git a/doc/guides/compressdevs/features/zsda.ini b/doc/guides/compressdevs/features/zsda.ini
new file mode 100644
index 0000000000..3b087ea7f9
--- /dev/null
+++ b/doc/guides/compressdevs/features/zsda.ini
@@ -0,0 +1,15 @@
+;
+; Refer to default.ini for the full list of available PMD features.
+;
+; Supported features of 'ZSDA' compression driver.
+;
+[Features]
+HW Accelerated = Y
+OOP SGL In SGL Out = Y
+OOP SGL In LB Out = Y
+OOP LB In SGL Out = Y
+Deflate = Y
+Adler32 = Y
+Crc32 = Y
+Fixed = Y
+Dynamic = Y
diff --git a/doc/guides/compressdevs/index.rst b/doc/guides/compressdevs/index.rst
index 87ed4f72a4..bab226ffbc 100644
--- a/doc/guides/compressdevs/index.rst
+++ b/doc/guides/compressdevs/index.rst
@@ -17,3 +17,4 @@ Compression Device Drivers
qat_comp
uadk
zlib
+ zsda
diff --git a/doc/guides/compressdevs/zsda.rst b/doc/guides/compressdevs/zsda.rst
new file mode 100644
index 0000000000..2d0737e4ba
--- /dev/null
+++ b/doc/guides/compressdevs/zsda.rst
@@ -0,0 +1,45 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2024 ZTE Corporation.
+
+ZTE Storage Data Accelerator (ZSDA) Poll Mode Driver
+=======================================================
+
+The ZSDA compression PMD provides poll mode compression & decompression driver
+support for the following hardware accelerator devices:
+
+* ``ZTE Processing accelerators 1cf2``
+
+
+Features
+--------
+
+ZSDA compression PMD has support for:
+
+Compression/Decompression algorithm:
+
+ * DEFLATE - using Fixed and Dynamic Huffman encoding
+
+Checksum generation:
+
+ * CRC32, Adler32
+
+Huffman code type:
+
+* FIXED
+* DYNAMIC
+
+
+Limitations
+-----------
+
+* Compressdev level 0, no compression, is not supported.
+* No BSD support as BSD ZSDA kernel driver not available.
+* Stateful is not supported.
+
+
+Installation
+------------
+
+The ZSDA compression PMD is built by default with a standard DPDK build.
+
+It depends on a ZSDA kernel driver, see :ref:`building_zsda`.
\ No newline at end of file
diff --git a/doc/guides/cryptodevs/features/zsda.ini b/doc/guides/cryptodevs/features/zsda.ini
new file mode 100644
index 0000000000..efa33fbf3c
--- /dev/null
+++ b/doc/guides/cryptodevs/features/zsda.ini
@@ -0,0 +1,53 @@
+;
+; Supported features of the 'zsda' crypto driver.
+;
+; Refer to default.ini for the full list of available PMD features.
+;
+[Features]
+Symmetric crypto = Y
+HW Accelerated = Y
+Protocol offload = Y
+In Place SGL = Y
+OOP SGL In SGL Out = Y
+OOP SGL In LB Out = Y
+OOP LB In SGL Out = Y
+OOP LB In LB Out = Y
+Digest encrypted = Y
+Sym raw data path API = Y
+
+;
+; Supported crypto algorithms of the 'zsda' crypto driver.
+;
+[Cipher]
+NULL = Y
+AES XTS (128) = Y
+AES XTS (256) = Y
+SM4 AES = Y
+;
+; Supported authentication algorithms of the 'zsda' crypto driver.
+;
+[Auth]
+NULL = Y
+SHA1 = Y
+SHA224 = Y
+SHA256 = Y
+SHA384 = Y
+SHA512 = Y
+SM3 = Y
+
+;
+; Supported AEAD algorithms of the 'zsda' crypto driver.
+;
+[AEAD]
+
+
+;
+; Supported Asymmetric algorithms of the 'zsda' crypto driver.
+;
+[Asymmetric]
+
+;
+; Supported Operating systems of the 'zsda' crypto driver.
+;
+[OS]
+Linux = Y
diff --git a/doc/guides/cryptodevs/index.rst b/doc/guides/cryptodevs/index.rst
index 1e57a9fe86..be2620f185 100644
--- a/doc/guides/cryptodevs/index.rst
+++ b/doc/guides/cryptodevs/index.rst
@@ -34,3 +34,4 @@ Crypto Device Drivers
uadk
virtio
zuc
+ zsda
diff --git a/doc/guides/cryptodevs/zsda.rst b/doc/guides/cryptodevs/zsda.rst
new file mode 100644
index 0000000000..fa6015182d
--- /dev/null
+++ b/doc/guides/cryptodevs/zsda.rst
@@ -0,0 +1,260 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2024 ZTE Corporation.
+
+ZTE Storage Data Accelerator (ZSDA) Poll Mode Driver
+==================================================
+
+ZSDA documentation consists of three parts:
+
+* Details of the symmetric crypto services below.
+* Details of the :doc:`compression service <../compressdevs/zsda>`
+ in the compressdev drivers section.
+* Details of building the common ZSDA infrastructure and the PMDs to support the
+ above services. See :ref:`building_zsda` below.
+
+
+Symmetric Crypto Service on ZSDA
+-------------------------------
+
+The ZSDA symmetric crypto PMD provides poll mode crypto driver
+support for the following hardware accelerator devices:
+
+* ``ZTE Processing accelerators 1cf2``
+
+Features
+~~~~~~~~
+
+The ZSDA SYM PMD has support for:
+
+Cipher algorithms:
+
+* ``RTE_CRYPTO_CIPHER_AES_XTS``
+* ``RTE_CRYPTO_CIPHER_SM4_XTS``
+
+Hash algorithms:
+
+* ``RTE_CRYPTO_AUTH_SHA1``
+* ``RTE_CRYPTO_AUTH_SHA224``
+* ``RTE_CRYPTO_AUTH_SHA256``
+* ``RTE_CRYPTO_AUTH_SHA384``
+* ``RTE_CRYPTO_AUTH_SHA512``
+* ``RTE_CRYPTO_AUTH_SM3``
+
+Limitations
+~~~~~~~~~~~
+
+* Only supports the session-oriented API implementation (session-less APIs are not supported).
+* No BSD support as BSD ZSDA kernel driver not available.
+
+* Queue-pairs are thread-safe on Intel CPUs but Queues are not (that is, within a single
+ queue-pair all enqueues to the TX queue must be done from one thread and all dequeues
+ from the RX queue must be done from one thread, but enqueues and dequeues may be done
+ in different threads.)
+
+
+.. _building_zsda:
+
+Building PMDs on ZSDA
+--------------------
+
+A ZSDA device can host multiple acceleration services:
+
+* symmetric cryptography
+* data compression
+
+These services are provided to DPDK applications via PMDs which register to
+implement the corresponding cryptodev and compressdev APIs. The PMDs use
+common ZSDA driver code which manages the ZSDA PCI device.
+
+
+Configuring and Building the DPDK ZSDA PMDs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+Further information on configuring, building and installing DPDK is described
+:doc:`here <../linux_gsg/build_dpdk>`.
+
+.. _building_zsda_config:
+
+Build Configuration
+~~~~~~~~~~~~~~~~~~~
+These is the build configuration options affecting ZSDA, and its default values:
+
+.. code-block:: console
+
+ RTE_PMD_ZSDA_MAX_PCI_DEVICES=256
+
+ZSDA SYM PMD has an external dependency on libcrypto, so is not built by default.
+
+Ubuntu
+
+.. code-block:: console
+
+ apt install libssl-dev
+
+RHEL
+
+.. code-block:: console
+
+ dnf install openssl-devel
+
+The ZSDA compressdev PMD has no external dependencies, so is built by default.
+
+
+Device and driver naming
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+* The zsda cryptodev symmetric crypto driver name is "crypto_zsda".
+* The zsda compressdev compress driver name is "compress_zsda".
+
+The "rte_cryptodev_devices_get()" returns the devices exposed by either of these drivers.
+
+* Each zsda sym crypto device has a unique name, in format
+ "<pci bdf>", e.g. "0000:cc:00.3_zsda".
+ This name can be passed to "rte_cryptodev_get_dev_id()" to get the device_id.
+
+.. Note::
+
+ The cryptodev driver name is passed to the dpdk-test-crypto-perf tool in the "-devtype" parameter.
+
+ The zsda crypto device name is in the format of the worker parameter passed to the crypto scheduler.
+
+* The zsda compressdev driver name is "compress_zsda".
+ The rte_compressdev_devices_get() returns the devices exposed by this driver.
+
+* Each zsda compression device has a unique name, in format
+ <pci bdf>, e.g. "0000:cc:00.3_zsda".
+ This name can be passed to rte_compressdev_get_dev_id() to get the device_id.
+
+
+Enable VFs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Instructions for installation are below, but first an explanation of the
+relationships between the PF/VF devices and the PMDs visible to
+DPDK applications.
+
+Each ZSDA PF device exposes a number of VF devices. Each VF device can
+enable one symmetric cryptodev PMD and/or one compressdev PMD.
+
+These ZSDA PMDs share the same underlying device and pci-mgmt code, but are
+enumerated independently on their respective APIs and appear as independent
+devices to applications.
+.. Note::
+
+ Each VF can only be used by one DPDK process. It is not possible to share
+ the same VF across multiple processes, even if these processes are using
+ different acceleration services.
+ Conversely one DPDK process can use one or more ZSDA VFs and can expose both
+ cryptodev and compressdev instances on each of those VFs.
+
+
+The examples below are based on the 1cf2 device, if you have a different device
+use the corresponding values in the above table.
+
+In BIOS ensure that SRIOV is enabled and either:
+
+* Disable VT-d or
+* Enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file.
+
+you need to expose the Virtual Functions (VFs) using the sysfs file system.
+
+First find the BDFs (Bus-Device-Function) of the physical functions (PFs) of
+your device, e.g.::
+
+ lspci -d:8050
+
+You should see output similar to::
+
+
+ cc:00.4 Processing accelerators: Device 1cf2:8050 (rev 01)
+ ce:00.3 Processing accelerators: Device 1cf2:8050 (rev 01)
+ d0:00.3 Processing accelerators: Device 1cf2:8050 (rev 01)
+ d2:00.3 Processing accelerators: Device 1cf2:8050 (rev 01)
+
+Enable the VFs for each PF by echoing the number of VFs per PF to the pci driver::
+
+ echo 31 > /sys/bus/pci/device/0000:cc:00.4/sriov_numvfs
+ echo 31 > /sys/bus/pci/device/0000:ce:00.3/sriov_numvfs
+ echo 31 > /sys/bus/pci/device/0000:d0:00.3/sriov_numvfs
+ echo 31 > /sys/bus/pci/device/0000:d2:00.3/sriov_numvfs
+
+Check that the VFs are available for use. For example ``lspci -d:8051`` should
+list 124 VF devices available.
+
+To complete the installation follow the instructions in
+`Binding the available VFs to the vfio-pci driver`_.
+
+.. Note::
+
+ If you see the following warning in ``/var/log/messages`` it can be ignored:
+ ``IOMMU should be enabled for SR-IOV to work correctly``.
+
+Binding the available VFs to the vfio-pci driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Note:
+
+* Please note that due to security issues, the usage of older DPDK igb_uio
+ driver is not recommended. This document shows how to use the more secure
+ vfio-pci driver.
+
+Unbind the VFs from the stock driver so they can be bound to the vfio-pci driver.
+
+Bind to the vfio-pci driver
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Load the vfio-pci driver, bind the VF PCI Device id to it using the
+``dpdk-devbind.py`` script then use the ``--status`` option
+to confirm the VF devices are now in use by vfio-pci kernel driver,
+e.g. for the 1cf2 device::
+
+ cd to the top-level DPDK directory
+ modprobe vfio-pci
+ usertools/dpdk-devbind.py -b vfio-pci 0000:cc:01.4
+ usertools/dpdk-devbind.py --status
+
+Use ``modprobe vfio-pci disable_denylist=1`` from kernel 5.9 onwards.
+See note in the section `Binding the available VFs to the vfio-pci driver`_
+above.
+
+Testing
+~~~~~~~
+
+ZSDA SYM crypto PMD can be tested by running the test application::
+
+ cd ./<build_dir>/app/test
+ ./dpdk-test -l1 -n1 -a <your zsda bdf>
+ RTE>>cryptodev_zsda_autotest
+
+ZSDA compression PMD can be tested by running the test application::
+
+ cd ./<build_dir>/app/test
+ ./dpdk-test -l1 -n1 -a <your zsda bdf>
+ RTE>>compressdev_autotest
+
+
+Debugging
+~~~~~~~~~
+
+There are 2 sets of trace available via the dynamic logging feature:
+
+* pmd.zsda.dp exposes trace on the data-path.
+* pmd.zsda.general exposes all other trace.
+
+pmd.zsda exposes both sets of traces.
+They can be enabled using the log-level option (where 8=maximum log level) on
+the process cmdline, e.g. using any of the following::
+
+ --log-level="pmd.zsda.general,8"
+ --log-level="pmd.zsda.dp,8"
+
+.. Note::
+
+ The global RTE_LOG_DP_LEVEL overrides data-path trace so must be set to
+ RTE_LOG_DEBUG to see all the trace. This variable is in config/rte_config.h
+ for meson build.
+ Also the dynamic global log level overrides both sets of trace, so e.g. no
+ ZSDA trace would display in this case::
+
+ --log-level="pmd.zsda.general,8" --log-level="pmd.zsda,8"
diff --git a/doc/guides/rel_notes/release_24_11.rst b/doc/guides/rel_notes/release_24_11.rst
index 0ff70d9057..4b666d3e79 100644
--- a/doc/guides/rel_notes/release_24_11.rst
+++ b/doc/guides/rel_notes/release_24_11.rst
@@ -24,6 +24,14 @@ DPDK Release 24.11
New Features
------------
+* **Added a cryptodev driver for the ZTE Storage Data Accelerator device.**
+ Added the new ``zsda`` cryptodev driver for the ZTE ZSDA device.
+ See the :doc:`../cryptodevs/zsda` cryptodev guide for more details on this new driver.
+
+* **Added a compressdev driver for the ZTE Storage Data Accelerator device.**
+ Added the new ``zsda`` compressdev driver for the ZTE ZSDA device.
+ See the :doc:`../compressdevs/zsda` compressdev guide for more details on this new driver.
+
.. This section should contain new features added in this release.
Sample format:
--
2.27.0