rte_pipeline.h File Reference

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

Data Structures
struct	rte_pipeline_params
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_mbuf **pkts, uint64_t *pkts_mask, struct rte_pipeline_table_entry **entries, void *arg)
typedef int(*	rte_pipeline_table_action_handler_miss )(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_mbuf **pkts, uint32_t n, uint64_t *pkts_mask, void *arg)
typedef int(*	rte_pipeline_port_out_action_handler )(struct rte_mbuf *pkt, uint64_t *pkt_mask, void *arg)
typedef int(*	rte_pipeline_port_out_action_handler_bulk )(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_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_out_create (struct rte_pipeline *p, struct rte_pipeline_port_out_params *params, uint32_t *port_id)
int	rte_pipeline_port_out_packet_insert (struct rte_pipeline *p, uint32_t port_id, struct rte_mbuf *pkt)

Detailed Description

RTE Pipeline

This tool is part of the Intel 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.

Macro Definition Documentation

#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.

#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.

#define RTE_PIPELINE_TABLE_MAX   64

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

Typedef Documentation

typedef int(* rte_pipeline_port_in_action_handler)(struct rte_mbuf **pkts, uint32_t n, uint64_t *pkts_mask, 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

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.
pkts_mask	64-bit bitmask specifying which packets in the input burst are still valid after the action handler is executed. When pkts_mask bit n is set, then element n of pkts array is pointing to a valid packet.
arg	Opaque parameter registered by the user at the pipeline table creation time

Returns

0 on success, error code otherwise

typedef int(* rte_pipeline_port_out_action_handler)(struct rte_mbuf *pkt, uint64_t *pkt_mask, void *arg)

Pipeline output port action handler for single packet

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

Parameters

pkt	Input packet
pkt_mask	Output argument set to 0 when the action handler decides to drop the input packet and to 1LLU otherwise
arg	Opaque parameter registered by the user at the pipeline table creation time

Returns

0 on success, error code otherwise

typedef int(* rte_pipeline_port_out_action_handler_bulk)(struct rte_mbuf **pkts, uint64_t *pkts_mask, void *arg)

Pipeline output port action handler bulk

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

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

typedef int(* rte_pipeline_table_action_handler_hit)(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

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

typedef int(* rte_pipeline_table_action_handler_miss)(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

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

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

Function Documentation

int rte_pipeline_check

(

struct rte_pipeline *

p

)

Pipeline consistency check

Parameters

p	Handle to pipeline instance

Returns

0 on success, error code otherwise

struct rte_pipeline* rte_pipeline_create ( struct rte_pipeline_params *  params )

read

Pipeline create

Parameters

params

Parameters for pipeline creation

Returns

Handle to pipeline instance on success or NULL otherwise

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_free

(

struct rte_pipeline *

p

)

Pipeline free

Parameters

p	Handle to pipeline instance

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_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_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_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_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_packet_insert	(	struct rte_pipeline *	p,
		uint32_t	port_id,
		struct rte_mbuf *	pkt
	)

Pipeline output port packet insert

This function is called by the table action handler whenever it generates a new packet to be sent out though one of the pipeline output ports. This packet is not part of the burst of input packets read from any of the pipeline input ports, so it is not an element of the pkts array input parameter of the table action handler. This packet can be dropped by the output port 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 table action handler

Returns

0 on success, error code otherwise

int rte_pipeline_run

(

struct rte_pipeline *

p

)

Pipeline run

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