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