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