Provided by: dpdk-doc_24.11.2-2_all bug

NAME

       rte_pipeline.h

SYNOPSIS

       #include <stdint.h>
       #include <rte_port.h>
       #include <rte_table.h>
       #include <rte_common.h>

   Data Structures
       struct rte_pipeline_params
       struct rte_pipeline_port_in_stats
       struct rte_pipeline_port_out_stats
       struct rte_pipeline_table_stats
       struct rte_pipeline_table_entry
       struct rte_pipeline_table_params
       struct rte_pipeline_port_in_params
       struct rte_pipeline_port_out_params

   Macros
       #define RTE_PIPELINE_TABLE_MAX   64
       #define RTE_PIPELINE_PORT_IN_MAX   64
       #define RTE_PIPELINE_PORT_OUT_MAX   64

   Typedefs
       typedef int(* rte_pipeline_table_action_handler_hit) (struct rte_pipeline *p, struct rte_mbuf **pkts,
           uint64_t pkts_mask, struct rte_pipeline_table_entry **entries, void *arg)
       typedef int(* rte_pipeline_table_action_handler_miss) (struct rte_pipeline *p, struct rte_mbuf **pkts,
           uint64_t pkts_mask, struct rte_pipeline_table_entry *entry, void *arg)
       typedef int(* rte_pipeline_port_in_action_handler) (struct rte_pipeline *p, struct rte_mbuf **pkts,
           uint32_t n, void *arg)
       typedef int(* rte_pipeline_port_out_action_handler) (struct rte_pipeline *p, struct rte_mbuf **pkts,
           uint64_t pkts_mask, void *arg)

   Enumerations
       enum rte_pipeline_action { RTE_PIPELINE_ACTION_DROP = 0, RTE_PIPELINE_ACTION_PORT,
           RTE_PIPELINE_ACTION_PORT_META, RTE_PIPELINE_ACTION_TABLE, RTE_PIPELINE_ACTIONS }

   Functions
       struct rte_pipeline * rte_pipeline_create (struct rte_pipeline_params *params)
       int rte_pipeline_free (struct rte_pipeline *p)
       int rte_pipeline_check (struct rte_pipeline *p)
       int rte_pipeline_run (struct rte_pipeline *p)
       int rte_pipeline_flush (struct rte_pipeline *p)
       int rte_pipeline_table_create (struct rte_pipeline *p, struct rte_pipeline_table_params *params, uint32_t
           *table_id)
       int rte_pipeline_table_default_entry_add (struct rte_pipeline *p, uint32_t table_id, struct
           rte_pipeline_table_entry *default_entry, struct rte_pipeline_table_entry **default_entry_ptr)
       int rte_pipeline_table_default_entry_delete (struct rte_pipeline *p, uint32_t table_id, struct
           rte_pipeline_table_entry *entry)
       int rte_pipeline_table_entry_add (struct rte_pipeline *p, uint32_t table_id, void *key, struct
           rte_pipeline_table_entry *entry, int *key_found, struct rte_pipeline_table_entry **entry_ptr)
       int rte_pipeline_table_entry_delete (struct rte_pipeline *p, uint32_t table_id, void *key, int
           *key_found, struct rte_pipeline_table_entry *entry)
       int rte_pipeline_table_entry_add_bulk (struct rte_pipeline *p, uint32_t table_id, void **keys, struct
           rte_pipeline_table_entry **entries, uint32_t n_keys, int *key_found, struct rte_pipeline_table_entry
           **entries_ptr)
       int rte_pipeline_table_entry_delete_bulk (struct rte_pipeline *p, uint32_t table_id, void **keys,
           uint32_t n_keys, int *key_found, struct rte_pipeline_table_entry **entries)
       int rte_pipeline_table_stats_read (struct rte_pipeline *p, uint32_t table_id, struct
           rte_pipeline_table_stats *stats, int clear)
       int rte_pipeline_port_in_create (struct rte_pipeline *p, struct rte_pipeline_port_in_params *params,
           uint32_t *port_id)
       int rte_pipeline_port_in_connect_to_table (struct rte_pipeline *p, uint32_t port_id, uint32_t table_id)
       int rte_pipeline_port_in_enable (struct rte_pipeline *p, uint32_t port_id)
       int rte_pipeline_port_in_disable (struct rte_pipeline *p, uint32_t port_id)
       int rte_pipeline_port_in_stats_read (struct rte_pipeline *p, uint32_t port_id, struct
           rte_pipeline_port_in_stats *stats, int clear)
       int rte_pipeline_port_out_create (struct rte_pipeline *p, struct rte_pipeline_port_out_params *params,
           uint32_t *port_id)
       int rte_pipeline_port_out_stats_read (struct rte_pipeline *p, uint32_t port_id, struct
           rte_pipeline_port_out_stats *stats, int clear)
       int rte_pipeline_port_out_packet_insert (struct rte_pipeline *p, uint32_t port_id, struct rte_mbuf *pkt)
       int rte_pipeline_ah_packet_hijack (struct rte_pipeline *p, uint64_t pkts_mask)
       int rte_pipeline_ah_packet_drop (struct rte_pipeline *p, uint64_t pkts_mask)

Detailed Description

       RTE Pipeline

       This tool is part of the DPDK Packet Framework tool suite and provides a standard methodology (logically
       similar to OpenFlow) for rapid development of complex packet processing pipelines out of ports, tables
       and actions.

       Basic operation. A pipeline is constructed by connecting its input ports to its output ports through a
       chain of lookup tables. As result of lookup operation into the current table, one of the table entries
       (or the default table entry, in case of lookup miss) is identified to provide the actions to be executed
       on the current packet and the associated action meta-data. The behavior of user actions is defined
       through the configurable table action handler, while the reserved actions define the next hop for the
       current packet (either another table, an output port or packet drop) and are handled transparently by the
       framework.

       Initialization and run-time flows. Once all the pipeline elements (input ports, tables, output ports)
       have been created, input ports connected to tables, table action handlers configured, tables populated
       with the initial set of entries (actions and action meta-data) and input ports enabled, the pipeline runs
       automatically, pushing packets from input ports to tables and output ports. At each table, the identified
       user actions are being executed, resulting in action meta-data (stored in the table entry) and packet
       meta-data (stored with the packet descriptor) being updated. The pipeline tables can have further updates
       and input ports can be disabled or enabled later on as required.

       Multi-core scaling. Typically, each CPU core will run its own pipeline instance. Complex application-
       level pipelines can be implemented by interconnecting multiple CPU core-level pipelines in tree-like
       topologies, as the same port devices (e.g. SW rings) can serve as output ports for the pipeline running
       on CPU core A, as well as input ports for the pipeline running on CPU core B. This approach enables the
       application development using the pipeline (CPU cores connected serially), cluster/run-to-completion (CPU
       cores connected in parallel) or mixed (pipeline of CPU core clusters) programming models.

       Thread safety. It is possible to have multiple pipelines running on the same CPU core, but it is not
       allowed (for thread safety reasons) to have multiple CPU cores running the same pipeline instance.

       Definition in file rte_pipeline.h.

Macro Definition Documentation

   #define RTE_PIPELINE_TABLE_MAX   64
       Maximum number of tables allowed for any given pipeline instance. The value of this parameter cannot be
       changed.

       Definition at line 200 of file rte_pipeline.h.

   #define RTE_PIPELINE_PORT_IN_MAX   64
       Maximum number of input ports allowed for any given pipeline instance. The value of this parameter cannot
       be changed.

       Definition at line 531 of file rte_pipeline.h.

   #define RTE_PIPELINE_PORT_OUT_MAX   64
       Maximum number of output ports allowed for any given pipeline instance. The value of this parameter
       cannot be changed.

       Definition at line 662 of file rte_pipeline.h.

Typedef Documentation

   typedef int(* rte_pipeline_table_action_handler_hit) (struct rte_pipeline *p, struct rte_mbuf **pkts,
       uint64_t pkts_mask, struct rte_pipeline_table_entry **entries, void *arg)
       Pipeline table action handler on lookup hit

       The action handler can decide to drop packets by resetting the associated packet bit in the pkts_mask
       parameter. In this case, the action handler is required not to free the packet buffer, which will be
       freed eventually by the pipeline.

       Parameters
           p Handle to pipeline instance
           pkts Burst of input packets specified as array of up to 64 pointers to struct rte_mbuf
           pkts_mask 64-bit bitmask specifying which packets in the input burst are valid. When pkts_mask bit n
           is set, then element n of pkts array is pointing to a valid packet and element n of entries array is
           pointing to a valid table entry associated with the packet, with the association typically done by
           the table lookup operation. Otherwise, element n of pkts array and element n of entries array will
           not be accessed.
           entries Set of table entries specified as array of up to 64 pointers to struct
           rte_pipeline_table_entry
           arg Opaque parameter registered by the user at the pipeline table creation time

       Returns
           0 on success, error code otherwise

       Definition at line 255 of file rte_pipeline.h.

   typedef int(* rte_pipeline_table_action_handler_miss) (struct rte_pipeline *p, struct rte_mbuf **pkts,
       uint64_t pkts_mask, struct rte_pipeline_table_entry *entry, void *arg)
       Pipeline table action handler on lookup miss

       The action handler can decide to drop packets by resetting the associated packet bit in the pkts_mask
       parameter. In this case, the action handler is required not to free the packet buffer, which will be
       freed eventually by the pipeline.

       Parameters
           p Handle to pipeline instance
           pkts Burst of input packets specified as array of up to 64 pointers to struct rte_mbuf
           pkts_mask 64-bit bitmask specifying which packets in the input burst are valid. When pkts_mask bit n
           is set, then element n of pkts array is pointing to a valid packet. Otherwise, element n of pkts
           array will not be accessed.
           entry Single table entry associated with all the valid packets from the input burst, specified as
           pointer to struct rte_pipeline_table_entry. This entry is the pipeline table default entry that is
           associated by the table lookup operation with the input packets that have resulted in lookup miss.
           arg Opaque parameter registered by the user at the pipeline table creation time

       Returns
           0 on success, error code otherwise

       Definition at line 291 of file rte_pipeline.h.

   typedef int(* rte_pipeline_port_in_action_handler) (struct rte_pipeline *p, struct rte_mbuf **pkts, uint32_t
       n, void *arg)
       Pipeline input port action handler

       The action handler can decide to drop packets by resetting the associated packet bit in the pkts_mask
       parameter. In this case, the action handler is required not to free the packet buffer, which will be
       freed eventually by the pipeline.

       Parameters
           p Handle to pipeline instance
           pkts Burst of input packets specified as array of up to 64 pointers to struct rte_mbuf
           n Number of packets in the input burst. This parameter specifies that elements 0 to (n-1) of pkts
           array are valid.
           arg Opaque parameter registered by the user at the pipeline table creation time

       Returns
           0 on success, error code otherwise

       Definition at line 555 of file rte_pipeline.h.

   typedef int(* rte_pipeline_port_out_action_handler) (struct rte_pipeline *p, struct rte_mbuf **pkts, uint64_t
       pkts_mask, void *arg)
       Pipeline output port action handler

       The action handler can decide to drop packets by resetting the associated packet bit in the pkts_mask
       parameter. In this case, the action handler is required not to free the packet buffer, which will be
       freed eventually by the pipeline.

       Parameters
           p Handle to pipeline instance
           pkts Burst of input packets specified as array of up to 64 pointers to struct rte_mbuf
           pkts_mask 64-bit bitmask specifying which packets in the input burst are valid. When pkts_mask bit n
           is set, then element n of pkts array is pointing to a valid packet. Otherwise, element n of pkts
           array will not be accessed.
           arg Opaque parameter registered by the user at the pipeline table creation time

       Returns
           0 on success, error code otherwise

       Definition at line 687 of file rte_pipeline.h.

Enumeration Type Documentation

   enum rte_pipeline_action
       Reserved actions

       Enumerator

       RTE_PIPELINE_ACTION_DROP
              Drop the packet

       RTE_PIPELINE_ACTION_PORT
              Send packet to output port

       RTE_PIPELINE_ACTION_PORT_META
              Send packet to output port read from packet meta-data

       RTE_PIPELINE_ACTION_TABLE
              Send packet to table

       RTE_PIPELINE_ACTIONS
              Number of reserved actions

       Definition at line 178 of file rte_pipeline.h.

Function Documentation

   struct rte_pipeline * rte_pipeline_create (struct rte_pipeline_params * params)
       Pipeline create

       Parameters
           params Parameters for pipeline creation

       Returns
           Handle to pipeline instance on success or NULL otherwise

   int rte_pipeline_free (struct rte_pipeline * p)
       Pipeline free

       Parameters
           p Handle to pipeline instance

       Returns
           0 on success, error code otherwise

   int rte_pipeline_check (struct rte_pipeline * p)
       Pipeline consistency check

       Parameters
           p Handle to pipeline instance

       Returns
           0 on success, error code otherwise

   int rte_pipeline_run (struct rte_pipeline * p)
       Pipeline run

       Parameters
           p Handle to pipeline instance

       Returns
           Number of packets read and processed

   int rte_pipeline_flush (struct rte_pipeline * p)
       Pipeline flush

       Parameters
           p Handle to pipeline instance

       Returns
           0 on success, error code otherwise

   int rte_pipeline_table_create (struct rte_pipeline * p, struct rte_pipeline_table_params * params, uint32_t *
       table_id)
       Pipeline table create

       Parameters
           p Handle to pipeline instance
           params Parameters for pipeline table creation
           table_id  Table  ID.  Valid only within the scope of table IDs of the current pipeline. Only returned
           after a successful invocation.

       Returns
           0 on success, error code otherwise

   int   rte_pipeline_table_default_entry_add   (struct   rte_pipeline   *   p,   uint32_t   table_id,    struct
       rte_pipeline_table_entry * default_entry, struct rte_pipeline_table_entry ** default_entry_ptr)
       Pipeline table default entry add

       The  contents  of  the  table  default entry is updated with the provided actions and meta-data. When the
       default entry is not configured (by using this function), the  built-in  default  entry  has  the  action
       'Drop' and meta-data set to all-zeros.

       Parameters
           p Handle to pipeline instance
           table_id Table ID (returned by previous invocation of pipeline table create)
           default_entry New contents for the table default entry
           default_entry_ptr  On successful invocation, pointer to the default table entry which can be used for
           further read-write accesses to this table entry. This pointer is valid until  the  default  entry  is
           deleted or re-added.

       Returns
           0 on success, error code otherwise

   int   rte_pipeline_table_default_entry_delete   (struct   rte_pipeline   *   p,   uint32_t  table_id,  struct
       rte_pipeline_table_entry * entry)
       Pipeline table default entry delete

       The new contents of the table default entry is set to reserved action 'Drop the  packet'  with  meta-data
       cleared (i.e. set to all-zeros).

       Parameters
           p Handle to pipeline instance
           table_id Table ID (returned by previous invocation of pipeline table create)
           entry  On  successful  invocation,  when entry points to a valid buffer, the previous contents of the
           table default entry (as it was just before the delete operation) is copied to this buffer

       Returns
           0 on success, error code otherwise

   int  rte_pipeline_table_entry_add  (struct  rte_pipeline  *  p,  uint32_t  table_id,  void  *   key,   struct
       rte_pipeline_table_entry * entry, int * key_found, struct rte_pipeline_table_entry ** entry_ptr)
       Pipeline table entry add

       Parameters
           p Handle to pipeline instance
           table_id Table ID (returned by previous invocation of pipeline table create)
           key Table entry key
           entry New contents for the table entry identified by key
           key_found  On  successful invocation, set to TRUE (value different than 0) if key was already present
           in the table before the add operation and to FALSE (value 0) if not
           entry_ptr On successful invocation, pointer to the table entry associated with key. This can be  used
           for  further  read-write  accesses to this table entry and is valid until the key is deleted from the
           table or re-added (usually for associating different actions and/or action meta-data to  the  current
           key)

       Returns
           0 on success, error code otherwise

   int rte_pipeline_table_entry_delete (struct rte_pipeline * p, uint32_t table_id, void * key, int * key_found,
       struct rte_pipeline_table_entry * entry)
       Pipeline table entry delete

       Parameters
           p Handle to pipeline instance
           table_id Table ID (returned by previous invocation of pipeline table create)
           key Table entry key
           key_found  On  successful  invocation,  set  to TRUE (value different than 0) if key was found in the
           table before the delete operation and to FALSE (value 0) if not
           entry On successful invocation, when key is found in the table and entry points to  a  valid  buffer,
           the table entry contents (as it was before the delete was performed) is copied to this buffer

       Returns
           0 on success, error code otherwise

   int  rte_pipeline_table_entry_add_bulk  (struct  rte_pipeline  *  p,  uint32_t table_id, void ** keys, struct
       rte_pipeline_table_entry ** entries, uint32_t n_keys, int * key_found, struct rte_pipeline_table_entry **
       entries_ptr)
       Pipeline table entry add bulk

       Parameters
           p Handle to pipeline instance
           table_id Table ID (returned by previous invocation of pipeline table create)
           keys Array containing table entry keys
           entries Array containing new contents for every table entry identified by key
           n_keys Number of keys to add
           key_found On successful invocation, key_found for every item in the  array  is  set  to  TRUE  (value
           different  than  0)  if  key  was  already present in the table before the add operation and to FALSE
           (value 0) if not
           entries_ptr On successful  invocation,  array  *entries_ptr  stores  pointer  to  every  table  entry
           associated  with  key.  This  can  be used for further read-write accesses to this table entry and is
           valid until the key is deleted from the table or re-added (usually for associating different  actions
           and/or action meta-data to the current key)

       Returns
           0 on success, error code otherwise

   int  rte_pipeline_table_entry_delete_bulk (struct rte_pipeline * p, uint32_t table_id, void ** keys, uint32_t
       n_keys, int * key_found, struct rte_pipeline_table_entry ** entries)
       Pipeline table entry delete bulk

       Parameters
           p Handle to pipeline instance
           table_id Table ID (returned by previous invocation of pipeline table create)
           keys Array containing table entry keys
           n_keys Number of keys to delete
           key_found On successful invocation, key_found for every item in the  array  is  set  to  TRUE  (value
           different than 0) if key was found in the table before the delete operation and to FALSE (value 0) if
           not
           entries  If  entries  pointer  is  NULL,  this  pointer is ignored for every entry found. Else, after
           successful invocation, if specific key is found in the table and entry points to a valid buffer,  the
           table entry contents (as it was before the delete was performed) is copied to this buffer.

       Returns
           0 on success, error code otherwise

   int    rte_pipeline_table_stats_read    (struct    rte_pipeline    *    p,    uint32_t    table_id,    struct
       rte_pipeline_table_stats * stats, int clear)
       Read pipeline table stats.

       This function reads table statistics identified by table_id of given pipeline p.

       Parameters
           p Handle to pipeline instance.
           table_id Port ID what stats will be returned.
           stats Statistics buffer.
           clear If not 0 clear stats after reading.

       Returns
           0 on success, error code otherwise

   int rte_pipeline_port_in_create (struct  rte_pipeline  *  p,  struct  rte_pipeline_port_in_params  *  params,
       uint32_t * port_id)
       Pipeline input port create

       Parameters
           p Handle to pipeline instance
           params Parameters for pipeline input port creation
           port_id  Input  port  ID. Valid only within the scope of input port IDs of the current pipeline. Only
           returned after a successful invocation.

       Returns
           0 on success, error code otherwise

   int rte_pipeline_port_in_connect_to_table (struct rte_pipeline * p, uint32_t port_id, uint32_t table_id)
       Pipeline input port connect to table

       Parameters
           p Handle to pipeline instance
           port_id Port ID (returned by previous invocation of pipeline input port create)
           table_id Table ID (returned by previous invocation of pipeline table create)

       Returns
           0 on success, error code otherwise

   int rte_pipeline_port_in_enable (struct rte_pipeline * p, uint32_t port_id)
       Pipeline input port enable

       Parameters
           p Handle to pipeline instance
           port_id Port ID (returned by previous invocation of pipeline input port create)

       Returns
           0 on success, error code otherwise

   int rte_pipeline_port_in_disable (struct rte_pipeline * p, uint32_t port_id)
       Pipeline input port disable

       Parameters
           p Handle to pipeline instance
           port_id Port ID (returned by previous invocation of pipeline input port create)

       Returns
           0 on success, error code otherwise

   int   rte_pipeline_port_in_stats_read    (struct    rte_pipeline    *    p,    uint32_t    port_id,    struct
       rte_pipeline_port_in_stats * stats, int clear)
       Read pipeline port in stats.

       This function reads port in statistics identified by port_id of given pipeline p.

       Parameters
           p Handle to pipeline instance.
           port_id Port ID what stats will be returned.
           stats Statistics buffer.
           clear If not 0 clear stats after reading.

       Returns
           0 on success, error code otherwise

   int  rte_pipeline_port_out_create  (struct  rte_pipeline  *  p, struct rte_pipeline_port_out_params * params,
       uint32_t * port_id)
       Pipeline output port create

       Parameters
           p Handle to pipeline instance
           params Parameters for pipeline output port creation
           port_id Output port ID. Valid only within the scope of output port IDs of the current pipeline.  Only
           returned after a successful invocation.

       Returns
           0 on success, error code otherwise

   int    rte_pipeline_port_out_stats_read    (struct    rte_pipeline    *    p,    uint32_t   port_id,   struct
       rte_pipeline_port_out_stats * stats, int clear)
       Read pipeline port out stats.

       This function reads port out statistics identified by port_id of given pipeline p.

       Parameters
           p Handle to pipeline instance.
           port_id Port ID what stats will be returned.
           stats Statistics buffer.
           clear If not 0 clear stats after reading.

       Returns
           0 on success, error code otherwise

   int rte_pipeline_port_out_packet_insert (struct rte_pipeline * p, uint32_t port_id, struct rte_mbuf * pkt)
       Action handler packet insert to output port

       This function can be called by any input/output port or table action handler to send a packet out through
       one of the pipeline output ports. This packet is generated by the action handler, i.e. this packet is not
       part of the burst of packets read from one of the pipeline input ports and  currently  processed  by  the
       pipeline (this packet is not an element of the pkts array input parameter of the action handler).

       Parameters
           p Handle to pipeline instance
           port_id  Output  port ID (returned by previous invocation of pipeline output port create) to send the
           packet specified by pkt
           pkt New packet generated by the action handler

       Returns
           0 on success, error code otherwise

   int rte_pipeline_ah_packet_hijack (struct rte_pipeline * p, uint64_t pkts_mask)
       Action handler packet hijack

       This function can be called by any input/output port or table action handler to hijack  selected  packets
       from  the  burst  of  packets  read  from  one of the pipeline input ports and currently processed by the
       pipeline. The hijacked packets are removed from any further pipeline processing, with the action  handler
       now having the full ownership for these packets.

       The  action handler can further send the hijacked packets out through any pipeline output port by calling
       the rte_pipeline_ah_port_out_packet_insert() function. The action handler can also drop these packets  by
       calling  the rte_pktmbuf_free() function, although a better alternative is provided by the action handler
       using the rte_pipeline_ah_packet_drop() function.

       Parameters
           p Handle to pipeline instance
           pkts_mask 64-bit bitmask specifying which of the packets handed over for  processing  to  the  action
           handler  is  to be hijacked by the action handler. When pkts_mask bit n is set, then element n of the
           pkts array (input argument to the action handler) is hijacked.

       Returns
           0 on success, error code otherwise

   int rte_pipeline_ah_packet_drop (struct rte_pipeline * p, uint64_t pkts_mask)
       Action handler packet drop

       This function is called by the pipeline action handlers (port in/out, table) to drop the packets selected
       using packet mask.

       This function can be called by any input/output port or table action handler  to  drop  selected  packets
       from  the  burst  of  packets  read  from  one of the pipeline input ports and currently processed by the
       pipeline. The dropped packets are removed from any further pipeline processing and the packet buffers are
       eventually freed to their buffer pool.

       This function updates the drop statistics counters correctly,  therefore  the  recommended  approach  for
       dropping  packets  by  the  action  handlers  is  to  call this function as opposed to the action handler
       hijacking  the  packets  first  and  then  dropping  them  invisibly  to  the  pipeline  (by  using   the
       rte_pktmbuf_free() function).

       Parameters
           p Handle to pipeline instance
           pkts_mask  64-bit  bitmask  specifying  which of the packets handed over for processing to the action
           handler is to be dropped by the action handler. When pkts_mask bit n is set, then element  n  of  the
           pkts array (input argument to the action handler) is dropped.

       Returns
           0 on success, error code otherwise

Author

       Generated automatically by Doxygen for DPDK from the source code.

DPDK                                             Version 24.11.2                               rte_pipeline.h(3)