--- name: "rte_mbuf_dynflag_register_bitnum" section: "3" platform: "linux" package: "dpdk-doc" version: "24.11.4-0+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/rte_mbuf_dyn.h" --- # rte\_mbuf\_dynflag\_register\_bitnum(3) Part of [rte\_mbuf\_dyn.h(3)](/rte_mbuf_dyn.h/3.md). ## NAME rte\_mbuf\_dyn.h ## SYNOPSIS `#include `\ `#include `\ ### 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'\ \#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)\ 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 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: - • a dynamic field is a named area in the **rte\_mbuf** structure, with a given size (\>= 1 byte) and alignment constraint. - • a dynamic flag is a named bit in the **rte\_mbuf** structure, stored in mbuf-\>ol\_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: - • A **rte\_mbuf\_dynfield** structure is defined, containing the parameters of the dynamic field to be registered: 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 will make the PMD to 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. - • When the PMD receives a packet, it can set the field: \*RTE\_MBUF\_DYNFIELD(m, offset, \) = value; - • In the main loop, the application can retrieve the value with the same macro. 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: - • - • - • - • any name that does not start with 'rte\_' in an application Definition in file **rte\_mbuf\_dyn.h**. ## Macro Definition Documentation ### #define RTE\_MBUF\_DYN\_NAMESIZE 64 Maximum length of the dynamic field or flag string. Definition at line **80** of file **rte\_mbuf\_dyn.h**. ### #define RTE\_MBUF\_DYNFIELD(m, offset, type) ((type)((uintptr\_t)(m) + (offset))) Helper macro to access to a dynamic field. Definition at line **227** of file **rte\_mbuf\_dyn.h**. ### #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 **262** of file **rte\_mbuf\_dyn.h**. ### #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 **268** of file **rte\_mbuf\_dyn.h**. ### #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 **301** of file **rte\_mbuf\_dyn.h**. ### #define RTE\_MBUF\_DYNFIELD\_IP\_REASSEMBLY\_NAME 'rte\_dynfield\_ip\_reassembly' For the PMDs which support IP reassembly of packets, PMD will update the packet with RTE\_MBUF\_DYNFLAG\_IP\_REASSEMBLY\_INCOMPLETE\_NAME to denote that IP reassembly is incomplete and application can retrieve the packets back using RTE\_MBUF\_DYNFIELD\_IP\_REASSEMBLY\_NAME. Definition at line **327** of file **rte\_mbuf\_dyn.h**. ## Function Documentation ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### void rte\_mbuf\_dyn\_dump (FILE \* out) Dump the status of dynamic fields and flags. **Parameters** *out* The stream where the status is displayed. ### 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. ### 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.