[dpdk-dev] [PATCH v14 5/6] doc: add DMA device library guide

[Walsh, Conor]

[snip]

Hi Chengwen,
I have included some feedback to improve the grammar and readability
of the docs inline.

> +Device Management
> +-----------------
> +
> +Device Creation
> +~~~~~~~~~~~~~~~
> +
> +Physical DMA controller is discovered during the PCI probe/enumeration of

^ "controllers are" instead of "controller is"

> the
> +EAL function which is executed at DPDK initialization, based on their PCI
> +device identifier, each unique PCI BDF (bus/bridge, device, function).

Change after the first , to the following "this is based on their PCI BDF
(bus/bridge, device, function)."

> Specific
> +physical DMA controller, like other physical devices in DPDK can be listed
> using

^ "controllers" instead of "controller"

> +the EAL command line options.
> +
> +And then dmadevs are dynamically allocated by

^ Change "And then" to "After DPDK initialization".

> rte_dmadev_pmd_allocate() based on
> +the number of hardware DMA channels.

[snip]

> +Device Features and Capabilities
> +--------------------------------
> +
> +DMA devices may support different feature set. In order to get the
> supported PMD

^ missing "s" at the end of line: "DMA devices may support different feature sets."

> +features ``rte_dmadev_info_get`` API which returns the info of the device
> and
> +it's supported features.

Replace "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." with:
The ``rte_dmadev_info_get`` API can be used to get a devices info and supported features.

> +
> +A special device capability is silent mode which application don't required to
> +invoke dequeue APIs.

Replace the above sentence with:
"Silent mode is a special device capability which does not require the application
to invoke dequeue APIs."

> +
> +
> +Enqueue / Dequeue APIs
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +The enqueue APIs include like ``rte_dmadev_copy`` and ``rte_dmadev_fill``,
> if
> +enqueue successful, an uint16_t ring_idx is returned. This ring_idx can be
> used
> +by applications to track per-operation metadata in an application defined
> +circular ring.

Replace the enqueue paragraph with the following:
"Enqueue APIs such as ``rte_dmadev_copy`` and ``rte_dmadev_fill`` can be used
to enqueue operations to hardware. If an enqueue is successful, a ``ring_idx``
is returned. This ``ring_idx`` can be used by applications to track per-operation metadata
in an application-defined circular ring."

> +
> +The ``rte_dmadev_submit`` API was used to issue doorbell to hardware,
> and also
> +there are flags (``RTE_DMA_OP_FLAG_SUBMIT``) parameter of the
> enqueue APIs
> +could do the same work.

Replace submit line with this:
"The ``rte_dmadev_submit`` API is used to issue the doorbell to hardware.
Alternatively the ``RTE_DMA_OP_FLAG_SUBMIT`` flag can be passed to the
enqueue APIs to also issue the doorbell to hardware."

> +
> +There are two dequeue APIs (``rte_dmadev_completed`` and
> +``rte_dmadev_completed_status``) could used to obtain the result of
> request.

Replace the above sentence with:
"There are two dequeue APIs ``rte_dmadev_completed`` and
``rte_dmadev_completed_status``, these are used to obtain the
results of the enqueue requests."

> +The first API returns the number of operation requests completed
> successfully,
> +the second API returns the number of operation requests completed which
> may
> +successfully or failed and also with meaningful status code.

Replace above line with the following:
"``rte_dmadev_completed`` will return the number of successfully completed operations.
``rte_dmadev_completed_status`` will return the total number of completed operations
along with the status of each operation (filled into the ``status`` array passed by user)."

> Also these two
> +APIs could return the last completed operation's ring_idx which will help to
> +track application-defined circular ring.

Replace the last line with this:
"These two APIs can also return the last completed operations ``ring_idx`` which
could help developers track operations within their own application-defined rings."

With the improvements suggested above,
Acked-by: Conor Walsh <conor.walsh at intel.com>

Thanks,
Conor.