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
--
2.17.1
