diff mbox series

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

Message ID 20201025054556.14277-6-honnappa.nagarahalli@arm.com (mailing list archive)
State Accepted, archived
Delegated to: David Marchand
Headers
Series lib/ring: add zero copy APIs |

Checks

Context Check Description
ci/checkpatch success coding style OK

Commit Message

Honnappa Nagarahalli Oct. 25, 2020, 5:45 a.m. UTC 
  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(+)

Comments

Ananyev, Konstantin Oct. 27, 2020, 2:11 p.m. UTC | #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. UTC | #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.
Ananyev, Konstantin Oct. 29, 2020, 11:28 a.m. UTC | #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. UTC | #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.
Honnappa Nagarahalli Oct. 29, 2020, 5:29 p.m. UTC | #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
diff mbox series

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