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 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  * Pipeline table entry add bulk
 470  *
 471  * @param p
 472  *   Handle to pipeline instance
 473  * @param table_id
 474  *   Table ID (returned by previous invocation of pipeline table create)
 475  * @param keys
 476  *   Array containing table entry keys
 477  * @param entries
 478  *   Array containung new contents for every table entry identified by key
 479  * @param n_keys
 480  *   Number of keys to add
 481  * @param key_found
 482  *   On successful invocation, key_found for every item in the array is set to
 483  *   TRUE (value different than 0) if key was already present in the table
 484  *   before the add operation and to FALSE (value 0) if not
 485  * @param entries_ptr
 486  *   On successful invocation, array *entries_ptr stores pointer to every table
 487  *   entry associated with key. This can be used for further read-write accesses
 488  *   to this table entry and is valid until the key is deleted from the table or
 489  *   re-added (usually for associating different actions and/or action meta-data
 490  *   to the current key)
 491  * @return
 492  *   0 on success, error code otherwise
 493  */
 494 int rte_pipeline_table_entry_add_bulk(struct rte_pipeline *p,
 495         uint32_t table_id,
 496         void **keys,
 497         struct rte_pipeline_table_entry **entries,
 498         uint32_t n_keys,
 499         int *key_found,
 500         struct rte_pipeline_table_entry **entries_ptr);
 501
 502 /**
 503  * Pipeline table entry delete bulk
 504  *
 505  * @param p
 506  *   Handle to pipeline instance
 507  * @param table_id
 508  *   Table ID (returned by previous invocation of pipeline table create)
 509  * @param keys
 510  *   Array containing table entry keys
 511  * @param n_keys
 512  *   Number of keys to delete
 513  * @param key_found
 514  *   On successful invocation, key_found for every item in the array is set to
 515  *   TRUE (value different than 0) if key was found in the table before the
 516  *   delete operation and to FALSE (value 0) if not
 517  * @param entries
 518  *   If entries pointer is NULL, this pointer is ignored for every entry found.
 519  *   Else, after successful invocation, if specific key is found in the table
 520  *   and entry points to a valid buffer, the table entry contents (as it was
 521  *   before the delete was performed) is copied to this buffer.
 522  * @return
 523  *   0 on success, error code otherwise
 524  */
 525 int rte_pipeline_table_entry_delete_bulk(struct rte_pipeline *p,
 526         uint32_t table_id,
 527         void **keys,
 528         uint32_t n_keys,
 529         int *key_found,
 530         struct rte_pipeline_table_entry **entries);
 531
 532 /**
 533  * Read pipeline table stats.
 534  *
 535  * This function reads table statistics identified by *table_id* of given
 536  * pipeline *p*.
 537  *
 538  * @param p
 539  *   Handle to pipeline instance.
 540  * @param table_id
 541  *   Port ID what stats will be returned.
 542  * @param stats
 543  *   Statistics buffer.
 544  * @param clear
 545  *   If not 0 clear stats after reading.
 546  * @return
 547  *   0 on success, error code otherwise
 548  */
 549 int rte_pipeline_table_stats_read(struct rte_pipeline *p, uint32_t table_id,
 550         struct rte_pipeline_table_stats *stats, int clear);
 551
 552 /*
 553  * Port IN
 554  *
 555  */
 556 /** Maximum number of input ports allowed for any given pipeline instance. The
 557         value of this parameter cannot be changed. */
 558 #define RTE_PIPELINE_PORT_IN_MAX                                    64
 559
 560 /**
 561  * Pipeline input port action handler
 562  *
 563  * The action handler can decide to drop packets by resetting the associated
 564  * packet bit in the pkts_mask parameter. In this case, the action handler is
 565  * required not to free the packet buffer, which will be freed eventually by
 566  * the pipeline.
 567  *
 568  * @param pkts
 569  *   Burst of input packets specified as array of up to 64 pointers to struct
 570  *   rte_mbuf
 571  * @param n
 572  *   Number of packets in the input burst. This parameter specifies that
 573  *   elements 0 to (n-1) of pkts array are valid.
 574  * @param pkts_mask
 575  *   64-bit bitmask specifying which packets in the input burst are still valid
 576  *   after the action handler is executed. When pkts_mask bit n is set, then
 577  *   element n of pkts array is pointing to a valid packet.
 578  * @param arg
 579  *   Opaque parameter registered by the user at the pipeline table creation
 580  *   time
 581  * @return
 582  *   0 on success, error code otherwise
 583  */
 584 typedef int (*rte_pipeline_port_in_action_handler)(
 585         struct rte_mbuf **pkts,
 586         uint32_t n,
 587         uint64_t *pkts_mask,
 588         void *arg);
 589
 590 /** Parameters for pipeline input port creation */
 591 struct rte_pipeline_port_in_params {
 592         /** Input port operations (specific to each table type) */
 593         struct rte_port_in_ops *ops;
 594         /** Opaque parameter to be passed to create operation when invoked */
 595         void *arg_create;
 596
 597         /** Callback function to execute the user actions on input packets.
 598                 Disabled if set to NULL. */
 599         rte_pipeline_port_in_action_handler f_action;
 600         /** Opaque parameter to be passed to the action handler when invoked */
 601         void *arg_ah;
 602
 603         /** Recommended burst size for the RX operation(in number of pkts) */
 604         uint32_t burst_size;
 605 };
 606
 607 /**
 608  * Pipeline input port create
 609  *
 610  * @param p
 611  *   Handle to pipeline instance
 612  * @param params
 613  *   Parameters for pipeline input port creation
 614  * @param port_id
 615  *   Input port ID. Valid only within the scope of input port IDs of the
 616  *   current pipeline. Only returned after a successful invocation.
 617  * @return
 618  *   0 on success, error code otherwise
 619  */
 620 int rte_pipeline_port_in_create(struct rte_pipeline *p,
 621         struct rte_pipeline_port_in_params *params,
 622         uint32_t *port_id);
 623
 624 /**
 625  * Pipeline input port connect to table
 626  *
 627  * @param p
 628  *   Handle to pipeline instance
 629  * @param port_id
 630  *   Port ID (returned by previous invocation of pipeline input port create)
 631  * @param table_id
 632  *   Table ID (returned by previous invocation of pipeline table create)
 633  * @return
 634  *   0 on success, error code otherwise
 635  */
 636 int rte_pipeline_port_in_connect_to_table(struct rte_pipeline *p,
 637         uint32_t port_id,
 638         uint32_t table_id);
 639
 640 /**
 641  * Pipeline input port enable
 642  *
 643  * @param p
 644  *   Handle to pipeline instance
 645  * @param port_id
 646  *   Port ID (returned by previous invocation of pipeline input port create)
 647  * @return
 648  *   0 on success, error code otherwise
 649  */
 650 int rte_pipeline_port_in_enable(struct rte_pipeline *p,
 651         uint32_t port_id);
 652
 653 /**
 654  * Pipeline input port disable
 655  *
 656  * @param p
 657  *   Handle to pipeline instance
 658  * @param port_id
 659  *   Port ID (returned by previous invocation of pipeline input port create)
 660  * @return
 661  *   0 on success, error code otherwise
 662  */
 663 int rte_pipeline_port_in_disable(struct rte_pipeline *p,
 664         uint32_t port_id);
 665
 666 /**
 667  * Read pipeline port in stats.
 668  *
 669  * This function reads port in statistics identified by *port_id* of given
 670  * pipeline *p*.
 671  *
 672  * @param p
 673  *   Handle to pipeline instance.
 674  * @param port_id
 675  *   Port ID what stats will be returned.
 676  * @param stats
 677  *   Statistics buffer.
 678  * @param clear
 679  *   If not 0 clear stats after reading.
 680  * @return
 681  *   0 on success, error code otherwise
 682  */
 683 int rte_pipeline_port_in_stats_read(struct rte_pipeline *p, uint32_t port_id,
 684         struct rte_pipeline_port_in_stats *stats, int clear);
 685
 686 /*
 687  * Port OUT
 688  *
 689  */
 690 /** Maximum number of output ports allowed for any given pipeline instance. The
 691         value of this parameter cannot be changed. */
 692 #define RTE_PIPELINE_PORT_OUT_MAX                                   64
 693
 694 /**
 695  * Pipeline output port action handler for single packet
 696  *
 697  * The action handler can decide to drop packets by resetting the pkt_mask
 698  * argument. In this case, the action handler is required not to free the
 699  * packet buffer, which will be freed eventually by the pipeline.
 700  *
 701  * @param pkt
 702  *   Input packet
 703  * @param pkt_mask
 704  *   Output argument set to 0 when the action handler decides to drop the input
 705  *   packet and to 1LLU otherwise
 706  * @param arg
 707  *   Opaque parameter registered by the user at the pipeline table creation
 708  *   time
 709  * @return
 710  *   0 on success, error code otherwise
 711  */
 712 typedef int (*rte_pipeline_port_out_action_handler)(
 713         struct rte_mbuf *pkt,
 714         uint64_t *pkt_mask,
 715         void *arg);
 716
 717 /**
 718  * Pipeline output port action handler bulk
 719  *
 720  * The action handler can decide to drop packets by resetting the associated
 721  * packet bit in the pkts_mask parameter. In this case, the action handler is
 722  * required not to free the packet buffer, which will be freed eventually by
 723  * the pipeline.
 724  *
 725  * @param pkts
 726  *   Burst of input packets specified as array of up to 64 pointers to struct
 727  *   rte_mbuf
 728  * @param pkts_mask
 729  *   64-bit bitmask specifying which packets in the input burst are valid. When
 730  *   pkts_mask bit n is set, then element n of pkts array is pointing to a
 731  *   valid packet. Otherwise, element n of pkts array will not be accessed.
 732  * @param arg
 733  *   Opaque parameter registered by the user at the pipeline table creation
 734  *   time
 735  * @return
 736  *   0 on success, error code otherwise
 737  */
 738 typedef int (*rte_pipeline_port_out_action_handler_bulk)(
 739         struct rte_mbuf **pkts,
 740         uint64_t *pkts_mask,
 741         void *arg);
 742
 743 /** Parameters for pipeline output port creation. The action handlers have to
 744 be either both enabled or both disabled (by setting them to NULL). When
 745 enabled, the pipeline selects between them at different moments, based on the
 746 number of packets that have to be sent to the same output port. */
 747 struct rte_pipeline_port_out_params {
 748         /** Output port operations (specific to each table type) */
 749         struct rte_port_out_ops *ops;
 750         /** Opaque parameter to be passed to create operation when invoked */
 751         void *arg_create;
 752
 753         /** Callback function executing the user actions on single input
 754         packet */
 755         rte_pipeline_port_out_action_handler f_action;
 756         /** Callback function executing the user actions on bust of input
 757         packets */
 758         rte_pipeline_port_out_action_handler_bulk f_action_bulk;
 759         /** Opaque parameter to be passed to the action handler when invoked */
 760         void *arg_ah;
 761 };
 762
 763 /**
 764  * Pipeline output port create
 765  *
 766  * @param p
 767  *   Handle to pipeline instance
 768  * @param params
 769  *   Parameters for pipeline output port creation
 770  * @param port_id
 771  *   Output port ID. Valid only within the scope of output port IDs of the
 772  *   current pipeline. Only returned after a successful invocation.
 773  * @return
 774  *   0 on success, error code otherwise
 775  */
 776 int rte_pipeline_port_out_create(struct rte_pipeline *p,
 777         struct rte_pipeline_port_out_params *params,
 778         uint32_t *port_id);
 779
 780 /**
 781  * Pipeline output port packet insert
 782  *
 783  * This function is called by the table action handler whenever it generates a
 784  * new packet to be sent out though one of the pipeline output ports. This
 785  * packet is not part of the burst of input packets read from any of the
 786  * pipeline input ports, so it is not an element of the pkts array input
 787  * parameter of the table action handler. This packet can be dropped by the
 788  * output port action handler.
 789  *
 790  * @param p
 791  *   Handle to pipeline instance
 792  * @param port_id
 793  *   Output port ID (returned by previous invocation of pipeline output port
 794  *   create) to send the packet specified by pkt
 795  * @param pkt
 796  *   New packet generated by the table action handler
 797  * @return
 798  *   0 on success, error code otherwise
 799  */
 800 int rte_pipeline_port_out_packet_insert(struct rte_pipeline *p,
 801         uint32_t port_id,
 802         struct rte_mbuf *pkt);
 803
 804 /**
 805  * Read pipeline port out stats.
 806  *
 807  * This function reads port out statistics identified by *port_id* of given
 808  * pipeline *p*.
 809  *
 810  * @param p
 811  *   Handle to pipeline instance.
 812  * @param port_id
 813  *   Port ID what stats will be returned.
 814  * @param stats
 815  *   Statistics buffer.
 816  * @param clear
 817  *   If not 0 clear stats after reading.
 818  * @return
 819  *   0 on success, error code otherwise
 820  */
 821 int rte_pipeline_port_out_stats_read(struct rte_pipeline *p, uint32_t port_id,
 822         struct rte_pipeline_port_out_stats *stats, int clear);
 823 #ifdef __cplusplus
 824 }
 825 #endif
 826
 827 #endif