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 * If p is NULL, no operation is performed. 991 */ 992 __rte_experimental 993 void 994 rte_swx_pipeline_flush(struct rte_swx_pipeline *p); 995 996 /** 997 * Pipeline free 998 * 999 * @param[in] p 1000 * Pipeline handle. 1001 */ 1002 __rte_experimental 1003 void 1004 rte_swx_pipeline_free(struct rte_swx_pipeline *p); 1005 1006 #ifdef __cplusplus 1007 } 1008 #endif 1009 1010 #endif 1011