lib/librte_pipeline/rte_pipeline.h

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