Flow API Test Suite Inquiry

Flow API Test Suite Inquiry

[Dean Marx]

Hello Ori,


I work at the UNH-IOL DPDK Community Lab, and I am writing an rte_flow
test suite to add to the DPDK Test Suite.


The flow API allows for an extremely broad set of rules to be created.
My understanding from my first pass at writing the test suite is that
there is a small subset of those rules that are “core functionality”
that the flow API aims to support, and there are also rules which
technically can be created, but may not be supported by the main PMDs
and/or may not be useful rules that people want to see tested.


For instance, I am pretty confident that a rule like the one below is
one which the community will care about, and which PMDs will support:


flow create 0 ingress pattern eth / ipv4 src is 192.168.0.1 / end
actions drop / end


But I do not know what is the full set of rules that I should be
validating from a DTS testsuite. Is it possible for you (or anyone
else on this mailing list) to provide some feedback on what rules are
most important and I should include in my test suite? If I can get
that feedback, I will draft a test plan and share it back on this
thread for community approval before I write up and submit the DTS
patch.


Thanks for your time,

Dean Marx

Re: Flow API Test Suite Inquiry

[Thomas Monjalon]

Hi,

15/04/2025 20:21, Dean Marx:
> The flow API allows for an extremely broad set of rules to be created.
> My understanding from my first pass at writing the test suite is that
> there is a small subset of those rules that are “core functionality”
> that the flow API aims to support, and there are also rules which
> technically can be created, but may not be supported by the main PMDs
> and/or may not be useful rules that people want to see tested.
> 
> For instance, I am pretty confident that a rule like the one below is
> one which the community will care about, and which PMDs will support:
> 
> flow create 0 ingress pattern eth / ipv4 src is 192.168.0.1 / end
> actions drop / end
> 
> But I do not know what is the full set of rules that I should be
> validating from a DTS testsuite. Is it possible for you (or anyone
> else on this mailing list) to provide some feedback on what rules are
> most important and I should include in my test suite? If I can get
> that feedback, I will draft a test plan and share it back on this
> thread for community approval before I write up and submit the DTS
> patch.

Ultimately it would be nice to test all flow items and actions.
As this is the first step of this long journey,
I agree we should focus on the minimum.

We can focus on the simple synchronous API for now,
and leave the template asynchronous API for a next step.

Let's talk about basic items and actions to test
simple forwarding rules.

Items are describing protocols.
The most common ones are:
	- RTE_FLOW_ITEM_TYPE_ETH
	- RTE_FLOW_ITEM_TYPE_IPV4 / RTE_FLOW_ITEM_TYPE_IPV6
	- RTE_FLOW_ITEM_TYPE_UDP
	- RTE_FLOW_ITEM_TYPE_TCP
	- RTE_FLOW_ITEM_TYPE_VLAN
Some header field values may be specified as well in the rule.
You probably want to test matching each field of these items,
except checksums, lengths, offsets.
The traffic direction can be specified with:
	- rte_flow_attr.ingress
	- rte_flow_attr.egress

The most basic actions are to specify where to forward a flow:
	- RTE_FLOW_ACTION_TYPE_QUEUE
	- RTE_FLOW_ACTION_TYPE_REPRESENTED_PORT
	- RTE_FLOW_ACTION_TYPE_RSS
	- RTE_FLOW_ACTION_TYPE_DROP

Next we want to create flow rules in groups:
	- rte_flow_attr.group
	- rte_flow_attr.priority
and connect groups with
	- RTE_FLOW_ACTION_TYPE_JUMP

The most versatile action is to modify packets (like TTL or src/dest) with
	- RTE_FLOW_ACTION_TYPE_MODIFY_FIELD

I believe you should play with that first.
Any other opinions?

Re: Flow API Test Suite Inquiry

[Dean Marx]

[-- Attachment #1: Type: text/plain, Size: 504 bytes --]

Hi Thomas,

This is very helpful. I've drafted a test plan that I believe will
work best to cover these attributes. My plan is to submit
incrementally larger tests as I go, to avoid the issues I've had in
the past when trying to write one monolithic suite that covers
everything. I will likely write a basic flow suite sometime in the
near future covering the basics, so if anyone has anything they would
like to see added based on the test plan, let me know in this thread
and I'll make sure to add it.

[-- Attachment #2: RTE Flow Test Plan DTS.txt --]
[-- Type: text/plain, Size: 8184 bytes --]

RTE Flow Test Plan DTS

This plan aims to cover testing of all synchronous Flow API functionality, including the following:

Patterns

- RTE_FLOW_ITEM_TYPE_ETH
- RTE_FLOW_ITEM_TYPE_IPV4 / RTE_FLOW_ITEM_TYPE_IPV6
- RTE_FLOW_ITEM_TYPE_UDP
- RTE_FLOW_ITEM_TYPE_TCP
- RTE_FLOW_ITEM_TYPE_VLAN

Actions

- RTE_FLOW_ACTION_TYPE_QUEUE
- RTE_FLOW_ACTION_TYPE_REPRESENTED_PORT
- RTE_FLOW_ACTION_TYPE_RSS
- RTE_FLOW_ACTION_TYPE_DROP
- RTE_FLOW_ACTION_TYPE_MODIFY_FIELD

Grouping

- rte_flow_attr.group
- rte_flow_attr.priority
- RTE_FLOW_ACTION_TYPE_JUMP

--------------------------------------------------------------------------------------------------

Prerequisites:

Two link port topology
Flow control capabilities
4 Tx queues for queue action cases
Tx only forward mode for egress case
	
--------------------------------------------------------------------------------------------------

Queue Action Eth

flow create 0 ingress pattern eth src is 02:00:00:00:00:00 / end actions queue index 1 / end
flow create 0 ingress pattern eth dst is 02:00:00:00:00:00 / end actions queue index 1 / end
flow create 0 ingress pattern eth type is 0x0800 / end actions queue index 1 / end

Steps:
	Start testpmd with 4 Tx queues and create first flow rule.
	Send test packet that matches the flow rule pattern.
	Destroy flow rule, repeat steps for all rules.
Verify:
	Verify queue stats show a packet was received.
	
--------------------------------------------------------------------------------------------------

Queue Action IPv4/IPv6

flow create 0 ingress pattern ipv4 src is 192.0.2.0 / end actions queue index 1 / end
flow create 0 ingress pattern ipv4 dst is 192.0.2.0 / end actions queue index 1 / end
flow create 0 ingress pattern ipv4 next_proto_id is 6 / end actions queue index 1 / end
flow create 0 ingress pattern ipv4 ttl is 64 / end actions queue index 1 / end
flow create 0 ingress pattern ipv6 src is 2001:db8::1 / end actions queue index 1 / end
flow create 0 ingress pattern ipv6 dst is 2001:db8::2 / end actions queue index 1 / end
flow create 0 ingress pattern ipv6 proto is 17 / end actions queue index 1 / end
flow create 0 ingress pattern ipv6 hop_limits is 128 / end actions queue index 1 / end

Steps:
	Start testpmd with 4 Tx queues and create first flow rule.
	Send test packet that matches the flow rule pattern.
	Destroy flow rule, repeat steps for all rules.
Verify:
	Verify queue stats show a packet was received.
	
--------------------------------------------------------------------------------------------------

Queue Action TCP/UDP

flow create 0 ingress pattern tcp src is 1234 / end actions queue index 1 / end
flow create 0 ingress pattern tcp dst is 80 / end actions queue index 1 / end
flow create 0 ingress pattern tcp flags is 0x02 / end actions queue index 1 / end
flow create 0 ingress pattern udp src is 5000 / end actions queue index 1 / end
flow create 0 ingress pattern udp dst is 53 / end actions queue index 1 / end

Steps:
	Start testpmd with 4 Tx queues and create first flow rule.
	Send test packet that matches the flow rule pattern.
	Destroy flow rule, repeat steps for all rules.
Verify:
	Verify queue stats show a packet was received.
	
--------------------------------------------------------------------------------------------------

Queue Action VLAN

flow create 0 ingress pattern vlan tci is 0x0064 mask 0x0fff / end actions queue index 1 / end
flow create 0 ingress pattern vlan inner_type is 0x0800 / end actions queue index 1 / end

Steps:
	Start testpmd with 4 Tx queues and create first flow rule.
	Send test packet that matches the flow rule pattern.
	Destroy flow rule, repeat steps for all rules.
Verify:
	Verify queue stats show a packet was received.
	
--------------------------------------------------------------------------------------------------

Drop Action Eth

flow create 0 ingress pattern eth src is 02:00:00:00:00:00 / end actions drop / end
flow create 0 ingress pattern eth dst is 02:00:00:00:00:00 / end actions drop / end
flow create 0 ingress pattern eth type is 0x0800 / end actions drop / end

Steps:
	Start testpmd with 4 Tx queues and create first flow rule.
	Send test packet that matches the flow rule pattern.
	Destroy flow rule, repeat steps for all rules.
Verify:
	Verify sent packet is not received.
	
--------------------------------------------------------------------------------------------------

Drop Action IPv4/IPv6

flow create 0 ingress pattern ipv4 src is 192.0.2.0 / end actions drop / end
flow create 0 ingress pattern ipv4 dst is 192.0.2.0 / end actions drop / end
flow create 0 ingress pattern ipv4 next_proto_id is 6 / end actions drop / end
flow create 0 ingress pattern ipv4 ttl is 64 / end actions drop / end
flow create 0 ingress pattern ipv6 src is 2001:db8::1 / end actions drop / end
flow create 0 ingress pattern ipv6 dst is 2001:db8::2 / end actions drop / end
flow create 0 ingress pattern ipv6 proto is 17 / end actions drop / end
flow create 0 ingress pattern ipv6 hop_limits is 128 / end actions drop / end

Steps:
	Start testpmd with 4 Tx queues and create first flow rule.
	Send test packet that matches the flow rule pattern.
	Destroy flow rule, repeat steps for all rules.
Verify:
	Verify sent packet is not received.
	
--------------------------------------------------------------------------------------------------

Drop Action TCP/UDP

flow create 0 ingress pattern tcp src is 1234 / end actions drop / end
flow create 0 ingress pattern tcp dst is 80 / end actions drop / end
flow create 0 ingress pattern tcp flags is 0x02 / end actions drop / end
flow create 0 ingress pattern udp src is 5000 / end actions drop / end
flow create 0 ingress pattern udp dst is 53 / end actions drop / end

Steps:
	Start testpmd with 4 Tx queues and create first flow rule.
	Send test packet that matches the flow rule pattern.
	Destroy flow rule, repeat steps for all rules.
Verify:
	Verify sent packet is not received.
	
--------------------------------------------------------------------------------------------------

Drop Action VLAN 

flow create 0 ingress pattern vlan tci is 0x0064 mask 0x0fff / end actions drop / end
flow create 0 ingress pattern vlan inner_type is 0x0800 / end actions drop / end

Steps:
	Start testpmd with 4 Tx queues and create first flow rule.
	Send test packet that matches the flow rule pattern.
	Destroy flow rule, repeat steps for all rules.
Verify:
	Verify sent packet is not received.
	
--------------------------------------------------------------------------------------------------

Modify Field Action

// rule to copy IPv4 src to IPv4 dst
flow create 0 ingress group 1 pattern eth / end actions modify_field op set dst_type ipv4_dst src_type ipv4_src width 32 / count / rss / end
// rule to copy src MAC to dst MAC
flow create 0 ingress group 1 pattern eth / end actions modify_field op set dst_type mac_dst src_type mac_src width 48 / count / rss / end

Steps:
	Start testpmd with 4 Tx queues and create first flow rule.
	Send test packet that matches the flow rule pattern.
	Destroy flow rule, repeat steps for all rules.
Verify:
	Verify packet is received with the new attributes.
	
--------------------------------------------------------------------------------------------------

Egress rules

flow create 0 egress pattern eth src is 02:00:00:00:00:00 / end actions drop / end
flow create 0 egress pattern ipv4 src is 192.0.2.0 / end actions drop / end
flow create 0 egress pattern tcp src is 1234 / end actions drop / end
flow create 0 egress pattern udp src is 5000 / end actions drop / end
flow create 0 egress pattern vlan tci is 0x0064 mask 0x0fff / end actions drop / end

Steps:
	Start testpmd with 4 Tx queues and create first flow rule.
	Send test packet that matches the flow rule pattern.
	Destroy flow rule, repeat steps for all rules.
Verify:
	Verify packet is dropped.
	
--------------------------------------------------------------------------------------------------
	
RSS test cases are omitted from this test plan, as they will be written later once
the RSS test suites are finished to avoid redundant test coverage.

Represented port, group, and priority test cases will be added later in development.