1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright 2019 6WIND S.A. 3 */ 4 5 #ifndef _RTE_MBUF_DYN_H_ 6 #define _RTE_MBUF_DYN_H_ 7 8 /** 9 * @file 10 * RTE Mbuf dynamic fields and flags 11 * 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 15 * the API or ABI. 16 * 17 * This module addresses this issue, by enabling the dynamic 18 * registration of fields or flags: 19 * 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 23 * in mbuf->ol_flags. 24 * 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. 29 * 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. 33 * 34 * Example of use: 35 * 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 49 * the same macro. 50 * 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. 53 * 54 * The registration can be done at any moment, but it is not possible 55 * to unregister fields or flags for now. 56 * 57 * A dynamic field can be reserved and used by an application only. 58 * It can for instance be a packet mark. 59 * 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 67 */ 68 69 #include <sys/types.h> 70 /** 71 * Maximum length of the dynamic field or flag string. 72 */ 73 #define RTE_MBUF_DYN_NAMESIZE 64 74 75 /** 76 * Structure describing the parameters of a mbuf dynamic field. 77 */ 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. */ 83 }; 84 85 /** 86 * Structure describing the parameters of a mbuf dynamic flag. 87 */ 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. */ 91 }; 92 93 /** 94 * Register space for a dynamic field in the mbuf structure. 95 * 96 * If the field is already registered (same name and parameters), its 97 * offset is returned. 98 * 99 * @param params 100 * A structure containing the requested parameters (name, size, 101 * alignment constraint and flags). 102 * @return 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. 111 */ 112 __rte_experimental 113 int rte_mbuf_dynfield_register(const struct rte_mbuf_dynfield *params); 114 115 /** 116 * Register space for a dynamic field in the mbuf structure at offset. 117 * 118 * If the field is already registered (same name, parameters and offset), 119 * the offset is returned. 120 * 121 * @param params 122 * A structure containing the requested parameters (name, size, 123 * alignment constraint and flags). 124 * @param offset 125 * The requested offset. Ignored if SIZE_MAX is passed. 126 * @return 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. 136 */ 137 __rte_experimental 138 int rte_mbuf_dynfield_register_offset(const struct rte_mbuf_dynfield *params, 139 size_t offset); 140 141 /** 142 * Lookup for a registered dynamic mbuf field. 143 * 144 * @param name 145 * A string identifying the dynamic field. 146 * @param params 147 * If not NULL, and if the lookup is successful, the structure is 148 * filled with the parameters of the dynamic field. 149 * @return 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. 153 */ 154 __rte_experimental 155 int rte_mbuf_dynfield_lookup(const char *name, 156 struct rte_mbuf_dynfield *params); 157 158 /** 159 * Register a dynamic flag in the mbuf structure. 160 * 161 * If the flag is already registered (same name and parameters), its 162 * bitnum is returned. 163 * 164 * @param params 165 * A structure containing the requested parameters of the dynamic 166 * flag (name and options). 167 * @return 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. 176 */ 177 __rte_experimental 178 int rte_mbuf_dynflag_register(const struct rte_mbuf_dynflag *params); 179 180 /** 181 * Register a dynamic flag in the mbuf structure specifying bitnum. 182 * 183 * If the flag is already registered (same name, parameters and bitnum), 184 * the bitnum is returned. 185 * 186 * @param params 187 * A structure containing the requested parameters of the dynamic 188 * flag (name and options). 189 * @param bitnum 190 * The requested bitnum. Ignored if UINT_MAX is passed. 191 * @return 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. 201 */ 202 __rte_experimental 203 int rte_mbuf_dynflag_register_bitnum(const struct rte_mbuf_dynflag *params, 204 unsigned int bitnum); 205 206 /** 207 * Lookup for a registered dynamic mbuf flag. 208 * 209 * @param name 210 * A string identifying the dynamic flag. 211 * @param params 212 * If not NULL, and if the lookup is successful, the structure is 213 * filled with the parameters of the dynamic flag. 214 * @return 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. 218 */ 219 __rte_experimental 220 int rte_mbuf_dynflag_lookup(const char *name, 221 struct rte_mbuf_dynflag *params); 222 223 /** 224 * Helper macro to access to a dynamic field. 225 */ 226 #define RTE_MBUF_DYNFIELD(m, offset, type) ((type)((uintptr_t)(m) + (offset))) 227 228 /** 229 * Dump the status of dynamic fields and flags. 230 * 231 * @param out 232 * The stream where the status is displayed. 233 */ 234 __rte_experimental 235 void rte_mbuf_dyn_dump(FILE *out); 236 237 /* 238 * Placeholder for dynamic fields and flags declarations. 239 * This is centralizing point to gather all field names 240 * and parameters together. 241 */ 242 243 /* 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. 249 */ 250 #define RTE_MBUF_DYNFIELD_METADATA_NAME "rte_flow_dynfield_metadata" 251 #define RTE_MBUF_DYNFLAG_METADATA_NAME "rte_flow_dynflag_metadata" 252 253 /** 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. 261 */ 262 #define RTE_MBUF_DYNFIELD_TIMESTAMP_NAME "rte_dynfield_timestamp" 263 typedef uint64_t rte_mbuf_timestamp_t; 264 265 /** 266 * Indicate that the timestamp field in the mbuf was filled by the driver. 267 */ 268 #define RTE_MBUF_DYNFLAG_RX_TIMESTAMP_NAME "rte_dynflag_rx_timestamp" 269 270 /** 271 * @warning 272 * @b EXPERIMENTAL: this API may change without prior notice. 273 * 274 * Register dynamic mbuf field and flag for Rx timestamp. 275 * 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. 279 * @param rx_flag 280 * Pointer to the mask of the registered offload flag, can be NULL. 281 * @return 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. 288 */ 289 __rte_experimental 290 int rte_mbuf_dyn_rx_timestamp_register(int *field_offset, uint64_t *rx_flag); 291 292 /** 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). 298 * 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. 304 */ 305 #define RTE_MBUF_DYNFLAG_TX_TIMESTAMP_NAME "rte_dynflag_tx_timestamp" 306 307 /** 308 * @warning 309 * @b EXPERIMENTAL: this API may change without prior notice. 310 * 311 * Register dynamic mbuf field and flag for Tx timestamp. 312 * 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. 316 * @param tx_flag 317 * Pointer to the mask of the registered offload flag, can be NULL. 318 * @return 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. 325 */ 326 __rte_experimental 327 int rte_mbuf_dyn_tx_timestamp_register(int *field_offset, uint64_t *tx_flag); 328 329 #endif 330