rte_ring_peek_zc.h

       Generated automatically by Doxygen for DPDK from the source code.

DPDK                                             Version 24.11.2                           rte_ring_peek_zc.h(3)

       It is not recommended to include this file directly. Please include <rte_ring_elem.h> instead.

       Ring Peek Zero Copy APIs These APIs make it possible to split public enqueue/dequeue API into 3 parts:

       • enqueue/dequeue start

       • copy data to/from the ring

       • enqueue/dequeue  finish  Along  with the advantages of the peek APIs, these APIs provide the ability to
         avoid copying of the data to temporary area (for ex: array of mbufs on the stack).

       Note that currently these APIs are available only for two sync modes: 1) Single Producer/Single  Consumer
       (RTE_RING_SYNC_ST)  2)  Serialized  Producer/Serialized  Consumer  (RTE_RING_SYNC_MT_HTS).  It  is user's
       responsibility to create/init ring with appropriate sync modes selected.

       Following are some examples showing the API usage. 1) struct  elem_obj  {uint64_t  a;  uint32_t  b,  c;};
       struct elem_obj *obj;

       //  Create  ring with sync type RTE_RING_SYNC_ST or RTE_RING_SYNC_MT_HTS // Reserve space on the ring n =
       rte_ring_enqueue_zc_bulk_elem_start(r, sizeof(elem_obj), 1, &zcd, NULL);

       // Produce the data directly on the ring memory obj = (struct elem_obj *)zcd->ptr1; obj->a = rte_get_a();
       obj->b = rte_get_b(); obj->c = rte_get_c(); rte_ring_enqueue_zc_elem_finish(ring, n);

       2) // Create ring with sync type RTE_RING_SYNC_ST or RTE_RING_SYNC_MT_HTS // 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 none other thread can proceed with enqueue/dequeue operation till
       finish completes.

       Definition in file rte_ring_peek_zc.h.

static__rte_always_inlineunsignedintrte_ring_enqueue_zc_bulk_elem_start(structrte_ring*r,unsignedintesize,unsignedintn,structrte_ring_zc_data*zcd,unsignedint*free_space)[static]
       Start  to  enqueue  several objects on the ring. Note that no actual objects are put in the queue by this
       function, it just reserves space for the user on the ring. User has to copy objects into the queue  using
       the  returned  pointers.  User  should  call  rte_ring_enqueue_zc_elem_finish  to  complete  the  enqueue
       operation.

       Parametersr A pointer to the ring structure.
           esize The size of ring element, in bytes. It must be a multiple of 4.
           n The number of objects to add in the ring.
           zcd Structure containing the pointers and length of the space reserved on the ring storage.
           free_space If non-NULL, returns the amount of space in the ring after the reservation  operation  has
           finished.

       Returns
           The number of objects that can be enqueued, either 0 or n

       Definition at line 180 of file rte_ring_peek_zc.h.

   static__rte_always_inlineunsignedintrte_ring_enqueue_zc_bulk_start(structrte_ring*r,unsignedintn,structrte_ring_zc_data*zcd,unsignedint*free_space)[static]
       Start to enqueue several pointers to objects on the ring. Note that no actual pointers  are  put  in  the
       queue  by  this  function,  it just reserves space for the user on the ring. User has to copy pointers to
       objects into the queue using the  returned  pointers.  User  should  call  rte_ring_enqueue_zc_finish  to
       complete the enqueue operation.

       Parametersr A pointer to the ring structure.
           n The number of objects to add in the ring.
           zcd Structure containing the pointers and length of the space reserved on the ring storage.
           free_space  If  non-NULL, returns the amount of space in the ring after the reservation operation has
           finished.

       Returns
           The number of objects that can be enqueued, either 0 or n

       Definition at line 210 of file rte_ring_peek_zc.h.

   static__rte_always_inlineunsignedintrte_ring_enqueue_zc_burst_elem_start(structrte_ring*r,unsignedintesize,unsignedintn,structrte_ring_zc_data*zcd,unsignedint*free_space)[static]
       Start  to  enqueue  several objects on the ring. Note that no actual objects are put in the queue by this
       function, it just reserves space for the user on the ring. User has to copy objects into the queue  using
       the  returned  pointers.  User  should  call  rte_ring_enqueue_zc_elem_finish  to  complete  the  enqueue
       operation.

       Parametersr A pointer to the ring structure.
           esize The size of ring element, in bytes. It must be a multiple of 4.
           n The number of objects to add in the ring.
           zcd Structure containing the pointers and length of the space reserved on the ring storage.
           free_space If non-NULL, returns the amount of space in the ring after the reservation  operation  has
           finished.

       Returns
           The number of objects that can be enqueued, either 0 or n

       Definition at line 241 of file rte_ring_peek_zc.h.

   static__rte_always_inlineunsignedintrte_ring_enqueue_zc_burst_start(structrte_ring*r,unsignedintn,structrte_ring_zc_data*zcd,unsignedint*free_space)[static]
       Start  to  enqueue  several  pointers to objects on the ring. Note that no actual pointers are put in the
       queue by this function, it just reserves space for the user on the ring. User has  to  copy  pointers  to
       objects  into  the  queue  using  the  returned  pointers. User should call rte_ring_enqueue_zc_finish to
       complete the enqueue operation.

       Parametersr A pointer to the ring structure.
           n The number of objects to add in the ring.
           zcd Structure containing the pointers and length of the space reserved on the ring storage.
           free_space If non-NULL, returns the amount of space in the ring after the reservation  operation  has
           finished.

       Returns
           The number of objects that can be enqueued, either 0 or n.

       Definition at line 271 of file rte_ring_peek_zc.h.

   static__rte_always_inlinevoidrte_ring_enqueue_zc_elem_finish(structrte_ring*r,unsignedintn)[static]
       Complete enqueuing several objects on the ring. Note that number of objects to enqueue should not  exceed
       previous enqueue_start return value.

       Parametersr A pointer to the ring structure.
           n The number of objects to add to the ring.

       Definition at line 289 of file rte_ring_peek_zc.h.

   static__rte_always_inlinevoidrte_ring_enqueue_zc_finish(structrte_ring*r,unsignedintn)[static]
       Complete enqueuing several pointers to objects on the ring. Note that number of objects to enqueue should
       not exceed previous enqueue_start return value.

       Parametersr A pointer to the ring structure.
           n The number of pointers to objects to add to the ring.

       Definition at line 321 of file rte_ring_peek_zc.h.

   static__rte_always_inlineunsignedintrte_ring_dequeue_zc_bulk_elem_start(structrte_ring*r,unsignedintesize,unsignedintn,structrte_ring_zc_data*zcd,unsignedint*available)[static]
       Start to dequeue several objects from the ring. Note that no actual objects are copied from the queue  by
       this  function.  User  has  to  copy objects from the queue using the returned pointers. User should call
       rte_ring_dequeue_zc_elem_finish to complete the dequeue operation.

       Parametersr A pointer to the ring structure.
           esize The size of ring element, in bytes. It must be a multiple of 4.
           n The number of objects to remove from the ring.
           zcd Structure containing the pointers and length of the space reserved on the ring storage.
           available If non-NULL, returns the number of remaining ring entries after the dequeue has finished.

       Returns
           The number of objects that can be dequeued, either 0 or n.

       Definition at line 387 of file rte_ring_peek_zc.h.

   static__rte_always_inlineunsignedintrte_ring_dequeue_zc_bulk_start(structrte_ring*r,unsignedintn,structrte_ring_zc_data*zcd,unsignedint*available)[static]
       Start to dequeue several pointers to objects from the ring. Note that no actual pointers are removed from
       the  queue  by  this  function.  User  has  to copy pointers to objects from the queue using the returned
       pointers. User should call rte_ring_dequeue_zc_finish to complete the dequeue operation.

       Parametersr A pointer to the ring structure.
           n The number of objects to remove from the ring.
           zcd Structure containing the pointers and length of the space reserved on the ring storage.
           available If non-NULL, returns the number of remaining ring entries after the dequeue has finished.

       Returns
           The number of objects that can be dequeued, either 0 or n.

       Definition at line 416 of file rte_ring_peek_zc.h.

   static__rte_always_inlineunsignedintrte_ring_dequeue_zc_burst_elem_start(structrte_ring*r,unsignedintesize,unsignedintn,structrte_ring_zc_data*zcd,unsignedint*available)[static]
       Start  to dequeue several objects from the ring. Note that no actual objects are copied from the queue by
       this function. User has to copy objects from the queue using the  returned  pointers.  User  should  call
       rte_ring_dequeue_zc_elem_finish to complete the dequeue operation.

       Parametersr A pointer to the ring structure.
           esize  The  size  of  ring element, in bytes. It must be a multiple of 4. This must be the same value
           used while creating the ring. Otherwise the results are undefined.
           n The number of objects to dequeue from the ring.
           zcd Structure containing the pointers and length of the space reserved on the ring storage.
           available If non-NULL, returns the number of remaining ring entries after the dequeue has finished.

       Returns
           The number of objects that can be dequeued, either 0 or n.

       Definition at line 448 of file rte_ring_peek_zc.h.

   static__rte_always_inlineunsignedintrte_ring_dequeue_zc_burst_start(structrte_ring*r,unsignedintn,structrte_ring_zc_data*zcd,unsignedint*available)[static]
       Start to dequeue several pointers to objects from the ring. Note that no actual pointers are removed from
       the queue by this function. User has to copy pointers to  objects  from  the  queue  using  the  returned
       pointers. User should call rte_ring_dequeue_zc_finish to complete the dequeue operation.

       Parametersr A pointer to the ring structure.
           n The number of objects to remove from the ring.
           zcd Structure containing the pointers and length of the space reserved on the ring storage.
           available If non-NULL, returns the number of remaining ring entries after the dequeue has finished.

       Returns
           The number of objects that can be dequeued, either 0 or n.

       Definition at line 477 of file rte_ring_peek_zc.h.

   static__rte_always_inlinevoidrte_ring_dequeue_zc_elem_finish(structrte_ring*r,unsignedintn)[static]
       Complete dequeuing several objects from the ring. Note that number of  objects  to  dequeued  should  not
       exceed previous dequeue_start return value.

       Parametersr A pointer to the ring structure.
           n The number of objects to remove from the ring.

       Definition at line 495 of file rte_ring_peek_zc.h.

   static__rte_always_inlinevoidrte_ring_dequeue_zc_finish(structrte_ring*r,unsignedintn)[static]
       Complete  dequeuing  several  objects  from  the ring. Note that number of objects to dequeued should not
       exceed previous dequeue_start return value.

       Parametersr A pointer to the ring structure.
           n The number of objects to remove from the ring.

       Definition at line 527 of file rte_ring_peek_zc.h.

       rte_ring_peek_zc.h

       #include <rte_ring_peek_elem_pvt.h>

   DataStructures
       struct rte_ring_zc_dataFunctions
       static __rte_always_inline unsigned int rte_ring_enqueue_zc_bulk_elem_start (struct rte_ring *r, unsigned
           int esize, unsigned int n, struct rte_ring_zc_data *zcd, unsigned int *free_space)
       static __rte_always_inline unsigned int rte_ring_enqueue_zc_bulk_start (struct rte_ring *r, unsigned int
           n, struct rte_ring_zc_data *zcd, unsigned int *free_space)
       static __rte_always_inline unsigned int rte_ring_enqueue_zc_burst_elem_start (struct rte_ring *r,
           unsigned int esize, unsigned int n, struct rte_ring_zc_data *zcd, unsigned int *free_space)
       static __rte_always_inline unsigned int rte_ring_enqueue_zc_burst_start (struct rte_ring *r, unsigned int
           n, struct rte_ring_zc_data *zcd, unsigned int *free_space)
       static __rte_always_inline void rte_ring_enqueue_zc_elem_finish (struct rte_ring *r, unsigned int n)
       static __rte_always_inline void rte_ring_enqueue_zc_finish (struct rte_ring *r, unsigned int n)
       static __rte_always_inline unsigned int rte_ring_dequeue_zc_bulk_elem_start (struct rte_ring *r, unsigned
           int esize, unsigned int n, struct rte_ring_zc_data *zcd, unsigned int *available)
       static __rte_always_inline unsigned int rte_ring_dequeue_zc_bulk_start (struct rte_ring *r, unsigned int
           n, struct rte_ring_zc_data *zcd, unsigned int *available)
       static __rte_always_inline unsigned int rte_ring_dequeue_zc_burst_elem_start (struct rte_ring *r,
           unsigned int esize, unsigned int n, struct rte_ring_zc_data *zcd, unsigned int *available)
       static __rte_always_inline unsigned int rte_ring_dequeue_zc_burst_start (struct rte_ring *r, unsigned int
           n, struct rte_ring_zc_data *zcd, unsigned int *available)
       static __rte_always_inline void rte_ring_dequeue_zc_elem_finish (struct rte_ring *r, unsigned int n)
       static __rte_always_inline void rte_ring_dequeue_zc_finish (struct rte_ring *r, unsigned int n)