>
> Add zero copy peek API documentation.
>
> Signed-off-by: Honnappa Nagarahalli <honnappa.nagaraha...@arm.com>
> ---
> doc/guides/prog_guide/ring_lib.rst | 41 ++++++++++++++++++++++++++
> doc/guides/rel_notes/release_20_11.rst | 9 ++++++
> 2 files changed, 50 insertions(+)
>
> diff --git a/doc/guides/prog_guide/ring_lib.rst
> b/doc/guides/prog_guide/ring_lib.rst
> index 895484d95..247646d38 100644
> --- a/doc/guides/prog_guide/ring_lib.rst
> +++ b/doc/guides/prog_guide/ring_lib.rst
> @@ -452,6 +452,47 @@ selected. As an example of usage:
> Note that between ``_start_`` and ``_finish_`` none other thread can proceed
> with enqueue(/dequeue) operation till ``_finish_`` completes.
>
> +Ring Peek Zero Copy API
> +-----------------------
> +
> +Along with the advantages of the peek APIs, zero copy APIs provide the
> ability
> +to copy the data to the ring memory directly without the need for temporary
> +storage (for ex: array of mbufs on the stack).
> +
> +These APIs make it possible to split public enqueue/dequeue API into 3
> phases:
> +
> +* enqueue/dequeue start
> +
> +* copy data to/from the ring
> +
> +* enqueue/dequeue finish
> +
> +Note that this API is available only for two sync modes:
> +
> +* Single Producer/Single Consumer (SP/SC)
> +
> +* Multi-producer/Multi-consumer with Head/Tail Sync (HTS)
> +
> +It is a user responsibility to create/init ring with appropriate sync modes.
> +Following is an example of usage:
> +
> +.. code-block:: c
> +
> + /* Reserve space on the ring */
> + n = rte_ring_enqueue_zc_burst_start(r, 32, &zcd, NULL);
> + /* Pkt I/O core polls packets from the NIC */
> + if (n != 0) {
> + nb_rx = rte_eth_rx_burst(portid, queueid, zcd->ptr1, zcd->n1);
> + if (nb_rx == zcd->n1 && n != zcd->n1)
> + nb_rx = rte_eth_rx_burst(portid, queueid, zcd->ptr2,
> + n - zcd->n1);
> + /* Provide packets to the packet processing cores */
> + rte_ring_enqueue_zc_finish(r, nb_rx);
> + }
> +
> +Note that between ``_start_`` and ``_finish_`` no other thread can proceed
> +with enqueue(/dequeue) operation till ``_finish_`` completes.
> +
> References
> ----------
>
> diff --git a/doc/guides/rel_notes/release_20_11.rst
> b/doc/guides/rel_notes/release_20_11.rst
> index d8ac359e5..fdc78b3da 100644
> --- a/doc/guides/rel_notes/release_20_11.rst
> +++ b/doc/guides/rel_notes/release_20_11.rst
> @@ -55,6 +55,15 @@ New Features
> Also, make sure to start the actual text at the margin.
> =======================================================
>
> +* **Added zero copy APIs for rte_ring.**
> +
> + For rings with producer/consumer in ``RTE_RING_SYNC_ST``,
> ``RTE_RING_SYNC_MT_HTS``
> + modes, these APIs split enqueue/dequeue operation into three phases
> + (enqueue/dequeue start, copy data to/from ring, enqueue/dequeue finish).
> + Along with the advantages of the peek APIs, these provide the ability to
> + copy the data to the ring memory directly without the need for temporary
> + storage.
> +
> * **Added write combining store APIs.**
>
> Added ``rte_write32_wc`` and ``rte_write32_wc_relaxed`` APIs
> --
Acked-by: Konstantin Ananyev <konstantin.anan...@intel.com>
> 2.17.1
