rte_mbuf_dyn.h(3)

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

✨ rte_mbuf_dyn.h ✨ — the DPDK dynamic mbuf fields & flags era 💅

okay bestie, buckle up, this one lives in the Library Functions Manual and it's lowkey one of the most important headers in DPDK for anyone who's ever screamed "WHERE DO I PUT MY CUSTOM DATA IN AN MBUF 😭". spoiler: here. it's here. you're welcome 🫶

🌸 NAME 🌸

rte_mbuf_dyn.h — literally just the header itself, no cap 💖

🎀 SYNOPSIS 🎀

the vibe check first. you pull these in:

#include <stdio.h>
#include <stdint.h>
#include <rte_stdatomic.h>

🦋 Data Structures

  • struct rte_mbuf_dynfield
  • struct rte_mbuf_dynflag

🦋 Macros

#define RTE_MBUF_DYN_NAMESIZE   64
#define RTE_MBUF_DYNFIELD(m,  offset,  type)
#define RTE_MBUF_DYNFIELD_HISTORY_NAME   'rte_mbuf_dynfield_history'
#define RTE_MBUF_DYNFIELD_TIMESTAMP_NAME   'rte_dynfield_timestamp'
#define RTE_MBUF_DYNFLAG_RX_TIMESTAMP_NAME   'rte_dynflag_rx_timestamp'
#define RTE_MBUF_DYNFLAG_TX_TIMESTAMP_NAME   'rte_dynflag_tx_timestamp'
#define RTE_MBUF_DYNFIELD_IP_REASSEMBLY_NAME
    'rte_dynfield_ip_reassembly'

🦋 Functions

int rte_mbuf_dynfield_register (const struct rte_mbuf_dynfield *params)
int rte_mbuf_dynfield_register_offset (const struct rte_mbuf_dynfield
    *params, size_t offset)
int rte_mbuf_dynfield_lookup (const char *name, struct rte_mbuf_dynfield
    *params)
int rte_mbuf_dynflag_register (const struct rte_mbuf_dynflag *params)
int rte_mbuf_dynflag_register_bitnum (const struct rte_mbuf_dynflag
    *params, unsigned int bitnum)
int rte_mbuf_dynflag_lookup (const char *name, struct rte_mbuf_dynflag
    *params)
void rte_mbuf_dyn_dump (FILE *out)
typedef (uint64_t) rte_mbuf_history_t
int rte_mbuf_dyn_rx_timestamp_register (int *field_offset, uint64_t
    *rx_flag)
int rte_mbuf_dyn_tx_timestamp_register (int *field_offset, uint64_t
    *tx_flag)

💜 Detailed Description 💜

RTE Mbuf dynamic fields and flags 👑

so the whole situation is: so many DPDK features wanna stash some data inside the mbuf. but the room in the mbuf structure is limited, bestie. there's no way to give every single feature its own field — physically impossible, it's giving overbooked flight 💀. and on top of that, just changing fields in the mbuf structure can break the API or the ABI. nope. not on our watch.

this module fixes that whole mess by letting you dynamically register fields or flags instead:

  • a dynamic field is a named area in the rte_mbuf structure, with a given size (>= 1 byte) and alignment constraint. cute, right? 🌸
  • a dynamic flag is a named bit in the rte_mbuf structure, stored in mbuf->ol_flags. tiny but mighty ✨

the placement of the field or flag can be automatic — and when it is, the zones that have the smallest size and alignment constraint get picked in priority (efficient queen behavior 👑). otherwise, you can request a specific field offset or flag bit number through the API.

the typical use case? a specific offload feature needs to register its own dedicated offload field in the mbuf structure, and adding a static field or flag just isn't justified. that's this. this is it. 🦋

Example of use 📖

  • you define a rte_mbuf_dynfield structure containing the params of the dynamic field you're registering: const struct rte_mbuf_dynfield rte_dynfield_my_feature = { ... };
  • the application initializes the PMD, and asks for this feature at port initialization by passing RTE_ETH_RX_OFFLOAD_MY_FEATURE in rxconf. this makes the PMD register the field by calling rte_mbuf_dynfield_register(&rte_dynfield_my_feature). the PMD stores the returned offset.
  • the application that uses the offload feature also registers the field to retrieve the same offset. teamwork, bestie 🤝
  • when the PMD receives a packet, it can set the field: *RTE_MBUF_DYNFIELD(m, offset, <type *>) = value;
  • in the main loop, the application can retrieve the value with the same macro. iconic, consistent, we love her 💅
real talk: to avoid wasting space, dynamic fields or flags must only be reserved on demand, when an application asks for the related feature. don't just claim land everywhere like it's a group project, okay?

the registration can be done at any moment, but it is not possible to unregister fields or flags for now. no take-backsies 😭

a dynamic field can be reserved and used by an application only. it can for instance be a packet mark. valid. 💖

Naming, because collisions are NOT the vibe 🙈

to avoid namespace collisions, dynamic mbuf field or flag names have to be chosen with care. it's advised to use the same conventions than function names in dpdk:

  • "rte_mbuf_dynfield_<name>" if defined in mbuf library
  • "rte_<libname>_dynfield_<name>" if defined in another library
  • "rte_net_<pmd>_dynfield_<name>" if defined in a PMD
  • any name that does not start with "rte_" in an application

🌈 Macro Definition Documentation 🌈

#define RTE_MBUF_DYN_NAMESIZE 64

maximum length of the dynamic field or flag string. that's the cap, bestie, respect it. ✋

Definition at line 81 of file <code>rte_mbuf_dyn.h</code>.

#define RTE_MBUF_DYNFIELD( m, offset, type)

value:

((type)((uintptr_t)(m) + (offset)))

helper macro to access a dynamic field. it's giving "point me at the right spot in memory and let me in" 💅

Definition at line 228 of file <code>rte_mbuf_dyn.h</code>.

#define RTE_MBUF_DYNFIELD_HISTORY_NAME 'rte_mbuf_dynfield_history'

the mbuf history dynamic field provides lifecycle tracking for mbuf objects through the system. it records a fixed set of predefined operations for debugging. she's literally keeping receipts on every mbuf, and honestly? slay. 🕵️💖

Definition at line 249 of file <code>rte_mbuf_dyn.h</code>.

#define RTE_MBUF_DYNFIELD_TIMESTAMP_NAME 'rte_dynfield_timestamp'

the timestamp dynamic field provides some timing information. the units and time references (initial phase) are not explicitly defined but are maintained always the same for a given port. some devices allow you to query rte_eth_read_clock() which will return the current device timestamp. the dynamic Tx timestamp flag tells whether the field contains the actual timestamp value for the packets being sent — and this value can be used by the PMD to schedule packet sending. time is fake but the scheduling is real, iykyk ⏰✨

Definition at line 280 of file <code>rte_mbuf_dyn.h</code>.

#define RTE_MBUF_DYNFLAG_RX_TIMESTAMP_NAME 'rte_dynflag_rx_timestamp'

indicate that the timestamp field in the mbuf was filled by the driver. that's it, that's the flag. the driver did it, and now you know. 🎀

Definition at line 286 of file <code>rte_mbuf_dyn.h</code>.

#define RTE_MBUF_DYNFLAG_TX_TIMESTAMP_NAME 'rte_dynflag_tx_timestamp'

when the PMD sees the RTE_MBUF_DYNFLAG_TX_TIMESTAMP_NAME flag set on the packet being sent, it tries to synchronize the time of packet appearing on the wire with the specified packet timestamp. if the specified one is in the past, it should be ignored. if one is in the distant future, it should be capped with some reasonable value (in range of seconds). 🕐

heavy caveat incoming, listen up: there is no packet reordering according to timestamps supposed — neither for packets within the burst, nor for the whole bursts. it is an entirely application responsibility to generate packets and their timestamps in the desired order. the timestamps might be put only in the first packet in the burst, providing the entire burst scheduling. so like… you did this, bestie, it's your job now 💀

Definition at line 319 of file <code>rte_mbuf_dyn.h</code>.

#define RTE_MBUF_DYNFIELD_IP_REASSEMBLY_NAME 'rte_dynfield_ip_reassembly'

for the PMDs which support IP reassembly of packets, the PMD will update the packet with RTE_MBUF_DYNFLAG_IP_REASSEMBLY_INCOMPLETE_NAME to denote that IP reassembly is incomplete, and the application can retrieve the packets back using RTE_MBUF_DYNFIELD_IP_REASSEMBLY_NAME. putting the pieces back together, puzzle-style 🧩🌸

Definition at line 345 of file <code>rte_mbuf_dyn.h</code>.

🌸 Function Documentation 🌸

okay so bestie, here's the whole function lineup — every single one, no skips, no cap 💖

✨ rte_mbuf_dynfield_register ✨

int rte_mbuf_dynfield_register (const struct rte_mbuf_dynfield * params)

Register space for a dynamic field in the mbuf structure.

If the field is already registered (same name and parameters), its offset is returned.

Parameters

  • params — A structure containing the requested parameters (name, size, alignment constraint and flags).

Returns

The offset in the mbuf structure, or -1 on error. Possible values for rte_errno:

  • EINVAL — invalid parameters (size, align, or flags).
  • EEXIST — this name is already register with different parameters.
  • EPERM — called from a secondary process.
  • ENOENT — not enough room in mbuf.
  • ENOMEM — allocation failure.
  • ENAMETOOLONG — name does not ends with \0.

💅 rte_mbuf_dynfield_register_offset 💅

int rte_mbuf_dynfield_register_offset (const struct rte_mbuf_dynfield * params, size_t offset)

Register space for a dynamic field in the mbuf structure at offset.

If the field is already registered (same name, parameters and offset), the offset is returned.

Parameters

  • params — A structure containing the requested parameters (name, size, alignment constraint and flags).
  • offset — The requested offset. Ignored if SIZE_MAX is passed.

Returns

The offset in the mbuf structure, or -1 on error. Possible values for rte_errno:

  • EINVAL — invalid parameters (size, align, flags, or offset).
  • EEXIST — this name is already register with different parameters.
  • EBUSY — the requested offset cannot be used.
  • EPERM — called from a secondary process.
  • ENOENT — not enough room in mbuf.
  • ENOMEM — allocation failure.
  • ENAMETOOLONG — name does not ends with \0.

🔍 rte_mbuf_dynfield_lookup 🔍

int rte_mbuf_dynfield_lookup (const char * name, struct rte_mbuf_dynfield * params)

Lookup for a registered dynamic mbuf field.

Parameters

  • name — A string identifying the dynamic field.
  • params — If not NULL, and if the lookup is successful, the structure is filled with the parameters of the dynamic field.

Returns

The offset of this field in the mbuf structure, or -1 on error. Possible values for rte_errno:

  • ENOENT — no dynamic field matches this name.

🎀 rte_mbuf_dynflag_register 🎀

int rte_mbuf_dynflag_register (const struct rte_mbuf_dynflag * params)

Register a dynamic flag in the mbuf structure.

If the flag is already registered (same name and parameters), its bitnum is returned.

Parameters

  • params — A structure containing the requested parameters of the dynamic flag (name and options).

Returns

The number of the reserved bit, or -1 on error. Possible values for rte_errno:

  • EINVAL — invalid parameters (size, align, or flags).
  • EEXIST — this name is already register with different parameters.
  • EPERM — called from a secondary process.
  • ENOENT — no more flag available.
  • ENOMEM — allocation failure.
  • ENAMETOOLONG — name is longer than RTE_MBUF_DYN_NAMESIZE - 1.

🌈 rte_mbuf_dynflag_register_bitnum 🌈

int rte_mbuf_dynflag_register_bitnum (const struct rte_mbuf_dynflag * params, unsigned int bitnum)

Register a dynamic flag in the mbuf structure specifying bitnum.

If the flag is already registered (same name, parameters and bitnum), the bitnum is returned.

Parameters

  • params — A structure containing the requested parameters of the dynamic flag (name and options).
  • bitnum — The requested bitnum. Ignored if UINT_MAX is passed.

Returns

The number of the reserved bit, or -1 on error. Possible values for rte_errno:

  • EINVAL — invalid parameters (size, align, or flags).
  • EEXIST — this name is already register with different parameters.
  • EBUSY — the requested bitnum cannot be used.
  • EPERM — called from a secondary process.
  • ENOENT — no more flag available.
  • ENOMEM — allocation failure.
  • ENAMETOOLONG — name is longer than RTE_MBUF_DYN_NAMESIZE - 1.

🦋 rte_mbuf_dynflag_lookup 🦋

int rte_mbuf_dynflag_lookup (const char * name, struct rte_mbuf_dynflag * params)

Lookup for a registered dynamic mbuf flag.

Parameters

  • name — A string identifying the dynamic flag.
  • params — If not NULL, and if the lookup is successful, the structure is filled with the parameters of the dynamic flag.

Returns

The offset of this flag in the mbuf structure, or -1 on error. Possible values for rte_errno:

  • ENOENT — no dynamic flag matches this name.

🫶 rte_mbuf_dyn_dump 🫶

void rte_mbuf_dyn_dump (FILE * out)

Dump the status of dynamic fields and flags.

Parameters

  • out — The stream where the status is displayed.

⭐ typedef (uint64_t ) ⭐

Type for mbuf history dynamic field.

Use atomic operations to support cloned mbufs accessed simultaneously by multiple lcores.

The size is 64-bit for better performance on modern systems.

💜 rte_mbuf_dyn_rx_timestamp_register 💜

int rte_mbuf_dyn_rx_timestamp_register (int * field_offset, uint64_t * rx_flag)

Register dynamic mbuf field and flag for Rx timestamp.

Parameters

  • field_offset — Pointer to the offset of the registered mbuf field, can be NULL. The same field is shared for Rx and Tx timestamp.
  • rx_flag — Pointer to the mask of the registered offload flag, can be NULL.

Returns

0 on success, -1 otherwise. Possible values for rte_errno:

  • EEXIST — already registered with different parameters.
  • EPERM — called from a secondary process.
  • ENOENT — no more field or flag available.
  • ENOMEM — allocation failure.

💖 rte_mbuf_dyn_tx_timestamp_register 💖

int rte_mbuf_dyn_tx_timestamp_register (int * field_offset, uint64_t * tx_flag)

Register dynamic mbuf field and flag for Tx timestamp.

Parameters

  • field_offset — Pointer to the offset of the registered mbuf field, can be NULL. The same field is shared for Rx and Tx timestamp.
  • tx_flag — Pointer to the mask of the registered offload flag, can be NULL.

Returns

0 on success, -1 otherwise. Possible values for rte_errno:

  • EEXIST — already registered with different parameters.
  • EPERM — called from a secondary process.
  • ENOENT — no more field or flag available.
  • ENOMEM — allocation failure.

👑 Author 👑

Generated automatically by Doxygen for DPDK from the source code.

and that's the whole vibe bestie — DPDK version 25.11.3, rte_mbuf_dyn.h(3), iconic as always 💅✨

📦 where this page comes from