lib/librte_pipeline/rte_pipeline.h

   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