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