rte_ring_peek_zc.h(3)

📦
version 25.11.3 · 10 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay so hi bestie 🫶 this is the manual page for rte_ring_peek_zc.h — straight out of the Library Functions Manual, section 3 (that's the "library calls" section, iykyk). It's the header that gives you the Zero Copy ring peek APIs, and honestly? she's iconic. Let's get into it. ✨

✨ SYNOPSIS ✨

#include <rte_ring_peek_elem_pvt.h>

🎀 Data Structures 🎀

  • struct rte_ring_zc_data

🔥 Functions 🔥

  • rte_ring_enqueue_zc_bulk_elem_start
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)
  • rte_ring_enqueue_zc_bulk_start
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)
  • rte_ring_enqueue_zc_burst_elem_start
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)
  • rte_ring_enqueue_zc_burst_start
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)
  • rte_ring_enqueue_zc_elem_finish
static __rte_always_inline void rte_ring_enqueue_zc_elem_finish (struct
    rte_ring *r, unsigned int n)
  • rte_ring_enqueue_zc_finish
static __rte_always_inline void rte_ring_enqueue_zc_finish (struct
    rte_ring *r, unsigned int n)
  • rte_ring_dequeue_zc_bulk_elem_start
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)
  • rte_ring_dequeue_zc_bulk_start
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)
  • rte_ring_dequeue_zc_burst_elem_start
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)
  • rte_ring_dequeue_zc_burst_start
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)
  • rte_ring_dequeue_zc_elem_finish
static __rte_always_inline void rte_ring_dequeue_zc_elem_finish (struct
    rte_ring *r, unsigned int n)
  • rte_ring_dequeue_zc_finish
static __rte_always_inline void rte_ring_dequeue_zc_finish (struct
    rte_ring *r, unsigned int n)

💅 DETAILED DESCRIPTION 💅

🚨 bestie, listen — it is not recommended to include this file directly. Please include <rte_ring_elem.h> instead. for real, don't be that girl 🙈

🦋 Ring Peek Zero Copy APIs 🦋

These APIs make it possible to split the 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 a temporary area (for ex: array of mbufs on the stack). no cap, that's the whole point. 💅

⚠️ 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. read that again bestie, that's on you. 😭

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. like, nobody. wait your turn. ✋

Definition in file rte_ring_peek_zc.h. 📄

🌸 more coming, bestie — this page is a whole saga, and part 2 is on the way 🌸

✨ FUNCTION DOCUMENTATION ✨

okay bestie, this is the part where we meet the actual functions. twelve of them. every single one is static and __rte_always_inline, which is just the compiler's way of saying "this is basically a vibe, not a function call" 💅

rte_ring_enqueue_zc_bulk_elem_start

__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)

Start to enqueue several objects on the ring. And listen — this function does not actually put anything in the queue. It just reserves space for you on the ring, like holding a table at a restaurant. You then copy your objects in yourself using the pointers it hands back. Once you're done, you call rte_ring_enqueue_zc_elem_finish to actually complete the enqueue operation. No cap.

Parameters

  • r — a pointer to the ring structure 🎀
  • esize — the size of a ring element, in bytes. It must be a multiple of 4.
  • n — the number of objects to add in the ring.
  • zcd — a structure containing the pointers and length of the space reserved on the ring storage. it's giving map-of-the-reservation ✨
  • free_space — if non-NULL, it 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. that's it, that's the whole range, it's binary bestie 😭

Definition at line 180 of file rte_ring_peek_zc.h.

rte_ring_enqueue_zc_bulk_start

__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)

Start to enqueue several pointers to objects on the ring. Same deal as above: no actual pointers get put in the queue here, it just reserves your space. You copy the pointers to objects into the queue yourself, using the pointers it returns. Then you call rte_ring_enqueue_zc_finish to wrap up the enqueue operation. periodt.

Parameters

  • r — 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.

rte_ring_enqueue_zc_burst_elem_start

__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)

Start to enqueue several objects on the ring. Again — nothing is actually put in the queue by this function. It only reserves space for you. You copy the objects in via the returned pointers, then call rte_ring_enqueue_zc_elem_finish to complete the enqueue operation. iconic behaviour tbh.

Parameters

  • r — 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 actual number of objects that can be enqueued. not just 0-or-n, the real number, we love a flexible queen ✨

Definition at line 241 of file rte_ring_peek_zc.h.

rte_ring_enqueue_zc_burst_start

__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)

Start to enqueue several pointers to objects on the ring. No actual pointers are put in the queue by this function — it only reserves space for you. You copy the pointers to objects into the queue using the returned pointers, and you should call rte_ring_enqueue_zc_finish to complete the enqueue operation. 💖

Parameters

  • r — 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 actual number of objects that can be enqueued. 🫶

Definition at line 271 of file rte_ring_peek_zc.h.

rte_ring_enqueue_zc_elem_finish

__rte_always_inline void
rte_ring_enqueue_zc_elem_finish(struct rte_ring *r, unsigned int n)

Complete enqueuing several objects on the ring. this is the "okay I'm actually done now" call 🌈

⚠️ Important, bestie: the number of objects to enqueue should not exceed the previous enqueue_start return value. Don't try it. it will not be cute.

Parameters

  • r — 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.

rte_ring_enqueue_zc_finish

__rte_always_inline void
rte_ring_enqueue_zc_finish(struct rte_ring *r, unsigned int n)

Complete enqueuing several pointers to objects on the ring. the pointer-flavoured twin of the one above 💅

⚠️ Same energy: the number of objects to enqueue should not exceed the previous enqueue_start return value.

Parameters

  • r — a pointer to the ring structure.
  • n — the number of pointers to objects to add to the ring. (pointers, not objects, note the distinction, iykyk)

Definition at line 321 of file rte_ring_peek_zc.h.

rte_ring_dequeue_zc_bulk_elem_start

__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)

Start to dequeue several objects from the ring. note that no actual objects are copied from the queue by this function. You do the copying yourself, using the returned pointers. Then call rte_ring_dequeue_zc_elem_finish to complete the dequeue operation. we love a two-step 🎀

Parameters

  • r — 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.

rte_ring_dequeue_zc_bulk_start

__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)

Start to dequeue several pointers to objects from the ring. no actual pointers are removed from the queue by this function. you copy the pointers to objects from the queue using the returned pointers, and you should call rte_ring_dequeue_zc_finish to complete the dequeue operation. slay 🦋

Parameters

  • r — 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.

rte_ring_dequeue_zc_burst_elem_start

__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)

Start to dequeue several objects from the ring. no actual objects are copied from the queue by this function — you copy objects from the queue using the returned pointers, then call rte_ring_dequeue_zc_elem_finish to complete the dequeue operation.

Parameters

  • r — 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. 💀 like, genuinely undefined, not "undefined" as a joke. match it up.
  • 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 actual number of objects that can be dequeued. 🔥

Definition at line 448 of file rte_ring_peek_zc.h.

rte_ring_dequeue_zc_burst_start

__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)

Start to dequeue several pointers to objects from the ring. no actual pointers are removed from the queue by this function. you copy the pointers to objects from the queue using the returned pointers, and call rte_ring_dequeue_zc_finish to complete the dequeue operation. 💜

Parameters

  • r — 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 actual number of objects that can be dequeued. 👑

Definition at line 477 of file rte_ring_peek_zc.h.

rte_ring_dequeue_zc_elem_finish

__rte_always_inline void
rte_ring_dequeue_zc_elem_finish(struct rte_ring *r, unsigned int n)

Complete dequeuing several objects from the ring. the closing ceremony ✨

⚠️ Note: the number of objects to dequeue should not exceed the previous dequeue_start return value. do not test this one, bestie, it's a trap.

Parameters

  • r — 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.

rte_ring_dequeue_zc_finish

__rte_always_inline void
rte_ring_dequeue_zc_finish(struct rte_ring *r, unsigned int n)

Complete dequeuing several objects from the ring. yes, the description really is word-for-word the same as rte_ring_dequeue_zc_elem_finish — it's the pointer-friend version, they're just like that 💀

⚠️ Note: the number of objects to dequeue should not exceed the previous dequeue_start return value.

Parameters

  • r — 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.

👑 AUTHOR 👑

Generated automatically by Doxygen for DPDK from the source code. (yes, a robot wrote this. a very diligent robot. respect.)

aaaand that's a wrap on rte_ring_peek_zc.h(3) fr fr 🎀 you made it to the end, bestie, that's main character energy right there. this page came straight out of the DPDK Version 25.11.3 docs, dated rte_ring_peek_zc.h(3) — go forth and zero-copy responsibly 💖✨

📦 where this page comes from