Re: [dpdk-dev] [PATCH v4 01/11] dma/ioat: add device probe and removal functions

[Bruce Richardson <bruce.richardson@intel.com>]

On Fri, Sep 17, 2021 at 03:42:17PM +0000, Conor Walsh wrote:
> Add the basic device probe/remove skeleton code and initial documentation
> for new IOAT DMA driver. Maintainers update is also included in this
> patch.
> 
> Signed-off-by: Conor Walsh <conor.walsh@intel.com>
> Reviewed-by: Kevin Laatz <kevin.laatz@intel.com>
> ---
>  MAINTAINERS                            |  6 +++
>  doc/guides/dmadevs/index.rst           |  2 +
>  doc/guides/dmadevs/ioat.rst            | 64 ++++++++++++++++++++++++
>  doc/guides/rel_notes/release_21_11.rst |  7 +--
>  drivers/dma/ioat/ioat_dmadev.c         | 69 ++++++++++++++++++++++++++
>  drivers/dma/ioat/ioat_hw_defs.h        | 35 +++++++++++++
>  drivers/dma/ioat/ioat_internal.h       | 20 ++++++++
>  drivers/dma/ioat/meson.build           |  7 +++
>  drivers/dma/ioat/version.map           |  3 ++
>  drivers/dma/meson.build                |  1 +
>  10 files changed, 211 insertions(+), 3 deletions(-)
>  create mode 100644 doc/guides/dmadevs/ioat.rst
>  create mode 100644 drivers/dma/ioat/ioat_dmadev.c
>  create mode 100644 drivers/dma/ioat/ioat_hw_defs.h
>  create mode 100644 drivers/dma/ioat/ioat_internal.h
>  create mode 100644 drivers/dma/ioat/meson.build
>  create mode 100644 drivers/dma/ioat/version.map
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 9cb59b831d..70993d23e8 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1209,6 +1209,12 @@ M: Kevin Laatz <kevin.laatz@intel.com>
>  F: drivers/dma/idxd/
>  F: doc/guides/dmadevs/idxd.rst
>  
> +Intel IOAT - EXPERIMENTAL
> +M: Bruce Richardson <bruce.richardson@intel.com>
> +M: Conor Walsh <conor.walsh@intel.com>
> +F: drivers/dma/ioat/
> +F: doc/guides/dmadevs/ioat.rst
> +
>  

Unlike the raw/ioat driver, this dmadev driver does not have a private APIs
so I'm not sure it needs the EXPERIMENTAL tag on it.

>  RegEx Drivers
>  -------------
> diff --git a/doc/guides/dmadevs/index.rst b/doc/guides/dmadevs/index.rst
> index 5d4abf880e..c59f4b5c92 100644
> --- a/doc/guides/dmadevs/index.rst
> +++ b/doc/guides/dmadevs/index.rst
> @@ -12,3 +12,5 @@ an application through DMA API.
>     :numbered:
>  
>     idxd
> +   ioat
> +
> diff --git a/doc/guides/dmadevs/ioat.rst b/doc/guides/dmadevs/ioat.rst
> new file mode 100644
> index 0000000000..45a2e65d70
> --- /dev/null
> +++ b/doc/guides/dmadevs/ioat.rst
> @@ -0,0 +1,64 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2021 Intel Corporation.
> +
> +.. include:: <isonum.txt>
> +
> +IOAT DMA Device Driver
> +=======================
> +
> +The ``ioat`` dmadev driver provides a poll-mode driver (PMD) for Intel\
> +|reg| QuickData Technology which is part of part of Intel\ |reg| I/O
> +Acceleration Technology (`Intel I/OAT
> +<https://www.intel.com/content/www/us/en/wireless-network/accel-technology.html>`_).
> +This PMD, when used on supported hardware, allows data copies, for example,
> +cloning packet data, to be accelerated by IOAT hardware rather than having to
> +be done by software, freeing up CPU cycles for other tasks.
> +
> +Hardware Requirements
> +----------------------
> +
> +The ``dpdk-devbind.py`` script, included with DPDK, can be used to show the
> +presence of supported hardware. Running ``dpdk-devbind.py --status-dev dma``
> +will show all the DMA devices on the system, IOAT devices are included in this
> +list. For Intel\ |reg| IOAT devices, the hardware will often be listed as
> +"Crystal Beach DMA", or "CBDMA" or on some newer systems '0b00' due to the
> +absence of pci-id database entries for them at this point.
> +
> +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.
> +
> +Device Setup
> +-------------
> +
> +Intel\ |reg| IOAT devices will need to be bound to a suitable DPDK-supported
> +user-space IO driver such as ``vfio-pci`` in order to be used by DPDK.
> +
> +The ``dpdk-devbind.py`` script can be used to view the state of the devices using::
> +
> +   $ dpdk-devbind.py --status-dev dma
> +
> +The ``dpdk-devbind.py`` script can also be used to bind devices to a suitable driver.
> +For example::
> +
> +	$ dpdk-devbind.py -b vfio-pci 00:01.0 00:01.1
> +
> +Device Probing and Initialization
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +For devices bound to a suitable DPDK-supported driver (``vfio-pci``), the HW
> +devices will be found as part of the device scan done at application
> +initialization time without the need to pass parameters to the application.
> +
> +If the application does not require all the devices available an allowlist can
> +be used in the same way that other DPDK devices use them.
> +
> +For example::
> +
> +	$ dpdk-test -a <b:d:f>
> +
> +Once probed successfully, the device will appear as a ``dmadev``, that is a
> +"DMA device type" inside DPDK, and can be accessed using APIs from the
> +``rte_dmadev`` library.
> diff --git a/doc/guides/rel_notes/release_21_11.rst b/doc/guides/rel_notes/release_21_11.rst
> index c0bfd9c1ba..4d2b7bde1b 100644
> --- a/doc/guides/rel_notes/release_21_11.rst
> +++ b/doc/guides/rel_notes/release_21_11.rst
> @@ -92,10 +92,11 @@ New Features
>    * Device allocation and it's multi-process support.
>    * Control and data plane functions.
>  
> -* **Added IDXD dmadev driver implementation.**
> +* **Added Intel dmadev driver implementations.**
>  
> -  The IDXD dmadev driver provide device drivers for the Intel DSA devices.
> -  This device driver can be used through the generic dmadev API.
> +  The IDXD and IOAT dmadev drivers provide device drivers for Intel DSA
> +  and IOAT devices. These device drivers can be used through the generic
> +  dmadev API.
>  

I'm not sure about merging two driver additions into a single release note
entry - one for the doc maintainers and tree committers to comment on.

Rather than "IOAT devices" I think the official name of the hardware should
be used, and you probably should add "respectively" at the end of the first
sentence to make it clear (once you change the name) which hardware is used
by which driver.