cryptodev: move device-specific structures

[dpdk.git] / doc / guides / rawdevs / ioat.rst

diff --git a/doc/guides/rawdevs/ioat.rst b/doc/guides/rawdevs/ioat.rst
index 7c2a2d4..98d15dd 100644 (file)
--- a/doc/guides/rawdevs/ioat.rst
+++ b/doc/guides/rawdevs/ioat.rst
@@ -6,6 +6,10 @@
 IOAT Rawdev Driver
 ===================
 
 IOAT Rawdev Driver
 ===================
 

+.. warning::
+        As of DPDK 21.11 the rawdev implementation of the IOAT driver has been deprecated.
+        Please use the dmadev library instead.
+

 The ``ioat`` rawdev driver provides a poll-mode driver (PMD) for Intel\ |reg|
 Data Streaming Accelerator `(Intel DSA)
 <https://01.org/blogs/2019/introducing-intel-data-streaming-accelerator>`_ and for Intel\ |reg|
 The ``ioat`` rawdev driver provides a poll-mode driver (PMD) for Intel\ |reg|
 Data Streaming Accelerator `(Intel DSA)
 <https://01.org/blogs/2019/introducing-intel-data-streaming-accelerator>`_ and for Intel\ |reg|


@@ -34,6 +38,14 @@ Compilation
 For builds using ``meson`` and ``ninja``, the driver will be built when the target platform is x86-based.
 No additional compilation steps are necessary.
 
 For builds using ``meson`` and ``ninja``, the driver will be built when the target platform is x86-based.
 No additional compilation steps are necessary.
 

+.. note::
+        Since the addition of the dmadev library, the ``ioat`` and ``idxd`` parts of this driver
+        will only be built if their ``dmadev`` counterparts are not built.
+        The following can be used to disable the ``dmadev`` drivers,
+        if the raw drivers are to be used instead::
+
+                $ meson -Ddisable_drivers=dma/* <build_dir>
+

 Device Setup
 -------------
 
 Device Setup
 -------------
 


@@ -65,7 +77,7 @@ To assign an engine to a group::
         $ accel-config config-engine dsa0/engine0.1 --group-id=1
 
 To assign work queues to groups for passing descriptors to the engines a similar accel-config command can be used.
         $ accel-config config-engine dsa0/engine0.1 --group-id=1
 
 To assign work queues to groups for passing descriptors to the engines a similar accel-config command can be used.

-However, the work queues also need to be configured depending on the use-case.
+However, the work queues also need to be configured depending on the use case.

 Some configuration options include:
 
 * mode (Dedicated/Shared): Indicates whether a WQ may accept jobs from multiple queues simultaneously.
 Some configuration options include:
 
 * mode (Dedicated/Shared): Indicates whether a WQ may accept jobs from multiple queues simultaneously.


@@ -78,7 +90,7 @@ Example configuration for a work queue::
 
         $ accel-config config-wq dsa0/wq0.0 --group-id=0 \
            --mode=dedicated --priority=10 --wq-size=8 \
 
         $ accel-config config-wq dsa0/wq0.0 --group-id=0 \
            --mode=dedicated --priority=10 --wq-size=8 \

-           --type=user --name=app1
+           --type=user --name=dpdk_app1

 
 Once the devices have been configured, they need to be enabled::
 
 
 Once the devices have been configured, they need to be enabled::
 


@@ -106,15 +118,26 @@ For devices bound to a suitable DPDK-supported VFIO/UIO driver, the HW devices w
 be found as part of the device scan done at application initialization time without
 the need to pass parameters to the application.
 
 be found as part of the device scan done at application initialization time without
 the need to pass parameters to the application.
 

-If the device is bound to the IDXD kernel driver (and previously configured with sysfs),
-then a specific work queue needs to be passed to the application via a vdev parameter.
-This vdev parameter take the driver name and work queue name as parameters.
-For example, to use work queue 0 on Intel\ |reg| DSA instance 0::
-
-        $ dpdk-test --no-pci --vdev=rawdev_idxd,wq=0.0
-
-Once probed successfully, the device will appear as a ``rawdev``, that is a
-"raw device type" inside DPDK, and can be accessed using APIs from the
+For Intel\ |reg| DSA devices, DPDK will automatically configure the device with the
+maximum number of workqueues available on it, partitioning all resources equally
+among the queues.
+If fewer workqueues are required, then the ``max_queues`` parameter may be passed to
+the device driver on the EAL commandline, via the ``allowlist`` or ``-a`` flag e.g.::
+
+       $ dpdk-test -a <b:d:f>,max_queues=4
+
+For devices bound to the IDXD kernel driver,
+the DPDK ioat driver will automatically perform a scan for available workqueues to use.
+Any workqueues found listed in ``/dev/dsa`` on the system will be checked in ``/sys``,
+and any which have ``dpdk_`` prefix in their name will be automatically probed by the
+driver to make them available to the application.
+Alternatively, to support use by multiple DPDK processes simultaneously,
+the value used as the DPDK ``--file-prefix`` parameter may be used as a workqueue name prefix,
+instead of ``dpdk_``,
+allowing each DPDK application instance to only use a subset of configured queues.
+
+Once probed successfully, irrespective of kernel driver, the device will appear as a ``rawdev``,
+that is a "raw device type" inside DPDK, and can be accessed using APIs from the

 ``rte_rawdev`` library.
 
 Using IOAT Rawdev Devices
 ``rte_rawdev`` library.
 
 Using IOAT Rawdev Devices


@@ -285,6 +308,16 @@ is correct before freeing the data buffers using the returned handles:
         }
 
 
         }
 
 

+Filling an Area of Memory
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The IOAT driver also has support for the ``fill`` operation, where an area
+of memory is overwritten, or filled, with a short pattern of data.
+Fill operations can be performed in much the same was as copy operations
+described above, just using the ``rte_ioat_enqueue_fill()`` function rather
+than the ``rte_ioat_enqueue_copy()`` function.
+
+

 Querying Device Statistics
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Querying Device Statistics
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~