#include <stdint.h>
#include <rte_compat.h>
#include <rte_common.h>
#include <rte_config.h>
#include <rte_mempool.h>
#include <rte_memory.h>
#include <rte_atomic.h>
#include <rte_prefetch.h>
#include <rte_branch_prediction.h>
#include <rte_byteorder.h>
#include <rte_mbuf_ptype.h>

Data Structures
struct	rte_mbuf_sched
struct	rte_mbuf
struct	rte_mbuf_ext_shared_info
struct	rte_pktmbuf_pool_private

Macros
#define	PKT_RX_VLAN (1ULL << 0)
#define	PKT_RX_RSS_HASH (1ULL << 1)
#define	PKT_RX_FDIR (1ULL << 2)
#define	PKT_RX_L4_CKSUM_BAD (1ULL << 3)
#define	PKT_RX_IP_CKSUM_BAD (1ULL << 4)
#define	PKT_RX_EIP_CKSUM_BAD (1ULL << 5)
#define	PKT_RX_VLAN_STRIPPED (1ULL << 6)
#define	PKT_RX_IP_CKSUM_MASK ((1ULL << 4) \| (1ULL << 7))
#define	PKT_RX_IP_CKSUM_BAD (1ULL << 4)
#define	PKT_RX_L4_CKSUM_MASK ((1ULL << 3) \| (1ULL << 8))
#define	PKT_RX_L4_CKSUM_BAD (1ULL << 3)
#define	PKT_RX_IEEE1588_PTP (1ULL << 9)
#define	PKT_RX_IEEE1588_TMST (1ULL << 10)
#define	PKT_RX_FDIR_ID (1ULL << 13)
#define	PKT_RX_FDIR_FLX (1ULL << 14)
#define	PKT_RX_QINQ_STRIPPED (1ULL << 15)
#define	PKT_RX_LRO (1ULL << 16)
#define	PKT_RX_TIMESTAMP (1ULL << 17)
#define	PKT_RX_SEC_OFFLOAD (1ULL << 18)
#define	PKT_RX_SEC_OFFLOAD_FAILED (1ULL << 19)
#define	PKT_RX_QINQ (1ULL << 20)
#define	PKT_RX_OUTER_L4_CKSUM_MASK ((1ULL << 21) \| (1ULL << 22))
#define	PKT_TX_METADATA (1ULL << 40)
#define	PKT_TX_OUTER_UDP_CKSUM (1ULL << 41)
#define	PKT_TX_UDP_SEG (1ULL << 42)
#define	PKT_TX_SEC_OFFLOAD (1ULL << 43)
#define	PKT_TX_MACSEC (1ULL << 44)
#define	PKT_TX_TUNNEL_VXLAN (0x1ULL << 45)
#define	PKT_TX_TUNNEL_MPLSINUDP (0x5ULL << 45)
#define	PKT_TX_TUNNEL_IP (0xDULL << 45)
#define	PKT_TX_TUNNEL_UDP (0xEULL << 45)
#define	PKT_TX_QINQ (1ULL << 49)
#define	PKT_TX_TCP_SEG (1ULL << 50)
#define	PKT_TX_IEEE1588_TMST (1ULL << 51)
#define	PKT_TX_L4_NO_CKSUM (0ULL << 52)
#define	PKT_TX_TCP_CKSUM (1ULL << 52)
#define	PKT_TX_SCTP_CKSUM (2ULL << 52)
#define	PKT_TX_UDP_CKSUM (3ULL << 52)
#define	PKT_TX_L4_MASK (3ULL << 52)
#define	PKT_TX_IP_CKSUM (1ULL << 54)
#define	PKT_TX_IPV4 (1ULL << 55)
#define	PKT_TX_IPV6 (1ULL << 56)
#define	PKT_TX_VLAN (1ULL << 57)
#define	PKT_TX_OUTER_IP_CKSUM (1ULL << 58)
#define	PKT_TX_OUTER_IPV4 (1ULL << 59)
#define	PKT_TX_OUTER_IPV6 (1ULL << 60)
#define	PKT_TX_OFFLOAD_MASK
#define	EXT_ATTACHED_MBUF (1ULL << 61)
#define	IND_ATTACHED_MBUF (1ULL << 62)
#define	RTE_MBUF_PRIV_ALIGN 8
#define	RTE_MBUF_DEFAULT_DATAROOM 2048
#define	RTE_MBUF_CLONED(mb) ((mb)->ol_flags & IND_ATTACHED_MBUF)
#define	RTE_MBUF_HAS_EXTBUF(mb) ((mb)->ol_flags & EXT_ATTACHED_MBUF)
#define	RTE_MBUF_DIRECT(mb) (!((mb)->ol_flags & (IND_ATTACHED_MBUF \| EXT_ATTACHED_MBUF)))
#define	__rte_mbuf_sanity_check(m, is_h) do { } while (0)
#define	RTE_MBUF_PREFETCH_TO_FREE(m)
#define	MBUF_INVALID_PORT UINT16_MAX
#define	rte_pktmbuf_detach_extbuf(m) rte_pktmbuf_detach(m)
#define	rte_pktmbuf_mtod_offset(m, t, o) ((t)((char *)(m)->buf_addr + (m)->data_off + (o)))
#define	rte_pktmbuf_mtod(m, t) rte_pktmbuf_mtod_offset(m, t, 0)
#define	rte_pktmbuf_iova_offset(m, o) (rte_iova_t)((m)->buf_iova + (m)->data_off + (o))
#define	rte_pktmbuf_iova(m) rte_pktmbuf_iova_offset(m, 0)
#define	rte_pktmbuf_pkt_len(m) ((m)->pkt_len)
#define	rte_pktmbuf_data_len(m) ((m)->data_len)

Typedefs
typedef void(*	rte_mbuf_extbuf_free_callback_t )(void addr, void opaque)

Enumerations
enum

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_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_experimental	rte_mbuf_buf_addr (struct rte_mbuf mb, struct rte_mempool mp)
static char *__rte_experimental	rte_mbuf_data_addr_default (struct rte_mbuf *mb)
static char *	rte_mbuf_to_baddr (struct rte_mbuf *md)
static void *__rte_experimental	rte_mbuf_to_priv (struct rte_mbuf *m)
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)
__rte_experimental 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 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)
static uint16_t	rte_pktmbuf_data_room_size (struct rte_mempool *mp)
static void	rte_pktmbuf_reset_headroom (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_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)
static struct rte_mbuf *	rte_pktmbuf_clone (struct rte_mbuf md, struct rte_mempool mp)
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 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)

Variables
__extension__ typedef void *	MARKER [0]
__extension__ typedef uint8_t	MARKER8 [0]
__extension__ typedef uint64_t	MARKER64 [0]
rte_iova_t	buf_physaddr

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 PKT_RX_VLAN (1ULL << 0)

The RX packet is a 802.1q VLAN packet, and the tci has been saved in in mbuf->vlan_tci. If the flag PKT_RX_VLAN_STRIPPED is also present, the VLAN header has been stripped from mbuf data, else it is still present.

Definition at line 72 of file rte_mbuf.h.

#define PKT_RX_RSS_HASH (1ULL << 1)

RX packet with RSS hash result.

Definition at line 74 of file rte_mbuf.h.

#define PKT_RX_FDIR (1ULL << 2)

RX packet with FDIR match indicate.

Definition at line 75 of file rte_mbuf.h.

#define PKT_RX_L4_CKSUM_BAD (1ULL << 3)

Deprecated. Checking this flag alone is deprecated: check the 2 bits of PKT_RX_L4_CKSUM_MASK. This flag was set when the L4 checksum of a packet was detected as wrong by the hardware.

Examples:: examples/tep_termination/vxlan_setup.c.

Definition at line 131 of file rte_mbuf.h.

#define PKT_RX_IP_CKSUM_BAD (1ULL << 4)

Deprecated. Checking this flag alone is deprecated: check the 2 bits of PKT_RX_IP_CKSUM_MASK. This flag was set when the IP checksum of a packet was detected as wrong by the hardware.

Examples:: examples/tep_termination/vxlan_setup.c.

Definition at line 116 of file rte_mbuf.h.

#define PKT_RX_EIP_CKSUM_BAD (1ULL << 5)

External IP header checksum error.

Definition at line 95 of file rte_mbuf.h.

#define PKT_RX_VLAN_STRIPPED (1ULL << 6)

A vlan has been stripped by the hardware and its tci is saved in mbuf->vlan_tci. This can only happen if vlan stripping is enabled in the RX configuration of the PMD. When PKT_RX_VLAN_STRIPPED is set, PKT_RX_VLAN must also be set.

Examples:: examples/bpf/t2.c.

Definition at line 103 of file rte_mbuf.h.

#define PKT_RX_IP_CKSUM_MASK ((1ULL << 4) | (1ULL << 7))

Mask of bits used to determine the status of RX IP checksum.

PKT_RX_IP_CKSUM_UNKNOWN: no information about the RX IP checksum
PKT_RX_IP_CKSUM_BAD: the IP checksum in the packet is wrong
PKT_RX_IP_CKSUM_GOOD: the IP checksum in the packet is valid
PKT_RX_IP_CKSUM_NONE: the IP checksum is not correct in the packet data, but the integrity of the IP header is verified.

Definition at line 113 of file rte_mbuf.h.

#define PKT_RX_IP_CKSUM_BAD (1ULL << 4)

Deprecated. Checking this flag alone is deprecated: check the 2 bits of PKT_RX_IP_CKSUM_MASK. This flag was set when the IP checksum of a packet was detected as wrong by the hardware.

Definition at line 116 of file rte_mbuf.h.

#define PKT_RX_L4_CKSUM_MASK ((1ULL << 3) | (1ULL << 8))

Mask of bits used to determine the status of RX L4 checksum.

PKT_RX_L4_CKSUM_UNKNOWN: no information about the RX L4 checksum
PKT_RX_L4_CKSUM_BAD: the L4 checksum in the packet is wrong
PKT_RX_L4_CKSUM_GOOD: the L4 checksum in the packet is valid
PKT_RX_L4_CKSUM_NONE: the L4 checksum is not correct in the packet data, but the integrity of the L4 data is verified.

Definition at line 128 of file rte_mbuf.h.

#define PKT_RX_L4_CKSUM_BAD (1ULL << 3)

Deprecated. Checking this flag alone is deprecated: check the 2 bits of PKT_RX_L4_CKSUM_MASK. This flag was set when the L4 checksum of a packet was detected as wrong by the hardware.

Definition at line 131 of file rte_mbuf.h.

#define PKT_RX_IEEE1588_PTP (1ULL << 9)

RX IEEE1588 L2 Ethernet PT Packet.

Examples:: examples/ptpclient/ptpclient.c.

Definition at line 135 of file rte_mbuf.h.

#define PKT_RX_IEEE1588_TMST (1ULL << 10)

RX IEEE1588 L2/L4 timestamped packet.

Definition at line 136 of file rte_mbuf.h.

#define PKT_RX_FDIR_ID (1ULL << 13)

FD id reported if FDIR match.

Definition at line 137 of file rte_mbuf.h.

#define PKT_RX_FDIR_FLX (1ULL << 14)

Flexible bytes reported if FDIR match.

Definition at line 138 of file rte_mbuf.h.

#define PKT_RX_QINQ_STRIPPED (1ULL << 15)

The 2 vlans have been stripped by the hardware and their tci are saved in mbuf->vlan_tci (inner) and mbuf->vlan_tci_outer (outer). This can only happen if vlan stripping is enabled in the RX configuration of the PMD. When PKT_RX_QINQ_STRIPPED is set, the flags (PKT_RX_VLAN | PKT_RX_VLAN_STRIPPED | PKT_RX_QINQ) must also be set.

Definition at line 148 of file rte_mbuf.h.

#define PKT_RX_LRO (1ULL << 16)

When packets are coalesced by a hardware or virtual driver, this flag can be set in the RX mbuf, meaning that the m->tso_segsz field is valid and is set to the segment size of original packets.

Definition at line 155 of file rte_mbuf.h.

#define PKT_RX_TIMESTAMP (1ULL << 17)

Indicate that the timestamp field in the mbuf is valid.

Definition at line 160 of file rte_mbuf.h.

#define PKT_RX_SEC_OFFLOAD (1ULL << 18)

Indicate that security offload processing was applied on the RX packet.

Examples:: examples/ipsec-secgw/esp.c, and examples/ipsec-secgw/ipsec-secgw.c.

Definition at line 165 of file rte_mbuf.h.

#define PKT_RX_SEC_OFFLOAD_FAILED (1ULL << 19)

Indicate that security offload processing failed on the RX packet.

Examples:: examples/ipsec-secgw/esp.c.

Definition at line 170 of file rte_mbuf.h.

#define PKT_RX_QINQ (1ULL << 20)

The RX packet is a double VLAN, and the outer tci has been saved in in mbuf->vlan_tci_outer. If PKT_RX_QINQ set, PKT_RX_VLAN also should be set and inner tci should be saved to mbuf->vlan_tci. If the flag PKT_RX_QINQ_STRIPPED is also present, both VLANs headers have been stripped from mbuf data, else they are still present.

Definition at line 180 of file rte_mbuf.h.

#define PKT_RX_OUTER_L4_CKSUM_MASK ((1ULL << 21) | (1ULL << 22))

Mask of bits used to determine the status of outer RX L4 checksum.

PKT_RX_OUTER_L4_CKSUM_UNKNOWN: no info about the outer RX L4 checksum
PKT_RX_OUTER_L4_CKSUM_BAD: the outer L4 checksum in the packet is wrong
PKT_RX_OUTER_L4_CKSUM_GOOD: the outer L4 checksum in the packet is valid
PKT_RX_OUTER_L4_CKSUM_INVALID: invalid outer L4 checksum state.

The detection of PKT_RX_OUTER_L4_CKSUM_GOOD shall be based on the given HW capability, At minimum, the PMD should support PKT_RX_OUTER_L4_CKSUM_UNKNOWN and PKT_RX_OUTER_L4_CKSUM_BAD states if the DEV_RX_OFFLOAD_OUTER_UDP_CKSUM offload is available.

Definition at line 194 of file rte_mbuf.h.

#define PKT_TX_METADATA (1ULL << 40)

Indicate that the metadata field in the mbuf is in use.

Definition at line 208 of file rte_mbuf.h.

#define PKT_TX_OUTER_UDP_CKSUM (1ULL << 41)

Outer UDP checksum offload flag. This flag is used for enabling outer UDP checksum in PMD. To use outer UDP checksum, the user needs to 1) Enable the following in mbuf, a) Fill outer_l2_len and outer_l3_len in mbuf. b) Set the PKT_TX_OUTER_UDP_CKSUM flag. c) Set the PKT_TX_OUTER_IPV4 or PKT_TX_OUTER_IPV6 flag. 2) Configure DEV_TX_OFFLOAD_OUTER_UDP_CKSUM offload flag.

Definition at line 219 of file rte_mbuf.h.

#define PKT_TX_UDP_SEG (1ULL << 42)

UDP Fragmentation Offload flag. This flag is used for enabling UDP fragmentation in SW or in HW. When use UFO, mbuf->tso_segsz is used to store the MSS of UDP fragments.

Definition at line 226 of file rte_mbuf.h.

#define PKT_TX_SEC_OFFLOAD (1ULL << 43)

Request security offload processing on the TX packet.

Examples:: examples/ipsec-secgw/esp.c, and examples/ipsec-secgw/ipsec-secgw.c.

Definition at line 231 of file rte_mbuf.h.

#define PKT_TX_MACSEC (1ULL << 44)

Offload the MACsec. This flag must be set by the application to enable this offload feature for a packet to be transmitted.

Definition at line 237 of file rte_mbuf.h.

#define PKT_TX_TUNNEL_VXLAN (0x1ULL << 45)

Bits 45:48 used for the tunnel type. The tunnel type must be specified for TSO or checksum on the inner part of tunnel packets. These flags can be used with PKT_TX_TCP_SEG for TSO, or PKT_TX_xxx_CKSUM. The mbuf fields for inner and outer header lengths are required: outer_l2_len, outer_l3_len, l2_len, l3_len, l4_len and tso_segsz for TSO.

Examples:: examples/tep_termination/vxlan.c.

Definition at line 247 of file rte_mbuf.h.

#define PKT_TX_TUNNEL_MPLSINUDP (0x5ULL << 45)

TX packet with MPLS-in-UDP RFC 7510 header.

Definition at line 252 of file rte_mbuf.h.

#define PKT_TX_TUNNEL_IP (0xDULL << 45)

Generic IP encapsulated tunnel type, used for TSO and checksum offload. It can be used for tunnels which are not standards or listed above. It is preferred to use specific tunnel flags like PKT_TX_TUNNEL_GRE or PKT_TX_TUNNEL_IPIP if possible. The ethdev must be configured with DEV_TX_OFFLOAD_IP_TNL_TSO. Outer and inner checksums are done according to the existing flags like PKT_TX_xxx_CKSUM. Specific tunnel headers that contain payload length, sequence id or checksum are not expected to be updated.

Definition at line 265 of file rte_mbuf.h.

#define PKT_TX_TUNNEL_UDP (0xEULL << 45)

Generic UDP encapsulated tunnel type, used for TSO and checksum offload. UDP tunnel type implies outer IP layer. It can be used for tunnels which are not standards or listed above. It is preferred to use specific tunnel flags like PKT_TX_TUNNEL_VXLAN if possible. The ethdev must be configured with DEV_TX_OFFLOAD_UDP_TNL_TSO. Outer and inner checksums are done according to the existing flags like PKT_TX_xxx_CKSUM. Specific tunnel headers that contain payload length, sequence id or checksum are not expected to be updated.

Definition at line 278 of file rte_mbuf.h.

#define PKT_TX_QINQ (1ULL << 49)

Double VLAN insertion (QinQ) request to driver, driver may offload the insertion based on device capability. mbuf 'vlan_tci' & 'vlan_tci_outer' must be valid when this flag is set.

Definition at line 287 of file rte_mbuf.h.

#define PKT_TX_TCP_SEG (1ULL << 50)

TCP segmentation offload. To enable this offload feature for a packet to be transmitted on hardware supporting TSO:

set the PKT_TX_TCP_SEG flag in mbuf->ol_flags (this flag implies PKT_TX_TCP_CKSUM)
set the flag PKT_TX_IPV4 or PKT_TX_IPV6
if it's IPv4, set the PKT_TX_IP_CKSUM flag
fill the mbuf offload information: l2_len, l3_len, l4_len, tso_segsz

Examples:: examples/tep_termination/vxlan.c, and examples/vhost/main.c.

Definition at line 300 of file rte_mbuf.h.

#define PKT_TX_IEEE1588_TMST (1ULL << 51)

TX IEEE1588 packet to timestamp.

Examples:: examples/ptpclient/ptpclient.c.

Definition at line 302 of file rte_mbuf.h.

#define PKT_TX_L4_NO_CKSUM (0ULL << 52)

Bits 52+53 used for L4 packet type with checksum enabled: 00: Reserved, 01: TCP checksum, 10: SCTP checksum, 11: UDP checksum. To use hardware L4 checksum offload, the user needs to:

fill l2_len and l3_len in mbuf
set the flags PKT_TX_TCP_CKSUM, PKT_TX_SCTP_CKSUM or PKT_TX_UDP_CKSUM
set the flag PKT_TX_IPV4 or PKT_TX_IPV6Disable L4 cksum of TX pkt.

Definition at line 312 of file rte_mbuf.h.

#define PKT_TX_TCP_CKSUM (1ULL << 52)

TCP cksum of TX pkt. computed by NIC.

Examples:: examples/tep_termination/vxlan.c.

Definition at line 313 of file rte_mbuf.h.

#define PKT_TX_SCTP_CKSUM (2ULL << 52)

SCTP cksum of TX pkt. computed by NIC.

Examples:: examples/tep_termination/vxlan.c.

Definition at line 314 of file rte_mbuf.h.

#define PKT_TX_UDP_CKSUM (3ULL << 52)

UDP cksum of TX pkt. computed by NIC.

Examples:: examples/tep_termination/vxlan.c.

Definition at line 315 of file rte_mbuf.h.

#define PKT_TX_L4_MASK (3ULL << 52)

Mask for L4 cksum offload request.

Definition at line 316 of file rte_mbuf.h.

#define PKT_TX_IP_CKSUM (1ULL << 54)

Offload the IP checksum in the hardware. The flag PKT_TX_IPV4 should also be set by the application, although a PMD will only check PKT_TX_IP_CKSUM.

fill the mbuf offload information: l2_len, l3_len

Examples:: examples/ipsec-secgw/ipsec-secgw.c, examples/tep_termination/vxlan.c, and examples/vhost/main.c.

Definition at line 324 of file rte_mbuf.h.

#define PKT_TX_IPV4 (1ULL << 55)

Packet is IPv4. This flag must be set when using any offload feature (TSO, L3 or L4 checksum) to tell the NIC that the packet is an IPv4 packet. If the packet is a tunneled packet, this flag is related to the inner headers.

Examples:: examples/ipsec-secgw/ipsec-secgw.c, examples/tep_termination/vxlan.c, and examples/vhost/main.c.

Definition at line 332 of file rte_mbuf.h.

#define PKT_TX_IPV6 (1ULL << 56)

Packet is IPv6. This flag must be set when using an offload feature (TSO or L4 checksum) to tell the NIC that the packet is an IPv6 packet. If the packet is a tunneled packet, this flag is related to the inner headers.

Examples:: examples/ipsec-secgw/ipsec-secgw.c, and examples/tep_termination/vxlan.c.

Definition at line 340 of file rte_mbuf.h.

#define PKT_TX_VLAN (1ULL << 57)

VLAN tag insertion request to driver, driver may offload the insertion based on the device capability. mbuf 'vlan_tci' field must be valid when this flag is set.

Definition at line 347 of file rte_mbuf.h.

#define PKT_TX_OUTER_IP_CKSUM (1ULL << 58)

Offload the IP checksum of an external header in the hardware. The flag PKT_TX_OUTER_IPV4 should also be set by the application, although a PMD will only check PKT_TX_OUTER_IP_CKSUM.

fill the mbuf offload information: outer_l2_len, outer_l3_len

Examples:: examples/tep_termination/vxlan.c.

Definition at line 357 of file rte_mbuf.h.

#define PKT_TX_OUTER_IPV4 (1ULL << 59)

Packet outer header is IPv4. This flag must be set when using any outer offload feature (L3 or L4 checksum) to tell the NIC that the outer header of the tunneled packet is an IPv4 packet.

Definition at line 364 of file rte_mbuf.h.

#define PKT_TX_OUTER_IPV6 (1ULL << 60)

Packet outer header is IPv6. This flag must be set when using any outer offload feature (L4 checksum) to tell the NIC that the outer header of the tunneled packet is an IPv6 packet.

Definition at line 371 of file rte_mbuf.h.

#define PKT_TX_OFFLOAD_MASK

Value:

(    \
                PKT_TX_OUTER_IPV6 |      \
                PKT_TX_OUTER_IPV4 |      \
                PKT_TX_OUTER_IP_CKSUM |  \
                PKT_TX_VLAN_PKT |        \
                PKT_TX_IPV6 |            \
                PKT_TX_IPV4 |            \
                PKT_TX_IP_CKSUM |        \
                PKT_TX_L4_MASK |         \
                PKT_TX_IEEE1588_TMST |   \
                PKT_TX_TCP_SEG |         \
                PKT_TX_QINQ_PKT |        \
                PKT_TX_TUNNEL_MASK |     \
                PKT_TX_MACSEC |          \
                PKT_TX_SEC_OFFLOAD |     \
                PKT_TX_UDP_SEG |         \
                PKT_TX_OUTER_UDP_CKSUM | \
                PKT_TX_METADATA)

Bitmask of all supported packet Tx offload features flags, which can be set for packet.

Definition at line 377 of file rte_mbuf.h.

#define EXT_ATTACHED_MBUF (1ULL << 61)

Mbuf having an external buffer attached. shinfo in mbuf must be filled.

Definition at line 399 of file rte_mbuf.h.

#define IND_ATTACHED_MBUF (1ULL << 62)

Indirect attached mbuf

Definition at line 401 of file rte_mbuf.h.

#define RTE_MBUF_PRIV_ALIGN 8

Alignment constraint of mbuf private area.

Definition at line 404 of file rte_mbuf.h.

#define RTE_MBUF_DEFAULT_DATAROOM 2048

Some NICs need at least 2KB buffer to RX standard Ethernet frame without splitting it into multiple segments. So, for mbufs that planned to be involved into RX/TX, the recommended minimal buffer length is 2KB + RTE_PKTMBUF_HEADROOM.

Definition at line 462 of file rte_mbuf.h.

#define RTE_MBUF_CLONED ( mb ) ((mb)->ol_flags & IND_ATTACHED_MBUF)

Returns TRUE if given mbuf is cloned by mbuf indirection, or FALSE otherwise.

If a mbuf has its data in another mbuf and references it by mbuf indirection, this mbuf can be defined as a cloned mbuf.

Definition at line 940 of file rte_mbuf.h.

#define RTE_MBUF_HAS_EXTBUF ( mb ) ((mb)->ol_flags & EXT_ATTACHED_MBUF)

Returns TRUE if given mbuf has an external buffer, or FALSE otherwise.

External buffer is a user-provided anonymous buffer.

Definition at line 947 of file rte_mbuf.h.

#define RTE_MBUF_DIRECT ( mb ) (!((mb)->ol_flags & (IND_ATTACHED_MBUF | EXT_ATTACHED_MBUF)))

Returns TRUE if given mbuf is direct, or FALSE otherwise.

If a mbuf embeds its own data after the rte_mbuf structure, this mbuf can be defined as a direct mbuf.

Definition at line 955 of file rte_mbuf.h.

#define __rte_mbuf_sanity_check	(	m,
		is_h
	)	do { } while (0)

check mbuf type in debug mode

Examples:: examples/ipv4_multicast/main.c.

Definition at line 977 of file rte_mbuf.h.

#define RTE_MBUF_PREFETCH_TO_FREE ( m )

Value:

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

Mbuf prefetch

Definition at line 1137 of file rte_mbuf.h.

#define MBUF_INVALID_PORT UINT16_MAX

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 1428 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 1662 of file rte_mbuf.h.

#define rte_pktmbuf_mtod_offset	(	m,
		t,
		o
	)	((t)((char *)(m)->buf_addr + (m)->data_off + (o)))

A macro that points to an offset into the data in the mbuf.

The returned pointer is cast to type t. Before using this function, the user must ensure that the first segment is large enough to accommodate its data.

Parameters

m	The packet mbuf.
o	The offset into the mbuf data.
t	The type to cast the result into.

Examples:: examples/bbdev_app/main.c, examples/ipsec-secgw/esp.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipsec-secgw/ipsec_process.c, examples/l3fwd-acl/main.c, examples/l3fwd-power/main.c, examples/l3fwd-vf/main.c, examples/load_balancer/runtime.c, examples/performance-thread/l3fwd-thread/main.c, examples/server_node_efd/node/node.c, examples/server_node_efd/server/main.c, and examples/vhost/virtio_net.c.

Definition at line 2020 of file rte_mbuf.h.

#define rte_pktmbuf_mtod	(	m,
		t
	)	rte_pktmbuf_mtod_offset(m, t, 0)

A macro that points to the start of the data in the mbuf.

The returned pointer is cast to type t. Before using this function, the user must ensure that the first segment is large enough to accommodate its data.

Parameters

m	The packet mbuf.
t	The type to cast the result into.

Examples:: examples/bbdev_app/main.c, examples/bond/main.c, examples/bpf/t3.c, examples/ethtool/ethtool-app/main.c, examples/exception_path/main.c, examples/fips_validation/main.c, examples/flow_filtering/main.c, examples/ip_fragmentation/main.c, examples/ip_reassembly/main.c, examples/ipsec-secgw/esp.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipsec-secgw/sa.c, examples/ipv4_multicast/main.c, examples/l2fwd-crypto/main.c, examples/l2fwd-jobstats/main.c, examples/l2fwd-keepalive/main.c, examples/l2fwd/main.c, examples/l3fwd-acl/main.c, examples/l3fwd-power/main.c, examples/l3fwd-vf/main.c, examples/l3fwd/l3fwd_em.c, examples/l3fwd/l3fwd_lpm.c, examples/link_status_interrupt/main.c, examples/load_balancer/runtime.c, examples/netmap_compat/lib/compat_netmap.c, examples/performance-thread/l3fwd-thread/main.c, examples/ptpclient/ptpclient.c, examples/qos_meter/main.c, examples/qos_sched/app_thread.c, examples/quota_watermark/qw/main.c, examples/tep_termination/vxlan.c, examples/tep_termination/vxlan_setup.c, examples/vhost/main.c, examples/vmdq/main.c, and examples/vmdq_dcb/main.c.

Definition at line 2035 of file rte_mbuf.h.

#define rte_pktmbuf_iova_offset	(	m,
		o
	)	(rte_iova_t)((m)->buf_iova + (m)->data_off + (o))

A macro that returns the IO address that points to an offset of the start of the data in the mbuf

Parameters

m	The packet mbuf.
o	The offset into the data to calculate address from.

Examples:: examples/fips_validation/fips_dev_self_test.c, examples/ipsec-secgw/esp.c, and examples/l2fwd-crypto/main.c.

Definition at line 2046 of file rte_mbuf.h.

#define rte_pktmbuf_iova ( m ) rte_pktmbuf_iova_offset(m, 0)

A macro that returns the IO address that points to the start of the data in the mbuf

Parameters

m	The packet mbuf.

Definition at line 2060 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.

Examples:: examples/fips_validation/main.c, examples/ipsec-secgw/esp.c, examples/l2fwd-crypto/main.c, and examples/qos_meter/main.c.

Definition at line 2073 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.

Examples:: examples/bbdev_app/main.c, examples/exception_path/main.c, examples/ipsec-secgw/esp.c, examples/l2fwd-crypto/main.c, examples/netmap_compat/lib/compat_netmap.c, and examples/vhost/virtio_net.c.

Definition at line 2083 of file rte_mbuf.h.

Typedef Documentation

typedef void(* rte_mbuf_extbuf_free_callback_t)(void *addr, void *opaque)

Function typedef of callback to free externally attached buffer.

Definition at line 733 of file rte_mbuf.h.

Enumeration Type Documentation

anonymous enum

enum for the tx_offload bit-fields lengths and offsets. defines the layout of rte_mbuf tx_offload field.

Definition at line 491 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: PKT_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 )

inlinestatic

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 758 of file rte_mbuf.h.

static void rte_mbuf_prefetch_part2 ( struct rte_mbuf * m )

inlinestatic

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.

Examples:: examples/ipsec-secgw/ipsec-secgw.c.

Definition at line 775 of file rte_mbuf.h.

static uint16_t rte_pktmbuf_priv_size ( struct rte_mempool * mp )

inlinestatic

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 1398 of file rte_mbuf.h.

static rte_iova_t rte_mbuf_data_iova ( const struct rte_mbuf * mb )

inlinestatic

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 796 of file rte_mbuf.h.

static rte_iova_t rte_mbuf_data_iova_default ( const struct rte_mbuf * mb )

inlinestatic

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 821 of file rte_mbuf.h.

static struct rte_mbuf* rte_mbuf_from_indirect ( struct rte_mbuf * mi )

staticread

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 842 of file rte_mbuf.h.

static char* __rte_experimental rte_mbuf_buf_addr	(	struct rte_mbuf *	mb,
		struct rte_mempool *	mp
	)

inlinestatic

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.

Warning: EXPERIMENTAL: This API may change without prior notice. This will be used by rte_mbuf_to_baddr() which has redundant code once experimental tag is removed.

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 868 of file rte_mbuf.h.

static char* __rte_experimental rte_mbuf_data_addr_default ( struct rte_mbuf * mb )

inlinestatic

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

Warning: EXPERIMENTAL: This API may change without prior notice.

Parameters

mb	The pointer to the mbuf.

Returns: The pointer of the beginning of the mbuf data.

Definition at line 885 of file rte_mbuf.h.

static char* rte_mbuf_to_baddr ( struct rte_mbuf * md )

inlinestatic

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 904 of file rte_mbuf.h.

static void* __rte_experimental rte_mbuf_to_priv ( struct rte_mbuf * m )

inlinestatic

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 928 of file rte_mbuf.h.

static uint16_t rte_mbuf_refcnt_update	(	struct rte_mbuf *	m,
		int16_t	value
	)

inlinestatic

Adds given value to an mbuf's refcnt and returns its new value.

Definition at line 1058 of file rte_mbuf.h.

static uint16_t rte_mbuf_refcnt_read ( const struct rte_mbuf * m )

inlinestatic

Reads the value of an mbuf's refcnt.

Definition at line 1067 of file rte_mbuf.h.

static void rte_mbuf_refcnt_set	(	struct rte_mbuf *	m,
		uint16_t	new_value
	)

inlinestatic

Sets an mbuf's refcnt to the defined value.

Definition at line 1076 of file rte_mbuf.h.

static uint16_t rte_mbuf_ext_refcnt_read ( const struct rte_mbuf_ext_shared_info * shinfo )

inlinestatic

Reads the refcnt of an external buffer.

Parameters

shinfo Shared data of the external buffer.

Returns: Reference count number.

Definition at line 1092 of file rte_mbuf.h.

static void rte_mbuf_ext_refcnt_set	(	struct rte_mbuf_ext_shared_info *	shinfo,
		uint16_t	new_value
	)

inlinestatic

Set refcnt of an external buffer.

Parameters

shinfo	Shared data of the external buffer.
new_value	Value set

Definition at line 1106 of file rte_mbuf.h.

static uint16_t rte_mbuf_ext_refcnt_update	(	struct rte_mbuf_ext_shared_info *	shinfo,
		int16_t	value
	)

inlinestatic

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

__rte_experimental 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 struct rte_mbuf* rte_mbuf_raw_alloc ( struct rte_mempool * mp )

staticread

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 1207 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 1232 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.

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.

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
	)

read

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
E_RTE_SECONDARY - function was called from a secondary process instance
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

Examples:: examples/bbdev_app/main.c, examples/bond/main.c, examples/distributor/main.c, examples/ethtool/ethtool-app/main.c, examples/eventdev_pipeline/main.c, examples/exception_path/main.c, examples/fips_validation/fips_dev_self_test.c, examples/fips_validation/main.c, examples/flow_classify/flow_classify.c, examples/flow_filtering/main.c, examples/ip_fragmentation/main.c, examples/ip_pipeline/mempool.c, examples/ip_reassembly/main.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipv4_multicast/main.c, examples/kni/main.c, examples/l2fwd-cat/l2fwd-cat.c, examples/l2fwd-crypto/main.c, examples/l2fwd-jobstats/main.c, examples/l2fwd-keepalive/main.c, examples/l2fwd/main.c, examples/l3fwd-acl/main.c, examples/l3fwd-power/main.c, examples/l3fwd-vf/main.c, examples/l3fwd/main.c, examples/link_status_interrupt/main.c, examples/load_balancer/init.c, examples/multi_process/client_server_mp/mp_server/init.c, examples/multi_process/symmetric_mp/main.c, examples/netmap_compat/bridge/bridge.c, examples/packet_ordering/main.c, examples/performance-thread/l3fwd-thread/main.c, examples/ptpclient/ptpclient.c, examples/qos_meter/main.c, examples/qos_sched/init.c, examples/quota_watermark/qw/main.c, examples/rxtx_callbacks/main.c, examples/server_node_efd/server/init.c, examples/skeleton/basicfwd.c, examples/tep_termination/main.c, examples/vhost/main.c, examples/vm_power_manager/main.c, examples/vmdq/main.c, and examples/vmdq_dcb/main.c.

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
	)

read

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
E_RTE_SECONDARY - function was called from a secondary process instance
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 )

inlinestatic

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 1377 of file rte_mbuf.h.

static void rte_pktmbuf_reset_headroom ( struct rte_mbuf * m )

inlinestatic

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 1414 of file rte_mbuf.h.

static struct rte_mbuf* rte_pktmbuf_alloc ( struct rte_mempool * mp )

staticread

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.

Examples:: examples/bond/main.c, examples/exception_path/main.c, examples/fips_validation/fips_dev_self_test.c, examples/fips_validation/main.c, examples/ipv4_multicast/main.c, examples/netmap_compat/lib/compat_netmap.c, examples/ptpclient/ptpclient.c, examples/quota_watermark/qw/main.c, and examples/vhost/virtio_net.c.

Definition at line 1461 of file rte_mbuf.h.

static int rte_pktmbuf_alloc_bulk	(	struct rte_mempool *	pool,
		struct rte_mbuf **	mbufs,
		unsigned	count
	)

inlinestatic

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

staticread

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.
[in,out]	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 1558 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
	)

inlinestatic

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 for 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.

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 1636 of file rte_mbuf.h.

static void rte_pktmbuf_attach	(	struct rte_mbuf *	mi,
		struct rte_mbuf *	m
	)

inlinestatic

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 1685 of file rte_mbuf.h.

static void rte_pktmbuf_detach ( struct rte_mbuf * m )

inlinestatic

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.

Parameters

m	The indirect attached packet mbuf.

Definition at line 1776 of file rte_mbuf.h.

static __rte_always_inline struct rte_mbuf* rte_pktmbuf_prefree_seg ( struct rte_mbuf * m )

staticread

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 1815 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 1857 of file rte_mbuf.h.

static void rte_pktmbuf_free ( struct rte_mbuf * m )

inlinestatic

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.

Examples:: examples/bbdev_app/main.c, examples/bond/main.c, examples/distributor/main.c, examples/exception_path/main.c, examples/fips_validation/fips_dev_self_test.c, examples/fips_validation/main.c, examples/flow_classify/flow_classify.c, examples/flow_filtering/main.c, examples/ip_fragmentation/main.c, examples/ip_reassembly/main.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipsec-secgw/ipsec.c, examples/ipsec-secgw/ipsec_process.c, examples/ipv4_multicast/main.c, examples/kni/main.c, examples/l2fwd-cat/l2fwd-cat.c, examples/l2fwd-crypto/main.c, examples/l3fwd-acl/main.c, examples/l3fwd-power/main.c, examples/l3fwd-vf/main.c, examples/load_balancer/runtime.c, examples/multi_process/client_server_mp/mp_client/client.c, examples/multi_process/client_server_mp/mp_server/main.c, examples/multi_process/symmetric_mp/main.c, examples/netmap_compat/lib/compat_netmap.c, examples/packet_ordering/main.c, examples/performance-thread/l3fwd-thread/main.c, examples/ptpclient/ptpclient.c, examples/qos_meter/main.c, examples/qos_sched/app_thread.c, examples/quota_watermark/qw/main.c, examples/rxtx_callbacks/main.c, examples/server_node_efd/node/node.c, examples/server_node_efd/server/main.c, examples/skeleton/basicfwd.c, examples/tep_termination/main.c, examples/tep_termination/vxlan_setup.c, examples/vhost/main.c, examples/vhost/virtio_net.c, examples/vmdq/main.c, and examples/vmdq_dcb/main.c.

Definition at line 1873 of file rte_mbuf.h.

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

staticread

Creates 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.

Examples:: examples/ipv4_multicast/main.c.

Definition at line 1904 of file rte_mbuf.h.

static void rte_pktmbuf_refcnt_update	(	struct rte_mbuf *	m,
		int16_t	v
	)

inlinestatic

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.

Examples:: examples/ipv4_multicast/main.c.

Definition at line 1952 of file rte_mbuf.h.

static uint16_t rte_pktmbuf_headroom ( const struct rte_mbuf * m )

inlinestatic

Get the headroom in a packet mbuf.

Parameters

m	The packet mbuf.

Returns: The length of the headroom.

Definition at line 1969 of file rte_mbuf.h.

static uint16_t rte_pktmbuf_tailroom ( const struct rte_mbuf * m )

inlinestatic

Get the tailroom of a packet mbuf.

Parameters

m	The packet mbuf.

Returns: The length of the tailroom.

Examples:: examples/vhost/main.c.

Definition at line 1983 of file rte_mbuf.h.

static struct rte_mbuf* rte_pktmbuf_lastseg ( struct rte_mbuf * m )

staticread

Get the last segment of the packet.

Parameters

m	The packet mbuf.

Returns: The last segment of the given mbuf.

Definition at line 1998 of file rte_mbuf.h.

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

inlinestatic

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

Examples:: examples/ip_fragmentation/main.c, examples/ipsec-secgw/esp.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipv4_multicast/main.c, and examples/tep_termination/vxlan.c.

Definition at line 2100 of file rte_mbuf.h.

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

inlinestatic

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

Examples:: examples/bbdev_app/main.c, examples/fips_validation/fips_dev_self_test.c, examples/fips_validation/main.c, examples/ipsec-secgw/esp.c, examples/l2fwd-crypto/main.c, and examples/netmap_compat/lib/compat_netmap.c.

Definition at line 2133 of file rte_mbuf.h.

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

inlinestatic

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.

Examples:: examples/ip_fragmentation/main.c, examples/ipsec-secgw/esp.c, examples/ipsec-secgw/ipsec-secgw.c, examples/ipv4_multicast/main.c, and examples/tep_termination/vxlan.c.

Definition at line 2164 of file rte_mbuf.h.

static int rte_pktmbuf_trim	(	struct rte_mbuf *	m,
		uint16_t	len
	)

inlinestatic

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.

Examples:: examples/bbdev_app/main.c, and examples/ipsec-secgw/esp.c.

Definition at line 2194 of file rte_mbuf.h.

static int rte_pktmbuf_is_contiguous ( const struct rte_mbuf * m )

inlinestatic

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 2218 of file rte_mbuf.h.

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

inlinestatic

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 2250 of file rte_mbuf.h.

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

inlinestatic

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 2275 of file rte_mbuf.h.

static int rte_validate_tx_offload ( const struct rte_mbuf * m )

inlinestatic

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 2348 of file rte_mbuf.h.

static int rte_pktmbuf_linearize ( struct rte_mbuf * mbuf )

inlinestatic

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 2393 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.

Examples:: examples/bpf/t3.c.

static uint32_t rte_mbuf_sched_queue_get ( const struct rte_mbuf * m )

inlinestatic

Get the value of mbuf sched queue_id field.

Definition at line 2451 of file rte_mbuf.h.

static uint8_t rte_mbuf_sched_traffic_class_get ( const struct rte_mbuf * m )

inlinestatic

Get the value of mbuf sched traffic_class field.

Definition at line 2460 of file rte_mbuf.h.

static uint8_t rte_mbuf_sched_color_get ( const struct rte_mbuf * m )

inlinestatic

Get the value of mbuf sched color field.

Definition at line 2469 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
	)

inlinestatic

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 2487 of file rte_mbuf.h.

static void rte_mbuf_sched_queue_set	(	struct rte_mbuf *	m,
		uint32_t	queue_id
	)

inlinestatic

Set the mbuf sched queue_id to the defined value.

Definition at line 2502 of file rte_mbuf.h.

static void rte_mbuf_sched_traffic_class_set	(	struct rte_mbuf *	m,
		uint8_t	traffic_class
	)

inlinestatic

Set the mbuf sched traffic_class id to the defined value.

Definition at line 2511 of file rte_mbuf.h.

static void rte_mbuf_sched_color_set	(	struct rte_mbuf *	m,
		uint8_t	color
	)

inlinestatic

Set the mbuf sched color id to the defined value.

Definition at line 2520 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
	)

inlinestatic

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 2538 of file rte_mbuf.h.

Variable Documentation

__extension__ typedef void* MARKER[0]

generic marker for a point in a structure

Definition at line 469 of file rte_mbuf.h.

__extension__ typedef uint8_t MARKER8[0]

generic marker with 1B alignment

Definition at line 471 of file rte_mbuf.h.

__extension__ typedef uint64_t MARKER64[0]

marker that allows us to overwrite 8 bytes with a single assignment

Definition at line 473 of file rte_mbuf.h.

rte_iova_t buf_physaddr

deprecated

Definition at line 550 of file rte_mbuf.h.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation