+
+.. _dmadev_enqueue_dequeue:
+
+
+Enqueue / Dequeue APIs
+~~~~~~~~~~~~~~~~~~~~~~
+
+Enqueue APIs such as ``rte_dma_copy`` and ``rte_dma_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_dma_submit`` API is used to issue 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.
+
+The following code demonstrates how to enqueue a burst of copies to the
+device and start the hardware processing of them:
+
+.. code-block:: C
+
+ struct rte_mbuf *srcs[DMA_BURST_SZ], *dsts[DMA_BURST_SZ];
+ unsigned int i;
+
+ for (i = 0; i < RTE_DIM(srcs); i++) {
+ if (rte_dma_copy(dev_id, vchan, rte_pktmbuf_iova(srcs[i]),
+ rte_pktmbuf_iova(dsts[i]), COPY_LEN, 0) < 0) {
+ PRINT_ERR("Error with rte_dma_copy for buffer %u\n", i);
+ return -1;
+ }
+ }
+ rte_dma_submit(dev_id, vchan);
+
+There are two dequeue APIs ``rte_dma_completed`` and
+``rte_dma_completed_status``, these are used to obtain the results of the
+enqueue requests. ``rte_dma_completed`` will return the number of successfully
+completed operations. ``rte_dma_completed_status`` will return the number of
+completed operations along with the status of each operation (filled into the
+``status`` array passed by user). These two APIs can also return the last
+completed operation's ``ring_idx`` which could help user track operations within
+their own application-defined rings.
+
+
+Querying Device Statistics
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The statistics from a dmadev device can be got via the statistics functions,
+i.e. ``rte_dma_stats_get()``. The statistics returned for each device instance are:
+
+* ``submitted``: The number of operations submitted to the device.
+* ``completed``: The number of operations which have completed (successful and failed).
+* ``errors``: The number of operations that completed with error.