| Message ID | 20201025054556.14277-6-honnappa.nagarahalli@arm.com |
|---|---|
| State | New |
| Headers | show |
| Series | lib/ring: add zero copy APIs | expand |
> > 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
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
> > 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
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
<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 --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
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