[v5,5/8] doc/ring: add zero copy peek APIs

Message ID 20201025054556.14277-6-honnappa.nagarahalli@arm.com
State New
Headers show
Series
  • lib/ring: add zero copy APIs
Related show

Commit Message

Honnappa Nagarahalli Oct. 25, 2020, 5:45 a.m.
Add zero copy peek API documentation.

Signed-off-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>

---
 doc/guides/prog_guide/ring_lib.rst     | 41 ++++++++++++++++++++++++++
 doc/guides/rel_notes/release_20_11.rst |  9 ++++++
 2 files changed, 50 insertions(+)

-- 
2.17.1

Comments

Ananyev, Konstantin Oct. 27, 2020, 2:11 p.m. | #1
> 

> Add zero copy peek API documentation.

> 

> Signed-off-by: Honnappa Nagarahalli <honnappa.nagarahalli@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.ananyev@intel.com>


> 2.17.1
David Marchand Oct. 29, 2020, 10:52 a.m. | #2
On Sun, Oct 25, 2020 at 6:46 AM Honnappa Nagarahalli
<honnappa.nagarahalli@arm.com> wrote:
> +.. 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);


Should it be nb_rx += ?

> +        /* 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.



-- 
David Marchand
Ananyev, Konstantin Oct. 29, 2020, 11:28 a.m. | #3
> 

> On Sun, Oct 25, 2020 at 6:46 AM Honnappa Nagarahalli

> <honnappa.nagarahalli@arm.com> wrote:

> > +.. 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);

> 

> Should it be nb_rx += ?


Yes, it should.
Good catch 😊

> 

> > +        /* 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.

> 

> 

> --

> David Marchand
David Marchand Oct. 29, 2020, 12:35 p.m. | #4
On Thu, Oct 29, 2020 at 12:29 PM Ananyev, Konstantin
<konstantin.ananyev@intel.com> wrote:
> > On Sun, Oct 25, 2020 at 6:46 AM Honnappa Nagarahalli

> > <honnappa.nagarahalli@arm.com> wrote:

> > > +.. 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);

> >

> > Should it be nb_rx += ?

>

> Yes, it should.

> Good catch


No need for a respin, I can fix.


-- 
David Marchand
Honnappa Nagarahalli Oct. 29, 2020, 5:29 p.m. | #5
<snip>

> 

> On Thu, Oct 29, 2020 at 12:29 PM Ananyev, Konstantin

> <konstantin.ananyev@intel.com> wrote:

> > > On Sun, Oct 25, 2020 at 6:46 AM Honnappa Nagarahalli

> > > <honnappa.nagarahalli@arm.com> wrote:

> > > > +.. 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);

> > >

> > > Should it be nb_rx += ?

> >

> > Yes, it should.

> > Good catch

> 

> No need for a respin, I can fix.

Thank you

> 

> 

> --

> David Marchand

Patch

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