[v11,2/2] doc: add dmadev library guide
Checks
Commit Message
This patch adds dmadev library guide.
Signed-off-by: Chengwen Feng <fengchengwen@huawei.com>
---
doc/guides/prog_guide/dmadev.rst | 123 +++++++++++++++++++++++++++++++++++++++
doc/guides/prog_guide/index.rst | 1 +
2 files changed, 124 insertions(+)
create mode 100644 doc/guides/prog_guide/dmadev.rst
Comments
On Tue, Jul 27, 2021 at 9:13 AM Chengwen Feng <fengchengwen@huawei.com> wrote:
>
> This patch adds dmadev library guide.
>
> Signed-off-by: Chengwen Feng <fengchengwen@huawei.com>
> ---
> doc/guides/prog_guide/dmadev.rst | 123 +++++++++++++++++++++++++++++++++++++++
> doc/guides/prog_guide/index.rst | 1 +
> 2 files changed, 124 insertions(+)
> create mode 100644 doc/guides/prog_guide/dmadev.rst
>
> diff --git a/doc/guides/prog_guide/dmadev.rst b/doc/guides/prog_guide/dmadev.rst
> new file mode 100644
> index 0000000..5bad598
> --- /dev/null
> +++ b/doc/guides/prog_guide/dmadev.rst
> @@ -0,0 +1,123 @@
> +.. SPDX-License-Identifier: BSD-3-Clause
> + Copyright 2021 HiSilicon Limited
> +
> +DMA Device Library
> +====================
> +
> +The DMA library provides a DMA device framework for management and provisioning
> +of hardware and software DMA poll mode drivers, defining generic APIs which
> +support a number of different DMA operations.
> +
> +
> +Design Principles
> +-----------------
> +
> +The DMA library follows the same basic principles as those used in DPDK's
> +Ethernet Device framework and the RegEx framework. The DMA framework provides
> +a generic DMA device framework which supports both physical (hardware)
> +and virtual (software) DMA devices as well as a generic DMA API which allows
> +DMA devices to be managed and configured and supports DMA operations to be
> +provisioned on DMA poll mode driver.
> +
> +Figure below outlines the model of the DMA framework built on:
> +
> +.. code-block:: console
> +
> + +-------------+ +-------------+ +-------------+
> + | virtual DMA | | virtual DMA | | virtual DMA |
> + | channel | | channel | | channel |
> + +-------------+ +-------------+ +-------------+
> + | | |
> + ------------------- |
> + | |
> + +----------+ +----------+
> + | dmadev | | dmadev |
> + +----------+ +----------+
> + | |
> + +--------------+ +--------------+
> + | hardware DMA | | hardware DMA |
> + | channel | | channel |
> + +--------------+ +--------------+
> + | |
> + --------------------------------
> + |
> + +--------------+
> + | hardware DMA |
> + | controller |
> + +--------------+
Please change to .svg file.
See grep -ri "Inkscape" doc/guides/contributing/documentation.rst
for guidelines.
> +
> + * The DMA controller could have multiple hardware DMA channels (aka. hardware
> + DMA queues), each hardware DMA channel should be represented by a dmadev.
> + * The dmadev could create multiple virtual DMA channels, each virtual DMA
> + channel represents a different transfer context. The DMA operation request
> + must be submitted to the virtual DMA channel. e.g. Application could create
> + virtual DMA channel 0 for memory-to-memory transfer scenario, and create
> + virtual DMA channel 1 for memory-to-device transfer scenario.
> +
> +
> +Device Management
> +-----------------
> +
> +Device Creation
> +~~~~~~~~~~~~~~~
> +
> +Physical DMA controller is discovered during the PCI probe/enumeration of the
> +EAL function which is executed at DPDK initialization, based on their PCI
> +device identifier, each unique PCI BDF (bus/bridge, device, function). Specific
> +physical DMA controller, like other physical devices in DPDK can be listed using
> +the EAL command line options.
> +
> +And then dmadevs are dynamically allocated by rte_dmadev_pmd_allocate() based on
> +the number of hardware DMA channels.
> +
> +
> +Device Identification
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +Each DMA device, whether physical or virtual is uniquely designated by two
> +identifiers:
> +
> +- A unique device index used to designate the DMA device in all functions
> + exported by the DMA API.
> +
> +- A device name used to designate the DMA device in console messages, for
> + administration or debugging purposes.
> +
> +
> +Device Configuration
> +~~~~~~~~~~~~~~~~~~~~
> +
> +The rte_dmadev_configure API is used to configure a DMA device.
> +
> +.. code-block:: c
> +
> + int rte_dmadev_configure(uint16_t dev_id,
> + const struct rte_dmadev_conf *dev_conf);
> +
> +The ``rte_dmadev_conf`` structure is used to pass the configuration parameters
> +for the DMA device for example maximum number of virtual DMA channels,
> +indication of whether to enable silent mode.
> +
> +
> +Configuration of Virtual DMA Channels
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The rte_dmadev_vchan_setup API is used to configure a virtual DMA channel.
> +
> +.. code-block:: c
> +
> + int rte_dmadev_vchan_setup(uint16_t dev_id,
> + const struct rte_dmadev_vchan_conf *conf);
> +
> +The ``rte_dmadev_vchan_conf`` structure is used to pass the configuration
> +parameters for the virtual DMA channel for example transfer direction, number of
> +descriptor for the virtual DMA channel, source device access port parameter,
> +destination device access port parameter.
Looks good. Some other section really useful and it is specific to
DMADEV could be added
1) ring_idx management, You can copy the texts from API header file or so
2) rte_dmadev_completed() management.
3) Talk about silent mode too.
On 2021/7/29 19:02, Jerin Jacob wrote:
[snip]
>> +
>> +The DMA library follows the same basic principles as those used in DPDK's
>> +Ethernet Device framework and the RegEx framework. The DMA framework provides
>> +a generic DMA device framework which supports both physical (hardware)
>> +and virtual (software) DMA devices as well as a generic DMA API which allows
>> +DMA devices to be managed and configured and supports DMA operations to be
>> +provisioned on DMA poll mode driver.
>> +
>> +Figure below outlines the model of the DMA framework built on:
>> +
>> +.. code-block:: console
>> +
>> + +-------------+ +-------------+ +-------------+
>> + | virtual DMA | | virtual DMA | | virtual DMA |
>> + | channel | | channel | | channel |
>> + +-------------+ +-------------+ +-------------+
>> + | | |
>> + ------------------- |
>> + | |
>> + +----------+ +----------+
>> + | dmadev | | dmadev |
>> + +----------+ +----------+
>> + | |
>> + +--------------+ +--------------+
>> + | hardware DMA | | hardware DMA |
>> + | channel | | channel |
>> + +--------------+ +--------------+
>> + | |
>> + --------------------------------
>> + |
>> + +--------------+
>> + | hardware DMA |
>> + | controller |
>> + +--------------+
>
> Please change to .svg file.
> See grep -ri "Inkscape" doc/guides/contributing/documentation.rst
> for guidelines.
Already send v12 without this, could it do later after merge ?
[snip]
sorry, self-response, add an explanation inline
On 2021/7/29 21:13, fengchengwen wrote:
> On 2021/7/29 19:02, Jerin Jacob wrote:
>
> [snip]
>
>>> +
>>> +The DMA library follows the same basic principles as those used in DPDK's
>>> +Ethernet Device framework and the RegEx framework. The DMA framework provides
>>> +a generic DMA device framework which supports both physical (hardware)
>>> +and virtual (software) DMA devices as well as a generic DMA API which allows
>>> +DMA devices to be managed and configured and supports DMA operations to be
>>> +provisioned on DMA poll mode driver.
>>> +
>>> +Figure below outlines the model of the DMA framework built on:
>>> +
>>> +.. code-block:: console
>>> +
>>> + +-------------+ +-------------+ +-------------+
>>> + | virtual DMA | | virtual DMA | | virtual DMA |
>>> + | channel | | channel | | channel |
>>> + +-------------+ +-------------+ +-------------+
>>> + | | |
>>> + ------------------- |
>>> + | |
>>> + +----------+ +----------+
>>> + | dmadev | | dmadev |
>>> + +----------+ +----------+
>>> + | |
>>> + +--------------+ +--------------+
>>> + | hardware DMA | | hardware DMA |
>>> + | channel | | channel |
>>> + +--------------+ +--------------+
>>> + | |
>>> + --------------------------------
>>> + |
>>> + +--------------+
>>> + | hardware DMA |
>>> + | controller |
>>> + +--------------+
>>
>> Please change to .svg file.
>> See grep -ri "Inkscape" doc/guides/contributing/documentation.rst
>> for guidelines.
>
> Already send v12 without this, could it do later after merge ?
I'm not familiar with "Inkscape" at the moment, and it may take some time to
modify it. so could we go with the above raw version first ?
>
> [snip]
> .
>
new file mode 100644
@@ -0,0 +1,123 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright 2021 HiSilicon Limited
+
+DMA Device Library
+====================
+
+The DMA library provides a DMA device framework for management and provisioning
+of hardware and software DMA poll mode drivers, defining generic APIs which
+support a number of different DMA operations.
+
+
+Design Principles
+-----------------
+
+The DMA library follows the same basic principles as those used in DPDK's
+Ethernet Device framework and the RegEx framework. The DMA framework provides
+a generic DMA device framework which supports both physical (hardware)
+and virtual (software) DMA devices as well as a generic DMA API which allows
+DMA devices to be managed and configured and supports DMA operations to be
+provisioned on DMA poll mode driver.
+
+Figure below outlines the model of the DMA framework built on:
+
+.. code-block:: console
+
+ +-------------+ +-------------+ +-------------+
+ | virtual DMA | | virtual DMA | | virtual DMA |
+ | channel | | channel | | channel |
+ +-------------+ +-------------+ +-------------+
+ | | |
+ ------------------- |
+ | |
+ +----------+ +----------+
+ | dmadev | | dmadev |
+ +----------+ +----------+
+ | |
+ +--------------+ +--------------+
+ | hardware DMA | | hardware DMA |
+ | channel | | channel |
+ +--------------+ +--------------+
+ | |
+ --------------------------------
+ |
+ +--------------+
+ | hardware DMA |
+ | controller |
+ +--------------+
+
+ * The DMA controller could have multiple hardware DMA channels (aka. hardware
+ DMA queues), each hardware DMA channel should be represented by a dmadev.
+ * The dmadev could create multiple virtual DMA channels, each virtual DMA
+ channel represents a different transfer context. The DMA operation request
+ must be submitted to the virtual DMA channel. e.g. Application could create
+ virtual DMA channel 0 for memory-to-memory transfer scenario, and create
+ virtual DMA channel 1 for memory-to-device transfer scenario.
+
+
+Device Management
+-----------------
+
+Device Creation
+~~~~~~~~~~~~~~~
+
+Physical DMA controller is discovered during the PCI probe/enumeration of the
+EAL function which is executed at DPDK initialization, based on their PCI
+device identifier, each unique PCI BDF (bus/bridge, device, function). Specific
+physical DMA controller, like other physical devices in DPDK can be listed using
+the EAL command line options.
+
+And then dmadevs are dynamically allocated by rte_dmadev_pmd_allocate() based on
+the number of hardware DMA channels.
+
+
+Device Identification
+~~~~~~~~~~~~~~~~~~~~~
+
+Each DMA device, whether physical or virtual is uniquely designated by two
+identifiers:
+
+- A unique device index used to designate the DMA device in all functions
+ exported by the DMA API.
+
+- A device name used to designate the DMA device in console messages, for
+ administration or debugging purposes.
+
+
+Device Configuration
+~~~~~~~~~~~~~~~~~~~~
+
+The rte_dmadev_configure API is used to configure a DMA device.
+
+.. code-block:: c
+
+ int rte_dmadev_configure(uint16_t dev_id,
+ const struct rte_dmadev_conf *dev_conf);
+
+The ``rte_dmadev_conf`` structure is used to pass the configuration parameters
+for the DMA device for example maximum number of virtual DMA channels,
+indication of whether to enable silent mode.
+
+
+Configuration of Virtual DMA Channels
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The rte_dmadev_vchan_setup API is used to configure a virtual DMA channel.
+
+.. code-block:: c
+
+ int rte_dmadev_vchan_setup(uint16_t dev_id,
+ const struct rte_dmadev_vchan_conf *conf);
+
+The ``rte_dmadev_vchan_conf`` structure is used to pass the configuration
+parameters for the virtual DMA channel for example transfer direction, number of
+descriptor for the virtual DMA channel, source device access port parameter,
+destination device access port parameter.
+
+
+Device Features and Capabilities
+--------------------------------
+
+DMA devices may support different feature set. In order to get the supported PMD
+features ``rte_dmadev_info_get`` API which returns the info of the device and
+it's supported features.
@@ -29,6 +29,7 @@ Programmer's Guide
regexdev
rte_security
rawdev
+ dmadev
link_bonding_poll_mode_drv_lib
timer_lib
hash_lib