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 #include <stdint.h> 57 58 #include <rte_port.h> 59 #include <rte_table.h> 60 #include <rte_common.h> 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 RTE_STD_C11 216 union { 217 /** Output port ID (meta-data for "Send packet to output port" 218 action) */ 219 uint32_t port_id; 220 /** Table ID (meta-data for "Send packet to table" action) */ 221 uint32_t table_id; 222 }; 223 /** Start of table entry area for user defined actions and meta-data */ 224 __extension__ uint8_t action_data[0]; 225 }; 226 227 /** 228 * Pipeline table action handler on lookup hit 229 * 230 * The action handler can decide to drop packets by resetting the associated 231 * packet bit in the pkts_mask parameter. In this case, the action handler is 232 * required not to free the packet buffer, which will be freed eventually by 233 * the pipeline. 234 * 235 * @param p 236 * Handle to pipeline instance 237 * @param pkts 238 * Burst of input packets specified as array of up to 64 pointers to struct 239 * rte_mbuf 240 * @param pkts_mask 241 * 64-bit bitmask specifying which packets in the input burst are valid. When 242 * pkts_mask bit n is set, then element n of pkts array is pointing to a 243 * valid packet and element n of entries array is pointing to a valid table 244 * entry associated with the packet, with the association typically done by 245 * the table lookup operation. Otherwise, element n of pkts array and element 246 * n of entries array will not be accessed. 247 * @param entries 248 * Set of table entries specified as array of up to 64 pointers to struct 249 * rte_pipeline_table_entry 250 * @param arg 251 * Opaque parameter registered by the user at the pipeline table creation 252 * time 253 * @return 254 * 0 on success, error code otherwise 255 */ 256 typedef int (*rte_pipeline_table_action_handler_hit)( 257 struct rte_pipeline *p, 258 struct rte_mbuf **pkts, 259 uint64_t pkts_mask, 260 struct rte_pipeline_table_entry **entries, 261 void *arg); 262 263 /** 264 * Pipeline table action handler on lookup miss 265 * 266 * The action handler can decide to drop packets by resetting the associated 267 * packet bit in the pkts_mask parameter. In this case, the action handler is 268 * required not to free the packet buffer, which will be freed eventually by 269 * the pipeline. 270 * 271 * @param p 272 * Handle to pipeline instance 273 * @param pkts 274 * Burst of input packets specified as array of up to 64 pointers to struct 275 * rte_mbuf 276 * @param pkts_mask 277 * 64-bit bitmask specifying which packets in the input burst are valid. When 278 * pkts_mask bit n is set, then element n of pkts array is pointing to a 279 * valid packet. Otherwise, element n of pkts array will not be accessed. 280 * @param entry 281 * Single table entry associated with all the valid packets from the input 282 * burst, specified as pointer to struct rte_pipeline_table_entry. 283 * This entry is the pipeline table default entry that is associated by the 284 * table lookup operation with the input packets that have resulted in lookup 285 * miss. 286 * @param arg 287 * Opaque parameter registered by the user at the pipeline table creation 288 * time 289 * @return 290 * 0 on success, error code otherwise 291 */ 292 typedef int (*rte_pipeline_table_action_handler_miss)( 293 struct rte_pipeline *p, 294 struct rte_mbuf **pkts, 295 uint64_t pkts_mask, 296 struct rte_pipeline_table_entry *entry, 297 void *arg); 298 299 /** Parameters for pipeline table creation. Action handlers have to be either 300 both enabled or both disabled (they can be disabled by setting them to 301 NULL). */ 302 struct rte_pipeline_table_params { 303 /** Table operations (specific to each table type) */ 304 struct rte_table_ops *ops; 305 /** Opaque param to be passed to the table create operation when 306 invoked */ 307 void *arg_create; 308 /** Callback function to execute the user actions on input packets in 309 case of lookup hit */ 310 rte_pipeline_table_action_handler_hit f_action_hit; 311 /** Callback function to execute the user actions on input packets in 312 case of lookup miss */ 313 rte_pipeline_table_action_handler_miss f_action_miss; 314 315 /** Opaque parameter to be passed to lookup hit and/or lookup miss 316 action handlers when invoked */ 317 void *arg_ah; 318 /** Memory size to be reserved per table entry for storing the user 319 actions and their meta-data */ 320 uint32_t action_data_size; 321 }; 322 323 /** 324 * Pipeline table create 325 * 326 * @param p 327 * Handle to pipeline instance 328 * @param params 329 * Parameters for pipeline table creation 330 * @param table_id 331 * Table ID. Valid only within the scope of table IDs of the current 332 * pipeline. Only returned after a successful invocation. 333 * @return 334 * 0 on success, error code otherwise 335 */ 336 int rte_pipeline_table_create(struct rte_pipeline *p, 337 struct rte_pipeline_table_params *params, 338 uint32_t *table_id); 339 340 /** 341 * Pipeline table default entry add 342 * 343 * The contents of the table default entry is updated with the provided actions 344 * and meta-data. When the default entry is not configured (by using this 345 * function), the built-in default entry has the action "Drop" and meta-data 346 * set to all-zeros. 347 * 348 * @param p 349 * Handle to pipeline instance 350 * @param table_id 351 * Table ID (returned by previous invocation of pipeline table create) 352 * @param default_entry 353 * New contents for the table default entry 354 * @param default_entry_ptr 355 * On successful invocation, pointer to the default table entry which can be 356 * used for further read-write accesses to this table entry. This pointer 357 * is valid until the default entry is deleted or re-added. 358 * @return 359 * 0 on success, error code otherwise 360 */ 361 int rte_pipeline_table_default_entry_add(struct rte_pipeline *p, 362 uint32_t table_id, 363 struct rte_pipeline_table_entry *default_entry, 364 struct rte_pipeline_table_entry **default_entry_ptr); 365 366 /** 367 * Pipeline table default entry delete 368 * 369 * The new contents of the table default entry is set to reserved action "Drop 370 * the packet" with meta-data cleared (i.e. set to all-zeros). 371 * 372 * @param p 373 * Handle to pipeline instance 374 * @param table_id 375 * Table ID (returned by previous invocation of pipeline table create) 376 * @param entry 377 * On successful invocation, when entry points to a valid buffer, the 378 * previous contents of the table default entry (as it was just before the 379 * delete operation) is copied to this buffer 380 * @return 381 * 0 on success, error code otherwise 382 */ 383 int rte_pipeline_table_default_entry_delete(struct rte_pipeline *p, 384 uint32_t table_id, 385 struct rte_pipeline_table_entry *entry); 386 387 /** 388 * Pipeline table entry add 389 * 390 * @param p 391 * Handle to pipeline instance 392 * @param table_id 393 * Table ID (returned by previous invocation of pipeline table create) 394 * @param key 395 * Table entry key 396 * @param entry 397 * New contents for the table entry identified by key 398 * @param key_found 399 * On successful invocation, set to TRUE (value different than 0) if key was 400 * already present in the table before the add operation and to FALSE (value 401 * 0) if not 402 * @param entry_ptr 403 * On successful invocation, pointer to the table entry associated with key. 404 * This can be used for further read-write accesses to this table entry and 405 * is valid until the key is deleted from the table or re-added (usually for 406 * associating different actions and/or action meta-data to the current key) 407 * @return 408 * 0 on success, error code otherwise 409 */ 410 int rte_pipeline_table_entry_add(struct rte_pipeline *p, 411 uint32_t table_id, 412 void *key, 413 struct rte_pipeline_table_entry *entry, 414 int *key_found, 415 struct rte_pipeline_table_entry **entry_ptr); 416 417 /** 418 * Pipeline table entry delete 419 * 420 * @param p 421 * Handle to pipeline instance 422 * @param table_id 423 * Table ID (returned by previous invocation of pipeline table create) 424 * @param key 425 * Table entry key 426 * @param key_found 427 * On successful invocation, set to TRUE (value different than 0) if key was 428 * found in the table before the delete operation and to FALSE (value 0) if 429 * not 430 * @param entry 431 * On successful invocation, when key is found in the table and entry points 432 * to a valid buffer, the table entry contents (as it was before the delete 433 * was performed) is copied to this buffer 434 * @return 435 * 0 on success, error code otherwise 436 */ 437 int rte_pipeline_table_entry_delete(struct rte_pipeline *p, 438 uint32_t table_id, 439 void *key, 440 int *key_found, 441 struct rte_pipeline_table_entry *entry); 442 443 /** 444 * Pipeline table entry add bulk 445 * 446 * @param p 447 * Handle to pipeline instance 448 * @param table_id 449 * Table ID (returned by previous invocation of pipeline table create) 450 * @param keys 451 * Array containing table entry keys 452 * @param entries 453 * Array containing new contents for every table entry identified by key 454 * @param n_keys 455 * Number of keys to add 456 * @param key_found 457 * On successful invocation, key_found for every item in the array is set to 458 * TRUE (value different than 0) if key was already present in the table 459 * before the add operation and to FALSE (value 0) if not 460 * @param entries_ptr 461 * On successful invocation, array *entries_ptr stores pointer to every table 462 * entry associated with key. This can be used for further read-write accesses 463 * to this table entry and is valid until the key is deleted from the table or 464 * re-added (usually for associating different actions and/or action meta-data 465 * to the current key) 466 * @return 467 * 0 on success, error code otherwise 468 */ 469 int rte_pipeline_table_entry_add_bulk(struct rte_pipeline *p, 470 uint32_t table_id, 471 void **keys, 472 struct rte_pipeline_table_entry **entries, 473 uint32_t n_keys, 474 int *key_found, 475 struct rte_pipeline_table_entry **entries_ptr); 476 477 /** 478 * Pipeline table entry delete bulk 479 * 480 * @param p 481 * Handle to pipeline instance 482 * @param table_id 483 * Table ID (returned by previous invocation of pipeline table create) 484 * @param keys 485 * Array containing table entry keys 486 * @param n_keys 487 * Number of keys to delete 488 * @param key_found 489 * On successful invocation, key_found for every item in the array is set to 490 * TRUE (value different than 0) if key was found in the table before the 491 * delete operation and to FALSE (value 0) if not 492 * @param entries 493 * If entries pointer is NULL, this pointer is ignored for every entry found. 494 * Else, after successful invocation, if specific key is found in the table 495 * and entry points to a valid buffer, the table entry contents (as it was 496 * before the delete was performed) is copied to this buffer. 497 * @return 498 * 0 on success, error code otherwise 499 */ 500 int rte_pipeline_table_entry_delete_bulk(struct rte_pipeline *p, 501 uint32_t table_id, 502 void **keys, 503 uint32_t n_keys, 504 int *key_found, 505 struct rte_pipeline_table_entry **entries); 506 507 /** 508 * Read pipeline table stats. 509 * 510 * This function reads table statistics identified by *table_id* of given 511 * pipeline *p*. 512 * 513 * @param p 514 * Handle to pipeline instance. 515 * @param table_id 516 * Port ID what stats will be returned. 517 * @param stats 518 * Statistics buffer. 519 * @param clear 520 * If not 0 clear stats after reading. 521 * @return 522 * 0 on success, error code otherwise 523 */ 524 int rte_pipeline_table_stats_read(struct rte_pipeline *p, uint32_t table_id, 525 struct rte_pipeline_table_stats *stats, int clear); 526 527 /* 528 * Port IN 529 */ 530 /** Maximum number of input ports allowed for any given pipeline instance. The 531 value of this parameter cannot be changed. */ 532 #define RTE_PIPELINE_PORT_IN_MAX 64 533 534 /** 535 * Pipeline input port action handler 536 * 537 * The action handler can decide to drop packets by resetting the associated 538 * packet bit in the pkts_mask parameter. In this case, the action handler is 539 * required not to free the packet buffer, which will be freed eventually by 540 * the pipeline. 541 * 542 * @param p 543 * Handle to pipeline instance 544 * @param pkts 545 * Burst of input packets specified as array of up to 64 pointers to struct 546 * rte_mbuf 547 * @param n 548 * Number of packets in the input burst. This parameter specifies that 549 * elements 0 to (n-1) of pkts array are valid. 550 * @param arg 551 * Opaque parameter registered by the user at the pipeline table creation 552 * time 553 * @return 554 * 0 on success, error code otherwise 555 */ 556 typedef int (*rte_pipeline_port_in_action_handler)( 557 struct rte_pipeline *p, 558 struct rte_mbuf **pkts, 559 uint32_t n, 560 void *arg); 561 562 /** Parameters for pipeline input port creation */ 563 struct rte_pipeline_port_in_params { 564 /** Input port operations (specific to each table type) */ 565 struct rte_port_in_ops *ops; 566 /** Opaque parameter to be passed to create operation when invoked */ 567 void *arg_create; 568 569 /** Callback function to execute the user actions on input packets. 570 Disabled if set to NULL. */ 571 rte_pipeline_port_in_action_handler f_action; 572 /** Opaque parameter to be passed to the action handler when invoked */ 573 void *arg_ah; 574 575 /** Recommended burst size for the RX operation(in number of pkts) */ 576 uint32_t burst_size; 577 }; 578 579 /** 580 * Pipeline input port create 581 * 582 * @param p 583 * Handle to pipeline instance 584 * @param params 585 * Parameters for pipeline input port creation 586 * @param port_id 587 * Input port ID. Valid only within the scope of input port IDs of the 588 * current pipeline. Only returned after a successful invocation. 589 * @return 590 * 0 on success, error code otherwise 591 */ 592 int rte_pipeline_port_in_create(struct rte_pipeline *p, 593 struct rte_pipeline_port_in_params *params, 594 uint32_t *port_id); 595 596 /** 597 * Pipeline input port connect to table 598 * 599 * @param p 600 * Handle to pipeline instance 601 * @param port_id 602 * Port ID (returned by previous invocation of pipeline input port create) 603 * @param table_id 604 * Table ID (returned by previous invocation of pipeline table create) 605 * @return 606 * 0 on success, error code otherwise 607 */ 608 int rte_pipeline_port_in_connect_to_table(struct rte_pipeline *p, 609 uint32_t port_id, 610 uint32_t table_id); 611 612 /** 613 * Pipeline input port enable 614 * 615 * @param p 616 * Handle to pipeline instance 617 * @param port_id 618 * Port ID (returned by previous invocation of pipeline input port create) 619 * @return 620 * 0 on success, error code otherwise 621 */ 622 int rte_pipeline_port_in_enable(struct rte_pipeline *p, 623 uint32_t port_id); 624 625 /** 626 * Pipeline input port disable 627 * 628 * @param p 629 * Handle to pipeline instance 630 * @param port_id 631 * Port ID (returned by previous invocation of pipeline input port create) 632 * @return 633 * 0 on success, error code otherwise 634 */ 635 int rte_pipeline_port_in_disable(struct rte_pipeline *p, 636 uint32_t port_id); 637 638 /** 639 * Read pipeline port in stats. 640 * 641 * This function reads port in statistics identified by *port_id* of given 642 * pipeline *p*. 643 * 644 * @param p 645 * Handle to pipeline instance. 646 * @param port_id 647 * Port ID what stats will be returned. 648 * @param stats 649 * Statistics buffer. 650 * @param clear 651 * If not 0 clear stats after reading. 652 * @return 653 * 0 on success, error code otherwise 654 */ 655 int rte_pipeline_port_in_stats_read(struct rte_pipeline *p, uint32_t port_id, 656 struct rte_pipeline_port_in_stats *stats, int clear); 657 658 /* 659 * Port OUT 660 */ 661 /** Maximum number of output ports allowed for any given pipeline instance. The 662 value of this parameter cannot be changed. */ 663 #define RTE_PIPELINE_PORT_OUT_MAX 64 664 665 /** 666 * Pipeline output port action handler 667 * 668 * The action handler can decide to drop packets by resetting the associated 669 * packet bit in the pkts_mask parameter. In this case, the action handler is 670 * required not to free the packet buffer, which will be freed eventually by 671 * the pipeline. 672 * 673 * @param p 674 * Handle to pipeline instance 675 * @param pkts 676 * Burst of input packets specified as array of up to 64 pointers to struct 677 * rte_mbuf 678 * @param pkts_mask 679 * 64-bit bitmask specifying which packets in the input burst are valid. When 680 * pkts_mask bit n is set, then element n of pkts array is pointing to a 681 * valid packet. Otherwise, element n of pkts array will not be accessed. 682 * @param arg 683 * Opaque parameter registered by the user at the pipeline table creation 684 * time 685 * @return 686 * 0 on success, error code otherwise 687 */ 688 typedef int (*rte_pipeline_port_out_action_handler)( 689 struct rte_pipeline *p, 690 struct rte_mbuf **pkts, 691 uint64_t pkts_mask, 692 void *arg); 693 694 /** Parameters for pipeline output port creation. The action handlers have to 695 be either both enabled or both disabled (by setting them to NULL). When 696 enabled, the pipeline selects between them at different moments, based on the 697 number of packets that have to be sent to the same output port. */ 698 struct rte_pipeline_port_out_params { 699 /** Output port operations (specific to each table type) */ 700 struct rte_port_out_ops *ops; 701 /** Opaque parameter to be passed to create operation when invoked */ 702 void *arg_create; 703 704 /** Callback function executing the user actions on bust of input 705 packets */ 706 rte_pipeline_port_out_action_handler f_action; 707 /** Opaque parameter to be passed to the action handler when invoked */ 708 void *arg_ah; 709 }; 710 711 /** 712 * Pipeline output port create 713 * 714 * @param p 715 * Handle to pipeline instance 716 * @param params 717 * Parameters for pipeline output port creation 718 * @param port_id 719 * Output port ID. Valid only within the scope of output port IDs of the 720 * current pipeline. Only returned after a successful invocation. 721 * @return 722 * 0 on success, error code otherwise 723 */ 724 int rte_pipeline_port_out_create(struct rte_pipeline *p, 725 struct rte_pipeline_port_out_params *params, 726 uint32_t *port_id); 727 728 /** 729 * Read pipeline port out stats. 730 * 731 * This function reads port out statistics identified by *port_id* of given 732 * pipeline *p*. 733 * 734 * @param p 735 * Handle to pipeline instance. 736 * @param port_id 737 * Port ID what stats will be returned. 738 * @param stats 739 * Statistics buffer. 740 * @param clear 741 * If not 0 clear stats after reading. 742 * @return 743 * 0 on success, error code otherwise 744 */ 745 int rte_pipeline_port_out_stats_read(struct rte_pipeline *p, uint32_t port_id, 746 struct rte_pipeline_port_out_stats *stats, int clear); 747 748 /* 749 * Functions to be called as part of the port IN/OUT or table action handlers 750 */ 751 /** 752 * Action handler packet insert to output port 753 * 754 * This function can be called by any input/output port or table action handler 755 * to send a packet out through one of the pipeline output ports. This packet is 756 * generated by the action handler, i.e. this packet is not part of the burst of 757 * packets read from one of the pipeline input ports and currently processed by 758 * the pipeline (this packet is not an element of the pkts array input parameter 759 * of the action handler). 760 * 761 * @param p 762 * Handle to pipeline instance 763 * @param port_id 764 * Output port ID (returned by previous invocation of pipeline output port 765 * create) to send the packet specified by pkt 766 * @param pkt 767 * New packet generated by the action handler 768 * @return 769 * 0 on success, error code otherwise 770 */ 771 int rte_pipeline_port_out_packet_insert(struct rte_pipeline *p, 772 uint32_t port_id, 773 struct rte_mbuf *pkt); 774 775 #define rte_pipeline_ah_port_out_packet_insert \ 776 rte_pipeline_port_out_packet_insert 777 778 /** 779 * Action handler packet hijack 780 * 781 * This function can be called by any input/output port or table action handler 782 * to hijack selected packets from the burst of packets read from one of the 783 * pipeline input ports and currently processed by the pipeline. The hijacked 784 * packets are removed from any further pipeline processing, with the action 785 * handler now having the full ownership for these packets. 786 * 787 * The action handler can further send the hijacked packets out through any 788 * pipeline output port by calling the rte_pipeline_ah_port_out_packet_insert() 789 * function. The action handler can also drop these packets by calling the 790 * rte_pktmbuf_free() function, although a better alternative is provided by 791 * the action handler using the rte_pipeline_ah_packet_drop() function. 792 * 793 * @param p 794 * Handle to pipeline instance 795 * @param pkts_mask 796 * 64-bit bitmask specifying which of the packets handed over for processing 797 * to the action handler is to be hijacked by the action handler. When 798 * pkts_mask bit n is set, then element n of the pkts array (input argument to 799 * the action handler) is hijacked. 800 * @return 801 * 0 on success, error code otherwise 802 */ 803 int rte_pipeline_ah_packet_hijack(struct rte_pipeline *p, 804 uint64_t pkts_mask); 805 806 /** 807 * Action handler packet drop 808 * 809 * This function is called by the pipeline action handlers (port in/out, table) 810 * to drop the packets selected using packet mask. 811 * 812 * This function can be called by any input/output port or table action handler 813 * to drop selected packets from the burst of packets read from one of the 814 * pipeline input ports and currently processed by the pipeline. The dropped 815 * packets are removed from any further pipeline processing and the packet 816 * buffers are eventually freed to their buffer pool. 817 * 818 * This function updates the drop statistics counters correctly, therefore the 819 * recommended approach for dropping packets by the action handlers is to call 820 * this function as opposed to the action handler hijacking the packets first 821 * and then dropping them invisibly to the pipeline (by using the 822 * rte_pktmbuf_free() function). 823 * 824 * @param p 825 * Handle to pipeline instance 826 * @param pkts_mask 827 * 64-bit bitmask specifying which of the packets handed over for processing 828 * to the action handler is to be dropped by the action handler. When 829 * pkts_mask bit n is set, then element n of the pkts array (input argument to 830 * the action handler) is dropped. 831 * @return 832 * 0 on success, error code otherwise 833 */ 834 int rte_pipeline_ah_packet_drop(struct rte_pipeline *p, 835 uint64_t pkts_mask); 836 837 #ifdef __cplusplus 838 } 839 #endif 840 841 #endif 842