DPDK  20.11.3
Data Structures | Macros | Functions
rte_mbuf_dyn.h File Reference
#include <stdio.h>
#include <stdint.h>
#include <sys/types.h>
#include <rte_compat.h>

Go to the source code of this file.

Data Structures

struct  rte_mbuf_dynfield
 
struct  rte_mbuf_dynflag
 

Macros

#define RTE_MBUF_DYN_NAMESIZE   64
 
#define RTE_MBUF_DYNFIELD(m, offset, type)   ((type)((uintptr_t)(m) + (offset)))
 
#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"
 

Functions

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

Detailed Description

RTE Mbuf dynamic fields and flags

Many DPDK features require to store data inside the mbuf. As the room in mbuf structure is limited, it is not possible to have a field for each feature. Also, changing fields in the mbuf structure can break the API or ABI.

This module addresses this issue, by enabling the dynamic registration of fields or flags:

The placement of the field or flag can be automatic, in this case the zones that have the smallest size and alignment constraint are selected in priority. Else, a specific field offset or flag bit number can be requested through the API.

The typical use case is when a specific offload feature requires to register a dedicated offload field in the mbuf structure, and adding a static field or flag is not justified.

Example of use:

To avoid wasting space, the dynamic fields or flags must only be reserved on demand, when an application asks for the related feature.

The registration can be done at any moment, but it is not possible to unregister fields or flags for now.

A dynamic field can be reserved and used by an application only. It can for instance be a packet mark.

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

Definition in file rte_mbuf_dyn.h.

Macro Definition Documentation

◆ RTE_MBUF_DYN_NAMESIZE

#define RTE_MBUF_DYN_NAMESIZE   64

Maximum length of the dynamic field or flag string.

Definition at line 82 of file rte_mbuf_dyn.h.

◆ RTE_MBUF_DYNFIELD

#define RTE_MBUF_DYNFIELD (   m,
  offset,
  type 
)    ((type)((uintptr_t)(m) + (offset)))

Helper macro to access to a dynamic field.

Examples:
examples/bbdev_app/main.c, and examples/rxtx_callbacks/main.c.

Definition at line 235 of file rte_mbuf_dyn.h.

◆ RTE_MBUF_DYNFIELD_TIMESTAMP_NAME

#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 to query rte_eth_read_clock() that will return the current device timestamp. The dynamic Tx timestamp flag tells whether the field contains actual timestamp value for the packets being sent, this value can be used by PMD to schedule packet sending.

Definition at line 271 of file rte_mbuf_dyn.h.

◆ RTE_MBUF_DYNFLAG_RX_TIMESTAMP_NAME

#define RTE_MBUF_DYNFLAG_RX_TIMESTAMP_NAME   "rte_dynflag_rx_timestamp"

Indicate that the timestamp field in the mbuf was filled by the driver.

Definition at line 277 of file rte_mbuf_dyn.h.

◆ RTE_MBUF_DYNFLAG_TX_TIMESTAMP_NAME

#define RTE_MBUF_DYNFLAG_TX_TIMESTAMP_NAME   "rte_dynflag_tx_timestamp"

When 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).

There is no any packet reordering according to timestamps is supposed, neither for packet within the burst, nor for the whole bursts, it is an entirely application responsibility to generate packets and its timestamps in desired order. The timestamps might be put only in the first packet in the burst providing the entire burst scheduling.

Definition at line 314 of file rte_mbuf_dyn.h.

Function Documentation

◆ rte_mbuf_dynfield_register()

__rte_experimental 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
paramsA 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.
Examples:
examples/bbdev_app/main.c, and examples/rxtx_callbacks/main.c.

◆ rte_mbuf_dynfield_register_offset()

__rte_experimental 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
paramsA structure containing the requested parameters (name, size, alignment constraint and flags).
offsetThe 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()

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

Lookup for a registered dynamic mbuf field.

Parameters
nameA string identifying the dynamic field.
paramsIf 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()

__rte_experimental 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
paramsA 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()

__rte_experimental 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
paramsA structure containing the requested parameters of the dynamic flag (name and options).
bitnumThe 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()

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

Lookup for a registered dynamic mbuf flag.

Parameters
nameA string identifying the dynamic flag.
paramsIf 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()

__rte_experimental void rte_mbuf_dyn_dump ( FILE *  out)

Dump the status of dynamic fields and flags.

Parameters
outThe stream where the status is displayed.

◆ rte_mbuf_dyn_rx_timestamp_register()

__rte_experimental int rte_mbuf_dyn_rx_timestamp_register ( int *  field_offset,
uint64_t *  rx_flag 
)
Warning
EXPERIMENTAL: this API may change without prior notice.

Register dynamic mbuf field and flag for Rx timestamp.

Parameters
field_offsetPointer to the offset of the registered mbuf field, can be NULL. The same field is shared for Rx and Tx timestamp.
rx_flagPointer 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.
Examples:
examples/rxtx_callbacks/main.c.

◆ rte_mbuf_dyn_tx_timestamp_register()

__rte_experimental int rte_mbuf_dyn_tx_timestamp_register ( int *  field_offset,
uint64_t *  tx_flag 
)
Warning
EXPERIMENTAL: this API may change without prior notice.

Register dynamic mbuf field and flag for Tx timestamp.

Parameters
field_offsetPointer to the offset of the registered mbuf field, can be NULL. The same field is shared for Rx and Tx timestamp.
tx_flagPointer 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.