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