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