lib/librte_pipeline/rte_pipeline.h

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