Group Attribute

Usage of the group attribute

Group 0 is used for setting up filters based on various header fields or to process all frames. All the other groups (1 to 32) are used to group together the flow rules that match the same location of header fields to process frames. For example, group 1 can be used to group a set of flow rules that match frames with a list of IPv4 addresses, and group 2 can be used for another set of flow rules that match IPv6 addresses. By default, group is set to 0.

The jump action is allowed only in flow rules with group 0, meaning it can be used to jump to another group.

Here is an example of testpmd commands that use group 1 for IPv4 flows and group 2 for IPv6 flows.

flow create 0 group 0 pattern end actions queue index 0 / end 
flow create 0 group 0 pattern ipv4 / end actions jump group 1 / end
flow create 0 group 0 pattern ipv6 / end actions jump group 2 / end

flow create 0 group 1 pattern ipv4 src is 21.22.23.24 dst is 10.10.11.10 / udp src is 2000 dst is 1001 / end actions port_id id 1 / end

flow create 0 group 2 pattern ipv6 src is 2001:db8:3333:4444:5555:6666:7777:8888 dst is 23a8:0cd6:0:0:0:0:0:19 / udp src is 2000 dst is 1001 / end actions port_id id 1 / end

Note: Each command must be in a single line without any line breaks.

The first flow rule creates a catch-all filter with group 0, which means it catches all frames and forward them to queue 0.
The second flow rule creates a filter with group 0 that matches IPv4 and jumps to group 1.
The third flow rule creates a filter with group 0 that matches IPv6 and jumps to group 2.
The fourth flow rule with group 1 matches frames with specific source and destination IPv4 addresses and specific UDP source and destination port numbers. It then transmits these frames on port 1.
The fifth flow rule with group 2 matches frames with specific source and destination IPv6 addresses and specific UDP source and destination port numbers. It then transmits these frames on port 1.

For more information on sequence of flow rules, see Correct sequence to define flow rules.

Differences between group 0 and groups 1-32

Functionality and available resources differ between group 0 and groups 1-32, as distinct hardware resources in the SmartNIC are utilized. The following table highlights the differences:

Characteristic	Group 0	Group 1-32
Available resources in the SmartNIC	A few thousand flows.	140 million flows.
Supported actions (queue and TX port)	Delivering to a queue. Transmitting on a port.	Delivering to a queue. Transmitting on a port.
Supported actions (HW-offload features)	Decrementing IPv4 time to live (TTL) or IPv6 hop limit.	Multiple policy lookups and enforcement. Usage metering. Protocol encapsulation/decapsulation. DSCP tagging. Network address translation (NAT). Decrementing IPv4 time to live (TTL) or IPv6 hop limit.
Priority of multiple flow rules	The last created filter gets the highest priority. See Priority in Group 0.	If two flows with the same header field in the same group are programmed, it leads to an undefined state. For instance, if two flows in a group have the same IP address with two different sets of actions, this results in unexpected behavior. Therefore, existing flows must not be duplicated.

Constraints for creating flow rules in groups 1-32

In each group of groups 1-32, flow rules are associated with specific fields or masks. The location of header fields is determined by the first flow rule. This means that the fields/masks used for the first flow rule must be used in all subsequent flow rules. The structure of these fields and masks cannot be changed within the same group. Only the value of the fields may change. See the following testpmd command examples.

flow create 0 group 0 pattern ipv4 / end actions jump group 1 / end

# The first flow rule in group 1: fields are now locked on ipv4 src with mask 255.255.255.0.
flow create 0 group 1 pattern ipv4 src spec 1.2.3.4 src mask 255.255.255.0 / end actions port_id id 1 / end 

# The following flow rule is allowed as the value of the IP address has changed.
flow create 0 group 1 pattern ipv4 src spec 5.6.7.8 src mask 255.255.255.0 / end actions port_id id 1 / end 

# The following flow rule is not allowed. The mask is changed. 
flow create 0 group 1 pattern ipv4 src spec 4.3.2.1 src mask 255.255.255.240 / end actions port_id id 1 / end

# The following flow rule is not allowed. The destination IP is selected instead of the source IP.
flow create 0 group 1 pattern ipv4 dst spec 8.7.6.5 src mask 255.255.255.0 / end actions port_id id 1 / end

The first flow rule in group 1 matches on the IPv4 source address with a mask of 255.255.255.0. Subsequent flow rules within group 1 must also match on the IPv4 source address with the same mask of 255.255.255.0. While the value of the source IP address can change, the structure of the fields and masks must remain consistent. Flow rules that deviate from this structure by changing the mask or targeting a different field, such as the destination IP, are not allowed within the same group as shown in the third flow rule and the fourth flow rule in group 1.