[PATCH REQUIREMENTS v2 5/7] net-features: Add n-tuple receive flow filters requirements

[Parav Pandit <parav@nvidia.com>]

Add virtio net device requirements for receive flow filters.

Signed-off-by: Parav Pandit <parav@nvidia.com>
---
changelog:
v1->v2:
- split setup and operations requirements
- added design goal
- worded requirements more precisely
v0->v1:
- fixed comments from Heng Li
- renamed receive flow steering to receive flow filters
- clarified byte offset in match criteria
---
 net-workstream/features-1.4.md | 98 ++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)

diff --git a/net-workstream/features-1.4.md b/net-workstream/features-1.4.md
index a34556c..ae40ee8 100644
--- a/net-workstream/features-1.4.md
+++ b/net-workstream/features-1.4.md
@@ -9,6 +9,7 @@ together is desired while updating the virtio net interface.
 1. Device counters visible to the driver
 2. Low latency tx and rx virtqueues for PCI transport
 3. Virtqueue notification coalescing re-arming support
+4  Virtqueue receive flow filters (RFF)
 
 # 3. Requirements
 ## 3.1 Device counters
@@ -169,3 +170,100 @@ struct vnet_rx_completion {
    generated notification. 
 2. When the driver enables the notification coalescing reporting, the device
    to notify again if notification coalescing conditions are met.
+
+## 3.4 Virtqueue receive flow filters (RFF)
+0. Design goal:
+   To filter and/or to steer packet based on specific pattern match to a
+   specific context to support application/networking stack driven receive
+   processing.
+1. Two use cases are: to support Linux netdev set_rxnfc() for ETHTOOL_SRXCLSRLINS
+   and to support netdev feature NETIF_F_NTUPLE aka ARFS.
+
+### 3.4.1 control path
+1. The number of flow filter operations/sec can range from 100k/sec to 1M/sec
+   or even more. Hence flow filter operations must be done over a queueing
+   interface using one or more queues.
+2. The device should be able to expose one or more supported flow filter queue
+   count and start vq index to the driver.
+3. High rate flow filter operations are supposed to operate that can make device
+   implementation of it in hardware accelerated manner. Hence transporting them
+   using a flow vq being different than control vq is needed.
+3. The driver should be able to query such capability over a DMA interface to
+   save on the device memory of the device config space region.
+4. Since flow filters are enabled much later in the driver life cycle, driver
+   will likely create these queues when flow filters are enabled.
+5. The device should be able to expose if it support filter masks.
+6. The driver may want to have priority among group of flow rules; to facilitate
+   the device support grouping flow filter rules by a notion of a group. Each
+   group defines priority in processing flow.
+
+### 3.4.2 flow operations path
+1. The driver should be able to define a receive packet match criteria, an
+   action and a destination for a packet. For example, an ipv4 packet with a
+   multicast address to be steered to the receive vq 0. The second example is
+   ipv4, tcp packet matching a specified IP address and tcp port tuple to
+   steered to receive vq 10.
+2. The match criteria should include exact tuple fields well-defined such as mac
+   address, IP addresses, tcp/udp ports, etc.
+3. The match criteria should also optionally include the field mask.
+4. The match criteria may optionally also include specific packet byte offset
+   pattern, match length, mask instead of RFC defined fields.
+   length, and matching pattern, which may not be defined in the standard RFC.
+5. Action includes (a) dropping or (b) forwarding the packet.
+6. Destination location is a receive virtqueue index or rss context.
+7. The device should process RFF rules before RSS rules, i.e., when there is a
+   miss on the RFF rule, RSS rule applies if RSS configuration exists.
+8. If multiple rules are programmed which has overlapping attributes for a
+   received packet, the driver to define the location/priority of the rule.
+9. The filter rule add/delete entries are usually short in size of few tens of
+   bytes, for example IPv6 + TCP tuple would be 36 bytes, and ops/sec rate is
+   high, hence supplying fields inside the queue descriptor is preferred for
+   up to a certain fixed size, say 56 bytes.
+10. The driver should be able to query flow filter table entries programmed in
+    the device by the flow id.
+11. The driver should be able to add the entry for attributes (a) match
+    criteria, (b) action, (c) destination and (d) assign a unique id of 32 bits.
+12. The driver should be able to delete the flow filter rule entry via a unique id.
+13. A group member device should be able to query the attributes of the flow
+    filter rules that device supports.
+14. The driver and group owner driver should be able to query supported device
+    limits for the flow rule entries.
+15. Filter rule operation completion to be reported via a completion queue
+    interface.
+
+### 3.4.3 interface example
+
+7. Flow filter capabilities to query using a DMA interface:
+
+```
+struct flow_filter_capabilities {
+	u8 flow_groups;
+	u16 num_flow_filter_vqs;
+	u16 start_vq_index;
+	u32 max_flow_filters_per_group;
+	u32 max_flow_filters;
+	u64 supported_packet_field_mask_bmap[4];
+};
+
+```
+
+1. Flow filter rule add/modify, delete:
+
+struct virtio_net_rff_add_modify {
+	u8 flow_op;
+	u8 group_id;
+	u8 padding[2];
+	le32 flow_id;
+	struct match_criteria mc;
+	struct destination dest;
+	struct action action;
+
+	struct match_criteria mask;	/* optional */
+};
+
+struct virtio_net_rff_delete {
+	u8 flow_op;
+	u8 group_id;
+	u8 padding[2];
+	le32 flow_id;
+};
-- 
2.26.2