rte_mbuf.h(3)

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

rte_mbuf.h(3) — Library Functions Manual 💖

bestie, welcome to the mbuf page. it's giving iconic, it's giving packet buffers, and we're gonna go through every single detail. no skipping. periodt. ✨

🌸 NAME 🌸

rte_mbuf.h — yeah, that's the file. that's the name. short, sweet, slay. 💅

✨ SYNOPSIS ✨

okay so first, the includes. you literally need these at the top, no cap:

#include <stdbool.h>
#include <stdint.h>
#include <rte_common.h>
#include <rte_config.h>
#include <rte_mempool.h>
#include <rte_prefetch.h>
#include <rte_branch_prediction.h>
#include <rte_mbuf_ptype.h>
#include <rte_mbuf_core.h>
#include <rte_mbuf_history.h>

🎀 Data Structures 🎀

here's the cast of structs, bestie:

  • struct rte_pktmbuf_pool_private
  • struct rte_pktmbuf_extmem

💅 Macros 💅

these are the macro moments. exact spacing kept because macros are picky and we respect them:

#define RTE_PKTMBUF_POOL_F_PINNED_EXT_BUF   (1 << 0)
#define RTE_MBUF_HAS_PINNED_EXTBUF(mb)
#define __rte_mbuf_raw_sanity_check_mp(m,  mp)
#define __rte_mbuf_sanity_check(m,  is_h)
#define RTE_MBUF_PREFETCH_TO_FREE(m)
#define __rte_mbuf_raw_sanity_check(m)
#define MBUF_RAW_ALLOC_CHECK(m)
#define rte_pktmbuf_detach_extbuf(m)
#define rte_pktmbuf_pkt_len(m)
#define rte_pktmbuf_data_len(m)

🦋 Functions 🦋

the full function roster, fr fr. signatures exactly as the manpage says, because we do not mess with prototypes in this house:

       const char * rte_get_rx_ol_flag_name (uint64_t mask)
       int rte_get_rx_ol_flag_list (uint64_t mask, char *buf, size_t buflen)
       const char * rte_get_tx_ol_flag_name (uint64_t mask)
       int rte_get_tx_ol_flag_list (uint64_t mask, char *buf, size_t buflen)
       static void rte_mbuf_prefetch_part1 (struct rte_mbuf *m)
       static void rte_mbuf_prefetch_part2 (struct rte_mbuf *m)
       static uint16_t rte_pktmbuf_priv_size (struct rte_mempool *mp)
       static rte_iova_t rte_mbuf_iova_get (const struct rte_mbuf *m)
       static void rte_mbuf_iova_set (struct rte_mbuf *m, rte_iova_t iova)
       static rte_iova_t rte_mbuf_data_iova (const struct rte_mbuf *mb)
       static rte_iova_t rte_mbuf_data_iova_default (const struct rte_mbuf *mb)
       static struct rte_mbuf * rte_mbuf_from_indirect (struct rte_mbuf *mi)
       static char * rte_mbuf_buf_addr (struct rte_mbuf *mb, struct rte_mempool
           *mp)
       static char * rte_mbuf_data_addr_default (struct rte_mbuf *mb)
       static char * rte_mbuf_to_baddr (struct rte_mbuf *md)
       static void * rte_mbuf_to_priv (struct rte_mbuf *m)
       static uint32_t rte_pktmbuf_priv_flags (struct rte_mempool *mp)
       static uint16_t rte_mbuf_refcnt_update (struct rte_mbuf *m, int16_t
           value)
       static uint16_t rte_mbuf_refcnt_read (const struct rte_mbuf *m)
       static void rte_mbuf_refcnt_set (struct rte_mbuf *m, uint16_t new_value)
       static uint16_t rte_mbuf_ext_refcnt_read (const struct
           rte_mbuf_ext_shared_info *shinfo)
       static void rte_mbuf_ext_refcnt_set (struct rte_mbuf_ext_shared_info
           *shinfo, uint16_t new_value)
       static uint16_t rte_mbuf_ext_refcnt_update (struct
           rte_mbuf_ext_shared_info *shinfo, int16_t value)
       void rte_mbuf_raw_sanity_check (const struct rte_mbuf *m, const struct
           rte_mempool *mp)
       int rte_mbuf_raw_check (const struct rte_mbuf *m, const struct
           rte_mempool *mp, const char **reason)
       void rte_mbuf_sanity_check (const struct rte_mbuf *m, int is_header)
       int rte_mbuf_check (const struct rte_mbuf *m, int is_header, const char
           **reason)
       static struct rte_mbuf * rte_mbuf_raw_alloc (struct rte_mempool *mp)
       static __rte_always_inline int rte_mbuf_raw_alloc_bulk (struct
           rte_mempool *mp, struct rte_mbuf **mbufs, unsigned int count)
       static __rte_always_inline void rte_mbuf_raw_free (struct rte_mbuf *m)
       static __rte_always_inline void rte_mbuf_raw_free_bulk (struct
           rte_mempool *mp, struct rte_mbuf **mbufs, unsigned int count)
       void rte_pktmbuf_init (struct rte_mempool *mp, void *opaque_arg, void
           *m, unsigned i)
       void rte_pktmbuf_pool_init (struct rte_mempool *mp, void *opaque_arg)
       struct rte_mempool * rte_pktmbuf_pool_create (const char *name, unsigned
           n, unsigned cache_size, uint16_t priv_size, uint16_t data_room_size,
           int socket_id)
       struct rte_mempool * rte_pktmbuf_pool_create_by_ops (const char *name,
           unsigned int n, unsigned int cache_size, uint16_t priv_size,
           uint16_t data_room_size, int socket_id, const char *ops_name)
       struct rte_mempool * rte_pktmbuf_pool_create_extbuf (const char *name,
           unsigned int n, unsigned int cache_size, uint16_t priv_size,
           uint16_t data_room_size, int socket_id, const struct
           rte_pktmbuf_extmem *ext_mem, unsigned int ext_num)
       static uint16_t rte_pktmbuf_data_room_size (struct rte_mempool *mp)
       static void rte_pktmbuf_reset_headroom (struct rte_mbuf *m)
       static void rte_mbuf_raw_reset_bulk (struct rte_mempool *mp, struct
           rte_mbuf **mbufs, unsigned int count)
       static void rte_pktmbuf_reset (struct rte_mbuf *m)
       static struct rte_mbuf * rte_pktmbuf_alloc (struct rte_mempool *mp)
       static int rte_pktmbuf_alloc_bulk (struct rte_mempool *pool, struct
           rte_mbuf **mbufs, unsigned count)
       static struct rte_mbuf_ext_shared_info *
           rte_pktmbuf_ext_shinfo_init_helper (void *buf_addr, uint16_t
           *buf_len, rte_mbuf_extbuf_free_callback_t free_cb, void *fcb_opaque)
       static void rte_pktmbuf_attach_extbuf (struct rte_mbuf *m, void
           *buf_addr, rte_iova_t buf_iova, uint16_t buf_len, struct
           rte_mbuf_ext_shared_info *shinfo)
       static void rte_mbuf_dynfield_copy (struct rte_mbuf *mdst, const struct
           rte_mbuf *msrc)
       static void rte_pktmbuf_attach (struct rte_mbuf *mi, struct rte_mbuf *m)
       static void rte_pktmbuf_detach (struct rte_mbuf *m)
       static __rte_always_inline struct rte_mbuf * rte_pktmbuf_prefree_seg
           (struct rte_mbuf *m)
       static __rte_always_inline void rte_pktmbuf_free_seg (struct rte_mbuf
           *m)
       static void rte_pktmbuf_free (struct rte_mbuf *m)
       void rte_pktmbuf_free_bulk (struct rte_mbuf **mbufs, unsigned int count)
       struct rte_mbuf * rte_pktmbuf_clone (struct rte_mbuf *md, struct
           rte_mempool *mp)
       struct rte_mbuf * rte_pktmbuf_copy (const struct rte_mbuf *m, struct
           rte_mempool *mp, uint32_t offset, uint32_t length)
       static void rte_pktmbuf_refcnt_update (struct rte_mbuf *m, int16_t v)
       static uint16_t rte_pktmbuf_headroom (const struct rte_mbuf *m)
       static uint16_t rte_pktmbuf_tailroom (const struct rte_mbuf *m)
       static struct rte_mbuf * rte_pktmbuf_lastseg (struct rte_mbuf *m)
       static char * rte_pktmbuf_prepend (struct rte_mbuf *m, uint16_t len)
       static char * rte_pktmbuf_append (struct rte_mbuf *m, uint16_t len)
       static char * rte_pktmbuf_adj (struct rte_mbuf *m, uint16_t len)
       static int rte_pktmbuf_trim (struct rte_mbuf *m, uint16_t len)
       static int rte_pktmbuf_is_contiguous (const struct rte_mbuf *m)
       static const void * rte_pktmbuf_read (const struct rte_mbuf *m, uint32_t
           off, uint32_t len, void *buf)
       static int rte_pktmbuf_chain (struct rte_mbuf *head, struct rte_mbuf
           *tail)
       static __rte_always_inline uint64_t rte_mbuf_tx_offload (uint64_t il2,
           uint64_t il3, uint64_t il4, uint64_t tso, uint64_t ol3, uint64_t
           ol2, uint64_t unused)
       static int rte_validate_tx_offload (const struct rte_mbuf *m)
       static int rte_pktmbuf_linearize (struct rte_mbuf *mbuf)
       void rte_pktmbuf_dump (FILE *f, const struct rte_mbuf *m, unsigned
           dump_len)
       static uint32_t rte_mbuf_sched_queue_get (const struct rte_mbuf *m)
       static uint8_t rte_mbuf_sched_traffic_class_get (const struct rte_mbuf
           *m)
       static uint8_t rte_mbuf_sched_color_get (const struct rte_mbuf *m)
       static void rte_mbuf_sched_get (const struct rte_mbuf *m, uint32_t
           *queue_id, uint8_t *traffic_class, uint8_t *color)
       static void rte_mbuf_sched_queue_set (struct rte_mbuf *m, uint32_t
           queue_id)
       static void rte_mbuf_sched_traffic_class_set (struct rte_mbuf *m,
           uint8_t traffic_class)
       static void rte_mbuf_sched_color_set (struct rte_mbuf *m, uint8_t color)
       static void rte_mbuf_sched_set (struct rte_mbuf *m, uint32_t queue_id,
           uint8_t traffic_class, uint8_t color)

💖 Detailed Description 💖

okay so RTE Mbuf is the whole vibe. the mbuf library provides the ability to create and destroy buffers that may be used by the RTE application to store message buffers. those message buffers are stored in a mempool, using the RTE mempool library. 🫶

the preferred way to create a mbuf pool is to use rte_pktmbuf_pool_create(). however, in some situations, an application may want to have more control (ex: populate the pool with specific memory), and in this case it is possible to use functions from rte_mempool. see how rte_pktmbuf_pool_create() is implemented for details. 👀

this library provides an API to allocate/free packet mbufs, which are used to carry network packets. 🌐

to understand the concepts of packet buffers or mbufs, you should read "TCP/IP Illustrated, Volume 2: The Implementation,Addison-Wesley, 1995, ISBN 0-201-63354-X from Richard Stevens" http://www.kohala.com/start/tcpipiv2.html 📚

definition in file rte_mbuf.h.

✨ Macro Definition Documentation ✨

🎀 #define RTE_PKTMBUF_POOL_F_PINNED_EXT_BUF (1 << 0)

okay so when this flag is set, a pktmbuf mempool is gonna hold only mbufs with a pinned external buffer. What does pinned mean bestie? It means the external buffer gets attached to the mbuf right at memory pool creation time, and it will never be detached when the mbuf free calls happen. it's giving forever-buffer 💅

one thing tho — the mbuf should not contain any room for data after the mbuf structure. that's the deal.

Definition at line 330 of file rte_mbuf.h.

🦋 #define RTE_MBUF_HAS_PINNED_EXTBUF( mb)

Value:

(rte_pktmbuf_priv_flags(mb->pool) & RTE_PKTMBUF_POOL_F_PINNED_EXT_BUF)

Returns non zero if the mbuf you handed it has a pinned external buffer, and zero if it doesn't. lowkey simple. The pinned external buffer is allocated at pool creation time and should not be freed when the mbuf gets freed — it is not that kind of buffer.

oh and an external buffer is a user-provided anonymous buffer, iykyk.

Definition at line 339 of file rte_mbuf.h.

🌸 #define __rte_mbuf_raw_sanity_check_mp( m, mp)

Value:

rte_mbuf_raw_sanity_check(m, mp)

Checks the reinitialized mbuf type in debug mode. your little debug-mode vibe check ✨

Definition at line 345 of file rte_mbuf.h.

🎀 #define __rte_mbuf_sanity_check( m, is_h)

Value:

rte_mbuf_sanity_check(m, is_h)

Checks the mbuf type in debug mode. again, debug mode only, bestie.

Definition at line 347 of file rte_mbuf.h.

💜 #define RTE_MBUF_PREFETCH_TO_FREE( m)

Value:

do {       \
    if ((m) != NULL)                        \
        rte_prefetch0(m);               \
} while (0)

Mbuf prefetch. it literally just peeks at the mbuf so the cache is ready when you go to free it 👑

Definition at line 514 of file rte_mbuf.h.

⭐ #define __rte_mbuf_raw_sanity_check( m)

Value:

__rte_mbuf_raw_sanity_check_mp(m, NULL)

For backwards compatibility. we keep it around because the old code still loves it.

Definition at line 598 of file rte_mbuf.h.

🌈 #define MBUF_RAW_ALLOC_CHECK( m)

Value:

__rte_mbuf_raw_sanity_check_mp(m, NULL)

For backwards compatibility too. same energy, different name.

Definition at line 601 of file rte_mbuf.h.

🧚 #define rte_pktmbuf_detach_extbuf( m)

Value:

rte_pktmbuf_detach(m)

Detaches the external buffer attached to an mbuf — literally same as rte_pktmbuf_detach().

Parameters

  • m — the mbuf having the external buffer.

Definition at line 1223 of file rte_mbuf.h.

🍓 #define rte_pktmbuf_pkt_len( m)

Value:

((m)->pkt_len)

A macro that hands you the length of the packet. you can read it or assign to it, both are valid, no gatekeeping.

Parameters

  • m — the packet mbuf.

Definition at line 1658 of file rte_mbuf.h.

🦋 #define rte_pktmbuf_data_len( m)

Value:

((m)->data_len)

A macro that hands you the length of the segment. read it or assign it, your call bestie.

Parameters

  • m — the packet mbuf.

Definition at line 1668 of file rte_mbuf.h.

🔥 Function Documentation 🔥

👑 const char * rte_get_rx_ol_flag_name (uint64_t mask)

Get the name of a RX offload flag. so like, you give it the mask, it gives you the string. iconic lookup behaviour.

Parameters

  • mask — the mask describing the flag.

Returns

  • The name of this flag, or NULL if it's not a valid RX flag. (yes, it can reject you 😭)

💖 int rte_get_rx_ol_flag_list (uint64_t mask, char * buf, size_t buflen)

Dump the list of RX offload flags into a buffer. all of them. into your lil buffer.

Parameters

  • mask — the mask describing the RX flags.
  • buf — the output buffer.
  • buflen — the length of the buffer.

Returns

  • 0 on success, (-1) on error.

⭐ const char * rte_get_tx_ol_flag_name (uint64_t mask)

Get the name of a TX offload flag.

Parameters

  • mask — the mask describing the flag. Usually only one bit must be set. Several bits can be given if they belong to the same mask. Ex: RTE_MBUF_F_TX_L4_MASK.

Returns

  • The name of this flag, or NULL if it's not a valid TX flag.

🌸 int rte_get_tx_ol_flag_list (uint64_t mask, char * buf, size_t buflen)

Dump the list of TX offload flags into a buffer. the TX sequel 🎬

Parameters

  • mask — the mask describing the TX flags.
  • buf — the output buffer.
  • buflen — the length of the buffer.

Returns

  • 0 on success, (-1) on error.

🌈 void rte_mbuf_prefetch_part1 (struct rte_mbuf * m) [inline], [static]

Prefetch the first part of the mbuf. so here's the tea: the first 64 bytes of the mbuf correspond to fields that get used early in the receive path. And if the cache line of your architecture is higher than 64B, the second part gets prefetched too. two for one <3

Parameters

  • m — the pointer to the mbuf.

Definition at line 111 of file rte_mbuf.h.

✨ void rte_mbuf_prefetch_part2 (struct rte_mbuf * m) [inline], [static]

Prefetch the second part of the mbuf. the next 64 bytes correspond to fields used in the transmit path. now if the cache line of the architecture is higher than 64B, this function literally does nothing, because it's expected that the full mbuf is already in cache. it's giving "already slayed, nothing left to do" 💅

Parameters

  • m — the pointer to the mbuf.

Definition at line 128 of file rte_mbuf.h.

🎀 uint16_t rte_pktmbuf_priv_size (struct rte_mempool * mp) [inline], [static]

Get the application private size of mbufs stored in a pktmbuf_pool.

so the private size of an mbuf is a zone sitting between the rte_mbuf structure and the data buffer, where your application can stash data associated to a packet. it's your little pocket 🫶

Parameters

  • mp — the packet mbuf pool.

Returns

  • The private size of mbufs stored in this mempool.

Definition at line 941 of file rte_mbuf.h.

💜 rte_iova_t rte_mbuf_iova_get (const struct rte_mbuf * m) [inline], [static]

Get the IOVA address of the mbuf data buffer.

Parameters

  • m — the pointer to the mbuf.

Returns

  • The IOVA address of the mbuf.

Definition at line 149 of file rte_mbuf.h.

🧚 void rte_mbuf_iova_set (struct rte_mbuf * m, rte_iova_t iova) [inline], [static]

Set the IOVA address of the mbuf data buffer.

Parameters

  • m — the pointer to the mbuf.
  • iova — value to set as IOVA address of the mbuf.

Definition at line 167 of file rte_mbuf.h.

🍓 rte_iova_t rte_mbuf_data_iova (const struct rte_mbuf * mb) [inline], [static]

Return the IO address of the beginning of the mbuf data.

Parameters

  • mb — the pointer to the mbuf.

Returns

  • The IO address of the beginning of the mbuf data.

Definition at line 186 of file rte_mbuf.h.

🦋 rte_iova_t rte_mbuf_data_iova_default (const struct rte_mbuf * mb) [inline], [static]

Return the default IO address of the beginning of the mbuf data.

this one is used by drivers in their receive function, because it returns the location where data should be written by the NIC — taking the default headroom into account. drivers love it here.

Parameters

  • mb — the pointer to the mbuf.

Returns

  • The IO address of the beginning of the mbuf data.

Definition at line 204 of file rte_mbuf.h.

🌈 struct rte_mbuf * rte_mbuf_from_indirect (struct rte_mbuf * mi) [inline], [static]

Return the mbuf owning the data buffer address of an indirect mbuf. finding the direct parent of your indirect bb, basically.

Parameters

  • mi — the pointer to the indirect mbuf.

Returns

  • The address of the direct mbuf corresponding to buffer_addr.

Definition at line 218 of file rte_mbuf.h.

⭐ char * rte_mbuf_buf_addr (struct rte_mbuf * mb, struct rte_mempool * mp) [inline], [static]

Return the address of the buffer embedded in the given mbuf.

the return value shall be the same as mb->buf_addr if the mbuf is already initialized and direct. but here's why this API is useful: if the mempool of the mbuf is already known, you can use this, because it doesn't need to access mbuf contents in order to get the mempool pointer. efficiency slay 💅

Parameters

  • mb — the pointer to the mbuf.
  • mp — the pointer to the mempool of the mbuf.

Returns

  • The pointer of the mbuf buffer.

Definition at line 239 of file rte_mbuf.h.

🎀 char * rte_mbuf_data_addr_default (struct rte_mbuf * mb) [inline], [static]

Return the default address of the beginning of the mbuf data.

Parameters

  • mb — the pointer to the mbuf.

Returns

  • The pointer of the beginning of the mbuf data.

Definition at line 253 of file rte_mbuf.h.

💖 char * rte_mbuf_to_baddr (struct rte_mbuf * md) [inline], [static]

Return the address of the buffer embedded in the given mbuf.

Note: accessing the mempool pointer of an mbuf is expensive, because that pointer is stored in the 2nd cache line of the mbuf. so if the mempool is known, it's better not to reference the mempool pointer in the mbuf — instead calling rte_mbuf_buf_addr() would be more efficient. no cap, do the efficient thing.

Parameters

  • md — the pointer to the mbuf.

Returns

  • The address of the data buffer owned by the mbuf.

Definition at line 272 of file rte_mbuf.h.

🧚 void * rte_mbuf_to_priv (struct rte_mbuf * m) [inline], [static]

Return the starting address of the private data area embedded in the given mbuf.

heads up tho — no check is made to ensure that a private data area actually exists in the supplied mbuf. so like, believe in it and it's yours 🙈

Parameters

  • m — the pointer to the mbuf.

Returns

  • The starting address of the private data area of the given mbuf.

Definition at line 290 of file rte_mbuf.h.

🍓 uint32_t rte_pktmbuf_priv_flags (struct rte_mempool * mp) [inline], [static]

Return the flags from the private data in a mempool structure.

Parameters

  • mp — a pointer to the mempool structure.

Returns

  • The flags from the private data structure.

Definition at line 316 of file rte_mbuf.h.

🦋 uint16_t rte_mbuf_refcnt_update (struct rte_mbuf * m, int16_t value) [inline], [static]

Adds the given value to an mbuf's refcnt and returns its new value. math but make it refcounting ✨

Definition at line 434 of file rte_mbuf.h.

💜 uint16_t rte_mbuf_refcnt_read (const struct rte_mbuf * m) [inline], [static]

Reads the value of an mbuf's refcnt. just a lil peek 👀

Definition at line 443 of file rte_mbuf.h.

⭐ void rte_mbuf_refcnt_set (struct rte_mbuf * m, uint16_t new_value) [inline], [static]

Sets an mbuf's refcnt to the defined value. you decide the number now bestie.

Definition at line 452 of file rte_mbuf.h.

🌈 uint16_t rte_mbuf_ext_refcnt_read (const struct rte_mbuf_ext_shared_info * shinfo) [inline], [static]

Reads the refcnt of an external buffer.

Parameters

  • shinfo — shared data of the external buffer.

Returns

  • Reference count number.

Definition at line 468 of file rte_mbuf.h.

🎀 void rte_mbuf_ext_refcnt_set (struct rte_mbuf_ext_shared_info * shinfo, uint16_t new_value) [inline], [static]

Set the refcnt of an external buffer.

Parameters

  • shinfo — shared data of the external buffer.
  • new_value — value set.

Definition at line 482 of file rte_mbuf.h.

🧚 uint16_t rte_mbuf_ext_refcnt_update (struct rte_mbuf_ext_shared_info * shinfo, int16_t value) [inline], [static]

Add the given value to the refcnt of an external buffer and return its new value. the external-buffer edition of the refcnt update.

Parameters

  • shinfo — shared data of the external buffer.
  • value — value to add/subtract.

Returns

  • Updated value.

Definition at line 500 of file rte_mbuf.h.

🔥 void rte_mbuf_raw_sanity_check (const struct rte_mbuf * m, const struct rte_mempool * mp)

Sanity checks on a reinitialized mbuf.

Check the consistency of the given reinitialized mbuf. this function will cause a panic if corruption is detected. so like, it is not playing around 😭

Check that the mbuf is properly reinitialized (refcnt=1, next=NULL, nb_segs=1), as done by rte_pktmbuf_prefree_seg().

  • m — the mbuf you're side-eyeing, bestie. This is the one getting checked. 👀
  • mp — the mempool it supposedly belongs to. Pass NULL if you literally don't know which pool it came from, and the check will just skip that part. No drama.

🩺 int rte_mbuf_raw_check (const struct rte_mbuf * m, const struct rte_mempool * mp, const char ** reason)

Sanity checks on a reinitialized mbuf. Yes, we're doing this again. ✨

It's almost like rte_mbuf_raw_sanity_check() — literally the same energy — except this one is the polite version. Instead of panicking at you when it finds corruption, it just tells you the reason. Gives you the tea instead of screaming. 😌

Parameters

  • m — the mbuf to be checked.
  • mp — the mempool the mbuf belongs to. NULL if unknown, and then it's not checked.
  • reason — a reference to a string pointer, where the reason gets stashed explaining why the mbuf is considered invalid.

Returns

  • 0 if no issue has been found, and reason is left untouched. Clean. No notes. ✨
  • -1 if a problem is detected, in which case reason points to a string describing exactly why the mbuf is deemed invalid. Receipts. 🧾

🩺 void rte_mbuf_sanity_check (const struct rte_mbuf * m, int is_header)

Sanity checks on an mbuf.

Checks the consistency of the mbuf you handed over. Heads up though — if corruption is detected, this function will cause a panic. Not a gentle vibe check, an actual panic. 💀

Parameters

  • m — the mbuf to be checked.
  • is_header — True if the mbuf is a packet header; false if it's a sub-segment of a packet. And in that sub-segment case, some fields like nb_segs don't get checked. So, partial vibe check. 🦋

🩺 int rte_mbuf_check (const struct rte_mbuf * m, int is_header, const char ** reason)

Sanity checks on an mbuf.

Almost like rte_mbuf_sanity_check(), but this one gives the reason when corruption is detected rather than panicking. Same as above — the chill twin. 🌸

Parameters

  • m — the mbuf to be checked.
  • is_header — True if the mbuf is a packet header, false if it's a sub-segment of a packet (and again, when it's a sub-segment, some fields like nb_segs are not checked).
  • reason — a reference to a string pointer where the reason gets stored, explaining why a mbuf is considered invalid.

Returns

  • 0 if no issue has been found, reason is left untouched.
  • -1 if a problem is detected, reason then points to a string describing the reason why the mbuf is deemed invalid.

🌱 struct rte_mbuf * rte_mbuf_raw_alloc (struct rte_mempool * mp) [inline], [static]

Allocate an uninitialized mbuf from mempool mp. Raw. Untouched. A whole blank canvas, fr fr. 🎨

This one is for the PMDs out there — especially in RX functions — to allocate an uninitialized mbuf. The driver is responsible for initializing all the required fields. See rte_pktmbuf_reset(). And for standard needs? Bestie, prefer rte_pktmbuf_alloc(). This is the "I know what I'm doing" path. 💅

The caller can expect that these fields of the mbuf structure are initialized: buf_addr, buf_iova, buf_len, refcnt=1, nb_segs=1, next=NULL, pool, priv_size. Every other field? That's on the caller. The other fields must be initialized by the caller. (Saying it twice because it matters. 🫶)

Parameters

  • mp — the mempool from which the mbuf is allocated.

Returns

  • The pointer to the new mbuf on success. 🎉
  • NULL if allocation failed. 😭

Definition at line 622 of file rte_mbuf.h.

🌱 __rte_always_inline int rte_mbuf_raw_alloc_bulk (struct rte_mempool * mp, struct rte_mbuf ** mbufs, unsigned int count) [static]

Allocate a bulk of uninitialized mbufs from mempool mp. It's giving group order. 👑

This can be used by PMDs (especially in Rx functions) to allocate a bulk of uninitialized mbufs. The driver is responsible for initializing all the required fields. See rte_pktmbuf_reset(). For standard needs, prefer rte_pktmbuf_alloc_bulk().

The caller can expect that the following fields of the mbuf structure are initialized: buf_addr, buf_iova, buf_len, refcnt=1, nb_segs=1, next=NULL, pool, priv_size. The other fields must be initialized by the caller.

Parameters

  • mp — the mempool from which mbufs are allocated.
  • mbufs — array of pointers to mbufs.
  • count — array size.

Returns

  • 0: Success. ✨
  • -ENOENT: Not enough entries in the mempool; no mbufs are retrieved. Tragic. 🙈

Definition at line 663 of file rte_mbuf.h.

♻️ __rte_always_inline void rte_mbuf_raw_free (struct rte_mbuf * m) [static]

Put mbuf back into its original mempool. Returning it home safe. 🏠

The caller must ensure that the mbuf is direct and properly reinitialized (refcnt=1, next=NULL, nb_segs=1), exactly as done by rte_pktmbuf_prefree_seg().

This function should be used with care, when optimization is required. For standard needs, prefer rte_pktmbuf_free() or rte_pktmbuf_free_seg().

Lowkey do not just yolo-call this one. Use with care. ⚠️

Parameters

  • m — the mbuf to be freed.

Definition at line 691 of file rte_mbuf.h.

♻️ __rte_always_inline void rte_mbuf_raw_free_bulk (struct rte_mempool * mp, struct rte_mbuf ** mbufs, unsigned int count) [static]

Put a bulk of mbufs allocated from the same mempool back into the mempool. Everyone goes back to the same house. 🏡

The caller must ensure that the mbufs come from the specified mempool, are direct, and are properly reinitialized (refcnt=1, next=NULL, nb_segs=1), as done by rte_pktmbuf_prefree_seg().

This function should be used with care, when optimization is required. For standard needs, prefer rte_pktmbuf_free_bulk().

See also

RTE_ETH_TX_OFFLOAD_MBUF_FAST_FREE

Parameters

  • mp — the mempool to which the mbufs belong.
  • mbufs — array of pointers to packet mbufs. The array must not contain NULL pointers. No empty seats at this table. 🚫
  • count — array size.

Definition at line 719 of file rte_mbuf.h.

🛠️ void rte_pktmbuf_init (struct rte_mempool * mp, void * opaque_arg, void * m, unsigned i)

The packet mbuf constructor. ✨

This function initializes some fields in the mbuf structure that are not modified by the user once created (origin pool, buffer start address, and so on). This function is given as a callback function to rte_mempool_obj_iter() or rte_mempool_create() at pool creation time.

This function expects that the mempool private area was previously initialized with rte_pktmbuf_pool_init().

Parameters

  • mp — the mempool from which mbufs originate.
  • opaque_arg — a pointer that can be used by the user to retrieve useful information for mbuf initialization. This pointer is the opaque argument passed to rte_mempool_obj_iter() or rte_mempool_create().
  • m — the mbuf to initialize.
  • i — the index of the mbuf in the pool table.

🛠️ void rte_pktmbuf_pool_init (struct rte_mempool * mp, void * opaque_arg)

A packet mbuf pool constructor.

This function initializes the mempool private data in the case of a pktmbuf pool. This private data is needed by the driver. The function must be called on the mempool before it is used, or it can be given as a callback function to rte_mempool_create() at pool creation. It can be extended by the user, for example, to provide another packet size. Go off, customize. 🎀

The mempool private area size must be at least equal to sizeof(struct rte_pktmbuf_pool_private). Minimum requirement, bestie.

Parameters

  • mp — the mempool from which mbufs originate.
  • opaque_arg — a pointer that can be used by the user to retrieve useful information for mbuf initialization. This pointer is the opaque argument passed to rte_mempool_create().

🏗️ struct rte_mempool * rte_pktmbuf_pool_create (const char * name, unsigned n, unsigned cache_size, uint16_t priv_size, uint16_t data_room_size, int socket_id)

Create a mbuf pool. The main character of pool creation. 👑

This function creates and initializes a packet mbuf pool. It is a wrapper to rte_mempool functions.

Parameters

  • name — the name of the mbuf pool.
  • n — the number of elements in the mbuf pool. The optimum size (in terms of memory usage) for a mempool is when n is a power of two minus one: n = (2^q - 1).
  • cache_size — size of the per-core object cache. See rte_mempool_create() for details.
  • priv_size — size of application private area between the rte_mbuf structure and the data buffer. This value must be aligned to RTE_MBUF_PRIV_ALIGN.
  • data_room_size — size of data buffer in each mbuf, including RTE_PKTMBUF_HEADROOM.
  • socket_id — the socket identifier where the memory should be allocated. The value can be SOCKET_ID_ANY if there is no NUMA constraint for the reserved zone.

Returns

The pointer to the new allocated mempool, on success. NULL on error with rte_errno set appropriately. Possible rte_errno values include:

  • E_RTE_NO_CONFIG — function could not get pointer to rte_config structure
  • EINVAL — cache size provided is too large, or priv_size is not aligned.
  • ENOSPC — the maximum number of memzones has already been allocated
  • EEXIST — a memzone with the same name already exists
  • ENOMEM — no appropriate memory area found in which to create memzone

🏗️ struct rte_mempool * rte_pktmbuf_pool_create_by_ops (const char * name, unsigned int n, unsigned int cache_size, uint16_t priv_size, uint16_t data_room_size, int socket_id, const char * ops_name)

Create a mbuf pool with a given mempool ops name. Same as above but you get to pick the ops, unlike everyone else. 💅

This function creates and initializes a packet mbuf pool. It is a wrapper to rte_mempool functions.

Parameters

  • name — the name of the mbuf pool.
  • n — the number of elements in the mbuf pool. The optimum size (in terms of memory usage) for a mempool is when n is a power of two minus one: n = (2^q - 1).
  • cache_size — size of the per-core object cache. See rte_mempool_create() for details.
  • priv_size — size of application private area between the rte_mbuf structure and the data buffer. This value must be aligned to RTE_MBUF_PRIV_ALIGN.
  • data_room_size — size of data buffer in each mbuf, including RTE_PKTMBUF_HEADROOM.
  • socket_id — the socket identifier where the memory should be allocated. The value can be SOCKET_ID_ANY if there is no NUMA constraint for the reserved zone.
  • ops_name — the mempool ops name to be used for this mempool instead of the default mempool. The value can be NULL to use the default mempool.

Returns

The pointer to the new allocated mempool, on success. NULL on error with rte_errno set appropriately. Possible rte_errno values include:

  • E_RTE_NO_CONFIG — function could not get pointer to rte_config structure
  • EINVAL — cache size provided is too large, or priv_size is not aligned.
  • ENOSPC — the maximum number of memzones has already been allocated
  • EEXIST — a memzone with the same name already exists
  • ENOMEM — no appropriate memory area found in which to create memzone

🏗️ struct rte_mempool * rte_pktmbuf_pool_create_extbuf (const char * name, unsigned int n, unsigned int cache_size, uint16_t priv_size, uint16_t data_room_size, int socket_id, const struct rte_pktmbuf_extmem * ext_mem, unsigned int ext_num)

Create a mbuf pool with external pinned data buffers. Ok this one is a whole different flavor. 🔥

This function creates and initializes a packet mbuf pool that contains only mbufs with external buffer. It is a wrapper to rte_mempool functions.

Parameters 🧸

  • name — the name of the mbuf pool. name it something cute, bestie 💖
  • n — how many elements live in the mbuf pool. ngl the optimum size (memory-usage-wise) for a mempool is a power of two minus one: n = (2^q - 1). math girlies rise 🧮
  • cache_size — size of the per-core object cache. deets are over in rte_mempool_create() ✨
  • priv_size — size of the application-private area, sitting between the rte_mbuf structure and the data buffer. this value must be aligned to RTE_MBUF_PRIV_ALIGN, no exceptions 💅
  • data_room_size — size of the data buffer in each mbuf, and yes babes that includes RTE_PKTMBUF_HEADROOM 🎀
  • socket_id — the socket identifier where the memory should be allocated. it can totally be SOCKET_ID_ANY if there's no NUMA constraint for the reserved zone 🦋
  • ext_mem — pointer to the array of structures describing the external memory for data buffers. it is the caller's responsibility to register this memory with rte_extmem_register() (if needed), map this memory to the appropriate physical device, etc. so like. on you bestie 🫶
  • ext_num — number of elements in the ext_mem array.

Returns 🌈

The pointer to the shiny new allocated mempool, on success. NULL on error, with rte_errno set appropriately. Possible rte_errno values include:

  • E_RTE_NO_CONFIG — the function could not get a pointer to the rte_config structure 😭
  • EINVAL — the cache size provided is too large, or priv_size is not aligned 🙈
  • ENOSPC — the maximum number of memzones has already been allocated 💀
  • EEXIST — a memzone with the same name already exists 👀
  • ENOMEM — no appropriate memory area found in which to create a memzone 🍓

uint16_t rte_pktmbuf_data_room_size (struct rte_mempool * mp) [inline], [static] 👑

Get the data room size of mbufs stored in a pktmbuf_pool.

The data room size = the amount of data that can be stored in a mbuf, including the headroom (RTE_PKTMBUF_HEADROOM). that's the whole vibe ✨

Parameters

  • mp — the packet mbuf pool.

Returns

The data room size of mbufs stored in this mempool. slay 💅

Definition at line 920 of file rte_mbuf.h.

void rte_pktmbuf_reset_headroom (struct rte_mbuf * m) [inline], [static] 🌸

Reset the data_off field of a packet mbuf back to its default value. factory reset energy fr fr

The given mbuf must have only one segment, and it should be empty 🫧

Parameters

  • m — the packet mbuf's data_off field has to be reset.

Definition at line 957 of file rte_mbuf.h.

void rte_mbuf_raw_reset_bulk (struct rte_mempool * mp, struct rte_mbuf ** mbufs, unsigned int count) [inline], [static] 🎀

Reset the fields of a whole bulk of packet mbufs to their default values.

The caller must ensure that the mbufs come from the specified mempool, are direct, and are properly reinitialized (refcnt=1, next=NULL, nb_segs=1), as done by rte_pktmbuf_prefree_seg().

This function should be used with care, like only when optimization is required. For standard needs, prefer rte_pktmbuf_reset() 👑

not me gatekeeping a bulk-reset function but it literally says use with care, so bestie, be careful 💀

Parameters

  • mp — the mempool to which the mbuf belongs.
  • mbufs — array of pointers to packet mbufs. the array must not contain NULL pointers 🙅‍♀️
  • count — array size.

Definition at line 982 of file rte_mbuf.h.

void rte_pktmbuf_reset (struct rte_mbuf * m) [inline], [static] 🦋

Reset the fields of a packet mbuf to their default values.

The given mbuf must have only one segment. that's the rule ✋

Parameters

  • m — the packet mbuf to be reset.

Definition at line 1015 of file rte_mbuf.h.

struct rte_mbuf * rte_pktmbuf_alloc (struct rte_mempool * mp) [inline], [static] ✨

Allocate a new mbuf from a mempool. brand new mbuf, who dis 💅

This new mbuf contains one segment, which has a length of 0. The pointer to data is initialized to have some bytes of headroom in the buffer (if the buffer size allows). cute 🎀

Parameters

  • mp — the mempool from which the mbuf is allocated.

Returns

  • The pointer to the new mbuf on success 🌈
  • NULL if allocation failed 😭

Definition at line 1046 of file rte_mbuf.h.

int rte_pktmbuf_alloc_bulk (struct rte_mempool * pool, struct rte_mbuf ** mbufs, unsigned count) [inline], [static] 💖

Allocate a bulk of mbufs, initialize refcnt, and reset the fields to default values. bulk girl summer 🍓

Parameters

  • pool — the mempool from which mbufs are allocated.
  • mbufs — array of pointers to mbufs.
  • count — array size.

Returns

  • 0: Success 🎉
  • -ENOENT: not enough entries in the mempool; no mbufs are retrieved 🙈

Definition at line 1068 of file rte_mbuf.h.

struct rte_mbuf_ext_shared_info * rte_pktmbuf_ext_shinfo_init_helper (void * buf_addr, uint16_t * buf_len, rte_mbuf_extbuf_free_callback_t free_cb, void * fcb_opaque) [inline], [static] 🧚

Initialize shared data at the end of an external buffer before attaching it to a mbuf via rte_pktmbuf_attach_extbuf(). This is not a mandatory initialization — it's just a little helper function to simply spare a few bytes at the end of the buffer for the shared data. If the shared data is allocated separately, this should not be called, and instead the application has to properly initialize the shared data according to its need 💜

Free callback and its argument get saved, and the refcnt is set to 1. iconic 🌟

Warning 💀 The value of buf_len will be reduced to RTE_PTR_DIFF(shinfo, buf_addr) after this initialization. This shall be used for rte_pktmbuf_attach_extbuf() 🔥

Parameters

  • buf_addr — the pointer to the external buffer.
  • buf_len — the pointer to the length of the external buffer. The input value must be larger than the size of struct rte_mbuf_ext_shared_info plus padding for alignment. If that's not enough, this function will return NULL. The adjusted buffer length will be returned through this pointer 🫡
  • free_cb — free callback function to call when the external buffer needs to be freed.
  • fcb_opaque — argument for the free callback function.

Returns

A pointer to the initialized shared data on success; NULL otherwise 😌

Definition at line 1115 of file rte_mbuf.h.

void rte_pktmbuf_attach_extbuf (struct rte_mbuf * m, void * buf_addr, rte_iova_t buf_iova, uint16_t buf_len, struct rte_mbuf_ext_shared_info * shinfo) [inline], [static] 🌸

Attach an external buffer to a mbuf. matching bracelets but for buffers 🫶

A user-managed anonymous buffer can be attached to a mbuf. When attaching it, the corresponding free callback function and its argument should be provided via shinfo. This callback function will be called once all the mbufs are detached from the buffer (refcnt becomes zero).

The headroom length of the attaching mbuf will be set to zero, and this can be properly adjusted after the attachment. For example, rte_pktmbuf_adj() or rte_pktmbuf_reset_headroom() might be used.

Similarly, the packet length is initialized to 0. If the buffer contains data, the user has to adjust data_len and the pkt_len field of the mbuf accordingly.

More mbufs can be attached to the same external buffer by rte_pktmbuf_attach() once the external buffer has been attached by this API.

Detachment can be done by either rte_pktmbuf_detach_extbuf() or rte_pktmbuf_detach().

Memory for the shared data must be provided, and the user must initialize all of the content properly — especially the free callback and the refcnt. The pointer of shared data will be stored in m->shinfo. rte_pktmbuf_ext_shinfo_init_helper can help to simply spare a few bytes at the end of the buffer for the shared data, store the free callback and its argument, and set the refcnt to 1. The following is an example:

struct rte_mbuf_ext_shared_info *shinfo =
rte_pktmbuf_ext_shinfo_init_helper(buf_addr, &buf_len,
                                            free_cb, fcb_arg);
rte_pktmbuf_attach_extbuf(m, buf_addr, buf_iova, buf_len, shinfo);
rte_pktmbuf_reset_headroom(m); rte_pktmbuf_adj(m, data_len);

Attaching an external buffer is quite similar to mbuf indirection in replacing buffer addresses and length of a mbuf, but a few differences:

  • When an indirect mbuf is attached, the refcnt of the direct mbuf would be 2 as long as the direct mbuf itself isn't freed after the attachment. In such cases, the buffer area of a direct mbuf must be read-only. But an external buffer has its own refcnt and it starts from 1. Unless multiple mbufs are attached to a mbuf having an external buffer, the external buffer is writable 💅
  • There's no need to allocate a buffer from a mempool. Any buffer can be attached with an appropriate free callback and its IO address 🌈
  • Smaller metadata is required to maintain shared data such as refcnt. minimalistic, we love that ✨

Parameters

  • m — the pointer to the mbuf.
  • buf_addr — the pointer to the external buffer.
  • buf_iova — IO address of the external buffer.
  • buf_len — the size of the external buffer.
  • shinfo — user-provided memory for shared data of the external buffer.

Definition at line 1197 of file rte_mbuf.h.

void rte_mbuf_dynfield_copy (struct rte_mbuf * mdst, const struct rte_mbuf * msrc) [inline], [static] 🎀

Copy dynamic fields from msrc to mdst. copy-paste but make it official 📋

Parameters

  • mdst — the destination mbuf.
  • msrc — the source mbuf.

Definition at line 1234 of file rte_mbuf.h.

void rte_pktmbuf_attach (struct rte_mbuf * mi, struct rte_mbuf * m) [inline], [static] 🦋

Attach packet mbuf to another packet mbuf. bestie bonding time 🫶

If the mbuf we are attaching to isn't a direct buffer and is attached to an external buffer, the mbuf being attached will be attached to the external buffer instead of doing mbuf indirection.

Otherwise, the mbuf will be indirectly attached. After attachment we refer to the mbuf we attached as 'indirect', while the mbuf we attached to is the 'direct' one. The direct mbuf's reference counter is incremented ⬆️

Right now, not supported:

  • attachment for an already-indirect mbuf (e.g. — mi has to be direct) 🙅‍♀️
  • the mbuf we're trying to attach (mi) is used by someone else, e.g. its reference counter is greater then 1 💀

Parameters

  • mi — the indirect packet mbuf.
  • m — the packet mbuf we're attaching to.

Definition at line 1276 of file rte_mbuf.h.

void rte_pktmbuf_detach (struct rte_mbuf * m) [inline], [static] 🌈

Detach a packet mbuf from an external buffer or a direct buffer. we're breaking up 😭

  • decrement refcnt and free the external/direct buffer if the refcnt becomes zero 🫧
  • restore the original mbuf address and length values.
  • reset pktmbuf data and data_len to their default values.

All other fields of the given packet mbuf will be left intact. no notes 💅

If the packet mbuf was allocated from the pool with pinned external buffers, rte_pktmbuf_detach does nothing with a mbuf of this kind, because the pinned buffers are not supposed to be detached. they're committed 🔒

Parameters

  • m — the indirect attached packet mbuf.

Definition at line 1366 of file rte_mbuf.h.

__rte_always_inline struct rte_mbuf * rte_pktmbuf_prefree_seg (struct rte_mbuf * m) [static] ⭐

Decrease reference counter and unlink a mbuf segment 🔗✂️

Okay bestie continuing right where we left off, no interruptions 💖

So like… this one does the exact same thing as a free, EXCEPT it does not hand the segment back to its pool. It just decrements the reference counter, and if that counter hits 0, then for an indirect mbuf it gets detached from its parent. 🫶

Parameters:

  • m — the mbuf to be unlinked

Returns:

  • (m) — if it's the last reference. It can be recycled or freed ♻️
  • (NULL) — if the mbuf still has remaining references on it

Definition at line 1458 of file rte_mbuf.h.

rte_pktmbuf_free_seg

__rte_always_inline void rte_pktmbuf_free_seg (struct rte_mbuf * m)

[static] ⭐

Free a single segment of a packet mbuf back into its original mempool, bestie. Basically it frees one mbuf and does not go parsing the other segments if you're dealing with chained buffers. One and done, no snooping 💅

Parameters:

  • m — the packet mbuf segment to be freed

Definition at line 1496 of file rte_mbuf.h.

rte_pktmbuf_free

void rte_pktmbuf_free (struct rte_mbuf * m)

[inline], [static] ✨

Free a packet mbuf back into its original mempool. And unlike its baby sibling up there, this one frees the mbuf and all its segments when the buffers are chained — every single segment goes back into its own original mempool. Full send 🌈

Parameters:

  • m — the packet mbuf to be freed. And ngl, if it's NULL, the function literally does nothing. Iconic, honestly 😌

Definition at line 1512 of file rte_mbuf.h.

rte_pktmbuf_free_bulk

void rte_pktmbuf_free_bulk (struct rte_mbuf ** mbufs, unsigned int count)

Free a whole bulk of packet mbufs back into their original mempools. Yes queen, bundle deal 📦✨ It frees all of them, and all their segments in the chained-buffer case, and each segment lands back in its own original mempool.

Parameters:

  • mbufs — array of pointers to packet mbufs. FYI the array may contain NULL pointers, no judgement 💀
  • count — array size

rte_pktmbuf_clone

struct rte_mbuf * rte_pktmbuf_clone (struct rte_mbuf * md, struct rte_mempool * mp)

Make a "clone" of the given packet mbuf 🧬✨ It walks through every segment of the given packet mbuf and for each one it:

  • creates a brand new packet mbuf from the given pool,
  • attaches that newly created mbuf to the segment, and then updates pkt_len and nb_segs on the "clone" packet mbuf so they match the values from the original packet mbuf.

Parameters:

  • md — the packet mbuf to be cloned
  • mp — the mempool that the "clone" mbufs get allocated from

Returns:

  • The pointer to the new "clone" mbuf on success 🎉
  • NULL if allocation fails 😭

rte_pktmbuf_copy

struct rte_mbuf * rte_pktmbuf_copy (const struct rte_mbuf * m, struct rte_mempool * mp, uint32_t offset, uint32_t length)

Create a full copy of a given packet mbuf. Not a clone, not a link, an actual copy 👑 It copies all the data from a given packet mbuf into a newly allocated set of mbufs. Heads up though: the private data are not copied, so don't come for me 🙈

Parameters:

  • m — the packet mbuf to be copied
  • mp — the mempool that the "clone" mbufs get allocated from
  • offset — the number of bytes to skip before copying. And if the mbuf doesn't have that many bytes, it's an error and NULL gets returned, periodt 💅
  • length — the upper limit on bytes to copy. Passing UINT32_MAX means all the data (after offset)

Returns:

  • The pointer to the new "clone" mbuf on success 🎉
  • NULL if allocation fails 😭

rte_pktmbuf_refcnt_update

void rte_pktmbuf_refcnt_update (struct rte_mbuf * m, int16_t v)

[inline], [static] ✨

Adds the given value to the refcnt of all packet mbuf segments. It walks through every segment of the given packet mbuf and for each of them it invokes rte_mbuf_refcnt_update(). Team effort fr fr 🫶

Parameters:

  • m — the packet mbuf whose refcnt is to be updated
  • v — the value to add to the mbuf's segments refcnt

Definition at line 1596 of file rte_mbuf.h.

rte_pktmbuf_headroom

uint16_t rte_pktmbuf_headroom (const struct rte_mbuf * m)

[inline], [static] ✨

Get the headroom in a packet mbuf 🌸

Parameters:

  • m — the packet mbuf

Returns: the length of the headroom.

Definition at line 1613 of file rte_mbuf.h.

rte_pktmbuf_tailroom

uint16_t rte_pktmbuf_tailroom (const struct rte_mbuf * m)

[inline], [static] ✨

Get the tailroom of a packet mbuf 🌸

Parameters:

  • m — the packet mbuf

Returns: the length of the tailroom.

Definition at line 1627 of file rte_mbuf.h.

rte_pktmbuf_lastseg

struct rte_mbuf * rte_pktmbuf_lastseg (struct rte_mbuf * m)

[inline], [static] ✨

Get the last segment of the packet. The tail end, the finale, the last one to arrive 🎀

Parameters:

  • m — the packet mbuf

Returns: the last segment of the given mbuf.

Definition at line 1642 of file rte_mbuf.h.

rte_pktmbuf_prepend

char * rte_pktmbuf_prepend (struct rte_mbuf * m, uint16_t len)

[inline], [static] ✨

Prepend len bytes to an mbuf data area. It returns a pointer to the new data start address. And here's the tea: if there isn't enough headroom in the first segment, the function returns NULL — without modifying the mbuf. No half-done nonsense here 💅

Parameters:

  • m — the pkt mbuf
  • len — the amount of data to prepend (in bytes)

Returns: a pointer to the start of the newly prepended data, or NULL if there is not enough headroom space in the first segment.

Definition at line 1685 of file rte_mbuf.h.

rte_pktmbuf_append

char * rte_pktmbuf_append (struct rte_mbuf * m, uint16_t len)

[inline], [static] ✨

Append len bytes to an mbuf. It appends len bytes to an mbuf and returns a pointer to the start address of the added data. Same energy as prepend: if there's not enough tailroom in the last segment, it returns NULL without modifying the mbuf 🙅‍♀️

Parameters:

  • m — the packet mbuf
  • len — the amount of data to append (in bytes)

Returns: a pointer to the start of the newly appended data, or NULL if there is not enough tailroom space in the last segment.

Definition at line 1718 of file rte_mbuf.h.

rte_pktmbuf_adj

char * rte_pktmbuf_adj (struct rte_mbuf * m, uint16_t len)

[inline], [static] ✨

Remove len bytes at the beginning of an mbuf. It returns a pointer to the start address of the new data area. But bestie, if the length is greater than the length of the first segment, the function will fail and return NULL, without modifying the mbuf. So no oopsie-daisies 😭

Parameters:

  • m — the packet mbuf
  • len — the amount of data to remove (in bytes)

Returns: a pointer to the new start of the data.

Definition at line 1749 of file rte_mbuf.h.

rte_pktmbuf_trim

int rte_pktmbuf_trim (struct rte_mbuf * m, uint16_t len)

[inline], [static] ✨

Remove len bytes of data at the end of the mbuf ✂️ And if the length is greater than the length of the last segment, the function will fail and return -1 without modifying the mbuf.

Parameters:

  • m — the packet mbuf
  • len — the amount of data to remove (in bytes)

Returns:

  • 0: on success
  • -1: on error

Definition at line 1779 of file rte_mbuf.h.

rte_pktmbuf_is_contiguous

int rte_pktmbuf_is_contiguous (const struct rte_mbuf * m)

[inline], [static] ✨

Test if mbuf data is contiguous 🧐

Parameters:

  • m — the packet mbuf

Returns:

  • 1, if all data is contiguous (one segment)
  • 0, if there is several segments

Definition at line 1803 of file rte_mbuf.h.

rte_pktmbuf_read

const void * rte_pktmbuf_read (const struct rte_mbuf * m, uint32_t off, uint32_t len, void * buf)

[inline], [static] ✨

Read len data bytes in a mbuf at a specified offset 👀 If the data is contiguous, it returns the pointer into the mbuf data; otherwise it copies the data into the buffer the user provided and returns that pointer. Whichever, you get your data 💅

Parameters:

  • m — the pointer to the mbuf
  • off — the offset of the data in the mbuf
  • len — the amount of bytes to read
  • buf — the buffer where data is copied if it is not contiguous in mbuf data. Its length should be at least equal to the len parameter

Returns: the pointer to the data, either in the mbuf if it is contiguous, or in the user buffer. And if the mbuf is too small, NULL is returned.

Definition at line 1835 of file rte_mbuf.h.

rte_pktmbuf_chain

int rte_pktmbuf_chain (struct rte_mbuf * head, struct rte_mbuf * tail)

[inline], [static] ✨

Chain an mbuf to another one, thereby creating a segmented packet 🔗

Note: the implementation will do a linear walk over the segments to find the tail entry. So for cases when there are many segments, it's better to chain the entries manually. Save yourself the walking tour 🚶‍♀️

Parameters:

  • head — the head of the mbuf chain (the first packet)
  • tail — the mbuf to put last in the chain

Returns:

  • 0, on success
  • -EOVERFLOW, if the chain segment limit exceeded 💀

Definition at line 1860 of file rte_mbuf.h.

rte_mbuf_tx_offload

__rte_always_inline uint64_t rte_mbuf_tx_offload (uint64_t il2, uint64_t il3, uint64_t il4, uint64_t tso, uint64_t ol3, uint64_t ol2, uint64_t unused)

[static] ✨

For given input values, generate the raw tx_offload value ⚙️ And note: it is the caller's responsibility to make sure the input parameters don't exceed maximum bit-field values. So no overstuffing the fields, bestie 🙈

Parameters:

  • il2 — l2_len value
  • il3 — l3_len value
  • il4 — l4_len value
  • tso — tso_segsz value
  • ol3 — outer_l3_len value
  • ol2 — outer_l2_len value
  • unused — unused value

Returns: raw tx_offload value.

Definition at line 1907 of file rte_mbuf.h.

rte_validate_tx_offload

int rte_validate_tx_offload (const struct rte_mbuf * m)

[inline], [static] ✨

Validate the general requirements for Tx offload in a mbuf. This function checks the correctness and completeness of the Tx offload settings. Vibe check on your offload config 💅

Parameters:

  • m — the packet mbuf to be validated

Returns: 0 if packet is valid.

Definition at line 1930 of file rte_mbuf.h.

rte_pktmbuf_linearize

int rte_pktmbuf_linearize (struct rte_mbuf * mbuf)

[inline], [static] ✨

Linearize data in mbuf. This function moves the mbuf data into the first segment if there is enough tailroom. The subsequent segments are unchained and freed. Cleaning house 🧹✨

Parameters:

  • mbuf — mbuf to linearize

Returns:

  • 0, on success
  • -1, on error

Definition at line 1980 of file rte_mbuf.h.

rte_pktmbuf_dump

void rte_pktmbuf_dump (FILE * f, const struct rte_mbuf * m, unsigned dump_len)

Dump an mbuf structure to a file 📝 It dumps all fields for the given packet mbuf and all its associated segments (in the chained buffer case too). Everything on display, no secrets 👑

Parameters:

  • f — a pointer to a file for output
  • m — the packet mbuf
  • dump_len — if dump_len != 0, also dump the "dump_len" first data bytes of the packet

rte_mbuf_sched_queue_get

uint32_t rte_mbuf_sched_queue_get (const struct rte_mbuf * m)

[inline], [static] ✨

Get the value of the mbuf sched queue_id field 🎯

Definition at line 2007 of file rte_mbuf.h.

rte_mbuf_sched_traffic_class_get

uint8_t rte_mbuf_sched_traffic_class_get (const struct rte_mbuf * m)

[inline], [static] ✨

Get the value of the mbuf sched traffic_class field 🎯

Definition at line 2016 of file rte_mbuf.h.

rte_mbuf_sched_color_get

uint8_t rte_mbuf_sched_color_get (const struct rte_mbuf * m)

[inline], [static] ✨

Get the value of the mbuf sched color field 🎨 Yes the colour, slay.

Definition at line 2025 of file rte_mbuf.h.

rte_mbuf_sched_get

void rte_mbuf_sched_get (const struct rte_mbuf * m, uint32_t * queue_id, uint8_t * traffic_class, uint8_t * color)

[inline], [static] ✨

Get the values of mbuf sched queue_id, traffic_class and color — all three at once, bundle deal 🎁

Parameters:

  • m — mbuf to read
  • queue_id — returns the queue id
  • traffic_class — returns the traffic class id
  • color — returns the colour id

Definition at line 2043 of file rte_mbuf.h.

rte_mbuf_sched_queue_set()</p> 💅

void rte_mbuf_sched_queue_set (struct rte_mbuf * m, uint32_t queue_id)

[inline], [static]

okay so bestie, this one does exactly one thing and it slays at it: it sets the mbuf's sched queue_id to the value you hand it. that's the whole vibe. no cap.

Definition at line 2058 of file rte_mbuf.h.

rte_mbuf_sched_traffic_class_set()</p> 🎀

void rte_mbuf_sched_traffic_class_set (struct rte_mbuf * m, uint8_t traffic_class)

[inline], [static]

the matching twin 🫶 — this one sets the mbuf's sched traffic_class id to whatever value you pass in. iconic behaviour, truly.

Definition at line 2067 of file rte_mbuf.h.

rte_mbuf_sched_color_set()</p> 🌈

void rte_mbuf_sched_color_set (struct rte_mbuf * m, uint8_t color)

[inline], [static]

and the third one in the lil trio ✨ — it sets the mbuf's sched color id to the value you give it. boom. done.

Definition at line 2076 of file rte_mbuf.h.

rte_mbuf_sched_set()</p> 👑

void rte_mbuf_sched_set (struct rte_mbuf * m, uint32_t queue_id, uint8_t traffic_class, uint8_t color)

[inline], [static]

main character energy fr fr — this is the all-in-one: it sets the mbuf's sched queue_id, traffic_class and color all at once. instead of calling the three lil functions above one by one, you just hit this one and you're done. it's giving efficiency, it's giving periodt. 💖

Parameters 🍓

  • m — the mbuf you're setting stuff on
  • queue_id — the queue id value to be set
  • traffic_class — the traffic class id value to be set
  • color — the color id to be set

Definition at line 2094 of file rte_mbuf.h.

🌸 AUTHOR 🌸

Generated automatically by Doxygen for DPDK from the source code.

and that's a wrap on the whole page bestie 😭💖 you read the entire thing, no skipping, and i'm so proud of you. this was DPDK Version 25.11.3, page rte_mbuf.h(3), and yes, it was auto-generated by Doxygen straight from the source code. go forth and set those sched queue ids. slay. 👑✨

📦 where this page comes from