1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright 2019 6WIND S.A.
5 #ifndef _RTE_MBUF_DYN_H_
6 #define _RTE_MBUF_DYN_H_
10 * RTE Mbuf dynamic fields and flags
12 * Many DPDK features require to store data inside the mbuf. As the room
13 * in mbuf structure is limited, it is not possible to have a field for
14 * each feature. Also, changing fields in the mbuf structure can break
17 * This module addresses this issue, by enabling the dynamic
18 * registration of fields or flags:
20 * - a dynamic field is a named area in the rte_mbuf structure, with a
21 * given size (>= 1 byte) and alignment constraint.
22 * - a dynamic flag is a named bit in the rte_mbuf structure, stored
25 * The placement of the field or flag can be automatic, in this case the
26 * zones that have the smallest size and alignment constraint are
27 * selected in priority. Else, a specific field offset or flag bit
28 * number can be requested through the API.
30 * The typical use case is when a specific offload feature requires to
31 * register a dedicated offload field in the mbuf structure, and adding
32 * a static field or flag is not justified.
36 * - A rte_mbuf_dynfield structure is defined, containing the parameters
37 * of the dynamic field to be registered:
38 * const struct rte_mbuf_dynfield rte_dynfield_my_feature = { ... };
39 * - The application initializes the PMD, and asks for this feature
40 * at port initialization by passing DEV_RX_OFFLOAD_MY_FEATURE in
41 * rxconf. This will make the PMD to register the field by calling
42 * rte_mbuf_dynfield_register(&rte_dynfield_my_feature). The PMD
43 * stores the returned offset.
44 * - The application that uses the offload feature also registers
45 * the field to retrieve the same offset.
46 * - When the PMD receives a packet, it can set the field:
47 * *RTE_MBUF_DYNFIELD(m, offset, <type *>) = value;
48 * - In the main loop, the application can retrieve the value with
51 * To avoid wasting space, the dynamic fields or flags must only be
52 * reserved on demand, when an application asks for the related feature.
54 * The registration can be done at any moment, but it is not possible
55 * to unregister fields or flags for now.
57 * A dynamic field can be reserved and used by an application only.
58 * It can for instance be a packet mark.
60 * To avoid namespace collisions, the dynamic mbuf field or flag names
61 * have to be chosen with care. It is advised to use the same
62 * conventions than function names in dpdk:
63 * - "rte_mbuf_dynfield_<name>" if defined in mbuf library
64 * - "rte_<libname>_dynfield_<name>" if defined in another library
65 * - "rte_net_<pmd>_dynfield_<name>" if defined in a PMD
66 * - any name that does not start with "rte_" in an application
69 #include <sys/types.h>
71 * Maximum length of the dynamic field or flag string.
73 #define RTE_MBUF_DYN_NAMESIZE 64
76 * Structure describing the parameters of a mbuf dynamic field.
78 struct rte_mbuf_dynfield {
79 char name[RTE_MBUF_DYN_NAMESIZE]; /**< Name of the field. */
80 size_t size; /**< The number of bytes to reserve. */
81 size_t align; /**< The alignment constraint (power of 2). */
82 unsigned int flags; /**< Reserved for future use, must be 0. */
86 * Structure describing the parameters of a mbuf dynamic flag.
88 struct rte_mbuf_dynflag {
89 char name[RTE_MBUF_DYN_NAMESIZE]; /**< Name of the dynamic flag. */
90 unsigned int flags; /**< Reserved for future use, must be 0. */
94 * Register space for a dynamic field in the mbuf structure.
96 * If the field is already registered (same name and parameters), its
100 * A structure containing the requested parameters (name, size,
101 * alignment constraint and flags).
103 * The offset in the mbuf structure, or -1 on error.
104 * Possible values for rte_errno:
105 * - EINVAL: invalid parameters (size, align, or flags).
106 * - EEXIST: this name is already register with different parameters.
107 * - EPERM: called from a secondary process.
108 * - ENOENT: not enough room in mbuf.
109 * - ENOMEM: allocation failure.
110 * - ENAMETOOLONG: name does not ends with \0.
113 int rte_mbuf_dynfield_register(const struct rte_mbuf_dynfield *params);
116 * Register space for a dynamic field in the mbuf structure at offset.
118 * If the field is already registered (same name, parameters and offset),
119 * the offset is returned.
122 * A structure containing the requested parameters (name, size,
123 * alignment constraint and flags).
125 * The requested offset. Ignored if SIZE_MAX is passed.
127 * The offset in the mbuf structure, or -1 on error.
128 * Possible values for rte_errno:
129 * - EINVAL: invalid parameters (size, align, flags, or offset).
130 * - EEXIST: this name is already register with different parameters.
131 * - EBUSY: the requested offset cannot be used.
132 * - EPERM: called from a secondary process.
133 * - ENOENT: not enough room in mbuf.
134 * - ENOMEM: allocation failure.
135 * - ENAMETOOLONG: name does not ends with \0.
138 int rte_mbuf_dynfield_register_offset(const struct rte_mbuf_dynfield *params,
142 * Lookup for a registered dynamic mbuf field.
145 * A string identifying the dynamic field.
147 * If not NULL, and if the lookup is successful, the structure is
148 * filled with the parameters of the dynamic field.
150 * The offset of this field in the mbuf structure, or -1 on error.
151 * Possible values for rte_errno:
152 * - ENOENT: no dynamic field matches this name.
155 int rte_mbuf_dynfield_lookup(const char *name,
156 struct rte_mbuf_dynfield *params);
159 * Register a dynamic flag in the mbuf structure.
161 * If the flag is already registered (same name and parameters), its
162 * bitnum is returned.
165 * A structure containing the requested parameters of the dynamic
166 * flag (name and options).
168 * The number of the reserved bit, or -1 on error.
169 * Possible values for rte_errno:
170 * - EINVAL: invalid parameters (size, align, or flags).
171 * - EEXIST: this name is already register with different parameters.
172 * - EPERM: called from a secondary process.
173 * - ENOENT: no more flag available.
174 * - ENOMEM: allocation failure.
175 * - ENAMETOOLONG: name is longer than RTE_MBUF_DYN_NAMESIZE - 1.
178 int rte_mbuf_dynflag_register(const struct rte_mbuf_dynflag *params);
181 * Register a dynamic flag in the mbuf structure specifying bitnum.
183 * If the flag is already registered (same name, parameters and bitnum),
184 * the bitnum is returned.
187 * A structure containing the requested parameters of the dynamic
188 * flag (name and options).
190 * The requested bitnum. Ignored if UINT_MAX is passed.
192 * The number of the reserved bit, or -1 on error.
193 * Possible values for rte_errno:
194 * - EINVAL: invalid parameters (size, align, or flags).
195 * - EEXIST: this name is already register with different parameters.
196 * - EBUSY: the requested bitnum cannot be used.
197 * - EPERM: called from a secondary process.
198 * - ENOENT: no more flag available.
199 * - ENOMEM: allocation failure.
200 * - ENAMETOOLONG: name is longer than RTE_MBUF_DYN_NAMESIZE - 1.
203 int rte_mbuf_dynflag_register_bitnum(const struct rte_mbuf_dynflag *params,
204 unsigned int bitnum);
207 * Lookup for a registered dynamic mbuf flag.
210 * A string identifying the dynamic flag.
212 * If not NULL, and if the lookup is successful, the structure is
213 * filled with the parameters of the dynamic flag.
215 * The offset of this flag in the mbuf structure, or -1 on error.
216 * Possible values for rte_errno:
217 * - ENOENT: no dynamic flag matches this name.
220 int rte_mbuf_dynflag_lookup(const char *name,
221 struct rte_mbuf_dynflag *params);
224 * Helper macro to access to a dynamic field.
226 #define RTE_MBUF_DYNFIELD(m, offset, type) ((type)((uintptr_t)(m) + (offset)))
229 * Dump the status of dynamic fields and flags.
232 * The stream where the status is displayed.
235 void rte_mbuf_dyn_dump(FILE *out);
238 * Placeholder for dynamic fields and flags declarations.
239 * This is centralizing point to gather all field names
240 * and parameters together.
244 * The metadata dynamic field provides some extra packet information
245 * to interact with RTE Flow engine. The metadata in sent mbufs can be
246 * used to match on some Flows. The metadata in received mbufs can
247 * provide some feedback from the Flows. The metadata flag tells
248 * whether the field contains actual value to send, or received one.
250 #define RTE_MBUF_DYNFIELD_METADATA_NAME "rte_flow_dynfield_metadata"
251 #define RTE_MBUF_DYNFLAG_METADATA_NAME "rte_flow_dynflag_metadata"
254 * The timestamp dynamic field provides some timing information, the
255 * units and time references (initial phase) are not explicitly defined
256 * but are maintained always the same for a given port. Some devices allow
257 * to query rte_eth_read_clock() that will return the current device
258 * timestamp. The dynamic Tx timestamp flag tells whether the field contains
259 * actual timestamp value for the packets being sent, this value can be
260 * used by PMD to schedule packet sending.
262 #define RTE_MBUF_DYNFIELD_TIMESTAMP_NAME "rte_dynfield_timestamp"
263 typedef uint64_t rte_mbuf_timestamp_t;
266 * Indicate that the timestamp field in the mbuf was filled by the driver.
268 #define RTE_MBUF_DYNFLAG_RX_TIMESTAMP_NAME "rte_dynflag_rx_timestamp"
272 * @b EXPERIMENTAL: this API may change without prior notice.
274 * Register dynamic mbuf field and flag for Rx timestamp.
276 * @param field_offset
277 * Pointer to the offset of the registered mbuf field, can be NULL.
278 * The same field is shared for Rx and Tx timestamp.
280 * Pointer to the mask of the registered offload flag, can be NULL.
282 * 0 on success, -1 otherwise.
283 * Possible values for rte_errno:
284 * - EEXIST: already registered with different parameters.
285 * - EPERM: called from a secondary process.
286 * - ENOENT: no more field or flag available.
287 * - ENOMEM: allocation failure.
290 int rte_mbuf_dyn_rx_timestamp_register(int *field_offset, uint64_t *rx_flag);
293 * When PMD sees the RTE_MBUF_DYNFLAG_TX_TIMESTAMP_NAME flag set on the
294 * packet being sent it tries to synchronize the time of packet appearing
295 * on the wire with the specified packet timestamp. If the specified one
296 * is in the past it should be ignored, if one is in the distant future
297 * it should be capped with some reasonable value (in range of seconds).
299 * There is no any packet reordering according to timestamps is supposed,
300 * neither for packet within the burst, nor for the whole bursts, it is
301 * an entirely application responsibility to generate packets and its
302 * timestamps in desired order. The timestamps might be put only in
303 * the first packet in the burst providing the entire burst scheduling.
305 #define RTE_MBUF_DYNFLAG_TX_TIMESTAMP_NAME "rte_dynflag_tx_timestamp"
309 * @b EXPERIMENTAL: this API may change without prior notice.
311 * Register dynamic mbuf field and flag for Tx timestamp.
313 * @param field_offset
314 * Pointer to the offset of the registered mbuf field, can be NULL.
315 * The same field is shared for Rx and Tx timestamp.
317 * Pointer to the mask of the registered offload flag, can be NULL.
319 * 0 on success, -1 otherwise.
320 * Possible values for rte_errno:
321 * - EEXIST: already registered with different parameters.
322 * - EPERM: called from a secondary process.
323 * - ENOENT: no more field or flag available.
324 * - ENOMEM: allocation failure.
327 int rte_mbuf_dyn_tx_timestamp_register(int *field_offset, uint64_t *tx_flag);