DPDK  17.02.1
Data Structures | Macros | Functions | Variables
rte_mbuf.h File Reference
#include <stdint.h>
#include <rte_common.h>
#include <rte_mempool.h>
#include <rte_memory.h>
#include <rte_atomic.h>
#include <rte_prefetch.h>
#include <rte_branch_prediction.h>
#include <rte_mbuf_ptype.h>

Go to the source code of this file.

Data Structures

struct  rte_mbuf
struct  rte_pktmbuf_pool_private

Macros

#define PKT_RX_VLAN_PKT   (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_QINQ_PKT   PKT_RX_QINQ_STRIPPED
#define PKT_RX_LRO   (1ULL << 16)
#define PKT_TX_MACSEC   (1ULL << 44)
#define PKT_TX_TUNNEL_VXLAN   (0x1ULL << 45)
#define PKT_TX_QINQ_PKT   (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_PKT   (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 __RESERVED   (1ULL << 61)
#define IND_ATTACHED_MBUF   (1ULL << 62)
#define CTRL_MBUF_FLAG   (1ULL << 63)
#define RTE_MBUF_PRIV_ALIGN   8
#define RTE_MBUF_DEFAULT_DATAROOM   2048
#define RTE_MBUF_INDIRECT(mb)   ((mb)->ol_flags & IND_ATTACHED_MBUF)
#define RTE_MBUF_DIRECT(mb)   (!RTE_MBUF_INDIRECT(mb))
#define __rte_mbuf_sanity_check(m, is_h)   do { } while (0)
#define RTE_MBUF_PREFETCH_TO_FREE(m)
#define rte_ctrlmbuf_alloc(mp)   rte_pktmbuf_alloc(mp)
#define rte_ctrlmbuf_free(m)   rte_pktmbuf_free(m)
#define rte_ctrlmbuf_data(m)   ((char *)((m)->buf_addr) + (m)->data_off)
#define rte_ctrlmbuf_len(m)   rte_pktmbuf_data_len(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_mtophys_offset(m, o)   (phys_addr_t)((m)->buf_physaddr + (m)->data_off + (o))
#define rte_pktmbuf_mtophys(m)   rte_pktmbuf_mtophys_offset(m, 0)
#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 phys_addr_t rte_mbuf_data_dma_addr (const struct rte_mbuf *mb)
static phys_addr_t rte_mbuf_data_dma_addr_default (const struct rte_mbuf *mb)
static struct rte_mbufrte_mbuf_from_indirect (struct rte_mbuf *mi)
static char * rte_mbuf_to_baddr (struct rte_mbuf *md)
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)
void rte_mbuf_sanity_check (const struct rte_mbuf *m, int is_header)
static struct rte_mbufrte_mbuf_raw_alloc (struct rte_mempool *mp)
void rte_ctrlmbuf_init (struct rte_mempool *mp, void *opaque_arg, void *m, unsigned i)
static int rte_is_ctrlmbuf (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_mempoolrte_pktmbuf_pool_create (const char *name, unsigned n, unsigned cache_size, uint16_t priv_size, uint16_t data_room_size, int socket_id)
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_mbufrte_pktmbuf_alloc (struct rte_mempool *mp)
static int rte_pktmbuf_alloc_bulk (struct rte_mempool *pool, struct rte_mbuf **mbufs, unsigned count)
static void rte_pktmbuf_attach (struct rte_mbuf *mi, struct rte_mbuf *m)
static void rte_pktmbuf_detach (struct rte_mbuf *m)
static void rte_pktmbuf_free_seg (struct rte_mbuf *m)
static void rte_pktmbuf_free (struct rte_mbuf *m)
static struct rte_mbufrte_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_mbufrte_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)

Variables

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

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.

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

RX packet is a 802.1q VLAN packet. This flag was set by PMDs when the packet is recognized as a VLAN, but the behavior between PMDs was not the same. This flag is kept for some time to avoid breaking applications and should be replaced by PKT_RX_VLAN_STRIPPED.

Definition at line 90 of file rte_mbuf.h.

#define PKT_RX_RSS_HASH   (1ULL << 1)

RX packet with RSS hash result.

Definition at line 92 of file rte_mbuf.h.

#define PKT_RX_FDIR   (1ULL << 2)

RX packet with FDIR match indicate.

Definition at line 93 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 148 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 133 of file rte_mbuf.h.

#define PKT_RX_EIP_CKSUM_BAD   (1ULL << 5)

External IP header checksum error.

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

Definition at line 120 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 130 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 133 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 145 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 148 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 152 of file rte_mbuf.h.

#define PKT_RX_IEEE1588_TMST   (1ULL << 10)

RX IEEE1588 L2/L4 timestamped packet.

Definition at line 153 of file rte_mbuf.h.

#define PKT_RX_FDIR_ID   (1ULL << 13)

FD id reported if FDIR match.

Definition at line 154 of file rte_mbuf.h.

#define PKT_RX_FDIR_FLX   (1ULL << 14)

Flexible bytes reported if FDIR match.

Definition at line 155 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. If this flag is set, PKT_RX_VLAN_STRIPPED must also be set.

Definition at line 164 of file rte_mbuf.h.

#define PKT_RX_QINQ_PKT   PKT_RX_QINQ_STRIPPED

Deprecated. RX packet with double VLAN stripped. This flag is replaced by PKT_RX_QINQ_STRIPPED.

Definition at line 171 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 178 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 188 of file rte_mbuf.h.

#define PKT_TX_TUNNEL_VXLAN   (0x1ULL << 45)

Bits 45:48 used for the tunnel type. When doing Tx offload like TSO or checksum, the HW needs to configure the tunnel type into the HW descriptors.

Examples:
examples/tep_termination/vxlan.c.

Definition at line 195 of file rte_mbuf.h.

#define PKT_TX_QINQ_PKT   (1ULL << 49)

Second VLAN insertion (QinQ) flag.TX packet with double VLAN inserted.

Definition at line 205 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 and write the IP checksum to 0 in the packet
  • fill the mbuf offload information: l2_len, l3_len, l4_len, tso_segsz
  • calculate the pseudo header checksum without taking ip_len in account, and set it in the TCP header. Refer to rte_ipv4_phdr_cksum() and rte_ipv6_phdr_cksum() that can be used as helpers.
Examples:
examples/tep_termination/vxlan.c, and examples/vhost/main.c.

Definition at line 220 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 222 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_IPV6
  • calculate the pseudo header checksum and set it in the L4 header (only for TCP or UDP). See rte_ipv4_phdr_cksum() and rte_ipv6_phdr_cksum(). For SCTP, set the crc field to 0.Disable L4 cksum of TX pkt.

Definition at line 235 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 236 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 237 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 238 of file rte_mbuf.h.

#define PKT_TX_L4_MASK   (3ULL << 52)

Mask for L4 cksum offload request.

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

  • set the IP checksum field in the packet to 0
  • 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 248 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 256 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 264 of file rte_mbuf.h.

#define PKT_TX_VLAN_PKT   (1ULL << 57)

TX packet is a 802.1q VLAN packet.

Examples:
examples/vhost/main.c.

Definition at line 266 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, alto ugh a PMD will only check PKT_TX_IP_CKSUM. The IP checksum field in the packet must be set to 0.

  • set the outer IP checksum field in the packet to 0
  • fill the mbuf offload information: outer_l2_len, outer_l3_len
Examples:
examples/tep_termination/vxlan.c.

Definition at line 276 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 283 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 290 of file rte_mbuf.h.

#define PKT_TX_OFFLOAD_MASK
Value:
( \
PKT_TX_IP_CKSUM | \
PKT_TX_L4_MASK | \
PKT_TX_OUTER_IP_CKSUM | \
PKT_TX_TCP_SEG | \
PKT_TX_IEEE1588_TMST | \
PKT_TX_QINQ_PKT | \
PKT_TX_VLAN_PKT | \
PKT_TX_TUNNEL_MASK | \
PKT_TX_MACSEC)

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

Definition at line 296 of file rte_mbuf.h.

#define __RESERVED   (1ULL << 61)

reserved for future mbuf use

Definition at line 307 of file rte_mbuf.h.

#define IND_ATTACHED_MBUF   (1ULL << 62)

Indirect attached mbuf

Definition at line 309 of file rte_mbuf.h.

#define CTRL_MBUF_FLAG   (1ULL << 63)

Mbuf contains control data

Definition at line 312 of file rte_mbuf.h.

#define RTE_MBUF_PRIV_ALIGN   8

Alignment constraint of mbuf private area.

Definition at line 315 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 373 of file rte_mbuf.h.

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

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

Definition at line 624 of file rte_mbuf.h.

#define RTE_MBUF_DIRECT (   mb)    (!RTE_MBUF_INDIRECT(mb))

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

Definition at line 629 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 650 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 742 of file rte_mbuf.h.

#define rte_ctrlmbuf_alloc (   mp)    rte_pktmbuf_alloc(mp)

Allocate a new mbuf (type is ctrl) from mempool mp.

This new mbuf is initialized with data pointing to the beginning of buffer, and with a length of zero.

Parameters
mpThe mempool from which the mbuf is allocated.
Returns
  • The pointer to the new mbuf on success.
  • NULL if allocation failed.

Definition at line 843 of file rte_mbuf.h.

#define rte_ctrlmbuf_free (   m)    rte_pktmbuf_free(m)

Free a control mbuf back into its original mempool.

Parameters
mThe control mbuf to be freed.

Definition at line 851 of file rte_mbuf.h.

#define rte_ctrlmbuf_data (   m)    ((char *)((m)->buf_addr) + (m)->data_off)

A macro that returns the pointer to the carried data.

The value that can be read or assigned.

Parameters
mThe control mbuf.

Definition at line 861 of file rte_mbuf.h.

#define rte_ctrlmbuf_len (   m)    rte_pktmbuf_data_len(m)

A macro that returns the length of the carried data.

The value that can be read or assigned.

Parameters
mThe control mbuf.

Definition at line 871 of file rte_mbuf.h.

#define rte_pktmbuf_mtod_offset (   m,
  t,
 
)    ((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
mThe packet mbuf.
oThe offset into the mbuf data.
tThe type to cast the result into.
Examples:
examples/ipsec-secgw/esp.c, examples/ipsec-secgw/ipsec-secgw.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, and examples/server_node_efd/server/main.c.

Definition at line 1405 of file rte_mbuf.h.

#define rte_pktmbuf_mtod (   m,
 
)    rte_pktmbuf_mtod_offset(m, t, 0)
#define rte_pktmbuf_mtophys_offset (   m,
 
)    (phys_addr_t)((m)->buf_physaddr + (m)->data_off + (o))

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

Parameters
mThe packet mbuf.
oThe offset into the data to calculate address from.
Examples:
examples/ipsec-secgw/esp.c, and examples/l2fwd-crypto/main.c.

Definition at line 1431 of file rte_mbuf.h.

#define rte_pktmbuf_mtophys (   m)    rte_pktmbuf_mtophys_offset(m, 0)

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

Parameters
mThe packet mbuf.

Definition at line 1441 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
mThe packet mbuf.
Examples:
examples/ipsec-secgw/esp.c, examples/l2fwd-crypto/main.c, and examples/qos_meter/main.c.

Definition at line 1451 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
mThe packet mbuf.
Examples:
examples/exception_path/main.c, examples/ipsec-secgw/esp.c, examples/l2fwd-crypto/main.c, and examples/netmap_compat/lib/compat_netmap.c.

Definition at line 1461 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
maskThe 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
maskThe mask describing the RX flags.
bufThe output buffer.
buflenThe 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
maskThe 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
maskThe mask describing the TX flags.
bufThe output buffer.
buflenThe 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
mThe pointer to the mbuf.

Definition at line 530 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
mThe pointer to the mbuf.
Examples:
examples/ipsec-secgw/ipsec-secgw.c.

Definition at line 547 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
mpThe packet mbuf pool.
Returns
The private size of mbufs stored in this mempool.

Definition at line 1004 of file rte_mbuf.h.

static phys_addr_t rte_mbuf_data_dma_addr ( const struct rte_mbuf mb)
inlinestatic

Return the DMA address of the beginning of the mbuf data

Parameters
mbThe pointer to the mbuf.
Returns
The physical address of the beginning of the mbuf data

Definition at line 568 of file rte_mbuf.h.

static phys_addr_t rte_mbuf_data_dma_addr_default ( const struct rte_mbuf mb)
inlinestatic

Return the default DMA 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
mbThe pointer to the mbuf.
Returns
The physical address of the beginning of the mbuf data

Definition at line 586 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
miThe pointer to the indirect mbuf.
Returns
The address of the direct mbuf corresponding to buffer_addr.

Definition at line 600 of file rte_mbuf.h.

static char* rte_mbuf_to_baddr ( struct rte_mbuf md)
inlinestatic

Return the buffer address embedded in the given mbuf.

Parameters
mdThe pointer to the mbuf.
Returns
The address of the data buffer owned by the mbuf.

Definition at line 614 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 715 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 725 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 734 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
mThe mbuf to be checked.
is_headerTrue 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)
static struct rte_mbuf* rte_mbuf_raw_alloc ( struct rte_mempool mp)
staticread

Allocate an unitialized mbuf from mempool mp.

This function can be used by PMDs (especially in RX functions) to allocate an unitialized mbuf. The driver is responsible of initializing all the required fields. See rte_pktmbuf_reset(). For standard needs, prefer rte_pktmbuf_alloc().

Parameters
mpThe mempool from which mbuf is allocated.
Returns
  • The pointer to the new mbuf on success.
  • NULL if allocation failed.

Definition at line 777 of file rte_mbuf.h.

void rte_ctrlmbuf_init ( struct rte_mempool mp,
void *  opaque_arg,
void *  m,
unsigned  i 
)

The control mbuf constructor.

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

Parameters
mpThe mempool from which the mbuf is allocated.
opaque_argA pointer that can be used by the user to retrieve useful information for mbuf initialization. This pointer comes from the init_arg parameter of rte_mempool_create().
mThe mbuf to initialize.
iThe index of the mbuf in the pool table.
static int rte_is_ctrlmbuf ( struct rte_mbuf m)
inlinestatic

Tests if an mbuf is a control mbuf

Parameters
mThe mbuf to be tested
Returns
  • True (1) if the mbuf is a control mbuf
  • False(0) otherwise

Definition at line 883 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_create() at pool creation time.

Parameters
mpThe mempool from which mbufs originate.
opaque_argA pointer that can be used by the user to retrieve useful information for mbuf initialization. This pointer comes from the init_arg parameter of rte_mempool_create().
mThe mbuf to initialize.
iThe index of the mbuf in the pool table.
Examples:
examples/ip_reassembly/main.c, and examples/tep_termination/main.c.
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 is 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
mpThe mempool from which mbufs originate.
opaque_argA pointer that can be used by the user to retrieve useful information for mbuf initialization. This pointer comes from the init_arg parameter of rte_mempool_create().
Examples:
examples/ip_reassembly/main.c, and examples/tep_termination/main.c.
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_create() with the proper packet constructor and mempool constructor.

Parameters
nameThe name of the mbuf pool.
nThe 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_sizeSize of the per-core object cache. See rte_mempool_create() for details.
priv_sizeSize 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_sizeSize of data buffer in each mbuf, including RTE_PKTMBUF_HEADROOM.
socket_idThe 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/bond/main.c, examples/distributor/main.c, examples/ethtool/ethtool-app/main.c, examples/exception_path/main.c, examples/ip_fragmentation/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/vhost/main.c, examples/vmdq/main.c, and examples/vmdq_dcb/main.c.
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
mpThe packet mbuf pool.
Returns
The data room size of mbufs stored in this mempool.

Definition at line 983 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
mThe packet mbuf's data_off field has to be reset.

Definition at line 1020 of file rte_mbuf.h.

static void rte_pktmbuf_reset ( struct rte_mbuf m)
inlinestatic

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

The given mbuf must have only one segment.

Parameters
mThe packet mbuf to be resetted.
Examples:
examples/netmap_compat/lib/compat_netmap.c.

Definition at line 1033 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
mpThe 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/ipv4_multicast/main.c, examples/netmap_compat/lib/compat_netmap.c, examples/ptpclient/ptpclient.c, and examples/quota_watermark/qw/main.c.

Definition at line 1064 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
poolThe mempool from which mbufs are allocated.
mbufsArray of pointers to mbufs
countArray size
Returns
  • 0: Success

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

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
miThe indirect packet mbuf.
mThe packet mbuf we're attaching to.

Definition at line 1144 of file rte_mbuf.h.

static void rte_pktmbuf_detach ( struct rte_mbuf m)
inlinestatic

Detach an indirect packet mbuf.

  • restore original mbuf address and length values.
  • reset pktmbuf data and data_len to their default values.
  • decrement the direct mbuf's reference counter. When the reference counter becomes 0, the direct mbuf is freed.

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

Parameters
mThe indirect attached packet mbuf.

Definition at line 1194 of file rte_mbuf.h.

static void rte_pktmbuf_free_seg ( struct rte_mbuf m)
inlinestatic

Free a segment of a packet mbuf into its original mempool.

Free an mbuf, without parsing other segments in case of chained buffers.

Parameters
mThe packet mbuf segment to be freed.

Definition at line 1240 of file rte_mbuf.h.

static void rte_pktmbuf_free ( struct rte_mbuf m)
inlinestatic
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
mdThe packet mbuf to be cloned.
mpThe 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 1287 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
mThe packet mbuf whose refcnt to be updated.
vThe value to add to the mbuf's segments refcnt.
Examples:
examples/ipv4_multicast/main.c.

Definition at line 1335 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
mThe packet mbuf.
Returns
The length of the headroom.

Definition at line 1352 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
mThe packet mbuf.
Returns
The length of the tailroom.
Examples:
examples/vhost/main.c.

Definition at line 1366 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
mThe packet mbuf.
Returns
The last segment of the given mbuf.

Definition at line 1381 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
mThe pkt mbuf.
lenThe 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 1478 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
mThe packet mbuf.
lenThe 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/ipsec-secgw/esp.c, examples/l2fwd-crypto/main.c, and examples/netmap_compat/lib/compat_netmap.c.

Definition at line 1508 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
mThe packet mbuf.
lenThe 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 1539 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
mThe packet mbuf.
lenThe amount of data to remove (in bytes).
Returns
  • 0: On success.
  • -1: On error.
Examples:
examples/ipsec-secgw/esp.c.

Definition at line 1566 of file rte_mbuf.h.

static int rte_pktmbuf_is_contiguous ( const struct rte_mbuf m)
inlinestatic

Test if mbuf data is contiguous.

Parameters
mThe packet mbuf.
Returns
  • 1, if all data is contiguous (one segment).
  • 0, if there is several segments.

Definition at line 1590 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
mThe pointer to the mbuf.
offThe offset of the data in the mbuf.
lenThe amount of bytes to read.
bufThe buffer where data is copied if it is not contigous 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 1622 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
headThe head of the mbuf chain (the first packet)
tailThe mbuf to put last in the chain
Returns
  • 0, on success.
  • -EOVERFLOW, if the chain is full (256 entries)

Definition at line 1647 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
mThe packet mbuf to be validated.
Returns
0 if packet is valid

Definition at line 1680 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
mbufmbuf to linearize
Returns
  • 0, on success
  • -1, on error

Definition at line 1733 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
fA pointer to a file for output
mThe packet mbuf.
dump_lenIf dump_len != 0, also dump the "dump_len" first data bytes of the packet.

Variable Documentation

__extension__ typedef void* MARKER[0]

generic marker for a point in a structure

Definition at line 380 of file rte_mbuf.h.

__extension__ typedef uint8_t MARKER8[0]

generic marker with 1B alignment

Definition at line 382 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 384 of file rte_mbuf.h.