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>
76 * Maximum length of the dynamic field or flag string.
78 #define RTE_MBUF_DYN_NAMESIZE 64
81 * Structure describing the parameters of a mbuf dynamic field.
83 struct rte_mbuf_dynfield {
84 char name[RTE_MBUF_DYN_NAMESIZE]; /**< Name of the field. */
85 size_t size; /**< The number of bytes to reserve. */
86 size_t align; /**< The alignment constraint (power of 2). */
87 unsigned int flags; /**< Reserved for future use, must be 0. */
91 * Structure describing the parameters of a mbuf dynamic flag.
93 struct rte_mbuf_dynflag {
94 char name[RTE_MBUF_DYN_NAMESIZE]; /**< Name of the dynamic flag. */
95 unsigned int flags; /**< Reserved for future use, must be 0. */
99 * Register space for a dynamic field in the mbuf structure.
101 * If the field is already registered (same name and parameters), its
102 * offset is returned.
105 * A structure containing the requested parameters (name, size,
106 * alignment constraint and flags).
108 * The offset in the mbuf structure, or -1 on error.
109 * Possible values for rte_errno:
110 * - EINVAL: invalid parameters (size, align, or flags).
111 * - EEXIST: this name is already register with different parameters.
112 * - EPERM: called from a secondary process.
113 * - ENOENT: not enough room in mbuf.
114 * - ENOMEM: allocation failure.
115 * - ENAMETOOLONG: name does not ends with \0.
118 int rte_mbuf_dynfield_register(const struct rte_mbuf_dynfield *params);
121 * Register space for a dynamic field in the mbuf structure at offset.
123 * If the field is already registered (same name, parameters and offset),
124 * the offset is returned.
127 * A structure containing the requested parameters (name, size,
128 * alignment constraint and flags).
130 * The requested offset. Ignored if SIZE_MAX is passed.
132 * The offset in the mbuf structure, or -1 on error.
133 * Possible values for rte_errno:
134 * - EINVAL: invalid parameters (size, align, flags, or offset).
135 * - EEXIST: this name is already register with different parameters.
136 * - EBUSY: the requested offset cannot be used.
137 * - EPERM: called from a secondary process.
138 * - ENOENT: not enough room in mbuf.
139 * - ENOMEM: allocation failure.
140 * - ENAMETOOLONG: name does not ends with \0.
143 int rte_mbuf_dynfield_register_offset(const struct rte_mbuf_dynfield *params,
147 * Lookup for a registered dynamic mbuf field.
150 * A string identifying the dynamic field.
152 * If not NULL, and if the lookup is successful, the structure is
153 * filled with the parameters of the dynamic field.
155 * The offset of this field in the mbuf structure, or -1 on error.
156 * Possible values for rte_errno:
157 * - ENOENT: no dynamic field matches this name.
160 int rte_mbuf_dynfield_lookup(const char *name,
161 struct rte_mbuf_dynfield *params);
164 * Register a dynamic flag in the mbuf structure.
166 * If the flag is already registered (same name and parameters), its
167 * bitnum is returned.
170 * A structure containing the requested parameters of the dynamic
171 * flag (name and options).
173 * The number of the reserved bit, or -1 on error.
174 * Possible values for rte_errno:
175 * - EINVAL: invalid parameters (size, align, or flags).
176 * - EEXIST: this name is already register with different parameters.
177 * - EPERM: called from a secondary process.
178 * - ENOENT: no more flag available.
179 * - ENOMEM: allocation failure.
180 * - ENAMETOOLONG: name is longer than RTE_MBUF_DYN_NAMESIZE - 1.
183 int rte_mbuf_dynflag_register(const struct rte_mbuf_dynflag *params);
186 * Register a dynamic flag in the mbuf structure specifying bitnum.
188 * If the flag is already registered (same name, parameters and bitnum),
189 * the bitnum is returned.
192 * A structure containing the requested parameters of the dynamic
193 * flag (name and options).
195 * The requested bitnum. Ignored if UINT_MAX is passed.
197 * The number of the reserved bit, or -1 on error.
198 * Possible values for rte_errno:
199 * - EINVAL: invalid parameters (size, align, or flags).
200 * - EEXIST: this name is already register with different parameters.
201 * - EBUSY: the requested bitnum cannot be used.
202 * - EPERM: called from a secondary process.
203 * - ENOENT: no more flag available.
204 * - ENOMEM: allocation failure.
205 * - ENAMETOOLONG: name is longer than RTE_MBUF_DYN_NAMESIZE - 1.
208 int rte_mbuf_dynflag_register_bitnum(const struct rte_mbuf_dynflag *params,
209 unsigned int bitnum);
212 * Lookup for a registered dynamic mbuf flag.
215 * A string identifying the dynamic flag.
217 * If not NULL, and if the lookup is successful, the structure is
218 * filled with the parameters of the dynamic flag.
220 * The offset of this flag in the mbuf structure, or -1 on error.
221 * Possible values for rte_errno:
222 * - ENOENT: no dynamic flag matches this name.
225 int rte_mbuf_dynflag_lookup(const char *name,
226 struct rte_mbuf_dynflag *params);
229 * Helper macro to access to a dynamic field.
231 #define RTE_MBUF_DYNFIELD(m, offset, type) ((type)((uintptr_t)(m) + (offset)))
234 * Dump the status of dynamic fields and flags.
237 * The stream where the status is displayed.
240 void rte_mbuf_dyn_dump(FILE *out);
243 * Placeholder for dynamic fields and flags declarations.
244 * This is centralizing point to gather all field names
245 * and parameters together.
249 * The metadata dynamic field provides some extra packet information
250 * to interact with RTE Flow engine. The metadata in sent mbufs can be
251 * used to match on some Flows. The metadata in received mbufs can
252 * provide some feedback from the Flows. The metadata flag tells
253 * whether the field contains actual value to send, or received one.
255 #define RTE_MBUF_DYNFIELD_METADATA_NAME "rte_flow_dynfield_metadata"
256 #define RTE_MBUF_DYNFLAG_METADATA_NAME "rte_flow_dynflag_metadata"
259 * The timestamp dynamic field provides some timing information, the
260 * units and time references (initial phase) are not explicitly defined
261 * but are maintained always the same for a given port. Some devices allow
262 * to query rte_eth_read_clock() that will return the current device
263 * timestamp. The dynamic Tx timestamp flag tells whether the field contains
264 * actual timestamp value for the packets being sent, this value can be
265 * used by PMD to schedule packet sending.
267 #define RTE_MBUF_DYNFIELD_TIMESTAMP_NAME "rte_dynfield_timestamp"
268 typedef uint64_t rte_mbuf_timestamp_t;
271 * Indicate that the timestamp field in the mbuf was filled by the driver.
273 #define RTE_MBUF_DYNFLAG_RX_TIMESTAMP_NAME "rte_dynflag_rx_timestamp"
277 * @b EXPERIMENTAL: this API may change without prior notice.
279 * Register dynamic mbuf field and flag for Rx timestamp.
281 * @param field_offset
282 * Pointer to the offset of the registered mbuf field, can be NULL.
283 * The same field is shared for Rx and Tx timestamp.
285 * Pointer to the mask of the registered offload flag, can be NULL.
287 * 0 on success, -1 otherwise.
288 * Possible values for rte_errno:
289 * - EEXIST: already registered with different parameters.
290 * - EPERM: called from a secondary process.
291 * - ENOENT: no more field or flag available.
292 * - ENOMEM: allocation failure.
295 int rte_mbuf_dyn_rx_timestamp_register(int *field_offset, uint64_t *rx_flag);
298 * When PMD sees the RTE_MBUF_DYNFLAG_TX_TIMESTAMP_NAME flag set on the
299 * packet being sent it tries to synchronize the time of packet appearing
300 * on the wire with the specified packet timestamp. If the specified one
301 * is in the past it should be ignored, if one is in the distant future
302 * it should be capped with some reasonable value (in range of seconds).
304 * There is no any packet reordering according to timestamps is supposed,
305 * neither for packet within the burst, nor for the whole bursts, it is
306 * an entirely application responsibility to generate packets and its
307 * timestamps in desired order. The timestamps might be put only in
308 * the first packet in the burst providing the entire burst scheduling.
310 #define RTE_MBUF_DYNFLAG_TX_TIMESTAMP_NAME "rte_dynflag_tx_timestamp"
314 * @b EXPERIMENTAL: this API may change without prior notice.
316 * Register dynamic mbuf field and flag for Tx timestamp.
318 * @param field_offset
319 * Pointer to the offset of the registered mbuf field, can be NULL.
320 * The same field is shared for Rx and Tx timestamp.
322 * Pointer to the mask of the registered offload flag, can be NULL.
324 * 0 on success, -1 otherwise.
325 * Possible values for rte_errno:
326 * - EEXIST: already registered with different parameters.
327 * - EPERM: called from a secondary process.
328 * - ENOENT: no more field or flag available.
329 * - ENOMEM: allocation failure.
332 int rte_mbuf_dyn_tx_timestamp_register(int *field_offset, uint64_t *tx_flag);
338 #endif /* _RTE_MBUF_DYN_H_ */