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