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_table.h"
  23 #include "rte_swx_extern.h"
  24
  25 /** Name size. */
  26 #ifndef RTE_SWX_NAME_SIZE
  27 #define RTE_SWX_NAME_SIZE 64
  28 #endif
  29 /*
  30  * Pipeline setup and operation
  31  */
  32
  33 /** Pipeline opaque data structure. */
  34 struct rte_swx_pipeline;
  35
  36 /**
  37  * Pipeline configure
  38  *
  39  * @param[out] p
  40  *   Pipeline handle. Must point to valid memory. Contains valid pipeline handle
  41  *   when the function returns successfully.
  42  * @param[in] numa_node
  43  *   Non-Uniform Memory Access (NUMA) node.
  44  * @return
  45  *   0 on success or the following error codes otherwise:
  46  *   -EINVAL: Invalid argument;
  47  *   -ENOMEM: Not enough space/cannot allocate memory.
  48  */
  49 __rte_experimental
  50 int
  51 rte_swx_pipeline_config(struct rte_swx_pipeline **p,
  52                         int numa_node);
  53
  54 /*
  55  * Pipeline input ports
  56  */
  57
  58 /**
  59  * Pipeline input port type register
  60  *
  61  * @param[in] p
  62  *   Pipeline handle.
  63  * @param[in] name
  64  *   Input port type name.
  65  * @param[in] ops
  66  *   Input port type operations.
  67  * @return
  68  *   0 on success or the following error codes otherwise:
  69  *   -EINVAL: Invalid argument;
  70  *   -ENOMEM: Not enough space/cannot allocate memory;
  71  *   -EEXIST: Input port type with this name already exists.
  72  */
  73 __rte_experimental
  74 int
  75 rte_swx_pipeline_port_in_type_register(struct rte_swx_pipeline *p,
  76                                        const char *name,
  77                                        struct rte_swx_port_in_ops *ops);
  78
  79 /**
  80  * Pipeline input port configure
  81  *
  82  * @param[in] p
  83  *   Pipeline handle.
  84  * @param[in] port_id
  85  *   Input port ID.
  86  * @param[in] port_type_name
  87  *   Existing input port type name.
  88  * @param[in] args
  89  *   Input port creation arguments.
  90  * @return
  91  *   0 on success or the following error codes otherwise:
  92  *   -EINVAL: Invalid argument;
  93  *   -ENOMEM: Not enough space/cannot allocate memory;
  94  *   -ENODEV: Input port object creation error.
  95  */
  96 __rte_experimental
  97 int
  98 rte_swx_pipeline_port_in_config(struct rte_swx_pipeline *p,
  99                                 uint32_t port_id,
 100                                 const char *port_type_name,
 101                                 void *args);
 102
 103 /*
 104  * Pipeline output ports
 105  */
 106
 107 /**
 108  * Pipeline output port type register
 109  *
 110  * @param[in] p
 111  *   Pipeline handle.
 112  * @param[in] name
 113  *   Output port type name.
 114  * @param[in] ops
 115  *   Output port type operations.
 116  * @return
 117  *   0 on success or the following error codes otherwise:
 118  *   -EINVAL: Invalid argument;
 119  *   -ENOMEM: Not enough space/cannot allocate memory;
 120  *   -EEXIST: Output port type with this name already exists.
 121  */
 122 __rte_experimental
 123 int
 124 rte_swx_pipeline_port_out_type_register(struct rte_swx_pipeline *p,
 125                                         const char *name,
 126                                         struct rte_swx_port_out_ops *ops);
 127
 128 /**
 129  * Pipeline output port configure
 130  *
 131  * @param[in] p
 132  *   Pipeline handle.
 133  * @param[in] port_id
 134  *   Output port ID.
 135  * @param[in] port_type_name
 136  *   Existing output port type name.
 137  * @param[in] args
 138  *   Output port creation arguments.
 139  * @return
 140  *   0 on success or the following error codes otherwise:
 141  *   -EINVAL: Invalid argument;
 142  *   -ENOMEM: Not enough space/cannot allocate memory;
 143  *   -ENODEV: Output port object creation error.
 144  */
 145 __rte_experimental
 146 int
 147 rte_swx_pipeline_port_out_config(struct rte_swx_pipeline *p,
 148                                  uint32_t port_id,
 149                                  const char *port_type_name,
 150                                  void *args);
 151
 152 /*
 153  * Extern objects and functions
 154  */
 155
 156 /**
 157  * Pipeline extern type register
 158  *
 159  * @param[in] p
 160  *   Pipeline handle.
 161  * @param[in] name
 162  *   Extern type name.
 163  * @param[in] mailbox_struct_type_name
 164  *   Name of existing struct type used to define the mailbox size and layout for
 165  *   the extern objects that are instances of this type. Each extern object gets
 166  *   its own mailbox, which is used to pass the input arguments to the member
 167  *   functions and retrieve the output results.
 168  * @param[in] constructor
 169  *   Function used to create the extern objects that are instances of this type.
 170  * @param[in] destructor
 171  *   Function used to free the extern objects that are instances of  this type.
 172  * @return
 173  *   0 on success or the following error codes otherwise:
 174  *   -EINVAL: Invalid argument;
 175  *   -ENOMEM: Not enough space/cannot allocate memory;
 176  *   -EEXIST: Extern type with this name already exists.
 177  */
 178 __rte_experimental
 179 int
 180 rte_swx_pipeline_extern_type_register(struct rte_swx_pipeline *p,
 181         const char *name,
 182         const char *mailbox_struct_type_name,
 183         rte_swx_extern_type_constructor_t constructor,
 184         rte_swx_extern_type_destructor_t destructor);
 185
 186 /**
 187  * Pipeline extern type member function register
 188  *
 189  * @param[in] p
 190  *   Pipeline handle.
 191  * @param[in] extern_type_name
 192  *   Existing extern type name.
 193  * @param[in] name
 194  *   Name for the new member function to be added to the extern type.
 195  * @param[in] member_func
 196  *   The new member function.
 197  * @return
 198  *   0 on success or the following error codes otherwise:
 199  *   -EINVAL: Invalid argument;
 200  *   -ENOMEM: Not enough space/cannot allocate memory;
 201  *   -EEXIST: Member function with this name already exists for this type;
 202  *   -ENOSPC: Maximum number of member functions reached for this type.
 203  */
 204 __rte_experimental
 205 int
 206 rte_swx_pipeline_extern_type_member_func_register(struct rte_swx_pipeline *p,
 207         const char *extern_type_name,
 208         const char *name,
 209         rte_swx_extern_type_member_func_t member_func);
 210
 211 /**
 212  * Pipeline extern object configure
 213  *
 214  * Instantiate a given extern type to create new extern object.
 215  *
 216  * @param[in] p
 217  *   Pipeline handle.
 218  * @param[in] extern_type_name
 219  *   Existing extern type name.
 220  * @param[in] name
 221  *   Name for the new object instantiating the extern type.
 222  * @param[in] args
 223  *   Extern object constructor arguments.
 224  * @return
 225  *   0 on success or the following error codes otherwise:
 226  *   -EINVAL: Invalid argument;
 227  *   -ENOMEM: Not enough space/cannot allocate memory;
 228  *   -EEXIST: Extern object with this name already exists;
 229  *   -ENODEV: Extern object constructor error.
 230  */
 231 __rte_experimental
 232 int
 233 rte_swx_pipeline_extern_object_config(struct rte_swx_pipeline *p,
 234                                       const char *extern_type_name,
 235                                       const char *name,
 236                                       const char *args);
 237
 238 /**
 239  * Pipeline extern function register
 240  *
 241  * @param[in] p
 242  *   Pipeline handle.
 243  * @param[in] name
 244  *   Extern function name.
 245  * @param[in] mailbox_struct_type_name
 246  *   Name of existing struct type used to define the mailbox size and layout for
 247  *   this extern function. The mailbox is used to pass the input arguments to
 248  *   the extern function and retrieve the output results.
 249  * @param[in] func
 250  *   The extern function.
 251  * @return
 252  *   0 on success or the following error codes otherwise:
 253  *   -EINVAL: Invalid argument;
 254  *   -ENOMEM: Not enough space/cannot allocate memory;
 255  *   -EEXIST: Extern function with this name already exists.
 256  */
 257 __rte_experimental
 258 int
 259 rte_swx_pipeline_extern_func_register(struct rte_swx_pipeline *p,
 260                                       const char *name,
 261                                       const char *mailbox_struct_type_name,
 262                                       rte_swx_extern_func_t func);
 263
 264 /*
 265  * Packet headers and meta-data
 266  */
 267
 268 /** Structure (struct) field. */
 269 struct rte_swx_field_params {
 270         /** Struct field name. */
 271         const char *name;
 272
 273         /** Struct field size (in bits).
 274          * Restriction: All struct fields must be a multiple of 8 bits.
 275          * Restriction: All struct fields must be no greater than 64 bits.
 276          */
 277         uint32_t n_bits;
 278 };
 279
 280 /**
 281  * Pipeline struct type register
 282  *
 283  * Structs are used extensively in many part of the pipeline to define the size
 284  * and layout of a specific memory piece such as: headers, meta-data, action
 285  * data stored in a table entry, mailboxes for extern objects and functions.
 286  * Similar to C language structs, they are a well defined sequence of fields,
 287  * with each field having a unique name and a constant size.
 288  *
 289  * @param[in] p
 290  *   Pipeline handle.
 291  * @param[in] name
 292  *   Struct type name.
 293  * @param[in] fields
 294  *   The sequence of struct fields.
 295  * @param[in] n_fields
 296  *   The number of struct fields.
 297  * @return
 298  *   0 on success or the following error codes otherwise:
 299  *   -EINVAL: Invalid argument;
 300  *   -ENOMEM: Not enough space/cannot allocate memory;
 301  *   -EEXIST: Struct type with this name already exists.
 302  */
 303 __rte_experimental
 304 int
 305 rte_swx_pipeline_struct_type_register(struct rte_swx_pipeline *p,
 306                                       const char *name,
 307                                       struct rte_swx_field_params *fields,
 308                                       uint32_t n_fields);
 309
 310 /**
 311  * Pipeline packet header register
 312  *
 313  * @param[in] p
 314  *   Pipeline handle.
 315  * @param[in] name
 316  *   Header name.
 317  * @param[in] struct_type_name
 318  *   The struct type instantiated by this packet header.
 319  * @return
 320  *   0 on success or the following error codes otherwise:
 321  *   -EINVAL: Invalid argument;
 322  *   -ENOMEM: Not enough space/cannot allocate memory;
 323  *   -EEXIST: Header with this name already exists;
 324  *   -ENOSPC: Maximum number of headers reached for the pipeline.
 325  */
 326 __rte_experimental
 327 int
 328 rte_swx_pipeline_packet_header_register(struct rte_swx_pipeline *p,
 329                                         const char *name,
 330                                         const char *struct_type_name);
 331
 332 /**
 333  * Pipeline packet meta-data register
 334  *
 335  * @param[in] p
 336  *   Pipeline handle.
 337  * @param[in] struct_type_name
 338  *   The struct type instantiated by the packet meta-data.
 339  * @return
 340  *   0 on success or the following error codes otherwise:
 341  *   -EINVAL: Invalid argument.
 342  */
 343 __rte_experimental
 344 int
 345 rte_swx_pipeline_packet_metadata_register(struct rte_swx_pipeline *p,
 346                                           const char *struct_type_name);
 347
 348 /*
 349  * Pipeline action
 350  */
 351
 352 /**
 353  * Pipeline action configure
 354  *
 355  * @param[in] p
 356  *   Pipeline handle.
 357  * @param[in] name
 358  *   Action name.
 359  * @param[in] args_struct_type_name
 360  *   The struct type instantiated by the action data. The action data represent
 361  *   the action arguments that are stored in the table entry together with the
 362  *   action ID. Set to NULL when the action does not have any arguments.
 363  * @param[in] instructions
 364  *   Action instructions.
 365  * @param[in] n_instructions
 366  *   Number of action instructions.
 367  * @return
 368  *   0 on success or the following error codes otherwise:
 369  *   -EINVAL: Invalid argument;
 370  *   -ENOMEM: Not enough space/cannot allocate memory;
 371  *   -EEXIST: Action with this name already exists.
 372  */
 373 __rte_experimental
 374 int
 375 rte_swx_pipeline_action_config(struct rte_swx_pipeline *p,
 376                                const char *name,
 377                                const char *args_struct_type_name,
 378                                const char **instructions,
 379                                uint32_t n_instructions);
 380
 381 /*
 382  * Pipeline table
 383  */
 384
 385 /**
 386  * Pipeline table type register
 387  *
 388  * @param[in] p
 389  *   Pipeline handle.
 390  * @param[in] name
 391  *   Table type name.
 392  * @param[in] match_type
 393  *   Match type implemented by the new table type.
 394  * @param[in] ops
 395  *   Table type operations.
 396  * @return
 397  *   0 on success or the following error codes otherwise:
 398  *   -EINVAL: Invalid argument;
 399  *   -ENOMEM: Not enough space/cannot allocate memory;
 400  *   -EEXIST: Table type with this name already exists.
 401  */
 402 __rte_experimental
 403 int
 404 rte_swx_pipeline_table_type_register(struct rte_swx_pipeline *p,
 405                                      const char *name,
 406                                      enum rte_swx_table_match_type match_type,
 407                                      struct rte_swx_table_ops *ops);
 408
 409 /** Match field parameters. */
 410 struct rte_swx_match_field_params {
 411         /** Match field name. Must be either a field of one of the registered
 412          * packet headers ("h.header.field") or a field of the registered
 413          * meta-data ("m.field").
 414          */
 415         const char *name;
 416
 417         /** Match type of the field. */
 418         enum rte_swx_table_match_type match_type;
 419 };
 420
 421 /** Pipeline table parameters. */
 422 struct rte_swx_pipeline_table_params {
 423         /** The set of match fields for the current table.
 424          * Restriction: All the match fields of the current table need to be
 425          * part of the same struct, i.e. either all the match fields are part of
 426          * the same header or all the match fields are part of the meta-data.
 427          */
 428         struct rte_swx_match_field_params *fields;
 429
 430         /** The number of match fields for the current table. If set to zero, no
 431          * "regular" entries (i.e. entries other than the default entry) can be
 432          * added to the current table and the match process always results in
 433          * lookup miss.
 434          */
 435         uint32_t n_fields;
 436
 437         /** The set of actions for the current table. */
 438         const char **action_names;
 439
 440         /** The number of actions for the current table. Must be at least one.
 441          */
 442         uint32_t n_actions;
 443
 444         /** The default table action that gets executed on lookup miss. Must be
 445          * one of the table actions included in the *action_names*.
 446          */
 447         const char *default_action_name;
 448
 449         /** Default action data. The size of this array is the action data size
 450          * of the default action. Must be NULL if the default action data size
 451          * is zero.
 452          */
 453         uint8_t *default_action_data;
 454
 455         /** If non-zero (true), then the default action of the current table
 456          * cannot be changed. If zero (false), then the default action can be
 457          * changed in the future with another action from the *action_names*
 458          * list.
 459          */
 460         int default_action_is_const;
 461 };
 462
 463 /**
 464  * Pipeline table configure
 465  *
 466  * @param[out] p
 467  *   Pipeline handle.
 468  * @param[in] name
 469  *   Table name.
 470  * @param[in] params
 471  *   Table parameters.
 472  * @param[in] recommended_table_type_name
 473  *   Recommended table type. Typically set to NULL. Useful as guidance when
 474  *   there are multiple table types registered for the match type of the table,
 475  *   as determined from the table match fields specification. Silently ignored
 476  *   if the recommended table type does not exist or it serves a different match
 477  *   type.
 478  * @param[in] args
 479  *   Table creation arguments.
 480  * @param[in] size
 481  *   Guideline on maximum number of table entries.
 482  * @return
 483  *   0 on success or the following error codes otherwise:
 484  *   -EINVAL: Invalid argument;
 485  *   -ENOMEM: Not enough space/cannot allocate memory;
 486  *   -EEXIST: Table with this name already exists;
 487  *   -ENODEV: Table creation error.
 488  */
 489 __rte_experimental
 490 int
 491 rte_swx_pipeline_table_config(struct rte_swx_pipeline *p,
 492                               const char *name,
 493                               struct rte_swx_pipeline_table_params *params,
 494                               const char *recommended_table_type_name,
 495                               const char *args,
 496                               uint32_t size);
 497
 498 /**
 499  * Pipeline instructions configure
 500  *
 501  * @param[in] p
 502  *   Pipeline handle.
 503  * @param[in] instructions
 504  *   Pipeline instructions.
 505  * @param[in] n_instructions
 506  *   Number of pipeline instructions.
 507  * @return
 508  *   0 on success or the following error codes otherwise:
 509  *   -EINVAL: Invalid argument;
 510  *   -ENOMEM: Not enough space/cannot allocate memory.
 511  */
 512 __rte_experimental
 513 int
 514 rte_swx_pipeline_instructions_config(struct rte_swx_pipeline *p,
 515                                      const char **instructions,
 516                                      uint32_t n_instructions);
 517
 518 /**
 519  * Pipeline build
 520  *
 521  * Once called, the pipeline build operation marks the end of pipeline
 522  * configuration. At this point, all the internal data structures needed to run
 523  * the pipeline are built.
 524  *
 525  * @param[in] p
 526  *   Pipeline handle.
 527  * @return
 528  *   0 on success or the following error codes otherwise:
 529  *   -EINVAL: Invalid argument;
 530  *   -ENOMEM: Not enough space/cannot allocate memory;
 531  *   -EEXIST: Pipeline was already built successfully.
 532  */
 533 __rte_experimental
 534 int
 535 rte_swx_pipeline_build(struct rte_swx_pipeline *p);
 536
 537 /**
 538  * Pipeline run
 539  *
 540  * @param[in] p
 541  *   Pipeline handle.
 542  * @param[in] n_instructions
 543  *   Number of instructions to execute.
 544  */
 545 __rte_experimental
 546 void
 547 rte_swx_pipeline_run(struct rte_swx_pipeline *p,
 548                      uint32_t n_instructions);
 549
 550 /**
 551  * Pipeline free
 552  *
 553  * @param[in] p
 554  *   Pipeline handle.
 555  */
 556 __rte_experimental
 557 void
 558 rte_swx_pipeline_free(struct rte_swx_pipeline *p);
 559
 560 #ifdef __cplusplus
 561 }
 562 #endif
 563
 564 #endif