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