lib/librte_pipeline/rte_swx_pipeline.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2020 Intel Corporation
   3  */
   4 #ifndef __INCLUDE_RTE_SWX_PIPELINE_H__
   5 #define __INCLUDE_RTE_SWX_PIPELINE_H__
   6
   7 #ifdef __cplusplus
   8 extern "C" {
   9 #endif
  10
  11 /**
  12  * @file
  13  * RTE SWX Pipeline
  14  */
  15
  16 #include <stddef.h>
  17 #include <stdint.h>
  18
  19 #include <rte_compat.h>
  20
  21 #include "rte_swx_port.h"
  22 #include "rte_swx_extern.h"
  23
  24 /** Name size. */
  25 #ifndef RTE_SWX_NAME_SIZE
  26 #define RTE_SWX_NAME_SIZE 64
  27 #endif
  28 /*
  29  * Pipeline setup and operation
  30  */
  31
  32 /** Pipeline opaque data structure. */
  33 struct rte_swx_pipeline;
  34
  35 /**
  36  * Pipeline configure
  37  *
  38  * @param[out] p
  39  *   Pipeline handle. Must point to valid memory. Contains valid pipeline handle
  40  *   when the function returns successfully.
  41  * @param[in] numa_node
  42  *   Non-Uniform Memory Access (NUMA) node.
  43  * @return
  44  *   0 on success or the following error codes otherwise:
  45  *   -EINVAL: Invalid argument;
  46  *   -ENOMEM: Not enough space/cannot allocate memory.
  47  */
  48 __rte_experimental
  49 int
  50 rte_swx_pipeline_config(struct rte_swx_pipeline **p,
  51                         int numa_node);
  52
  53 /*
  54  * Pipeline input ports
  55  */
  56
  57 /**
  58  * Pipeline input port type register
  59  *
  60  * @param[in] p
  61  *   Pipeline handle.
  62  * @param[in] name
  63  *   Input port type name.
  64  * @param[in] ops
  65  *   Input port type operations.
  66  * @return
  67  *   0 on success or the following error codes otherwise:
  68  *   -EINVAL: Invalid argument;
  69  *   -ENOMEM: Not enough space/cannot allocate memory;
  70  *   -EEXIST: Input port type with this name already exists.
  71  */
  72 __rte_experimental
  73 int
  74 rte_swx_pipeline_port_in_type_register(struct rte_swx_pipeline *p,
  75                                        const char *name,
  76                                        struct rte_swx_port_in_ops *ops);
  77
  78 /**
  79  * Pipeline input port configure
  80  *
  81  * @param[in] p
  82  *   Pipeline handle.
  83  * @param[in] port_id
  84  *   Input port ID.
  85  * @param[in] port_type_name
  86  *   Existing input port type name.
  87  * @param[in] args
  88  *   Input port creation arguments.
  89  * @return
  90  *   0 on success or the following error codes otherwise:
  91  *   -EINVAL: Invalid argument;
  92  *   -ENOMEM: Not enough space/cannot allocate memory;
  93  *   -ENODEV: Input port object creation error.
  94  */
  95 __rte_experimental
  96 int
  97 rte_swx_pipeline_port_in_config(struct rte_swx_pipeline *p,
  98                                 uint32_t port_id,
  99                                 const char *port_type_name,
 100                                 void *args);
 101
 102 /*
 103  * Pipeline output ports
 104  */
 105
 106 /**
 107  * Pipeline output port type register
 108  *
 109  * @param[in] p
 110  *   Pipeline handle.
 111  * @param[in] name
 112  *   Output port type name.
 113  * @param[in] ops
 114  *   Output port type operations.
 115  * @return
 116  *   0 on success or the following error codes otherwise:
 117  *   -EINVAL: Invalid argument;
 118  *   -ENOMEM: Not enough space/cannot allocate memory;
 119  *   -EEXIST: Output port type with this name already exists.
 120  */
 121 __rte_experimental
 122 int
 123 rte_swx_pipeline_port_out_type_register(struct rte_swx_pipeline *p,
 124                                         const char *name,
 125                                         struct rte_swx_port_out_ops *ops);
 126
 127 /**
 128  * Pipeline output port configure
 129  *
 130  * @param[in] p
 131  *   Pipeline handle.
 132  * @param[in] port_id
 133  *   Output port ID.
 134  * @param[in] port_type_name
 135  *   Existing output port type name.
 136  * @param[in] args
 137  *   Output port creation arguments.
 138  * @return
 139  *   0 on success or the following error codes otherwise:
 140  *   -EINVAL: Invalid argument;
 141  *   -ENOMEM: Not enough space/cannot allocate memory;
 142  *   -ENODEV: Output port object creation error.
 143  */
 144 __rte_experimental
 145 int
 146 rte_swx_pipeline_port_out_config(struct rte_swx_pipeline *p,
 147                                  uint32_t port_id,
 148                                  const char *port_type_name,
 149                                  void *args);
 150
 151 /*
 152  * Extern objects and functions
 153  */
 154
 155 /**
 156  * Pipeline extern type register
 157  *
 158  * @param[in] p
 159  *   Pipeline handle.
 160  * @param[in] name
 161  *   Extern type name.
 162  * @param[in] mailbox_struct_type_name
 163  *   Name of existing struct type used to define the mailbox size and layout for
 164  *   the extern objects that are instances of this type. Each extern object gets
 165  *   its own mailbox, which is used to pass the input arguments to the member
 166  *   functions and retrieve the output results.
 167  * @param[in] constructor
 168  *   Function used to create the extern objects that are instances of this type.
 169  * @param[in] destructor
 170  *   Function used to free the extern objects that are instances of  this type.
 171  * @return
 172  *   0 on success or the following error codes otherwise:
 173  *   -EINVAL: Invalid argument;
 174  *   -ENOMEM: Not enough space/cannot allocate memory;
 175  *   -EEXIST: Extern type with this name already exists.
 176  */
 177 __rte_experimental
 178 int
 179 rte_swx_pipeline_extern_type_register(struct rte_swx_pipeline *p,
 180         const char *name,
 181         const char *mailbox_struct_type_name,
 182         rte_swx_extern_type_constructor_t constructor,
 183         rte_swx_extern_type_destructor_t destructor);
 184
 185 /**
 186  * Pipeline extern type member function register
 187  *
 188  * @param[in] p
 189  *   Pipeline handle.
 190  * @param[in] extern_type_name
 191  *   Existing extern type name.
 192  * @param[in] name
 193  *   Name for the new member function to be added to the extern type.
 194  * @param[in] member_func
 195  *   The new member function.
 196  * @return
 197  *   0 on success or the following error codes otherwise:
 198  *   -EINVAL: Invalid argument;
 199  *   -ENOMEM: Not enough space/cannot allocate memory;
 200  *   -EEXIST: Member function with this name already exists for this type;
 201  *   -ENOSPC: Maximum number of member functions reached for this type.
 202  */
 203 __rte_experimental
 204 int
 205 rte_swx_pipeline_extern_type_member_func_register(struct rte_swx_pipeline *p,
 206         const char *extern_type_name,
 207         const char *name,
 208         rte_swx_extern_type_member_func_t member_func);
 209
 210 /**
 211  * Pipeline extern object configure
 212  *
 213  * Instantiate a given extern type to create new extern object.
 214  *
 215  * @param[in] p
 216  *   Pipeline handle.
 217  * @param[in] extern_type_name
 218  *   Existing extern type name.
 219  * @param[in] name
 220  *   Name for the new object instantiating the extern type.
 221  * @param[in] args
 222  *   Extern object constructor arguments.
 223  * @return
 224  *   0 on success or the following error codes otherwise:
 225  *   -EINVAL: Invalid argument;
 226  *   -ENOMEM: Not enough space/cannot allocate memory;
 227  *   -EEXIST: Extern object with this name already exists;
 228  *   -ENODEV: Extern object constructor error.
 229  */
 230 __rte_experimental
 231 int
 232 rte_swx_pipeline_extern_object_config(struct rte_swx_pipeline *p,
 233                                       const char *extern_type_name,
 234                                       const char *name,
 235                                       const char *args);
 236
 237 /**
 238  * Pipeline extern function register
 239  *
 240  * @param[in] p
 241  *   Pipeline handle.
 242  * @param[in] name
 243  *   Extern function name.
 244  * @param[in] mailbox_struct_type_name
 245  *   Name of existing struct type used to define the mailbox size and layout for
 246  *   this extern function. The mailbox is used to pass the input arguments to
 247  *   the extern function and retrieve the output results.
 248  * @param[in] func
 249  *   The extern function.
 250  * @return
 251  *   0 on success or the following error codes otherwise:
 252  *   -EINVAL: Invalid argument;
 253  *   -ENOMEM: Not enough space/cannot allocate memory;
 254  *   -EEXIST: Extern function with this name already exists.
 255  */
 256 __rte_experimental
 257 int
 258 rte_swx_pipeline_extern_func_register(struct rte_swx_pipeline *p,
 259                                       const char *name,
 260                                       const char *mailbox_struct_type_name,
 261                                       rte_swx_extern_func_t func);
 262
 263 /*
 264  * Packet headers and meta-data
 265  */
 266
 267 /** Structure (struct) field. */
 268 struct rte_swx_field_params {
 269         /** Struct field name. */
 270         const char *name;
 271
 272         /** Struct field size (in bits).
 273          * Restriction: All struct fields must be a multiple of 8 bits.
 274          * Restriction: All struct fields must be no greater than 64 bits.
 275          */
 276         uint32_t n_bits;
 277 };
 278
 279 /**
 280  * Pipeline struct type register
 281  *
 282  * Structs are used extensively in many part of the pipeline to define the size
 283  * and layout of a specific memory piece such as: headers, meta-data, action
 284  * data stored in a table entry, mailboxes for extern objects and functions.
 285  * Similar to C language structs, they are a well defined sequence of fields,
 286  * with each field having a unique name and a constant size.
 287  *
 288  * @param[in] p
 289  *   Pipeline handle.
 290  * @param[in] name
 291  *   Struct type name.
 292  * @param[in] fields
 293  *   The sequence of struct fields.
 294  * @param[in] n_fields
 295  *   The number of struct fields.
 296  * @return
 297  *   0 on success or the following error codes otherwise:
 298  *   -EINVAL: Invalid argument;
 299  *   -ENOMEM: Not enough space/cannot allocate memory;
 300  *   -EEXIST: Struct type with this name already exists.
 301  */
 302 __rte_experimental
 303 int
 304 rte_swx_pipeline_struct_type_register(struct rte_swx_pipeline *p,
 305                                       const char *name,
 306                                       struct rte_swx_field_params *fields,
 307                                       uint32_t n_fields);
 308
 309 /**
 310  * Pipeline packet header register
 311  *
 312  * @param[in] p
 313  *   Pipeline handle.
 314  * @param[in] name
 315  *   Header name.
 316  * @param[in] struct_type_name
 317  *   The struct type instantiated by this packet header.
 318  * @return
 319  *   0 on success or the following error codes otherwise:
 320  *   -EINVAL: Invalid argument;
 321  *   -ENOMEM: Not enough space/cannot allocate memory;
 322  *   -EEXIST: Header with this name already exists;
 323  *   -ENOSPC: Maximum number of headers reached for the pipeline.
 324  */
 325 __rte_experimental
 326 int
 327 rte_swx_pipeline_packet_header_register(struct rte_swx_pipeline *p,
 328                                         const char *name,
 329                                         const char *struct_type_name);
 330
 331 /**
 332  * Pipeline packet meta-data register
 333  *
 334  * @param[in] p
 335  *   Pipeline handle.
 336  * @param[in] struct_type_name
 337  *   The struct type instantiated by the packet meta-data.
 338  * @return
 339  *   0 on success or the following error codes otherwise:
 340  *   -EINVAL: Invalid argument.
 341  */
 342 __rte_experimental
 343 int
 344 rte_swx_pipeline_packet_metadata_register(struct rte_swx_pipeline *p,
 345                                           const char *struct_type_name);
 346
 347 /*
 348  * Pipeline action
 349  */
 350
 351 /**
 352  * Pipeline action configure
 353  *
 354  * @param[in] p
 355  *   Pipeline handle.
 356  * @param[in] name
 357  *   Action name.
 358  * @param[in] args_struct_type_name
 359  *   The struct type instantiated by the action data. The action data represent
 360  *   the action arguments that are stored in the table entry together with the
 361  *   action ID. Set to NULL when the action does not have any arguments.
 362  * @param[in] instructions
 363  *   Action instructions.
 364  * @param[in] n_instructions
 365  *   Number of action instructions.
 366  * @return
 367  *   0 on success or the following error codes otherwise:
 368  *   -EINVAL: Invalid argument;
 369  *   -ENOMEM: Not enough space/cannot allocate memory;
 370  *   -EEXIST: Action with this name already exists.
 371  */
 372 __rte_experimental
 373 int
 374 rte_swx_pipeline_action_config(struct rte_swx_pipeline *p,
 375                                const char *name,
 376                                const char *args_struct_type_name,
 377                                const char **instructions,
 378                                uint32_t n_instructions);
 379
 380 /**
 381  * Pipeline build
 382  *
 383  * Once called, the pipeline build operation marks the end of pipeline
 384  * configuration. At this point, all the internal data structures needed to run
 385  * the pipeline are built.
 386  *
 387  * @param[in] p
 388  *   Pipeline handle.
 389  * @return
 390  *   0 on success or the following error codes otherwise:
 391  *   -EINVAL: Invalid argument;
 392  *   -ENOMEM: Not enough space/cannot allocate memory;
 393  *   -EEXIST: Pipeline was already built successfully.
 394  */
 395 __rte_experimental
 396 int
 397 rte_swx_pipeline_build(struct rte_swx_pipeline *p);
 398
 399 /**
 400  * Pipeline free
 401  *
 402  * @param[in] p
 403  *   Pipeline handle.
 404  */
 405 __rte_experimental
 406 void
 407 rte_swx_pipeline_free(struct rte_swx_pipeline *p);
 408
 409 #ifdef __cplusplus
 410 }
 411 #endif
 412
 413 #endif