Provided by: dpdk-doc_24.11.2-2_all 
NAME
rte_mbuf.h
SYNOPSIS
#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>
Data Structures
struct rte_pktmbuf_pool_private
struct rte_pktmbuf_extmem
Macros
#define RTE_PKTMBUF_POOL_F_PINNED_EXT_BUF (1 << 0)
#define RTE_MBUF_HAS_PINNED_EXTBUF(mb) (rte_pktmbuf_priv_flags(mb->pool) &
RTE_PKTMBUF_POOL_F_PINNED_EXT_BUF)
#define __rte_mbuf_sanity_check(m, is_h) do { } while (0)
#define RTE_MBUF_PREFETCH_TO_FREE(m)
#define MBUF_RAW_ALLOC_CHECK(m) __rte_mbuf_raw_sanity_check(m)
#define rte_pktmbuf_detach_extbuf(m) rte_pktmbuf_detach(m)
#define rte_pktmbuf_pkt_len(m) ((m)->pkt_len)
#define rte_pktmbuf_data_len(m) ((m)->data_len)
Functions
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_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 __rte_always_inline void __rte_mbuf_raw_sanity_check (__rte_unused const struct rte_mbuf *m)
static struct rte_mbuf * rte_mbuf_raw_alloc (struct rte_mempool *mp)
static __rte_always_inline void rte_mbuf_raw_free (struct rte_mbuf *m)
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_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
RTE Mbuf
The mbuf library provides the ability to create and destroy buffers that may be used by the RTE
application to store message buffers. The 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), 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)
When set, pktmbuf mempool will hold only mbufs with pinned external buffer. The external buffer will be
attached to the mbuf at the memory pool creation and will never be detached by the mbuf free calls. mbuf
should not contain any room for data after the mbuf structure.
Definition at line 328 of file rte_mbuf.h.
#define RTE_MBUF_HAS_PINNED_EXTBUF(mb) (rte_pktmbuf_priv_flags(mb->pool) &
RTE_PKTMBUF_POOL_F_PINNED_EXT_BUF)
Returns non zero if given mbuf has a pinned external buffer, or zero otherwise. The pinned external
buffer is allocated at pool creation time and should not be freed on mbuf freeing.
External buffer is a user-provided anonymous buffer.
Definition at line 337 of file rte_mbuf.h.
#define __rte_mbuf_sanity_check(m, is_h) do { } while (0)
check mbuf type in debug mode
Definition at line 348 of file rte_mbuf.h.
#define RTE_MBUF_PREFETCH_TO_FREE(m)
Value:.PP
do { \
if ((m) != NULL) \
rte_prefetch0(m); \
} while (0)
Mbuf prefetch
Definition at line 510 of file rte_mbuf.h.
#define MBUF_RAW_ALLOC_CHECK(m) __rte_mbuf_raw_sanity_check(m)
For backwards compatibility.
Definition at line 575 of file rte_mbuf.h.
#define rte_pktmbuf_detach_extbuf(m) rte_pktmbuf_detach(m)
Detach the external buffer attached to a mbuf, same as rte_pktmbuf_detach()
Parameters
m The mbuf having external buffer.
Definition at line 1112 of file rte_mbuf.h.
#define rte_pktmbuf_pkt_len(m) ((m)->pkt_len)
A macro that returns the length of the packet.
The value can be read or assigned.
Parameters
m The packet mbuf.
Definition at line 1561 of file rte_mbuf.h.
#define rte_pktmbuf_data_len(m) ((m)->data_len)
A macro that returns the length of the segment.
The value can be read or assigned.
Parameters
m The packet mbuf.
Definition at line 1571 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
Parameters
mask The mask describing the flag.
Returns
The name of this flag, or NULL if it's not a valid RX flag.
int rte_get_rx_ol_flag_list (uint64_t mask, char * buf, size_t buflen)
Dump the list of RX offload flags in a 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 in a buffer
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.
static void rte_mbuf_prefetch_part1 (struct rte_mbuf * m) [inline], [static]
Prefetch the first part of the mbuf
The first 64 bytes of the mbuf corresponds to fields that are used early in the receive path. If the
cache line of the architecture is higher than 64B, the second part will also be prefetched.
Parameters
m The pointer to the mbuf.
Definition at line 109 of file rte_mbuf.h.
static void rte_mbuf_prefetch_part2 (struct rte_mbuf * m) [inline], [static]
Prefetch the second part of the mbuf
The next 64 bytes of the mbuf corresponds to fields that are used in the transmit path. If the cache line
of the architecture is higher than 64B, this function does nothing as it is expected that the full mbuf
is already in cache.
Parameters
m The pointer to the mbuf.
Definition at line 126 of file rte_mbuf.h.
static uint16_t rte_pktmbuf_priv_size (struct rte_mempool * mp) [inline], [static]
Get the application private size of mbufs stored in a pktmbuf_pool
The private size of mbuf is a zone located between the rte_mbuf structure and the data buffer where an
application can store data associated to a packet.
Parameters
mp The packet mbuf pool.
Returns
The private size of mbufs stored in this mempool.
Definition at line 846 of file rte_mbuf.h.
static 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 147 of file rte_mbuf.h.
static 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 165 of file rte_mbuf.h.
static 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 184 of file rte_mbuf.h.
static 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 function is used by drivers in their receive function, as it returns the location where data should
be written by the NIC, taking the default headroom in account.
Parameters
mb The pointer to the mbuf.
Returns
The IO address of the beginning of the mbuf data
Definition at line 202 of file rte_mbuf.h.
static 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.
Parameters
mi The pointer to the indirect mbuf.
Returns
The address of the direct mbuf corresponding to buffer_addr.
Definition at line 216 of file rte_mbuf.h.
static char * rte_mbuf_buf_addr (struct rte_mbuf * mb, struct rte_mempool * mp) [inline], [static]
Return address of buffer embedded in the given mbuf.
The return value shall be same as mb->buf_addr if the mbuf is already initialized and direct. However,
this API is useful if mempool of the mbuf is already known because it doesn't need to access mbuf
contents in order to get the mempool pointer.
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 237 of file rte_mbuf.h.
static 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 251 of file rte_mbuf.h.
static char * rte_mbuf_to_baddr (struct rte_mbuf * md) [inline], [static]
Return address of buffer embedded in the given mbuf.
Note
: Accessing mempool pointer of a mbuf is expensive because the pointer is stored in the 2nd cache
line of mbuf. If mempool is known, it is better not to reference the mempool pointer in mbuf but
calling rte_mbuf_buf_addr() would be more efficient.
Parameters
md The pointer to the mbuf.
Returns
The address of the data buffer owned by the mbuf.
Definition at line 270 of file rte_mbuf.h.
static 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.
Note that no check is made to ensure that a private data area actually exists in the supplied mbuf.
Parameters
m The pointer to the mbuf.
Returns
The starting address of the private data area of the given mbuf.
Definition at line 288 of file rte_mbuf.h.
static uint32_t rte_pktmbuf_priv_flags (struct rte_mempool * mp) [inline], [static]
Return the flags from private data in an mempool structure.
Parameters
mp A pointer to the mempool structure.
Returns
The flags from the private data structure.
Definition at line 314 of file rte_mbuf.h.
static uint16_t rte_mbuf_refcnt_update (struct rte_mbuf * m, int16_t value) [inline], [static]
Adds given value to an mbuf's refcnt and returns its new value.
Definition at line 430 of file rte_mbuf.h.
static uint16_t rte_mbuf_refcnt_read (const struct rte_mbuf * m) [inline], [static]
Reads the value of an mbuf's refcnt.
Definition at line 439 of file rte_mbuf.h.
static void rte_mbuf_refcnt_set (struct rte_mbuf * m, uint16_t new_value) [inline], [static]
Sets an mbuf's refcnt to the defined value.
Definition at line 448 of file rte_mbuf.h.
static 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 464 of file rte_mbuf.h.
static void rte_mbuf_ext_refcnt_set (struct rte_mbuf_ext_shared_info * shinfo, uint16_t new_value) [inline],
[static]
Set refcnt of an external buffer.
Parameters
shinfo Shared data of the external buffer.
new_value Value set
Definition at line 478 of file rte_mbuf.h.
static uint16_t rte_mbuf_ext_refcnt_update (struct rte_mbuf_ext_shared_info * shinfo, int16_t value)
[inline], [static]
Add given value to refcnt of an external buffer and return its new value.
Parameters
shinfo Shared data of the external buffer.
value Value to add/subtract
Returns
Updated value
Definition at line 496 of file rte_mbuf.h.
void rte_mbuf_sanity_check (const struct rte_mbuf * m, int is_header)
Sanity checks on an mbuf.
Check the consistency of the given mbuf. The function will cause a panic if corruption is detected.
Parameters
m The mbuf to be checked.
is_header True if the mbuf is a packet header, false if it is a sub-segment of a packet (in this
case, some fields like nb_segs are not checked)
int rte_mbuf_check (const struct rte_mbuf * m, int is_header, const char ** reason)
Sanity checks on a mbuf.
Almost like rte_mbuf_sanity_check(), but this function gives the reason if corruption is detected rather
than panic.
Parameters
m The mbuf to be checked.
is_header True if the mbuf is a packet header, false if it is a sub-segment of a packet (in this
case, some fields like nb_segs are not checked)
reason A reference to a string pointer where to store the reason 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.
static __rte_always_inline void __rte_mbuf_raw_sanity_check (__rte_unused const struct rte_mbuf * m) [static]
Sanity checks on a reinitialized mbuf in debug mode.
Check the consistency of the given reinitialized mbuf. The function will cause a panic if corruption is
detected.
Check that the mbuf is properly reinitialized (refcnt=1, next=NULL, nb_segs=1), as done by
rte_pktmbuf_prefree_seg().
Parameters
m The mbuf to be checked.
Definition at line 566 of file rte_mbuf.h.
static struct rte_mbuf * rte_mbuf_raw_alloc (struct rte_mempool * mp) [inline], [static]
Allocate an uninitialized mbuf from mempool mp.
This function can be used by PMDs (especially in RX functions) to allocate an uninitialized mbuf. The
driver is responsible of initializing all the required fields. See rte_pktmbuf_reset(). For standard
needs, prefer rte_pktmbuf_alloc().
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 mbuf is allocated.
Returns
• The pointer to the new mbuf on success.
• NULL if allocation failed.
Definition at line 596 of file rte_mbuf.h.
static __rte_always_inline void rte_mbuf_raw_free (struct rte_mbuf * m) [static]
Put mbuf back into its original mempool.
The caller must ensure that the mbuf is direct and 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() or rte_pktmbuf_free_seg().
Parameters
m The mbuf to be freed.
Definition at line 624 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.
The mempool private area size must be at least equal to sizeof(struct rte_pktmbuf_pool_private).
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.
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 are 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
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 are 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 default mempool. The value can
be NULL to use 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.
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.
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 are 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.
ext_mem Pointer to the array of structures describing the external memory for data buffers. It is
caller responsibility to register this memory with rte_extmem_register() (if needed), map this memory
to appropriate physical device, etc.
ext_num Number of elements in the ext_mem array.
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
static 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 is the amount of data that can be stored in a mbuf including the headroom
(RTE_PKTMBUF_HEADROOM).
Parameters
mp The packet mbuf pool.
Returns
The data room size of mbufs stored in this mempool.
Definition at line 825 of file rte_mbuf.h.
static void rte_pktmbuf_reset_headroom (struct rte_mbuf * m) [inline], [static]
Reset the data_off field of a packet mbuf to its default value.
The given mbuf must have only one segment, which should be empty.
Parameters
m The packet mbuf's data_off field has to be reset.
Definition at line 862 of file rte_mbuf.h.
static 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.
Parameters
m The packet mbuf to be reset.
Definition at line 876 of file rte_mbuf.h.
static struct rte_mbuf * rte_pktmbuf_alloc (struct rte_mempool * mp) [inline], [static]
Allocate a new mbuf from a mempool.
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 buffer size allows).
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 907 of file rte_mbuf.h.
static 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.
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 929 of file rte_mbuf.h.
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) [inline], [static]
Initialize shared data at the end of an external buffer before attaching to a mbuf by
rte_pktmbuf_attach_extbuf(). This is not a mandatory initialization but a helper function to simply spare
a few bytes at the end of the buffer for shared data. If shared data is allocated separately, this should
not be called but application has to properly initialize the shared data according to its need.
Free callback and its argument is saved and the refcnt is set to 1.
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 length of the external buffer. Input value must be larger than the size of
struct rte_mbuf_ext_shared_info and padding for alignment. If not enough, this function will return
NULL. 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, return NULL otherwise.
Definition at line 1004 of file rte_mbuf.h.
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) [inline], [static]
Attach an external buffer to a mbuf.
User-managed anonymous buffer can be attached to an mbuf. When attaching it, 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
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 shared data must be provided and user must initialize all of the content properly, especially
free callback and 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 buffer for the
shared data, store 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, 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 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 buffer from a mempool. Any buffer can be attached with appropriate free
callback and its IO address.
• Smaller metadata is required to maintain shared data such as refcnt.
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 1086 of file rte_mbuf.h.
static void rte_mbuf_dynfield_copy (struct rte_mbuf * mdst, const struct rte_mbuf * msrc) [inline], [static]
Copy dynamic fields from msrc to mdst.
Parameters
mdst The destination mbuf.
msrc The source mbuf.
Definition at line 1123 of file rte_mbuf.h.
static void rte_pktmbuf_attach (struct rte_mbuf * mi, struct rte_mbuf * m) [inline], [static]
Attach packet mbuf to another packet mbuf.
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 mbuf indirection.
Otherwise, the mbuf will be indirectly attached. After attachment we refer the mbuf we attached as
'indirect', while mbuf we attached to as 'direct'. The direct mbuf's reference counter is incremented.
Right now, not supported:
• attachment for already indirect mbuf (e.g. - mi has to be direct).
• mbuf we trying to attach (mi) is used by someone else e.g. it's reference counter is greater then 1.
Parameters
mi The indirect packet mbuf.
m The packet mbuf we're attaching to.
Definition at line 1165 of file rte_mbuf.h.
static void rte_pktmbuf_detach (struct rte_mbuf * m) [inline], [static]
Detach a packet mbuf from external buffer or direct buffer.
• decrement refcnt and free the external/direct buffer if refcnt becomes zero.
• restore 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.
If the packet mbuf was allocated from the pool with pinned external buffers the rte_pktmbuf_detach does
nothing with the mbuf of this kind, because the pinned buffers are not supposed to be detached.
Parameters
m The indirect attached packet mbuf.
Definition at line 1255 of file rte_mbuf.h.
static __rte_always_inline struct rte_mbuf * rte_pktmbuf_prefree_seg (struct rte_mbuf * m) [static]
Decrease reference counter and unlink a mbuf segment
This function does the same than a free, except that it does not return the segment to its pool. It
decreases the reference counter, and if it reaches 0, it is detached from its parent for an indirect
mbuf.
Parameters
m The mbuf to be unlinked
Returns
• (m) if it is the last reference. It can be recycled or freed.
• (NULL) if the mbuf still has remaining references on it.
Definition at line 1347 of file rte_mbuf.h.
static __rte_always_inline void rte_pktmbuf_free_seg (struct rte_mbuf * m) [static]
Free a segment of a packet mbuf into its original mempool.
Free an mbuf, without parsing other segments in case of chained buffers.
Parameters
m The packet mbuf segment to be freed.
Definition at line 1399 of file rte_mbuf.h.
static void rte_pktmbuf_free (struct rte_mbuf * m) [inline], [static]
Free a packet mbuf back into its original mempool.
Free an mbuf, and all its segments in case of chained buffers. Each segment is added back into its
original mempool.
Parameters
m The packet mbuf to be freed. If NULL, the function does nothing.
Definition at line 1415 of file rte_mbuf.h.
void rte_pktmbuf_free_bulk (struct rte_mbuf ** mbufs, unsigned int count)
Free a bulk of packet mbufs back into their original mempools.
Free a bulk of mbufs, and all their segments in case of chained buffers. Each segment is added back into
its original mempool.
Parameters
mbufs Array of pointers to packet mbufs. The array may contain NULL pointers.
count Array size.
struct rte_mbuf * rte_pktmbuf_clone (struct rte_mbuf * md, struct rte_mempool * mp)
Create a 'clone' of the given packet mbuf.
Walks through all segments of the given packet mbuf, and for each of them:
• Creates a new packet mbuf from the given pool.
• Attaches newly created mbuf to the segment. Then updates pkt_len and nb_segs of the 'clone' packet mbuf
to match values from the original packet mbuf.
Parameters
md The packet mbuf to be cloned.
mp The mempool from which the 'clone' mbufs are allocated.
Returns
• The pointer to the new 'clone' mbuf on success.
• NULL if allocation fails.
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.
Copies all the data from a given packet mbuf to a newly allocated set of mbufs. The private data are is
not copied.
Parameters
m The packet mbuf to be copied.
mp The mempool from which the 'clone' mbufs are allocated.
offset The number of bytes to skip before copying. If the mbuf does not have that many bytes, it is
an error and NULL is returned.
length The upper limit on bytes to copy. Passing UINT32_MAX means all data (after offset).
Returns
• The pointer to the new 'clone' mbuf on success.
• NULL if allocation fails.
static void rte_pktmbuf_refcnt_update (struct rte_mbuf * m, int16_t v) [inline], [static]
Adds given value to the refcnt of all packet mbuf segments.
Walks through all segments of given packet mbuf and for each of them invokes rte_mbuf_refcnt_update().
Parameters
m The packet mbuf whose refcnt to be updated.
v The value to add to the mbuf's segments refcnt.
Definition at line 1499 of file rte_mbuf.h.
static 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 1516 of file rte_mbuf.h.
static 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 1530 of file rte_mbuf.h.
static struct rte_mbuf * rte_pktmbuf_lastseg (struct rte_mbuf * m) [inline], [static]
Get the last segment of the packet.
Parameters
m The packet mbuf.
Returns
The last segment of the given mbuf.
Definition at line 1545 of file rte_mbuf.h.
static char * rte_pktmbuf_prepend (struct rte_mbuf * m, uint16_t len) [inline], [static]
Prepend len bytes to an mbuf data area.
Returns a pointer to the new data start address. If there is not enough headroom in the first segment,
the function will return NULL, without modifying the mbuf.
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 1588 of file rte_mbuf.h.
static char * rte_pktmbuf_append (struct rte_mbuf * m, uint16_t len) [inline], [static]
Append len bytes to an mbuf.
Append len bytes to an mbuf and return a pointer to the start address of the added data. If there is not
enough tailroom in the last segment, the function will return 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 1621 of file rte_mbuf.h.
static char * rte_pktmbuf_adj (struct rte_mbuf * m, uint16_t len) [inline], [static]
Remove len bytes at the beginning of an mbuf.
Returns a pointer to the start address of the new data area. If the length is greater than the length of
the first segment, then the function will fail and return NULL, without modifying the mbuf.
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 1652 of file rte_mbuf.h.
static int rte_pktmbuf_trim (struct rte_mbuf * m, uint16_t len) [inline], [static]
Remove len bytes of data at the end of the mbuf.
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 1682 of file rte_mbuf.h.
static 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 1706 of file rte_mbuf.h.
static 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 specified offset.
If the data is contiguous, return the pointer in the mbuf data, else copy the data in the buffer provided
by the user and return its pointer.
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. If mbuf is
too small, NULL is returned.
Definition at line 1738 of file rte_mbuf.h.
static int rte_pktmbuf_chain (struct rte_mbuf * head, struct rte_mbuf * tail) [inline], [static]
Chain an mbuf to another, thereby creating a segmented packet.
Note: The implementation will do a linear walk over the segments to find the tail entry. For cases when
there are many segments, it's better to chain the entries manually.
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 1763 of file rte_mbuf.h.
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]
For given input values generate raw tx_offload value. Note that it is caller responsibility to make sure
that input parameters don't exceed maximum bit-field values.
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 1810 of file rte_mbuf.h.
static int rte_validate_tx_offload (const struct rte_mbuf * m) [inline], [static]
Validate general requirements for Tx offload in mbuf.
This function checks correctness and completeness of Tx offload settings.
Parameters
m The packet mbuf to be validated.
Returns
0 if packet is valid
Definition at line 1833 of file rte_mbuf.h.
static int rte_pktmbuf_linearize (struct rte_mbuf * mbuf) [inline], [static]
Linearize data in mbuf.
This function moves the mbuf data in the first segment if there is enough tailroom. The subsequent
segments are unchained and freed.
Parameters
mbuf mbuf to linearize
Returns
• 0, on success
• -1, on error
Definition at line 1883 of file rte_mbuf.h.
void rte_pktmbuf_dump (FILE * f, const struct rte_mbuf * m, unsigned dump_len)
Dump an mbuf structure to a file.
Dump all fields for the given packet mbuf and all its associated segments (in the case of a chained
buffer).
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.
static uint32_t rte_mbuf_sched_queue_get (const struct rte_mbuf * m) [inline], [static]
Get the value of mbuf sched queue_id field.
Definition at line 1910 of file rte_mbuf.h.
static uint8_t rte_mbuf_sched_traffic_class_get (const struct rte_mbuf * m) [inline], [static]
Get the value of mbuf sched traffic_class field.
Definition at line 1919 of file rte_mbuf.h.
static uint8_t rte_mbuf_sched_color_get (const struct rte_mbuf * m) [inline], [static]
Get the value of mbuf sched color field.
Definition at line 1928 of file rte_mbuf.h.
static 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.
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 1946 of file rte_mbuf.h.
static void rte_mbuf_sched_queue_set (struct rte_mbuf * m, uint32_t queue_id) [inline], [static]
Set the mbuf sched queue_id to the defined value.
Definition at line 1961 of file rte_mbuf.h.
static void rte_mbuf_sched_traffic_class_set (struct rte_mbuf * m, uint8_t traffic_class) [inline], [static]
Set the mbuf sched traffic_class id to the defined value.
Definition at line 1970 of file rte_mbuf.h.
static void rte_mbuf_sched_color_set (struct rte_mbuf * m, uint8_t color) [inline], [static]
Set the mbuf sched color id to the defined value.
Definition at line 1979 of file rte_mbuf.h.
static void rte_mbuf_sched_set (struct rte_mbuf * m, uint32_t queue_id, uint8_t traffic_class, uint8_t color)
[inline], [static]
Set the mbuf sched queue_id, traffic_class and color.
Parameters
m Mbuf to set
queue_id Queue id value to be set
traffic_class Traffic class id value to be set
color Color id to be set
Definition at line 1997 of file rte_mbuf.h.
Author
Generated automatically by Doxygen for DPDK from the source code.
DPDK Version 24.11.2 rte_mbuf.h(3)