1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2010-2016 Intel Corporation 3 */ 4 5 #ifndef __INCLUDE_RTE_PIPELINE_H__ 6 #define __INCLUDE_RTE_PIPELINE_H__ 7 8 #ifdef __cplusplus 9 extern "C" { 10 #endif 11 12 /** 13 * @file 14 * RTE Pipeline 15 * 16 * This tool is part of the DPDK Packet Framework tool suite and provides 17 * a standard methodology (logically similar to OpenFlow) for rapid development 18 * of complex packet processing pipelines out of ports, tables and actions. 19 * 20 * <B>Basic operation.</B> A pipeline is constructed by connecting its input 21 * ports to its output ports through a chain of lookup tables. As result of 22 * lookup operation into the current table, one of the table entries (or the 23 * default table entry, in case of lookup miss) is identified to provide the 24 * actions to be executed on the current packet and the associated action 25 * meta-data. The behavior of user actions is defined through the configurable 26 * table action handler, while the reserved actions define the next hop for the 27 * current packet (either another table, an output port or packet drop) and are 28 * handled transparently by the framework. 29 * 30 * <B>Initialization and run-time flows.</B> Once all the pipeline elements 31 * (input ports, tables, output ports) have been created, input ports connected 32 * to tables, table action handlers configured, tables populated with the 33 * initial set of entries (actions and action meta-data) and input ports 34 * enabled, the pipeline runs automatically, pushing packets from input ports 35 * to tables and output ports. At each table, the identified user actions are 36 * being executed, resulting in action meta-data (stored in the table entry) 37 * and packet meta-data (stored with the packet descriptor) being updated. The 38 * pipeline tables can have further updates and input ports can be disabled or 39 * enabled later on as required. 40 * 41 * <B>Multi-core scaling.</B> Typically, each CPU core will run its own 42 * pipeline instance. Complex application-level pipelines can be implemented by 43 * interconnecting multiple CPU core-level pipelines in tree-like topologies, 44 * as the same port devices (e.g. SW rings) can serve as output ports for the 45 * pipeline running on CPU core A, as well as input ports for the pipeline 46 * running on CPU core B. This approach enables the application development 47 * using the pipeline (CPU cores connected serially), cluster/run-to-completion 48 * (CPU cores connected in parallel) or mixed (pipeline of CPU core clusters) 49 * programming models. 50 * 51 * <B>Thread safety.</B> It is possible to have multiple pipelines running on 52 * the same CPU core, but it is not allowed (for thread safety reasons) to have 53 * multiple CPU cores running the same pipeline instance. 54 * 55 ***/ 56 57 #include <stdint.h> 58 59 #include <rte_port.h> 60 #include <rte_table.h> 61 #include <rte_common.h> 62 63 struct rte_mbuf; 64 65 /* 66 * Pipeline 67 * 68 */ 69 /** Opaque data type for pipeline */ 70 struct rte_pipeline; 71 72 /** Parameters for pipeline creation */ 73 struct rte_pipeline_params { 74 /** Pipeline name */ 75 const char *name; 76 77 /** CPU socket ID where memory for the pipeline and its elements (ports 78 and tables) should be allocated */ 79 int socket_id; 80 81 /** Offset within packet meta-data to port_id to be used by action 82 "Send packet to output port read from packet meta-data". Has to be 83 4-byte aligned. */ 84 uint32_t offset_port_id; 85 }; 86 87 /** Pipeline port in stats. */ 88 struct rte_pipeline_port_in_stats { 89 /** Port in stats. */ 90 struct rte_port_in_stats stats; 91 92 /** Number of packets dropped by action handler. */ 93 uint64_t n_pkts_dropped_by_ah; 94 95 }; 96 97 /** Pipeline port out stats. */ 98 struct rte_pipeline_port_out_stats { 99 /** Port out stats. */ 100 struct rte_port_out_stats stats; 101 102 /** Number of packets dropped by action handler. */ 103 uint64_t n_pkts_dropped_by_ah; 104 }; 105 106 /** Pipeline table stats. */ 107 struct rte_pipeline_table_stats { 108 /** Table stats. */ 109 struct rte_table_stats stats; 110 111 /** Number of packets dropped by lookup hit action handler. */ 112 uint64_t n_pkts_dropped_by_lkp_hit_ah; 113 114 /** Number of packets dropped by lookup miss action handler. */ 115 uint64_t n_pkts_dropped_by_lkp_miss_ah; 116 117 /** Number of packets dropped by pipeline in behalf of this 118 * table based on action specified in table entry. */ 119 uint64_t n_pkts_dropped_lkp_hit; 120 121 /** Number of packets dropped by pipeline in behalf of this 122 * table based on action specified in table entry. */ 123 uint64_t n_pkts_dropped_lkp_miss; 124 }; 125 126 /** 127 * Pipeline create 128 * 129 * @param params 130 * Parameters for pipeline creation 131 * @return 132 * Handle to pipeline instance on success or NULL otherwise 133 */ 134 struct rte_pipeline *rte_pipeline_create(struct rte_pipeline_params *params); 135 136 /** 137 * Pipeline free 138 * 139 * @param p 140 * Handle to pipeline instance 141 * @return 142 * 0 on success, error code otherwise 143 */ 144 int rte_pipeline_free(struct rte_pipeline *p); 145 146 /** 147 * Pipeline consistency check 148 * 149 * @param p 150 * Handle to pipeline instance 151 * @return 152 * 0 on success, error code otherwise 153 */ 154 int rte_pipeline_check(struct rte_pipeline *p); 155 156 /** 157 * Pipeline run 158 * 159 * @param p 160 * Handle to pipeline instance 161 * @return 162 * Number of packets read and processed 163 */ 164 int rte_pipeline_run(struct rte_pipeline *p); 165 166 /** 167 * Pipeline flush 168 * 169 * @param p 170 * Handle to pipeline instance 171 * @return 172 * 0 on success, error code otherwise 173 */ 174 int rte_pipeline_flush(struct rte_pipeline *p); 175 176 /* 177 * Actions 178 * 179 */ 180 /** Reserved actions */ 181 enum rte_pipeline_action { 182 /** Drop the packet */ 183 RTE_PIPELINE_ACTION_DROP = 0, 184 185 /** Send packet to output port */ 186 RTE_PIPELINE_ACTION_PORT, 187 188 /** Send packet to output port read from packet meta-data */ 189 RTE_PIPELINE_ACTION_PORT_META, 190 191 /** Send packet to table */ 192 RTE_PIPELINE_ACTION_TABLE, 193 194 /** Number of reserved actions */ 195 RTE_PIPELINE_ACTIONS 196 }; 197 198 /* 199 * Table 200 * 201 */ 202 /** Maximum number of tables allowed for any given pipeline instance. The 203 value of this parameter cannot be changed. */ 204 #define RTE_PIPELINE_TABLE_MAX 64 205 206 /** 207 * Head format for the table entry of any pipeline table. For any given 208 * pipeline table, all table entries should have the same size and format. For 209 * any given pipeline table, the table entry has to start with a head of this 210 * structure, which contains the reserved actions and their associated 211 * meta-data, and then optionally continues with user actions and their 212 * associated meta-data. As all the currently defined reserved actions are 213 * mutually exclusive, only one reserved action can be set per table entry. 214 */ 215 struct rte_pipeline_table_entry { 216 /** Reserved action */ 217 enum rte_pipeline_action action; 218 219 RTE_STD_C11 220 union { 221 /** Output port ID (meta-data for "Send packet to output port" 222 action) */ 223 uint32_t port_id; 224 /** Table ID (meta-data for "Send packet to table" action) */ 225 uint32_t table_id; 226 }; 227 /** Start of table entry area for user defined actions and meta-data */ 228 __extension__ uint8_t action_data[0]; 229 }; 230 231 /** 232 * Pipeline table action handler on lookup hit 233 * 234 * The action handler can decide to drop packets by resetting the associated 235 * packet bit in the pkts_mask parameter. In this case, the action handler is 236 * required not to free the packet buffer, which will be freed eventually by 237 * the pipeline. 238 * 239 * @param p 240 * Handle to pipeline instance 241 * @param pkts 242 * Burst of input packets specified as array of up to 64 pointers to struct 243 * rte_mbuf 244 * @param pkts_mask 245 * 64-bit bitmask specifying which packets in the input burst are valid. When 246 * pkts_mask bit n is set, then element n of pkts array is pointing to a 247 * valid packet and element n of entries array is pointing to a valid table 248 * entry associated with the packet, with the association typically done by 249 * the table lookup operation. Otherwise, element n of pkts array and element 250 * n of entries array will not be accessed. 251 * @param entries 252 * Set of table entries specified as array of up to 64 pointers to struct 253 * rte_pipeline_table_entry 254 * @param arg 255 * Opaque parameter registered by the user at the pipeline table creation 256 * time 257 * @return 258 * 0 on success, error code otherwise 259 */ 260 typedef int (*rte_pipeline_table_action_handler_hit)( 261 struct rte_pipeline *p, 262 struct rte_mbuf **pkts, 263 uint64_t pkts_mask, 264 struct rte_pipeline_table_entry **entries, 265 void *arg); 266 267 /** 268 * Pipeline table action handler on lookup miss 269 * 270 * The action handler can decide to drop packets by resetting the associated 271 * packet bit in the pkts_mask parameter. In this case, the action handler is 272 * required not to free the packet buffer, which will be freed eventually by 273 * the pipeline. 274 * 275 * @param p 276 * Handle to pipeline instance 277 * @param pkts 278 * Burst of input packets specified as array of up to 64 pointers to struct 279 * rte_mbuf 280 * @param pkts_mask 281 * 64-bit bitmask specifying which packets in the input burst are valid. When 282 * pkts_mask bit n is set, then element n of pkts array is pointing to a 283 * valid packet. Otherwise, element n of pkts array will not be accessed. 284 * @param entry 285 * Single table entry associated with all the valid packets from the input 286 * burst, specified as pointer to struct rte_pipeline_table_entry. 287 * This entry is the pipeline table default entry that is associated by the 288 * table lookup operation with the input packets that have resulted in lookup 289 * miss. 290 * @param arg 291 * Opaque parameter registered by the user at the pipeline table creation 292 * time 293 * @return 294 * 0 on success, error code otherwise 295 */ 296 typedef int (*rte_pipeline_table_action_handler_miss)( 297 struct rte_pipeline *p, 298 struct rte_mbuf **pkts, 299 uint64_t pkts_mask, 300 struct rte_pipeline_table_entry *entry, 301 void *arg); 302 303 /** Parameters for pipeline table creation. Action handlers have to be either 304 both enabled or both disabled (they can be disabled by setting them to 305 NULL). */ 306 struct rte_pipeline_table_params { 307 /** Table operations (specific to each table type) */ 308 struct rte_table_ops *ops; 309 /** Opaque param to be passed to the table create operation when 310 invoked */ 311 void *arg_create; 312 /** Callback function to execute the user actions on input packets in 313 case of lookup hit */ 314 rte_pipeline_table_action_handler_hit f_action_hit; 315 /** Callback function to execute the user actions on input packets in 316 case of lookup miss */ 317 rte_pipeline_table_action_handler_miss f_action_miss; 318 319 /** Opaque parameter to be passed to lookup hit and/or lookup miss 320 action handlers when invoked */ 321 void *arg_ah; 322 /** Memory size to be reserved per table entry for storing the user 323 actions and their meta-data */ 324 uint32_t action_data_size; 325 }; 326 327 /** 328 * Pipeline table create 329 * 330 * @param p 331 * Handle to pipeline instance 332 * @param params 333 * Parameters for pipeline table creation 334 * @param table_id 335 * Table ID. Valid only within the scope of table IDs of the current 336 * pipeline. Only returned after a successful invocation. 337 * @return 338 * 0 on success, error code otherwise 339 */ 340 int rte_pipeline_table_create(struct rte_pipeline *p, 341 struct rte_pipeline_table_params *params, 342 uint32_t *table_id); 343 344 /** 345 * Pipeline table default entry add 346 * 347 * The contents of the table default entry is updated with the provided actions 348 * and meta-data. When the default entry is not configured (by using this 349 * function), the built-in default entry has the action "Drop" and meta-data 350 * set to all-zeros. 351 * 352 * @param p 353 * Handle to pipeline instance 354 * @param table_id 355 * Table ID (returned by previous invocation of pipeline table create) 356 * @param default_entry 357 * New contents for the table default entry 358 * @param default_entry_ptr 359 * On successful invocation, pointer to the default table entry which can be 360 * used for further read-write accesses to this table entry. This pointer 361 * is valid until the default entry is deleted or re-added. 362 * @return 363 * 0 on success, error code otherwise 364 */ 365 int rte_pipeline_table_default_entry_add(struct rte_pipeline *p, 366 uint32_t table_id, 367 struct rte_pipeline_table_entry *default_entry, 368 struct rte_pipeline_table_entry **default_entry_ptr); 369 370 /** 371 * Pipeline table default entry delete 372 * 373 * The new contents of the table default entry is set to reserved action "Drop 374 * the packet" with meta-data cleared (i.e. set to all-zeros). 375 * 376 * @param p 377 * Handle to pipeline instance 378 * @param table_id 379 * Table ID (returned by previous invocation of pipeline table create) 380 * @param entry 381 * On successful invocation, when entry points to a valid buffer, the 382 * previous contents of the table default entry (as it was just before the 383 * delete operation) is copied to this buffer 384 * @return 385 * 0 on success, error code otherwise 386 */ 387 int rte_pipeline_table_default_entry_delete(struct rte_pipeline *p, 388 uint32_t table_id, 389 struct rte_pipeline_table_entry *entry); 390 391 /** 392 * Pipeline table entry add 393 * 394 * @param p 395 * Handle to pipeline instance 396 * @param table_id 397 * Table ID (returned by previous invocation of pipeline table create) 398 * @param key 399 * Table entry key 400 * @param entry 401 * New contents for the table entry identified by key 402 * @param key_found 403 * On successful invocation, set to TRUE (value different than 0) if key was 404 * already present in the table before the add operation and to FALSE (value 405 * 0) if not 406 * @param entry_ptr 407 * On successful invocation, pointer to the table entry associated with key. 408 * This can be used for further read-write accesses to this table entry and 409 * is valid until the key is deleted from the table or re-added (usually for 410 * associating different actions and/or action meta-data to the current key) 411 * @return 412 * 0 on success, error code otherwise 413 */ 414 int rte_pipeline_table_entry_add(struct rte_pipeline *p, 415 uint32_t table_id, 416 void *key, 417 struct rte_pipeline_table_entry *entry, 418 int *key_found, 419 struct rte_pipeline_table_entry **entry_ptr); 420 421 /** 422 * Pipeline table entry delete 423 * 424 * @param p 425 * Handle to pipeline instance 426 * @param table_id 427 * Table ID (returned by previous invocation of pipeline table create) 428 * @param key 429 * Table entry key 430 * @param key_found 431 * On successful invocation, set to TRUE (value different than 0) if key was 432 * found in the table before the delete operation and to FALSE (value 0) if 433 * not 434 * @param entry 435 * On successful invocation, when key is found in the table and entry points 436 * to a valid buffer, the table entry contents (as it was before the delete 437 * was performed) is copied to this buffer 438 * @return 439 * 0 on success, error code otherwise 440 */ 441 int rte_pipeline_table_entry_delete(struct rte_pipeline *p, 442 uint32_t table_id, 443 void *key, 444 int *key_found, 445 struct rte_pipeline_table_entry *entry); 446 447 /** 448 * Pipeline table entry add bulk 449 * 450 * @param p 451 * Handle to pipeline instance 452 * @param table_id 453 * Table ID (returned by previous invocation of pipeline table create) 454 * @param keys 455 * Array containing table entry keys 456 * @param entries 457 * Array containing new contents for every table entry identified by key 458 * @param n_keys 459 * Number of keys to add 460 * @param key_found 461 * On successful invocation, key_found for every item in the array is set to 462 * TRUE (value different than 0) if key was already present in the table 463 * before the add operation and to FALSE (value 0) if not 464 * @param entries_ptr 465 * On successful invocation, array *entries_ptr stores pointer to every table 466 * entry associated with key. This can be used for further read-write accesses 467 * to this table entry and is valid until the key is deleted from the table or 468 * re-added (usually for associating different actions and/or action meta-data 469 * to the current key) 470 * @return 471 * 0 on success, error code otherwise 472 */ 473 int rte_pipeline_table_entry_add_bulk(struct rte_pipeline *p, 474 uint32_t table_id, 475 void **keys, 476 struct rte_pipeline_table_entry **entries, 477 uint32_t n_keys, 478 int *key_found, 479 struct rte_pipeline_table_entry **entries_ptr); 480 481 /** 482 * Pipeline table entry delete bulk 483 * 484 * @param p 485 * Handle to pipeline instance 486 * @param table_id 487 * Table ID (returned by previous invocation of pipeline table create) 488 * @param keys 489 * Array containing table entry keys 490 * @param n_keys 491 * Number of keys to delete 492 * @param key_found 493 * On successful invocation, key_found for every item in the array is set to 494 * TRUE (value different than 0) if key was found in the table before the 495 * delete operation and to FALSE (value 0) if not 496 * @param entries 497 * If entries pointer is NULL, this pointer is ignored for every entry found. 498 * Else, after successful invocation, if specific key is found in the table 499 * and entry points to a valid buffer, the table entry contents (as it was 500 * before the delete was performed) is copied to this buffer. 501 * @return 502 * 0 on success, error code otherwise 503 */ 504 int rte_pipeline_table_entry_delete_bulk(struct rte_pipeline *p, 505 uint32_t table_id, 506 void **keys, 507 uint32_t n_keys, 508 int *key_found, 509 struct rte_pipeline_table_entry **entries); 510 511 /** 512 * Read pipeline table stats. 513 * 514 * This function reads table statistics identified by *table_id* of given 515 * pipeline *p*. 516 * 517 * @param p 518 * Handle to pipeline instance. 519 * @param table_id 520 * Port ID what stats will be returned. 521 * @param stats 522 * Statistics buffer. 523 * @param clear 524 * If not 0 clear stats after reading. 525 * @return 526 * 0 on success, error code otherwise 527 */ 528 int rte_pipeline_table_stats_read(struct rte_pipeline *p, uint32_t table_id, 529 struct rte_pipeline_table_stats *stats, int clear); 530 531 /* 532 * Port IN 533 * 534 */ 535 /** Maximum number of input ports allowed for any given pipeline instance. The 536 value of this parameter cannot be changed. */ 537 #define RTE_PIPELINE_PORT_IN_MAX 64 538 539 /** 540 * Pipeline input port action handler 541 * 542 * The action handler can decide to drop packets by resetting the associated 543 * packet bit in the pkts_mask parameter. In this case, the action handler is 544 * required not to free the packet buffer, which will be freed eventually by 545 * the pipeline. 546 * 547 * @param p 548 * Handle to pipeline instance 549 * @param pkts 550 * Burst of input packets specified as array of up to 64 pointers to struct 551 * rte_mbuf 552 * @param n 553 * Number of packets in the input burst. This parameter specifies that 554 * elements 0 to (n-1) of pkts array are valid. 555 * @param arg 556 * Opaque parameter registered by the user at the pipeline table creation 557 * time 558 * @return 559 * 0 on success, error code otherwise 560 */ 561 typedef int (*rte_pipeline_port_in_action_handler)( 562 struct rte_pipeline *p, 563 struct rte_mbuf **pkts, 564 uint32_t n, 565 void *arg); 566 567 /** Parameters for pipeline input port creation */ 568 struct rte_pipeline_port_in_params { 569 /** Input port operations (specific to each table type) */ 570 struct rte_port_in_ops *ops; 571 /** Opaque parameter to be passed to create operation when invoked */ 572 void *arg_create; 573 574 /** Callback function to execute the user actions on input packets. 575 Disabled if set to NULL. */ 576 rte_pipeline_port_in_action_handler f_action; 577 /** Opaque parameter to be passed to the action handler when invoked */ 578 void *arg_ah; 579 580 /** Recommended burst size for the RX operation(in number of pkts) */ 581 uint32_t burst_size; 582 }; 583 584 /** 585 * Pipeline input port create 586 * 587 * @param p 588 * Handle to pipeline instance 589 * @param params 590 * Parameters for pipeline input port creation 591 * @param port_id 592 * Input port ID. Valid only within the scope of input port IDs of the 593 * current pipeline. Only returned after a successful invocation. 594 * @return 595 * 0 on success, error code otherwise 596 */ 597 int rte_pipeline_port_in_create(struct rte_pipeline *p, 598 struct rte_pipeline_port_in_params *params, 599 uint32_t *port_id); 600 601 /** 602 * Pipeline input port connect to table 603 * 604 * @param p 605 * Handle to pipeline instance 606 * @param port_id 607 * Port ID (returned by previous invocation of pipeline input port create) 608 * @param table_id 609 * Table ID (returned by previous invocation of pipeline table create) 610 * @return 611 * 0 on success, error code otherwise 612 */ 613 int rte_pipeline_port_in_connect_to_table(struct rte_pipeline *p, 614 uint32_t port_id, 615 uint32_t table_id); 616 617 /** 618 * Pipeline input port enable 619 * 620 * @param p 621 * Handle to pipeline instance 622 * @param port_id 623 * Port ID (returned by previous invocation of pipeline input port create) 624 * @return 625 * 0 on success, error code otherwise 626 */ 627 int rte_pipeline_port_in_enable(struct rte_pipeline *p, 628 uint32_t port_id); 629 630 /** 631 * Pipeline input port disable 632 * 633 * @param p 634 * Handle to pipeline instance 635 * @param port_id 636 * Port ID (returned by previous invocation of pipeline input port create) 637 * @return 638 * 0 on success, error code otherwise 639 */ 640 int rte_pipeline_port_in_disable(struct rte_pipeline *p, 641 uint32_t port_id); 642 643 /** 644 * Read pipeline port in stats. 645 * 646 * This function reads port in statistics identified by *port_id* of given 647 * pipeline *p*. 648 * 649 * @param p 650 * Handle to pipeline instance. 651 * @param port_id 652 * Port ID what stats will be returned. 653 * @param stats 654 * Statistics buffer. 655 * @param clear 656 * If not 0 clear stats after reading. 657 * @return 658 * 0 on success, error code otherwise 659 */ 660 int rte_pipeline_port_in_stats_read(struct rte_pipeline *p, uint32_t port_id, 661 struct rte_pipeline_port_in_stats *stats, int clear); 662 663 /* 664 * Port OUT 665 * 666 */ 667 /** Maximum number of output ports allowed for any given pipeline instance. The 668 value of this parameter cannot be changed. */ 669 #define RTE_PIPELINE_PORT_OUT_MAX 64 670 671 /** 672 * Pipeline output port action handler 673 * 674 * The action handler can decide to drop packets by resetting the associated 675 * packet bit in the pkts_mask parameter. In this case, the action handler is 676 * required not to free the packet buffer, which will be freed eventually by 677 * the pipeline. 678 * 679 * @param p 680 * Handle to pipeline instance 681 * @param pkts 682 * Burst of input packets specified as array of up to 64 pointers to struct 683 * rte_mbuf 684 * @param pkts_mask 685 * 64-bit bitmask specifying which packets in the input burst are valid. When 686 * pkts_mask bit n is set, then element n of pkts array is pointing to a 687 * valid packet. Otherwise, element n of pkts array will not be accessed. 688 * @param arg 689 * Opaque parameter registered by the user at the pipeline table creation 690 * time 691 * @return 692 * 0 on success, error code otherwise 693 */ 694 typedef int (*rte_pipeline_port_out_action_handler)( 695 struct rte_pipeline *p, 696 struct rte_mbuf **pkts, 697 uint64_t pkts_mask, 698 void *arg); 699 700 /** Parameters for pipeline output port creation. The action handlers have to 701 be either both enabled or both disabled (by setting them to NULL). When 702 enabled, the pipeline selects between them at different moments, based on the 703 number of packets that have to be sent to the same output port. */ 704 struct rte_pipeline_port_out_params { 705 /** Output port operations (specific to each table type) */ 706 struct rte_port_out_ops *ops; 707 /** Opaque parameter to be passed to create operation when invoked */ 708 void *arg_create; 709 710 /** Callback function executing the user actions on bust of input 711 packets */ 712 rte_pipeline_port_out_action_handler f_action; 713 /** Opaque parameter to be passed to the action handler when invoked */ 714 void *arg_ah; 715 }; 716 717 /** 718 * Pipeline output port create 719 * 720 * @param p 721 * Handle to pipeline instance 722 * @param params 723 * Parameters for pipeline output port creation 724 * @param port_id 725 * Output port ID. Valid only within the scope of output port IDs of the 726 * current pipeline. Only returned after a successful invocation. 727 * @return 728 * 0 on success, error code otherwise 729 */ 730 int rte_pipeline_port_out_create(struct rte_pipeline *p, 731 struct rte_pipeline_port_out_params *params, 732 uint32_t *port_id); 733 734 /** 735 * Read pipeline port out stats. 736 * 737 * This function reads port out statistics identified by *port_id* of given 738 * pipeline *p*. 739 * 740 * @param p 741 * Handle to pipeline instance. 742 * @param port_id 743 * Port ID what stats will be returned. 744 * @param stats 745 * Statistics buffer. 746 * @param clear 747 * If not 0 clear stats after reading. 748 * @return 749 * 0 on success, error code otherwise 750 */ 751 int rte_pipeline_port_out_stats_read(struct rte_pipeline *p, uint32_t port_id, 752 struct rte_pipeline_port_out_stats *stats, int clear); 753 754 /* 755 * Functions to be called as part of the port IN/OUT or table action handlers 756 * 757 */ 758 /** 759 * Action handler packet insert to output port 760 * 761 * This function can be called by any input/output port or table action handler 762 * to send a packet out through one of the pipeline output ports. This packet is 763 * generated by the action handler, i.e. this packet is not part of the burst of 764 * packets read from one of the pipeline input ports and currently processed by 765 * the pipeline (this packet is not an element of the pkts array input parameter 766 * of the action handler). 767 * 768 * @param p 769 * Handle to pipeline instance 770 * @param port_id 771 * Output port ID (returned by previous invocation of pipeline output port 772 * create) to send the packet specified by pkt 773 * @param pkt 774 * New packet generated by the action handler 775 * @return 776 * 0 on success, error code otherwise 777 */ 778 int rte_pipeline_port_out_packet_insert(struct rte_pipeline *p, 779 uint32_t port_id, 780 struct rte_mbuf *pkt); 781 782 #define rte_pipeline_ah_port_out_packet_insert \ 783 rte_pipeline_port_out_packet_insert 784 785 /** 786 * Action handler packet hijack 787 * 788 * This function can be called by any input/output port or table action handler 789 * to hijack selected packets from the burst of packets read from one of the 790 * pipeline input ports and currently processed by the pipeline. The hijacked 791 * packets are removed from any further pipeline processing, with the action 792 * handler now having the full ownership for these packets. 793 * 794 * The action handler can further send the hijacked packets out through any 795 * pipeline output port by calling the rte_pipeline_ah_port_out_packet_insert() 796 * function. The action handler can also drop these packets by calling the 797 * rte_pktmbuf_free() function, although a better alternative is provided by 798 * the action handler using the rte_pipeline_ah_packet_drop() function. 799 * 800 * @param p 801 * Handle to pipeline instance 802 * @param pkts_mask 803 * 64-bit bitmask specifying which of the packets handed over for processing 804 * to the action handler is to be hijacked by the action handler. When 805 * pkts_mask bit n is set, then element n of the pkts array (input argument to 806 * the action handler) is hijacked. 807 * @return 808 * 0 on success, error code otherwise 809 */ 810 int rte_pipeline_ah_packet_hijack(struct rte_pipeline *p, 811 uint64_t pkts_mask); 812 813 /** 814 * Action handler packet drop 815 * 816 * This function is called by the pipeline action handlers (port in/out, table) 817 * to drop the packets selected using packet mask. 818 * 819 * This function can be called by any input/output port or table action handler 820 * to drop selected packets from the burst of packets read from one of the 821 * pipeline input ports and currently processed by the pipeline. The dropped 822 * packets are removed from any further pipeline processing and the packet 823 * buffers are eventually freed to their buffer pool. 824 * 825 * This function updates the drop statistics counters correctly, therefore the 826 * recommended approach for dropping packets by the action handlers is to call 827 * this function as opposed to the action handler hijacking the packets first 828 * and then dropping them invisibly to the pipeline (by using the 829 * rte_pktmbuf_free() function). 830 * 831 * @param p 832 * Handle to pipeline instance 833 * @param pkts_mask 834 * 64-bit bitmask specifying which of the packets handed over for processing 835 * to the action handler is to be dropped by the action handler. When 836 * pkts_mask bit n is set, then element n of the pkts array (input argument to 837 * the action handler) is dropped. 838 * @return 839 * 0 on success, error code otherwise 840 */ 841 int rte_pipeline_ah_packet_drop(struct rte_pipeline *p, 842 uint64_t pkts_mask); 843 844 #ifdef __cplusplus 845 } 846 #endif 847 848 #endif 849