lib/librte_mbuf/rte_mbuf_dyn.h

   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 <stdio.h>
  70 #include <stdint.h>
  71 #include <sys/types.h>
  72
  73 #include <rte_compat.h>
  74
  75 #ifdef __cplusplus
  76 extern "C" {
  77 #endif
  78
  79 /**
  80  * Maximum length of the dynamic field or flag string.
  81  */
  82 #define RTE_MBUF_DYN_NAMESIZE 64
  83
  84 /**
  85  * Structure describing the parameters of a mbuf dynamic field.
  86  */
  87 struct rte_mbuf_dynfield {
  88         char name[RTE_MBUF_DYN_NAMESIZE]; /**< Name of the field. */
  89         size_t size;        /**< The number of bytes to reserve. */
  90         size_t align;       /**< The alignment constraint (power of 2). */
  91         unsigned int flags; /**< Reserved for future use, must be 0. */
  92 };
  93
  94 /**
  95  * Structure describing the parameters of a mbuf dynamic flag.
  96  */
  97 struct rte_mbuf_dynflag {
  98         char name[RTE_MBUF_DYN_NAMESIZE]; /**< Name of the dynamic flag. */
  99         unsigned int flags; /**< Reserved for future use, must be 0. */
 100 };
 101
 102 /**
 103  * Register space for a dynamic field in the mbuf structure.
 104  *
 105  * If the field is already registered (same name and parameters), its
 106  * offset is returned.
 107  *
 108  * @param params
 109  *   A structure containing the requested parameters (name, size,
 110  *   alignment constraint and flags).
 111  * @return
 112  *   The offset in the mbuf structure, or -1 on error.
 113  *   Possible values for rte_errno:
 114  *   - EINVAL: invalid parameters (size, align, or flags).
 115  *   - EEXIST: this name is already register with different parameters.
 116  *   - EPERM: called from a secondary process.
 117  *   - ENOENT: not enough room in mbuf.
 118  *   - ENOMEM: allocation failure.
 119  *   - ENAMETOOLONG: name does not ends with \0.
 120  */
 121 __rte_experimental
 122 int rte_mbuf_dynfield_register(const struct rte_mbuf_dynfield *params);
 123
 124 /**
 125  * Register space for a dynamic field in the mbuf structure at offset.
 126  *
 127  * If the field is already registered (same name, parameters and offset),
 128  * the offset is returned.
 129  *
 130  * @param params
 131  *   A structure containing the requested parameters (name, size,
 132  *   alignment constraint and flags).
 133  * @param offset
 134  *   The requested offset. Ignored if SIZE_MAX is passed.
 135  * @return
 136  *   The offset in the mbuf structure, or -1 on error.
 137  *   Possible values for rte_errno:
 138  *   - EINVAL: invalid parameters (size, align, flags, or offset).
 139  *   - EEXIST: this name is already register with different parameters.
 140  *   - EBUSY: the requested offset cannot be used.
 141  *   - EPERM: called from a secondary process.
 142  *   - ENOENT: not enough room in mbuf.
 143  *   - ENOMEM: allocation failure.
 144  *   - ENAMETOOLONG: name does not ends with \0.
 145  */
 146 __rte_experimental
 147 int rte_mbuf_dynfield_register_offset(const struct rte_mbuf_dynfield *params,
 148                                 size_t offset);
 149
 150 /**
 151  * Lookup for a registered dynamic mbuf field.
 152  *
 153  * @param name
 154  *   A string identifying the dynamic field.
 155  * @param params
 156  *   If not NULL, and if the lookup is successful, the structure is
 157  *   filled with the parameters of the dynamic field.
 158  * @return
 159  *   The offset of this field in the mbuf structure, or -1 on error.
 160  *   Possible values for rte_errno:
 161  *   - ENOENT: no dynamic field matches this name.
 162  */
 163 __rte_experimental
 164 int rte_mbuf_dynfield_lookup(const char *name,
 165                         struct rte_mbuf_dynfield *params);
 166
 167 /**
 168  * Register a dynamic flag in the mbuf structure.
 169  *
 170  * If the flag is already registered (same name and parameters), its
 171  * bitnum is returned.
 172  *
 173  * @param params
 174  *   A structure containing the requested parameters of the dynamic
 175  *   flag (name and options).
 176  * @return
 177  *   The number of the reserved bit, or -1 on error.
 178  *   Possible values for rte_errno:
 179  *   - EINVAL: invalid parameters (size, align, or flags).
 180  *   - EEXIST: this name is already register with different parameters.
 181  *   - EPERM: called from a secondary process.
 182  *   - ENOENT: no more flag available.
 183  *   - ENOMEM: allocation failure.
 184  *   - ENAMETOOLONG: name is longer than RTE_MBUF_DYN_NAMESIZE - 1.
 185  */
 186 __rte_experimental
 187 int rte_mbuf_dynflag_register(const struct rte_mbuf_dynflag *params);
 188
 189 /**
 190  * Register a dynamic flag in the mbuf structure specifying bitnum.
 191  *
 192  * If the flag is already registered (same name, parameters and bitnum),
 193  * the bitnum is returned.
 194  *
 195  * @param params
 196  *   A structure containing the requested parameters of the dynamic
 197  *   flag (name and options).
 198  * @param bitnum
 199  *   The requested bitnum. Ignored if UINT_MAX is passed.
 200  * @return
 201  *   The number of the reserved bit, or -1 on error.
 202  *   Possible values for rte_errno:
 203  *   - EINVAL: invalid parameters (size, align, or flags).
 204  *   - EEXIST: this name is already register with different parameters.
 205  *   - EBUSY: the requested bitnum cannot be used.
 206  *   - EPERM: called from a secondary process.
 207  *   - ENOENT: no more flag available.
 208  *   - ENOMEM: allocation failure.
 209  *   - ENAMETOOLONG: name is longer than RTE_MBUF_DYN_NAMESIZE - 1.
 210  */
 211 __rte_experimental
 212 int rte_mbuf_dynflag_register_bitnum(const struct rte_mbuf_dynflag *params,
 213                                 unsigned int bitnum);
 214
 215 /**
 216  * Lookup for a registered dynamic mbuf flag.
 217  *
 218  * @param name
 219  *   A string identifying the dynamic flag.
 220  * @param params
 221  *   If not NULL, and if the lookup is successful, the structure is
 222  *   filled with the parameters of the dynamic flag.
 223  * @return
 224  *   The offset of this flag in the mbuf structure, or -1 on error.
 225  *   Possible values for rte_errno:
 226  *   - ENOENT: no dynamic flag matches this name.
 227  */
 228 __rte_experimental
 229 int rte_mbuf_dynflag_lookup(const char *name,
 230                         struct rte_mbuf_dynflag *params);
 231
 232 /**
 233  * Helper macro to access to a dynamic field.
 234  */
 235 #define RTE_MBUF_DYNFIELD(m, offset, type) ((type)((uintptr_t)(m) + (offset)))
 236
 237 /**
 238  * Dump the status of dynamic fields and flags.
 239  *
 240  * @param out
 241  *   The stream where the status is displayed.
 242  */
 243 __rte_experimental
 244 void rte_mbuf_dyn_dump(FILE *out);
 245
 246 /*
 247  * Placeholder for dynamic fields and flags declarations.
 248  * This is centralizing point to gather all field names
 249  * and parameters together.
 250  */
 251
 252 /*
 253  * The metadata dynamic field provides some extra packet information
 254  * to interact with RTE Flow engine. The metadata in sent mbufs can be
 255  * used to match on some Flows. The metadata in received mbufs can
 256  * provide some feedback from the Flows. The metadata flag tells
 257  * whether the field contains actual value to send, or received one.
 258  */
 259 #define RTE_MBUF_DYNFIELD_METADATA_NAME "rte_flow_dynfield_metadata"
 260 #define RTE_MBUF_DYNFLAG_METADATA_NAME "rte_flow_dynflag_metadata"
 261
 262 /**
 263  * The timestamp dynamic field provides some timing information, the
 264  * units and time references (initial phase) are not explicitly defined
 265  * but are maintained always the same for a given port. Some devices allow
 266  * to query rte_eth_read_clock() that will return the current device
 267  * timestamp. The dynamic Tx timestamp flag tells whether the field contains
 268  * actual timestamp value for the packets being sent, this value can be
 269  * used by PMD to schedule packet sending.
 270  */
 271 #define RTE_MBUF_DYNFIELD_TIMESTAMP_NAME "rte_dynfield_timestamp"
 272 typedef uint64_t rte_mbuf_timestamp_t;
 273
 274 /**
 275  * Indicate that the timestamp field in the mbuf was filled by the driver.
 276  */
 277 #define RTE_MBUF_DYNFLAG_RX_TIMESTAMP_NAME "rte_dynflag_rx_timestamp"
 278
 279 /**
 280  * @warning
 281  * @b EXPERIMENTAL: this API may change without prior notice.
 282  *
 283  * Register dynamic mbuf field and flag for Rx timestamp.
 284  *
 285  * @param field_offset
 286  *   Pointer to the offset of the registered mbuf field, can be NULL.
 287  *   The same field is shared for Rx and Tx timestamp.
 288  * @param rx_flag
 289  *   Pointer to the mask of the registered offload flag, can be NULL.
 290  * @return
 291  *   0 on success, -1 otherwise.
 292  *   Possible values for rte_errno:
 293  *   - EEXIST: already registered with different parameters.
 294  *   - EPERM: called from a secondary process.
 295  *   - ENOENT: no more field or flag available.
 296  *   - ENOMEM: allocation failure.
 297  */
 298 __rte_experimental
 299 int rte_mbuf_dyn_rx_timestamp_register(int *field_offset, uint64_t *rx_flag);
 300
 301 /**
 302  * When PMD sees the RTE_MBUF_DYNFLAG_TX_TIMESTAMP_NAME flag set on the
 303  * packet being sent it tries to synchronize the time of packet appearing
 304  * on the wire with the specified packet timestamp. If the specified one
 305  * is in the past it should be ignored, if one is in the distant future
 306  * it should be capped with some reasonable value (in range of seconds).
 307  *
 308  * There is no any packet reordering according to timestamps is supposed,
 309  * neither for packet within the burst, nor for the whole bursts, it is
 310  * an entirely application responsibility to generate packets and its
 311  * timestamps in desired order. The timestamps might be put only in
 312  * the first packet in the burst providing the entire burst scheduling.
 313  */
 314 #define RTE_MBUF_DYNFLAG_TX_TIMESTAMP_NAME "rte_dynflag_tx_timestamp"
 315
 316 /**
 317  * @warning
 318  * @b EXPERIMENTAL: this API may change without prior notice.
 319  *
 320  * Register dynamic mbuf field and flag for Tx timestamp.
 321  *
 322  * @param field_offset
 323  *   Pointer to the offset of the registered mbuf field, can be NULL.
 324  *   The same field is shared for Rx and Tx timestamp.
 325  * @param tx_flag
 326  *   Pointer to the mask of the registered offload flag, can be NULL.
 327  * @return
 328  *   0 on success, -1 otherwise.
 329  *   Possible values for rte_errno:
 330  *   - EEXIST: already registered with different parameters.
 331  *   - EPERM: called from a secondary process.
 332  *   - ENOENT: no more field or flag available.
 333  *   - ENOMEM: allocation failure.
 334  */
 335 __rte_experimental
 336 int rte_mbuf_dyn_tx_timestamp_register(int *field_offset, uint64_t *tx_flag);
 337
 338 #ifdef __cplusplus
 339 }
 340 #endif
 341
 342 #endif /* _RTE_MBUF_DYN_H_ */