Install Now
rte_pipeline.h
Contents
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.
Basicoperation. 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.
Initializationandrun-timeflows. 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-corescaling. 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.
Threadsafety. 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.
Enumeration Type Documentation
enumrte_pipeline_action
Reserved actions
EnumeratorRTE_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
structrte_pipeline*rte_pipeline_create(structrte_pipeline_params*params)
Pipeline create
Parametersparams Parameters for pipeline creation
Returns
Handle to pipeline instance on success or NULL otherwise
intrte_pipeline_free(structrte_pipeline*p)
Pipeline free
Parametersp Handle to pipeline instance
Returns
0 on success, error code otherwise
intrte_pipeline_check(structrte_pipeline*p)
Pipeline consistency check
Parametersp Handle to pipeline instance
Returns
0 on success, error code otherwise
intrte_pipeline_run(structrte_pipeline*p)
Pipeline run
Parametersp Handle to pipeline instance
Returns
Number of packets read and processed
intrte_pipeline_flush(structrte_pipeline*p)
Pipeline flush
Parametersp Handle to pipeline instance
Returns
0 on success, error code otherwise
intrte_pipeline_table_create(structrte_pipeline*p,structrte_pipeline_table_params*params,uint32_t*table_id)
Pipeline table create
Parametersp 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
intrte_pipeline_table_default_entry_add(structrte_pipeline*p,uint32_ttable_id,structrte_pipeline_table_entry*default_entry,structrte_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.
Parametersp 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
intrte_pipeline_table_default_entry_delete(structrte_pipeline*p,uint32_ttable_id,structrte_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).
Parametersp 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
intrte_pipeline_table_entry_add(structrte_pipeline*p,uint32_ttable_id,void*key,structrte_pipeline_table_entry*entry,int*key_found,structrte_pipeline_table_entry**entry_ptr)
Pipeline table entry add
Parametersp 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
intrte_pipeline_table_entry_delete(structrte_pipeline*p,uint32_ttable_id,void*key,int*key_found,structrte_pipeline_table_entry*entry)
Pipeline table entry delete
Parametersp 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
intrte_pipeline_table_entry_add_bulk(structrte_pipeline*p,uint32_ttable_id,void**keys,structrte_pipeline_table_entry**entries,uint32_tn_keys,int*key_found,structrte_pipeline_table_entry**entries_ptr)
Pipeline table entry add bulk
Parametersp 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
intrte_pipeline_table_entry_delete_bulk(structrte_pipeline*p,uint32_ttable_id,void**keys,uint32_tn_keys,int*key_found,structrte_pipeline_table_entry**entries)
Pipeline table entry delete bulk
Parametersp 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
intrte_pipeline_table_stats_read(structrte_pipeline*p,uint32_ttable_id,structrte_pipeline_table_stats*stats,intclear)
Read pipeline table stats.
This function reads table statistics identified by table_id of given pipeline p.
Parametersp 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
intrte_pipeline_port_in_create(structrte_pipeline*p,structrte_pipeline_port_in_params*params,uint32_t*port_id)
Pipeline input port create
Parametersp 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
intrte_pipeline_port_in_connect_to_table(structrte_pipeline*p,uint32_tport_id,uint32_ttable_id)
Pipeline input port connect to table
Parametersp 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
intrte_pipeline_port_in_enable(structrte_pipeline*p,uint32_tport_id)
Pipeline input port enable
Parametersp Handle to pipeline instance
port_id Port ID (returned by previous invocation of pipeline input port create)
Returns
0 on success, error code otherwise
intrte_pipeline_port_in_disable(structrte_pipeline*p,uint32_tport_id)
Pipeline input port disable
Parametersp Handle to pipeline instance
port_id Port ID (returned by previous invocation of pipeline input port create)
Returns
0 on success, error code otherwise
intrte_pipeline_port_in_stats_read(structrte_pipeline*p,uint32_tport_id,structrte_pipeline_port_in_stats*stats,intclear)
Read pipeline port in stats.
This function reads port in statistics identified by port_id of given pipeline p.
Parametersp 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
intrte_pipeline_port_out_create(structrte_pipeline*p,structrte_pipeline_port_out_params*params,uint32_t*port_id)
Pipeline output port create
Parametersp 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
intrte_pipeline_port_out_stats_read(structrte_pipeline*p,uint32_tport_id,structrte_pipeline_port_out_stats*stats,intclear)
Read pipeline port out stats.
This function reads port out statistics identified by port_id of given pipeline p.
Parametersp 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
intrte_pipeline_port_out_packet_insert(structrte_pipeline*p,uint32_tport_id,structrte_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).
Parametersp 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
intrte_pipeline_ah_packet_hijack(structrte_pipeline*p,uint64_tpkts_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.
Parametersp 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
intrte_pipeline_ah_packet_drop(structrte_pipeline*p,uint64_tpkts_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).
Parametersp 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
Macro Definition Documentation
#defineRTE_PIPELINE_TABLE_MAX64
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.
#defineRTE_PIPELINE_PORT_IN_MAX64
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.
#defineRTE_PIPELINE_PORT_OUT_MAX64
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.
Name
rte_pipeline.h
Synopsis
#include <stdint.h>
#include <rte_port.h>
#include <rte_table.h>
#include <rte_common.h>
DataStructures
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_paramsMacros
#define RTE_PIPELINE_TABLE_MAX 64
#define RTE_PIPELINE_PORT_IN_MAX 64
#define RTE_PIPELINE_PORT_OUT_MAX 64
Typedefstypedef 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)
Typedef Documentation
typedefint(*rte_pipeline_table_action_handler_hit)(structrte_pipeline*p,structrte_mbuf**pkts,uint64_tpkts_mask,structrte_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.
Parametersp Handle to pipeline instance
pkts Burst of input packets specified as array of up to 64 pointers to struct rte_mbufpkts_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_entryarg 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.
typedefint(*rte_pipeline_table_action_handler_miss)(structrte_pipeline*p,structrte_mbuf**pkts,uint64_tpkts_mask,structrte_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.
Parametersp Handle to pipeline instance
pkts Burst of input packets specified as array of up to 64 pointers to struct rte_mbufpkts_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.
typedefint(*rte_pipeline_port_in_action_handler)(structrte_pipeline*p,structrte_mbuf**pkts,uint32_tn,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.
Parametersp Handle to pipeline instance
pkts Burst of input packets specified as array of up to 64 pointers to struct rte_mbufn 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.
typedefint(*rte_pipeline_port_out_action_handler)(structrte_pipeline*p,structrte_mbuf**pkts,uint64_tpkts_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.
Parametersp Handle to pipeline instance
pkts Burst of input packets specified as array of up to 64 pointers to struct rte_mbufpkts_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.
PNG Icons