lib/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 <stdint.h>
  17 #include <stdio.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 /** Instruction size. */
  31 #ifndef RTE_SWX_INSTRUCTION_SIZE
  32 #define RTE_SWX_INSTRUCTION_SIZE 256
  33 #endif
  34
  35 /** Instruction tokens. */
  36 #ifndef RTE_SWX_INSTRUCTION_TOKENS_MAX
  37 #define RTE_SWX_INSTRUCTION_TOKENS_MAX 16
  38 #endif
  39
  40 /*
  41  * Pipeline setup and operation
  42  */
  43
  44 /** Pipeline opaque data structure. */
  45 struct rte_swx_pipeline;
  46
  47 /**
  48  * Pipeline configure
  49  *
  50  * @param[out] p
  51  *   Pipeline handle. Must point to valid memory. Contains valid pipeline handle
  52  *   when the function returns successfully.
  53  * @param[in] numa_node
  54  *   Non-Uniform Memory Access (NUMA) node.
  55  * @return
  56  *   0 on success or the following error codes otherwise:
  57  *   -EINVAL: Invalid argument;
  58  *   -ENOMEM: Not enough space/cannot allocate memory.
  59  */
  60 __rte_experimental
  61 int
  62 rte_swx_pipeline_config(struct rte_swx_pipeline **p,
  63                         int numa_node);
  64
  65 /*
  66  * Pipeline input ports
  67  */
  68
  69 /**
  70  * Pipeline input port type register
  71  *
  72  * @param[in] p
  73  *   Pipeline handle.
  74  * @param[in] name
  75  *   Input port type name.
  76  * @param[in] ops
  77  *   Input port type operations.
  78  * @return
  79  *   0 on success or the following error codes otherwise:
  80  *   -EINVAL: Invalid argument;
  81  *   -ENOMEM: Not enough space/cannot allocate memory;
  82  *   -EEXIST: Input port type with this name already exists.
  83  */
  84 __rte_experimental
  85 int
  86 rte_swx_pipeline_port_in_type_register(struct rte_swx_pipeline *p,
  87                                        const char *name,
  88                                        struct rte_swx_port_in_ops *ops);
  89
  90 /**
  91  * Pipeline input port configure
  92  *
  93  * @param[in] p
  94  *   Pipeline handle.
  95  * @param[in] port_id
  96  *   Input port ID.
  97  * @param[in] port_type_name
  98  *   Existing input port type name.
  99  * @param[in] args
 100  *   Input port creation arguments.
 101  * @return
 102  *   0 on success or the following error codes otherwise:
 103  *   -EINVAL: Invalid argument;
 104  *   -ENOMEM: Not enough space/cannot allocate memory;
 105  *   -ENODEV: Input port object creation error.
 106  */
 107 __rte_experimental
 108 int
 109 rte_swx_pipeline_port_in_config(struct rte_swx_pipeline *p,
 110                                 uint32_t port_id,
 111                                 const char *port_type_name,
 112                                 void *args);
 113
 114 /*
 115  * Pipeline output ports
 116  */
 117
 118 /**
 119  * Pipeline output port type register
 120  *
 121  * @param[in] p
 122  *   Pipeline handle.
 123  * @param[in] name
 124  *   Output port type name.
 125  * @param[in] ops
 126  *   Output port type operations.
 127  * @return
 128  *   0 on success or the following error codes otherwise:
 129  *   -EINVAL: Invalid argument;
 130  *   -ENOMEM: Not enough space/cannot allocate memory;
 131  *   -EEXIST: Output port type with this name already exists.
 132  */
 133 __rte_experimental
 134 int
 135 rte_swx_pipeline_port_out_type_register(struct rte_swx_pipeline *p,
 136                                         const char *name,
 137                                         struct rte_swx_port_out_ops *ops);
 138
 139 /**
 140  * Pipeline output port configure
 141  *
 142  * @param[in] p
 143  *   Pipeline handle.
 144  * @param[in] port_id
 145  *   Output port ID.
 146  * @param[in] port_type_name
 147  *   Existing output port type name.
 148  * @param[in] args
 149  *   Output port creation arguments.
 150  * @return
 151  *   0 on success or the following error codes otherwise:
 152  *   -EINVAL: Invalid argument;
 153  *   -ENOMEM: Not enough space/cannot allocate memory;
 154  *   -ENODEV: Output port object creation error.
 155  */
 156 __rte_experimental
 157 int
 158 rte_swx_pipeline_port_out_config(struct rte_swx_pipeline *p,
 159                                  uint32_t port_id,
 160                                  const char *port_type_name,
 161                                  void *args);
 162
 163 /*
 164  * Extern objects and functions
 165  */
 166
 167 /**
 168  * Pipeline extern type register
 169  *
 170  * @param[in] p
 171  *   Pipeline handle.
 172  * @param[in] name
 173  *   Extern type name.
 174  * @param[in] mailbox_struct_type_name
 175  *   Name of existing struct type used to define the mailbox size and layout for
 176  *   the extern objects that are instances of this type. Each extern object gets
 177  *   its own mailbox, which is used to pass the input arguments to the member
 178  *   functions and retrieve the output results.
 179  * @param[in] constructor
 180  *   Function used to create the extern objects that are instances of this type.
 181  * @param[in] destructor
 182  *   Function used to free the extern objects that are instances of  this type.
 183  * @return
 184  *   0 on success or the following error codes otherwise:
 185  *   -EINVAL: Invalid argument;
 186  *   -ENOMEM: Not enough space/cannot allocate memory;
 187  *   -EEXIST: Extern type with this name already exists.
 188  */
 189 __rte_experimental
 190 int
 191 rte_swx_pipeline_extern_type_register(struct rte_swx_pipeline *p,
 192         const char *name,
 193         const char *mailbox_struct_type_name,
 194         rte_swx_extern_type_constructor_t constructor,
 195         rte_swx_extern_type_destructor_t destructor);
 196
 197 /**
 198  * Pipeline extern type member function register
 199  *
 200  * @param[in] p
 201  *   Pipeline handle.
 202  * @param[in] extern_type_name
 203  *   Existing extern type name.
 204  * @param[in] name
 205  *   Name for the new member function to be added to the extern type.
 206  * @param[in] member_func
 207  *   The new member function.
 208  * @return
 209  *   0 on success or the following error codes otherwise:
 210  *   -EINVAL: Invalid argument;
 211  *   -ENOMEM: Not enough space/cannot allocate memory;
 212  *   -EEXIST: Member function with this name already exists for this type;
 213  *   -ENOSPC: Maximum number of member functions reached for this type.
 214  */
 215 __rte_experimental
 216 int
 217 rte_swx_pipeline_extern_type_member_func_register(struct rte_swx_pipeline *p,
 218         const char *extern_type_name,
 219         const char *name,
 220         rte_swx_extern_type_member_func_t member_func);
 221
 222 /**
 223  * Pipeline extern object configure
 224  *
 225  * Instantiate a given extern type to create new extern object.
 226  *
 227  * @param[in] p
 228  *   Pipeline handle.
 229  * @param[in] extern_type_name
 230  *   Existing extern type name.
 231  * @param[in] name
 232  *   Name for the new object instantiating the extern type.
 233  * @param[in] args
 234  *   Extern object constructor arguments.
 235  * @return
 236  *   0 on success or the following error codes otherwise:
 237  *   -EINVAL: Invalid argument;
 238  *   -ENOMEM: Not enough space/cannot allocate memory;
 239  *   -EEXIST: Extern object with this name already exists;
 240  *   -ENODEV: Extern object constructor error.
 241  */
 242 __rte_experimental
 243 int
 244 rte_swx_pipeline_extern_object_config(struct rte_swx_pipeline *p,
 245                                       const char *extern_type_name,
 246                                       const char *name,
 247                                       const char *args);
 248
 249 /**
 250  * Pipeline extern function register
 251  *
 252  * @param[in] p
 253  *   Pipeline handle.
 254  * @param[in] name
 255  *   Extern function name.
 256  * @param[in] mailbox_struct_type_name
 257  *   Name of existing struct type used to define the mailbox size and layout for
 258  *   this extern function. The mailbox is used to pass the input arguments to
 259  *   the extern function and retrieve the output results.
 260  * @param[in] func
 261  *   The extern function.
 262  * @return
 263  *   0 on success or the following error codes otherwise:
 264  *   -EINVAL: Invalid argument;
 265  *   -ENOMEM: Not enough space/cannot allocate memory;
 266  *   -EEXIST: Extern function with this name already exists.
 267  */
 268 __rte_experimental
 269 int
 270 rte_swx_pipeline_extern_func_register(struct rte_swx_pipeline *p,
 271                                       const char *name,
 272                                       const char *mailbox_struct_type_name,
 273                                       rte_swx_extern_func_t func);
 274
 275 /*
 276  * Packet headers and meta-data
 277  */
 278
 279 /** Structure (struct) field. */
 280 struct rte_swx_field_params {
 281         /** Struct field name. */
 282         const char *name;
 283
 284         /** Struct field size (in bits).
 285          * Restriction: All struct fields must be a multiple of 8 bits.
 286          * Restriction: All struct fields must be no greater than 64 bits.
 287          */
 288         uint32_t n_bits;
 289 };
 290
 291 /**
 292  * Pipeline struct type register
 293  *
 294  * Structs are used extensively in many part of the pipeline to define the size
 295  * and layout of a specific memory piece such as: headers, meta-data, action
 296  * data stored in a table entry, mailboxes for extern objects and functions.
 297  * Similar to C language structs, they are a well defined sequence of fields,
 298  * with each field having a unique name and a constant size.
 299  *
 300  * In order to use structs to express variable size packet headers such as IPv4
 301  * with options, it is allowed for the last field of the struct type to have a
 302  * variable size between 0 and *n_bits* bits, with the actual size of this field
 303  * determined at run-time for each packet. This struct feature is restricted to
 304  * just a few selected instructions that deal with packet headers, so a typical
 305  * struct generally has a constant size that is fully known when its struct type
 306  * is registered.
 307  *
 308  * @param[in] p
 309  *   Pipeline handle.
 310  * @param[in] name
 311  *   Struct type name.
 312  * @param[in] fields
 313  *   The sequence of struct fields.
 314  * @param[in] n_fields
 315  *   The number of struct fields.
 316  * @param[in] last_field_has_variable_size
 317  *   If non-zero (true), then the last field has a variable size between 0 and
 318  *   *n_bits* bits, with its actual size determined at run-time for each packet.
 319  *   If zero (false), then the last field has a constant size of *n_bits* bits.
 320  * @return
 321  *   0 on success or the following error codes otherwise:
 322  *   -EINVAL: Invalid argument;
 323  *   -ENOMEM: Not enough space/cannot allocate memory;
 324  *   -EEXIST: Struct type with this name already exists.
 325  */
 326 __rte_experimental
 327 int
 328 rte_swx_pipeline_struct_type_register(struct rte_swx_pipeline *p,
 329                                       const char *name,
 330                                       struct rte_swx_field_params *fields,
 331                                       uint32_t n_fields,
 332                                       int last_field_has_variable_size);
 333
 334 /**
 335  * Pipeline packet header register
 336  *
 337  * @param[in] p
 338  *   Pipeline handle.
 339  * @param[in] name
 340  *   Header name.
 341  * @param[in] struct_type_name
 342  *   The struct type instantiated by this packet header.
 343  * @return
 344  *   0 on success or the following error codes otherwise:
 345  *   -EINVAL: Invalid argument;
 346  *   -ENOMEM: Not enough space/cannot allocate memory;
 347  *   -EEXIST: Header with this name already exists;
 348  *   -ENOSPC: Maximum number of headers reached for the pipeline.
 349  */
 350 __rte_experimental
 351 int
 352 rte_swx_pipeline_packet_header_register(struct rte_swx_pipeline *p,
 353                                         const char *name,
 354                                         const char *struct_type_name);
 355
 356 /**
 357  * Pipeline packet meta-data register
 358  *
 359  * @param[in] p
 360  *   Pipeline handle.
 361  * @param[in] struct_type_name
 362  *   The struct type instantiated by the packet meta-data.
 363  * @return
 364  *   0 on success or the following error codes otherwise:
 365  *   -EINVAL: Invalid argument.
 366  */
 367 __rte_experimental
 368 int
 369 rte_swx_pipeline_packet_metadata_register(struct rte_swx_pipeline *p,
 370                                           const char *struct_type_name);
 371
 372 /*
 373  * Instructions
 374  */
 375
 376 /**
 377  * Instruction operands:
 378  *
 379  *<pre>+-----+---------------------------+------------------+-----+-----+</pre>
 380  *<pre>|     | Description               | Format           | DST | SRC |</pre>
 381  *<pre>+-----+---------------------------+------------------+-----+-----+</pre>
 382  *<pre>| hdr | Header                    | h.header         |     |     |</pre>
 383  *<pre>+-----+---------------------------+------------------+-----+-----+</pre>
 384  *<pre>| act | Action                    | ACTION           |     |     |</pre>
 385  *<pre>+-----+---------------------------+------------------+-----+-----+</pre>
 386  *<pre>| tbl | Table                     | TABLE            |     |     |</pre>
 387  *<pre>+-----+---------------------------+------------------+-----+-----+</pre>
 388  *<pre>| H   | Header field              | h.header.field   | YES | YES |</pre>
 389  *<pre>+-----+---------------------------+------------------+-----+-----+</pre>
 390  *<pre>| M   | Meta-data field           | m.field          | YES | YES |</pre>
 391  *<pre>+-----+---------------------------+------------------+-----+-----+</pre>
 392  *<pre>| E   | Extern obj mailbox field  | e.ext_obj.field  | YES | YES |</pre>
 393  *<pre>+-----+---------------------------+------------------+-----+-----+</pre>
 394  *<pre>| F   | Extern func mailbox field | f.ext_func.field | YES | YES |</pre>
 395  *<pre>+-----+---------------------------+------------------+-----+-----+</pre>
 396  *<pre>| T   | Table action data field   | t.header.field   | NO  | YES |</pre>
 397  *<pre>+-----+---------------------------+------------------+-----+-----+</pre>
 398  *<pre>| I   | Immediate value (64-bit)  | h.header.field   | NO  | YES |</pre>
 399  *<pre>+-----+---------------------------+------------------+-----+-----+</pre>
 400  *
 401  * Instruction set:
 402  *
 403  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 404  *<pre>| Instr.     | Instruction          | Instruction       | 1st  | 2nd    |</pre>
 405  *<pre>| Name       | Description          | Format            | opnd.| opnd.  |</pre>
 406  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 407  *<pre>| rx         | Receive one pkt      | rx m.port_in      | M    |        |</pre>
 408  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 409  *<pre>| tx         | Transmit one pkt     | tx m.port_out     | M    |        |</pre>
 410  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 411  *<pre>| extract    | Extract one hdr      | extract h.hdr     | hdr  |        |</pre>
 412  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 413  *<pre>| emit       | Emit one hdr         | emit h.hdr        | hdr  |        |</pre>
 414  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 415  *<pre>| validate   | Validate one hdr     | validate h.hdr    | hdr  |        |</pre>
 416  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 417  *<pre>| invalidate | Invalidate one hdr   | invalidate h.hdr  | hdr  |        |</pre>
 418  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 419  *<pre>| mov        | dst = src            | mov dst src       | HMEF | HMEFTI |</pre>
 420  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 421  *<pre>| add        | dst += src           | add dst src       | HMEF | HMEFTI |</pre>
 422  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 423  *<pre>| sub        | dst -= src           | add dst src       | HMEF | HMEFTI |</pre>
 424  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 425  *<pre>| ckadd      | Checksum add: dst =  | add dst src       | HMEF | HMEFTI |</pre>
 426  *<pre>|            | dst '+ src[0:1] '+   |                   |      | or hdr |</pre>
 427  *<pre>|            | src[2:3] '+ ...      |                   |      |        |</pre>
 428  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 429  *<pre>| cksub      | Checksum subtract:   | add dst src       | HMEF | HMEFTI |</pre>
 430  *<pre>|            | dst = dst '- src     |                   |      |        |</pre>
 431  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 432  *<pre>| and        | dst &= src           | and dst src       | HMEF | HMEFTI |</pre>
 433  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 434  *<pre>| or         | dst |= src           | or  dst src       | HMEF | HMEFTI |</pre>
 435  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 436  *<pre>| xor        | dst ^= src           | xor dst src       | HMEF | HMEFTI |</pre>
 437  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 438  *<pre>| shl        | dst <<= src          | shl dst src       | HMEF | HMEFTI |</pre>
 439  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 440  *<pre>| shr        | dst >>= src          | shr dst src       | HMEF | HMEFTI |</pre>
 441  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 442  *<pre>| table      | Table lookup         | table TABLE       | tbl  |        |</pre>
 443  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 444  *<pre>| extern     | Ext obj member func  | extern e.obj.mfunc| ext  |        |</pre>
 445  *<pre>|            | call or ext func call| extern f.func     |      |        |</pre>
 446  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 447  *<pre>| jmp        | Unconditional jump   | jmp LABEL         |      |        |</pre>
 448  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 449  *<pre>| jmpv       | Jump if hdr is valid | jmpv LABEL h.hdr  | hdr  |        |</pre>
 450  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 451  *<pre>| jmpnv      | Jump if hdr is inval | jmpnv LABEL h.hdr | hdr  |        |</pre>
 452  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 453  *<pre>| jmph       | Jump if tbl lkp hit  | jmph LABEL        |      |        |</pre>
 454  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 455  *<pre>| jmpnh      | Jump if tbl lkp miss | jmpnh LABEL       |      |        |</pre>
 456  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 457  *<pre>| jmpa       | Jump if action run   | jmpa LABEL ACTION | act  |        |</pre>
 458  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 459  *<pre>| jmpna      | Jump if act not run  | jmpna LABEL ACTION| act  |        |</pre>
 460  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 461  *<pre>| jmpeq      | Jump if (a == b)     | jmpeq LABEL a b   | HMEFT| HMEFTI |</pre>
 462  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 463  *<pre>| jmpneq     | Jump if (a != b)     | jmpneq LABEL a b  | HMEFT| HMEFTI |</pre>
 464  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 465  *<pre>| jmplt      | Jump if (a < b)      | jmplt LABEL a b   | HMEFT| HMEFTI |</pre>
 466  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 467  *<pre>| jmpgt      | Jump if (a > b)      | jmpgt LABEL a b   | HMEFT| HMEFTI |</pre>
 468  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 469  *<pre>| return     | Return from action   | return            |      |        |</pre>
 470  *<pre>+------------+----------------------+-------------------+------+--------+</pre>
 471  *
 472  * At initialization time, the pipeline and action instructions (including the
 473  * symbolic name operands) are translated to internal data structures that are
 474  * used at run-time.
 475  */
 476
 477 /*
 478  * Pipeline action
 479  */
 480
 481 /**
 482  * Pipeline action configure
 483  *
 484  * @param[in] p
 485  *   Pipeline handle.
 486  * @param[in] name
 487  *   Action name.
 488  * @param[in] args_struct_type_name
 489  *   The struct type instantiated by the action data. The action data represent
 490  *   the action arguments that are stored in the table entry together with the
 491  *   action ID. Set to NULL when the action does not have any arguments.
 492  * @param[in] instructions
 493  *   Action instructions.
 494  * @param[in] n_instructions
 495  *   Number of action instructions.
 496  * @return
 497  *   0 on success or the following error codes otherwise:
 498  *   -EINVAL: Invalid argument;
 499  *   -ENOMEM: Not enough space/cannot allocate memory;
 500  *   -EEXIST: Action with this name already exists.
 501  */
 502 __rte_experimental
 503 int
 504 rte_swx_pipeline_action_config(struct rte_swx_pipeline *p,
 505                                const char *name,
 506                                const char *args_struct_type_name,
 507                                const char **instructions,
 508                                uint32_t n_instructions);
 509
 510 /*
 511  * Pipeline table
 512  */
 513
 514 /**
 515  * Pipeline table type register
 516  *
 517  * @param[in] p
 518  *   Pipeline handle.
 519  * @param[in] name
 520  *   Table type name.
 521  * @param[in] match_type
 522  *   Match type implemented by the new table type.
 523  * @param[in] ops
 524  *   Table type operations.
 525  * @return
 526  *   0 on success or the following error codes otherwise:
 527  *   -EINVAL: Invalid argument;
 528  *   -ENOMEM: Not enough space/cannot allocate memory;
 529  *   -EEXIST: Table type with this name already exists.
 530  */
 531 __rte_experimental
 532 int
 533 rte_swx_pipeline_table_type_register(struct rte_swx_pipeline *p,
 534                                      const char *name,
 535                                      enum rte_swx_table_match_type match_type,
 536                                      struct rte_swx_table_ops *ops);
 537
 538 /** Match field parameters. */
 539 struct rte_swx_match_field_params {
 540         /** Match field name. Must be either a field of one of the registered
 541          * packet headers ("h.header.field") or a field of the registered
 542          * meta-data ("m.field").
 543          */
 544         const char *name;
 545
 546         /** Match type of the field. */
 547         enum rte_swx_table_match_type match_type;
 548 };
 549
 550 /** Pipeline table parameters. */
 551 struct rte_swx_pipeline_table_params {
 552         /** The set of match fields for the current table.
 553          * Restriction: All the match fields of the current table need to be
 554          * part of the same struct, i.e. either all the match fields are part of
 555          * the same header or all the match fields are part of the meta-data.
 556          */
 557         struct rte_swx_match_field_params *fields;
 558
 559         /** The number of match fields for the current table. If set to zero, no
 560          * "regular" entries (i.e. entries other than the default entry) can be
 561          * added to the current table and the match process always results in
 562          * lookup miss.
 563          */
 564         uint32_t n_fields;
 565
 566         /** The set of actions for the current table. */
 567         const char **action_names;
 568
 569         /**  Array of *n_actions* flags. For each action, the associated flag
 570          * indicates whether the action can be assigned to regular table entries
 571          * (when non-zero, i.e. true) or not (when zero, i.e. false). When set
 572          * to NULL, it defaults to true for all actions.
 573          */
 574         int *action_is_for_table_entries;
 575
 576         /**  Array of *n_actions* flags. For each action, the associated flag
 577          * indicates whether the action can be assigned to the default table
 578          * entry (when non-zero, i.e. true) or not (when zero, i.e. false).
 579          * When set to NULL, it defaults to true for all actions.
 580          */
 581         int *action_is_for_default_entry;
 582
 583         /** The number of actions for the current table. Must be at least one.
 584          */
 585         uint32_t n_actions;
 586
 587         /** The default table action that gets executed on lookup miss. Must be
 588          * one of the table actions included in the *action_names*.
 589          */
 590         const char *default_action_name;
 591
 592         /** Default action data. The size of this array is the action data size
 593          * of the default action. Must be NULL if the default action data size
 594          * is zero.
 595          */
 596         uint8_t *default_action_data;
 597
 598         /** If non-zero (true), then the default action of the current table
 599          * cannot be changed. If zero (false), then the default action can be
 600          * changed in the future with another action from the *action_names*
 601          * list.
 602          */
 603         int default_action_is_const;
 604 };
 605
 606 /**
 607  * Pipeline table configure
 608  *
 609  * @param[out] p
 610  *   Pipeline handle.
 611  * @param[in] name
 612  *   Table name.
 613  * @param[in] params
 614  *   Table parameters.
 615  * @param[in] recommended_table_type_name
 616  *   Recommended table type. Typically set to NULL. Useful as guidance when
 617  *   there are multiple table types registered for the match type of the table,
 618  *   as determined from the table match fields specification. Silently ignored
 619  *   if the recommended table type does not exist or it serves a different match
 620  *   type.
 621  * @param[in] args
 622  *   Table creation arguments.
 623  * @param[in] size
 624  *   Guideline on maximum number of table entries.
 625  * @return
 626  *   0 on success or the following error codes otherwise:
 627  *   -EINVAL: Invalid argument;
 628  *   -ENOMEM: Not enough space/cannot allocate memory;
 629  *   -EEXIST: Table with this name already exists;
 630  *   -ENODEV: Table creation error.
 631  */
 632 __rte_experimental
 633 int
 634 rte_swx_pipeline_table_config(struct rte_swx_pipeline *p,
 635                               const char *name,
 636                               struct rte_swx_pipeline_table_params *params,
 637                               const char *recommended_table_type_name,
 638                               const char *args,
 639                               uint32_t size);
 640
 641 /** Pipeline selector table parameters. */
 642 struct rte_swx_pipeline_selector_params {
 643         /** The group ID field. Input into the selection operation.
 644          * Restriction: This field must be a meta-data field.
 645          */
 646         const char *group_id_field_name;
 647
 648         /** The set of fields used to select (through a hashing scheme) the
 649          * member within the current group. Inputs into the selection operation.
 650          * Restriction: All the selector fields must be part of the same struct,
 651          * i.e. part of the same header or part of the meta-data structure.
 652          */
 653         const char **selector_field_names;
 654
 655         /** The number of selector fields. Must be non-zero. */
 656         uint32_t n_selector_fields;
 657
 658         /** The member ID field. Output from the selection operation.
 659          * Restriction: This field must be a meta-data field.
 660          */
 661         const char *member_id_field_name;
 662
 663         /** Maximum number of groups. Must be non-zero. */
 664         uint32_t n_groups_max;
 665
 666         /** Maximum number of members per group. Must be non-zero. */
 667         uint32_t n_members_per_group_max;
 668 };
 669
 670 /**
 671  * Pipeline selector table configure
 672  *
 673  * @param[out] p
 674  *   Pipeline handle.
 675  * @param[in] name
 676  *   Selector table name.
 677  * @param[in] params
 678  *   Selector table parameters.
 679  * @return
 680  *   0 on success or the following error codes otherwise:
 681  *   -EINVAL: Invalid argument;
 682  *   -ENOMEM: Not enough space/cannot allocate memory;
 683  *   -EEXIST: Selector table with this name already exists;
 684  *   -ENODEV: Selector table creation error.
 685  */
 686 __rte_experimental
 687 int
 688 rte_swx_pipeline_selector_config(struct rte_swx_pipeline *p,
 689                                  const char *name,
 690                                  struct rte_swx_pipeline_selector_params *params);
 691
 692 /** Pipeline learner table parameters. */
 693 struct rte_swx_pipeline_learner_params {
 694         /** The set of match fields for the current table.
 695          * Restriction: All the match fields of the current table need to be
 696          * part of the same struct, i.e. either all the match fields are part of
 697          * the same header or all the match fields are part of the meta-data.
 698          */
 699         const char **field_names;
 700
 701         /** The number of match fields for the current table. Must be non-zero.
 702          */
 703         uint32_t n_fields;
 704
 705         /** The set of actions for the current table. */
 706         const char **action_names;
 707
 708         /**  Array of *n_actions* flags. For each action, the associated flag
 709          * indicates whether the action can be assigned to regular table entries
 710          * (when non-zero, i.e. true) or not (when zero, i.e. false). When set
 711          * to NULL, it defaults to true for all actions.
 712          */
 713         int *action_is_for_table_entries;
 714
 715         /**  Array of *n_actions* flags. For each action, the associated flag
 716          * indicates whether the action can be assigned to the default table
 717          * entry (when non-zero, i.e. true) or not (when zero, i.e. false).
 718          * When set to NULL, it defaults to true for all actions.
 719          */
 720         int *action_is_for_default_entry;
 721
 722         /** The number of actions for the current table. Must be at least one.
 723          */
 724         uint32_t n_actions;
 725
 726         /** The default table action that gets executed on lookup miss. Must be
 727          * one of the table actions included in the *action_names*.
 728          */
 729         const char *default_action_name;
 730
 731         /** Default action data. The size of this array is the action data size
 732          * of the default action. Must be NULL if the default action data size
 733          * is zero.
 734          */
 735         uint8_t *default_action_data;
 736
 737         /** If non-zero (true), then the default action of the current table
 738          * cannot be changed. If zero (false), then the default action can be
 739          * changed in the future with another action from the *action_names*
 740          * list.
 741          */
 742         int default_action_is_const;
 743 };
 744
 745 /**
 746  * Pipeline learner table configure
 747  *
 748  * @param[out] p
 749  *   Pipeline handle.
 750  * @param[in] name
 751  *   Learner table name.
 752  * @param[in] params
 753  *   Learner table parameters.
 754  * @param[in] size
 755  *   The maximum number of table entries. Must be non-zero.
 756  * @param[in] timeout
 757  *   Table entry timeout in seconds. Must be non-zero.
 758  * @return
 759  *   0 on success or the following error codes otherwise:
 760  *   -EINVAL: Invalid argument;
 761  *   -ENOMEM: Not enough space/cannot allocate memory;
 762  *   -EEXIST: Learner table with this name already exists;
 763  *   -ENODEV: Learner table creation error.
 764  */
 765 __rte_experimental
 766 int
 767 rte_swx_pipeline_learner_config(struct rte_swx_pipeline *p,
 768                                 const char *name,
 769                                 struct rte_swx_pipeline_learner_params *params,
 770                                 uint32_t size,
 771                                 uint32_t timeout);
 772
 773 /**
 774  * Pipeline register array configure
 775  *
 776  * @param[in] p
 777  *   Pipeline handle.
 778  * @param[in] name
 779  *   Register array name.
 780  * @param[in] size
 781  *   Number of registers in the array. Each register is 64-bit in size.
 782  * @param[in] init_val
 783  *   Initial value for every register in the array. The recommended value is 0.
 784  * @return
 785  *   0 on success or the following error codes otherwise:
 786  *   -EINVAL: Invalid argument;
 787  *   -ENOMEM: Not enough space/cannot allocate memory;
 788  *   -EEXIST: Register array with this name already exists.
 789  */
 790 __rte_experimental
 791 int
 792 rte_swx_pipeline_regarray_config(struct rte_swx_pipeline *p,
 793                                  const char *name,
 794                                  uint32_t size,
 795                                  uint64_t init_val);
 796
 797 /**
 798  * Pipeline meter array configure
 799  *
 800  * @param[in] p
 801  *   Pipeline handle.
 802  * @param[in] name
 803  *   Meter array name.
 804  * @param[in] size
 805  *   Number of meters in the array. Each meter in the array implements the Two
 806  *   Rate Three Color Marker (trTCM) algorithm, as specified by RFC 2698.
 807  * @return
 808  *   0 on success or the following error codes otherwise:
 809  *   -EINVAL: Invalid argument;
 810  *   -ENOMEM: Not enough space/cannot allocate memory;
 811  *   -EEXIST: Meter array with this name already exists.
 812  */
 813 __rte_experimental
 814 int
 815 rte_swx_pipeline_metarray_config(struct rte_swx_pipeline *p,
 816                                  const char *name,
 817                                  uint32_t size);
 818
 819 /**
 820  * Pipeline instructions configure
 821  *
 822  * @param[in] p
 823  *   Pipeline handle.
 824  * @param[in] instructions
 825  *   Pipeline instructions.
 826  * @param[in] n_instructions
 827  *   Number of pipeline instructions.
 828  * @return
 829  *   0 on success or the following error codes otherwise:
 830  *   -EINVAL: Invalid argument;
 831  *   -ENOMEM: Not enough space/cannot allocate memory.
 832  */
 833 __rte_experimental
 834 int
 835 rte_swx_pipeline_instructions_config(struct rte_swx_pipeline *p,
 836                                      const char **instructions,
 837                                      uint32_t n_instructions);
 838
 839 /**
 840  * Pipeline build
 841  *
 842  * Once called, the pipeline build operation marks the end of pipeline
 843  * configuration. At this point, all the internal data structures needed to run
 844  * the pipeline are built.
 845  *
 846  * @param[in] p
 847  *   Pipeline handle.
 848  * @return
 849  *   0 on success or the following error codes otherwise:
 850  *   -EINVAL: Invalid argument;
 851  *   -ENOMEM: Not enough space/cannot allocate memory;
 852  *   -EEXIST: Pipeline was already built successfully.
 853  */
 854 __rte_experimental
 855 int
 856 rte_swx_pipeline_build(struct rte_swx_pipeline *p);
 857
 858 /**
 859  * Pipeline build from specification file
 860  *
 861  * @param[in] p
 862  *   Pipeline handle.
 863  * @param[in] spec
 864  *   Pipeline specification file.
 865  * @param[out] err_line
 866  *   In case of error and non-NULL, the line number within the *spec* file where
 867  *   the error occurred. The first line number in the file is 1.
 868  * @param[out] err_msg
 869  *   In case of error and non-NULL, the error message.
 870  * @return
 871  *   0 on success or the following error codes otherwise:
 872  *   -EINVAL: Invalid argument;
 873  *   -ENOMEM: Not enough space/cannot allocate memory;
 874  *   -EEXIST: Resource with the same name already exists;
 875  *   -ENODEV: Extern object or table creation error.
 876  */
 877 __rte_experimental
 878 int
 879 rte_swx_pipeline_build_from_spec(struct rte_swx_pipeline *p,
 880                                  FILE *spec,
 881                                  uint32_t *err_line,
 882                                  const char **err_msg);
 883
 884 /**
 885  * Pipeline run
 886  *
 887  * @param[in] p
 888  *   Pipeline handle.
 889  * @param[in] n_instructions
 890  *   Number of instructions to execute.
 891  */
 892 __rte_experimental
 893 void
 894 rte_swx_pipeline_run(struct rte_swx_pipeline *p,
 895                      uint32_t n_instructions);
 896
 897 /**
 898  * Pipeline flush
 899  *
 900  * Flush all output ports of the pipeline.
 901  *
 902  * @param[in] p
 903  *   Pipeline handle.
 904  */
 905 __rte_experimental
 906 void
 907 rte_swx_pipeline_flush(struct rte_swx_pipeline *p);
 908
 909 /**
 910  * Pipeline free
 911  *
 912  * @param[in] p
 913  *   Pipeline handle.
 914  */
 915 __rte_experimental
 916 void
 917 rte_swx_pipeline_free(struct rte_swx_pipeline *p);
 918
 919 #ifdef __cplusplus
 920 }
 921 #endif
 922
 923 #endif