DPDK  17.05.2
Data Structures | Enumerations | Functions | Variables
rte_flow.h File Reference
#include <rte_arp.h>
#include <rte_ether.h>
#include <rte_icmp.h>
#include <rte_ip.h>
#include <rte_sctp.h>
#include <rte_tcp.h>
#include <rte_udp.h>
#include <rte_byteorder.h>

Go to the source code of this file.

Data Structures

struct  rte_flow_attr
struct  rte_flow_item_any
struct  rte_flow_item_vf
struct  rte_flow_item_port
struct  rte_flow_item_raw
struct  rte_flow_item_eth
struct  rte_flow_item_vlan
struct  rte_flow_item_ipv4
struct  rte_flow_item_ipv6
struct  rte_flow_item_icmp
struct  rte_flow_item_udp
struct  rte_flow_item_tcp
struct  rte_flow_item_sctp
struct  rte_flow_item_vxlan
struct  rte_flow_item_e_tag
struct  rte_flow_item_nvgre
struct  rte_flow_item_mpls
struct  rte_flow_item_gre
struct  rte_flow_item
struct  rte_flow_action_mark
struct  rte_flow_action_queue
struct  rte_flow_query_count
struct  rte_flow_action_dup
struct  rte_flow_action_rss
struct  rte_flow_action_vf
struct  rte_flow_action
struct  rte_flow_error

Enumerations

enum  rte_flow_item_type {
  RTE_FLOW_ITEM_TYPE_END, RTE_FLOW_ITEM_TYPE_VOID, RTE_FLOW_ITEM_TYPE_INVERT, RTE_FLOW_ITEM_TYPE_ANY,
  RTE_FLOW_ITEM_TYPE_PF, RTE_FLOW_ITEM_TYPE_VF, RTE_FLOW_ITEM_TYPE_PORT, RTE_FLOW_ITEM_TYPE_RAW,
  RTE_FLOW_ITEM_TYPE_ETH, RTE_FLOW_ITEM_TYPE_VLAN, RTE_FLOW_ITEM_TYPE_IPV4, RTE_FLOW_ITEM_TYPE_IPV6,
  RTE_FLOW_ITEM_TYPE_ICMP, RTE_FLOW_ITEM_TYPE_UDP, RTE_FLOW_ITEM_TYPE_TCP, RTE_FLOW_ITEM_TYPE_SCTP,
  RTE_FLOW_ITEM_TYPE_VXLAN, RTE_FLOW_ITEM_TYPE_E_TAG, RTE_FLOW_ITEM_TYPE_NVGRE, RTE_FLOW_ITEM_TYPE_MPLS,
  RTE_FLOW_ITEM_TYPE_GRE
}
enum  rte_flow_action_type {
  RTE_FLOW_ACTION_TYPE_END, RTE_FLOW_ACTION_TYPE_VOID, RTE_FLOW_ACTION_TYPE_PASSTHRU, RTE_FLOW_ACTION_TYPE_MARK,
  RTE_FLOW_ACTION_TYPE_FLAG, RTE_FLOW_ACTION_TYPE_QUEUE, RTE_FLOW_ACTION_TYPE_DROP, RTE_FLOW_ACTION_TYPE_COUNT,
  RTE_FLOW_ACTION_TYPE_DUP, RTE_FLOW_ACTION_TYPE_RSS, RTE_FLOW_ACTION_TYPE_PF, RTE_FLOW_ACTION_TYPE_VF
}
enum  rte_flow_error_type {
  RTE_FLOW_ERROR_TYPE_NONE, RTE_FLOW_ERROR_TYPE_UNSPECIFIED, RTE_FLOW_ERROR_TYPE_HANDLE, RTE_FLOW_ERROR_TYPE_ATTR_GROUP,
  RTE_FLOW_ERROR_TYPE_ATTR_PRIORITY, RTE_FLOW_ERROR_TYPE_ATTR_INGRESS, RTE_FLOW_ERROR_TYPE_ATTR_EGRESS, RTE_FLOW_ERROR_TYPE_ATTR,
  RTE_FLOW_ERROR_TYPE_ITEM_NUM, RTE_FLOW_ERROR_TYPE_ITEM, RTE_FLOW_ERROR_TYPE_ACTION_NUM, RTE_FLOW_ERROR_TYPE_ACTION
}

Functions

int rte_flow_validate (uint8_t port_id, const struct rte_flow_attr *attr, const struct rte_flow_item pattern[], const struct rte_flow_action actions[], struct rte_flow_error *error)
struct rte_flow * rte_flow_create (uint8_t port_id, const struct rte_flow_attr *attr, const struct rte_flow_item pattern[], const struct rte_flow_action actions[], struct rte_flow_error *error)
int rte_flow_destroy (uint8_t port_id, struct rte_flow *flow, struct rte_flow_error *error)
int rte_flow_flush (uint8_t port_id, struct rte_flow_error *error)
int rte_flow_query (uint8_t port_id, struct rte_flow *flow, enum rte_flow_action_type action, void *data, struct rte_flow_error *error)

Variables

static struct rte_flow_item_any rte_flow_item_any_mask
static struct rte_flow_item_vf rte_flow_item_vf_mask
static struct rte_flow_item_port rte_flow_item_port_mask
static struct rte_flow_item_raw rte_flow_item_raw_mask
static struct rte_flow_item_eth rte_flow_item_eth_mask
static struct rte_flow_item_vlan rte_flow_item_vlan_mask
static struct rte_flow_item_ipv4 rte_flow_item_ipv4_mask
static struct rte_flow_item_ipv6 rte_flow_item_ipv6_mask
static struct rte_flow_item_icmp rte_flow_item_icmp_mask
static struct rte_flow_item_udp rte_flow_item_udp_mask
static struct rte_flow_item_tcp rte_flow_item_tcp_mask
static struct rte_flow_item_sctp rte_flow_item_sctp_mask
static struct rte_flow_item_vxlan rte_flow_item_vxlan_mask
static struct rte_flow_item_e_tag rte_flow_item_e_tag_mask
static struct rte_flow_item_nvgre rte_flow_item_nvgre_mask
static struct rte_flow_item_mpls rte_flow_item_mpls_mask
static struct rte_flow_item_gre rte_flow_item_gre_mask

Detailed Description

RTE generic flow API

This interface provides the ability to program packet matching and associated actions in hardware through flow rules.

Definition in file rte_flow.h.

Enumeration Type Documentation

Matching pattern item types.

Pattern items fall in two categories:

  • Matching protocol headers and packet data (ANY, RAW, ETH, VLAN, IPV4, IPV6, ICMP, UDP, TCP, SCTP, VXLAN and so on), usually associated with a specification structure. These must be stacked in the same order as the protocol layers to match, starting from the lowest.
  • Matching meta-data or affecting pattern processing (END, VOID, INVERT, PF, VF, PORT and so on), often without a specification structure. Since they do not match packet contents, these can be specified anywhere within item lists without affecting others.

See the description of individual types for more information. Those marked with [META] fall into the second category.

Enumerator:
RTE_FLOW_ITEM_TYPE_END 

[META]

End marker for item lists. Prevents further processing of items, thereby ending the pattern.

No associated specification structure.

RTE_FLOW_ITEM_TYPE_VOID 

[META]

Used as a placeholder for convenience. It is ignored and simply discarded by PMDs.

No associated specification structure.

RTE_FLOW_ITEM_TYPE_INVERT 

[META]

Inverted matching, i.e. process packets that do not match the pattern.

No associated specification structure.

RTE_FLOW_ITEM_TYPE_ANY 

Matches any protocol in place of the current layer, a single ANY may also stand for several protocol layers.

See struct rte_flow_item_any.

RTE_FLOW_ITEM_TYPE_PF 

[META]

Matches packets addressed to the physical function of the device.

If the underlying device function differs from the one that would normally receive the matched traffic, specifying this item prevents it from reaching that device unless the flow rule contains a PF action. Packets are not duplicated between device instances by default.

No associated specification structure.

RTE_FLOW_ITEM_TYPE_VF 

[META]

Matches packets addressed to a virtual function ID of the device.

If the underlying device function differs from the one that would normally receive the matched traffic, specifying this item prevents it from reaching that device unless the flow rule contains a VF action. Packets are not duplicated between device instances by default.

See struct rte_flow_item_vf.

RTE_FLOW_ITEM_TYPE_PORT 

[META]

Matches packets coming from the specified physical port of the underlying device.

The first PORT item overrides the physical port normally associated with the specified DPDK input port (port_id). This item can be provided several times to match additional physical ports.

See struct rte_flow_item_port.

RTE_FLOW_ITEM_TYPE_RAW 

Matches a byte string of a given length at a given offset.

See struct rte_flow_item_raw.

RTE_FLOW_ITEM_TYPE_ETH 

Matches an Ethernet header.

See struct rte_flow_item_eth.

RTE_FLOW_ITEM_TYPE_VLAN 

Matches an 802.1Q/ad VLAN tag.

See struct rte_flow_item_vlan.

RTE_FLOW_ITEM_TYPE_IPV4 

Matches an IPv4 header.

See struct rte_flow_item_ipv4.

RTE_FLOW_ITEM_TYPE_IPV6 

Matches an IPv6 header.

See struct rte_flow_item_ipv6.

RTE_FLOW_ITEM_TYPE_ICMP 

Matches an ICMP header.

See struct rte_flow_item_icmp.

RTE_FLOW_ITEM_TYPE_UDP 

Matches a UDP header.

See struct rte_flow_item_udp.

RTE_FLOW_ITEM_TYPE_TCP 

Matches a TCP header.

See struct rte_flow_item_tcp.

RTE_FLOW_ITEM_TYPE_SCTP 

Matches a SCTP header.

See struct rte_flow_item_sctp.

RTE_FLOW_ITEM_TYPE_VXLAN 

Matches a VXLAN header.

See struct rte_flow_item_vxlan.

RTE_FLOW_ITEM_TYPE_E_TAG 

Matches a E_TAG header.

See struct rte_flow_item_e_tag.

RTE_FLOW_ITEM_TYPE_NVGRE 

Matches a NVGRE header.

See struct rte_flow_item_nvgre.

RTE_FLOW_ITEM_TYPE_MPLS 

Matches a MPLS header.

See struct rte_flow_item_mpls.

RTE_FLOW_ITEM_TYPE_GRE 

Matches a GRE header.

See struct rte_flow_item_gre.

Definition at line 119 of file rte_flow.h.

Action types.

Each possible action is represented by a type. Some have associated configuration structures. Several actions combined in a list can be affected to a flow rule. That list is not ordered.

They fall in three categories:

  • Terminating actions (such as QUEUE, DROP, RSS, PF, VF) that prevent processing matched packets by subsequent flow rules, unless overridden with PASSTHRU.
  • Non terminating actions (PASSTHRU, DUP) that leave matched packets up for additional processing by subsequent flow rules.
  • Other non terminating meta actions that do not affect the fate of packets (END, VOID, MARK, FLAG, COUNT).

When several actions are combined in a flow rule, they should all have different types (e.g. dropping a packet twice is not possible).

Only the last action of a given type is taken into account. PMDs still perform error checking on the entire list.

Note that PASSTHRU is the only action able to override a terminating rule.

Enumerator:
RTE_FLOW_ACTION_TYPE_END 

[META]

End marker for action lists. Prevents further processing of actions, thereby ending the list.

No associated configuration structure.

RTE_FLOW_ACTION_TYPE_VOID 

[META]

Used as a placeholder for convenience. It is ignored and simply discarded by PMDs.

No associated configuration structure.

RTE_FLOW_ACTION_TYPE_PASSTHRU 

Leaves packets up for additional processing by subsequent flow rules. This is the default when a rule does not contain a terminating action, but can be specified to force a rule to become non-terminating.

No associated configuration structure.

RTE_FLOW_ACTION_TYPE_MARK 

[META]

Attaches an integer value to packets and sets PKT_RX_FDIR and PKT_RX_FDIR_ID mbuf flags.

See struct rte_flow_action_mark.

RTE_FLOW_ACTION_TYPE_FLAG 

[META]

Flags packets. Similar to MARK without a specific value; only sets the PKT_RX_FDIR mbuf flag.

No associated configuration structure.

RTE_FLOW_ACTION_TYPE_QUEUE 

Assigns packets to a given queue index.

See struct rte_flow_action_queue.

RTE_FLOW_ACTION_TYPE_DROP 

Drops packets.

PASSTHRU overrides this action if both are specified.

No associated configuration structure.

RTE_FLOW_ACTION_TYPE_COUNT 

[META]

Enables counters for this rule.

These counters can be retrieved and reset through rte_flow_query(), see struct rte_flow_query_count.

No associated configuration structure.

RTE_FLOW_ACTION_TYPE_DUP 

Duplicates packets to a given queue index.

This is normally combined with QUEUE, however when used alone, it is actually similar to QUEUE + PASSTHRU.

See struct rte_flow_action_dup.

RTE_FLOW_ACTION_TYPE_RSS 

Similar to QUEUE, except RSS is additionally performed on packets to spread them among several queues according to the provided parameters.

See struct rte_flow_action_rss.

RTE_FLOW_ACTION_TYPE_PF 

Redirects packets to the physical function (PF) of the current device.

No associated configuration structure.

RTE_FLOW_ACTION_TYPE_VF 

Redirects packets to the virtual function (VF) of the current device with the specified ID.

See struct rte_flow_action_vf.

Definition at line 771 of file rte_flow.h.

Verbose error types.

Most of them provide the type of the object referenced by struct rte_flow_error.cause.

Enumerator:
RTE_FLOW_ERROR_TYPE_NONE 

No error.

RTE_FLOW_ERROR_TYPE_UNSPECIFIED 

Cause unspecified.

RTE_FLOW_ERROR_TYPE_HANDLE 

Flow rule (handle).

RTE_FLOW_ERROR_TYPE_ATTR_GROUP 

Group field.

RTE_FLOW_ERROR_TYPE_ATTR_PRIORITY 

Priority field.

RTE_FLOW_ERROR_TYPE_ATTR_INGRESS 

Ingress field.

RTE_FLOW_ERROR_TYPE_ATTR_EGRESS 

Egress field.

RTE_FLOW_ERROR_TYPE_ATTR 

Attributes structure.

RTE_FLOW_ERROR_TYPE_ITEM_NUM 

Pattern length.

RTE_FLOW_ERROR_TYPE_ITEM 

Specific pattern item.

RTE_FLOW_ERROR_TYPE_ACTION_NUM 

Number of actions.

RTE_FLOW_ERROR_TYPE_ACTION 

Specific action.

Definition at line 1002 of file rte_flow.h.

Function Documentation

int rte_flow_validate ( uint8_t  port_id,
const struct rte_flow_attr attr,
const struct rte_flow_item  pattern[],
const struct rte_flow_action  actions[],
struct rte_flow_error error 
)

Check whether a flow rule can be created on a given port.

The flow rule is validated for correctness and whether it could be accepted by the device given sufficient resources. The rule is checked against the current device mode and queue configuration. The flow rule may also optionally be validated against existing flow rules and device resources. This function has no effect on the target device.

The returned value is guaranteed to remain valid only as long as no successful calls to rte_flow_create() or rte_flow_destroy() are made in the meantime and no device parameter affecting flow rules in any way are modified, due to possible collisions or resource limitations (although in such cases EINVAL should not be returned).

Parameters
port_idPort identifier of Ethernet device.
[in]attrFlow rule attributes.
[in]patternPattern specification (list terminated by the END pattern item).
[in]actionsAssociated actions (list terminated by the END action).
[out]errorPerform verbose error reporting if not NULL. PMDs initialize this structure in case of error only.
Returns
0 if flow rule is valid and can be created. A negative errno value otherwise (rte_errno is also set), the following errors are defined:

-ENOSYS: underlying device does not support this functionality.

-EINVAL: unknown or invalid rule specification.

-ENOTSUP: valid but unsupported rule specification (e.g. partial bit-masks are unsupported).

-EEXIST: collision with an existing rule. Only returned if device supports flow rule collision checking and there was a flow rule collision. Not receiving this return code is no guarantee that creating the rule will not fail due to a collision.

-ENOMEM: not enough memory to execute the function, or if the device supports resource validation, resource limitation on the device.

-EBUSY: action cannot be performed due to busy device resources, may succeed if the affected queues or even the entire port are in a stopped state (see rte_eth_dev_rx_queue_stop() and rte_eth_dev_stop()).

struct rte_flow* rte_flow_create ( uint8_t  port_id,
const struct rte_flow_attr attr,
const struct rte_flow_item  pattern[],
const struct rte_flow_action  actions[],
struct rte_flow_error error 
)
read

Create a flow rule on a given port.

Parameters
port_idPort identifier of Ethernet device.
[in]attrFlow rule attributes.
[in]patternPattern specification (list terminated by the END pattern item).
[in]actionsAssociated actions (list terminated by the END action).
[out]errorPerform verbose error reporting if not NULL. PMDs initialize this structure in case of error only.
Returns
A valid handle in case of success, NULL otherwise and rte_errno is set to the positive version of one of the error codes defined for rte_flow_validate().
int rte_flow_destroy ( uint8_t  port_id,
struct rte_flow *  flow,
struct rte_flow_error error 
)

Destroy a flow rule on a given port.

Failure to destroy a flow rule handle may occur when other flow rules depend on it, and destroying it would result in an inconsistent state.

This function is only guaranteed to succeed if handles are destroyed in reverse order of their creation.

Parameters
port_idPort identifier of Ethernet device.
flowFlow rule handle to destroy.
[out]errorPerform verbose error reporting if not NULL. PMDs initialize this structure in case of error only.
Returns
0 on success, a negative errno value otherwise and rte_errno is set.
int rte_flow_flush ( uint8_t  port_id,
struct rte_flow_error error 
)

Destroy all flow rules associated with a port.

In the unlikely event of failure, handles are still considered destroyed and no longer valid but the port must be assumed to be in an inconsistent state.

Parameters
port_idPort identifier of Ethernet device.
[out]errorPerform verbose error reporting if not NULL. PMDs initialize this structure in case of error only.
Returns
0 on success, a negative errno value otherwise and rte_errno is set.
int rte_flow_query ( uint8_t  port_id,
struct rte_flow *  flow,
enum rte_flow_action_type  action,
void *  data,
struct rte_flow_error error 
)

Query an existing flow rule.

This function allows retrieving flow-specific data such as counters. Data is gathered by special actions which must be present in the flow rule definition.

See Also
RTE_FLOW_ACTION_TYPE_COUNT
Parameters
port_idPort identifier of Ethernet device.
flowFlow rule handle to query.
actionAction type to query.
[in,out]dataPointer to storage for the associated query data type.
[out]errorPerform verbose error reporting if not NULL. PMDs initialize this structure in case of error only.
Returns
0 on success, a negative errno value otherwise and rte_errno is set.

Variable Documentation

struct rte_flow_item_any rte_flow_item_any_mask
static
Initial value:
{
.num = 0x00000000,
}

Default mask for RTE_FLOW_ITEM_TYPE_ANY.

Definition at line 319 of file rte_flow.h.

struct rte_flow_item_vf rte_flow_item_vf_mask
static
Initial value:
{
.id = 0x00000000,
}

Default mask for RTE_FLOW_ITEM_TYPE_VF.

Definition at line 348 of file rte_flow.h.

struct rte_flow_item_port rte_flow_item_port_mask
static
Initial value:
{
.index = 0x00000000,
}

Default mask for RTE_FLOW_ITEM_TYPE_PORT.

Definition at line 379 of file rte_flow.h.

struct rte_flow_item_raw rte_flow_item_raw_mask
static
Initial value:
{
.relative = 1,
.search = 1,
.reserved = 0x3fffffff,
.offset = 0xffffffff,
.limit = 0xffff,
.length = 0xffff,
}

Default mask for RTE_FLOW_ITEM_TYPE_RAW.

Definition at line 414 of file rte_flow.h.

struct rte_flow_item_eth rte_flow_item_eth_mask
static
Initial value:
{
.dst.addr_bytes = "\xff\xff\xff\xff\xff\xff",
.src.addr_bytes = "\xff\xff\xff\xff\xff\xff",
.type = 0x0000,
}

Default mask for RTE_FLOW_ITEM_TYPE_ETH.

Definition at line 437 of file rte_flow.h.

struct rte_flow_item_vlan rte_flow_item_vlan_mask
static
Initial value:
{
.tpid = 0x0000,
.tci = 0xffff,
}

Default mask for RTE_FLOW_ITEM_TYPE_VLAN.

Definition at line 459 of file rte_flow.h.

struct rte_flow_item_ipv4 rte_flow_item_ipv4_mask
static
Initial value:
{
.hdr = {
.src_addr = 0xffffffff,
.dst_addr = 0xffffffff,
},
}

Default mask for RTE_FLOW_ITEM_TYPE_IPV4.

Definition at line 478 of file rte_flow.h.

struct rte_flow_item_ipv6 rte_flow_item_ipv6_mask
static
Initial value:
{
.hdr = {
.src_addr =
"\xff\xff\xff\xff\xff\xff\xff\xff"
"\xff\xff\xff\xff\xff\xff\xff\xff",
.dst_addr =
"\xff\xff\xff\xff\xff\xff\xff\xff"
"\xff\xff\xff\xff\xff\xff\xff\xff",
},
}

Default mask for RTE_FLOW_ITEM_TYPE_IPV6.

Definition at line 499 of file rte_flow.h.

struct rte_flow_item_icmp rte_flow_item_icmp_mask
static
Initial value:
{
.hdr = {
.icmp_type = 0xff,
.icmp_code = 0xff,
},
}

Default mask for RTE_FLOW_ITEM_TYPE_ICMP.

Definition at line 522 of file rte_flow.h.

struct rte_flow_item_udp rte_flow_item_udp_mask
static
Initial value:
{
.hdr = {
.src_port = 0xffff,
.dst_port = 0xffff,
},
}

Default mask for RTE_FLOW_ITEM_TYPE_UDP.

Definition at line 541 of file rte_flow.h.

struct rte_flow_item_tcp rte_flow_item_tcp_mask
static
Initial value:
{
.hdr = {
.src_port = 0xffff,
.dst_port = 0xffff,
},
}

Default mask for RTE_FLOW_ITEM_TYPE_TCP.

Definition at line 560 of file rte_flow.h.

struct rte_flow_item_sctp rte_flow_item_sctp_mask
static
Initial value:
{
.hdr = {
.src_port = 0xffff,
.dst_port = 0xffff,
},
}

Default mask for RTE_FLOW_ITEM_TYPE_SCTP.

Definition at line 579 of file rte_flow.h.

struct rte_flow_item_vxlan rte_flow_item_vxlan_mask
static
Initial value:
{
.vni = "\xff\xff\xff",
}

Default mask for RTE_FLOW_ITEM_TYPE_VXLAN.

Definition at line 601 of file rte_flow.h.

struct rte_flow_item_e_tag rte_flow_item_e_tag_mask
static
Initial value:
{
.rsvd_grp_ecid_b = 0x3fff,
}

Default mask for RTE_FLOW_ITEM_TYPE_E_TAG.

Definition at line 626 of file rte_flow.h.

struct rte_flow_item_nvgre rte_flow_item_nvgre_mask
static
Initial value:
{
.tni = "\xff\xff\xff",
}

Default mask for RTE_FLOW_ITEM_TYPE_NVGRE.

Definition at line 657 of file rte_flow.h.

struct rte_flow_item_mpls rte_flow_item_mpls_mask
static
Initial value:
{
.label_tc_s = "\xff\xff\xf0",
}

Default mask for RTE_FLOW_ITEM_TYPE_MPLS.

Definition at line 677 of file rte_flow.h.

struct rte_flow_item_gre rte_flow_item_gre_mask
static
Initial value:
{
.protocol = 0xffff,
}

Default mask for RTE_FLOW_ITEM_TYPE_GRE.

Definition at line 698 of file rte_flow.h.