[PATCH v11 08/13] virtio-net: Add theory of operation for flow filter

[Parav Pandit <parav@nvidia.com>]

Currently packet allow/drop interface has following limitations.

1. Driver can either select which MAC and VLANs to consider
for allowing/dropping packets, here, the driver has a
limitation that driver needs to supply full mac
table or full vlan table for each type. Driver cannot add or
delete an individual entry.

2. Driver cannot select mac+vlan combination for which
to allow/drop packet.

3. Driver cannot not set other commonly used packet match fields
such as IP header fields, TCP, UDP, SCP header fields.

4. Driver cannot steer specific packets based on the match
fields to specific receiveq.

5. Driver do not have multiple or dedicated virtqueues to
   perform flow filter requests in accelerated manner in
   the device.

Flow filter as a generic framework overcome above limitations.

As starting point it is useful to support at least two use cases.
a. ARFS
b. ethtool ntuple steering

In future it can be further extended for usecases such as
switching device, connection tracking or may be more.

The flow filter has following properties.

1. It is an extendible object that driver can create, destroy.
2. It belongs to a flow filter group.
3. Each flow filter rule is identified using a unique id,
   has priority, match key, destination(rq) and action(allow/drop).
4. Flow filter key also refers to the mask to learn which fields
   of the packets to match.

This patch adds theory of operation for flow filter functionality.

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179
Signed-off-by: Parav Pandit <parav@nvidia.com>
Signed-off-by: Heng Qi <hengqi@linux.alibaba.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
changelog:
v9->v10:
- updated to refer to device resource object
v6->v7:
- addressed comments from Cornelia
- plenty of grammar corrections suggested by Cornelia
- removed stale reference to flow filter virtqueue
- removed incorrect stale hunk of a label
- removed dependency on feature bit and control vq
- rebased to use device capabilities and device resources
v4->v5:
- to avoid feature bit overlap with rss context patch, pick next
  unique bit 65
v3->v4:
- removed flow filter virtqueue section as dynamic queues are
  not supported currently
v2->v3:
- removed dependency on the dynamic queue creation as the
  infrastructure is not yet ready
v1->v2:
- fixed comments from Heng
- grammar corrections
- spelling corrections
---
 device-types/net/description.tex | 68 ++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/device-types/net/description.tex b/device-types/net/description.tex
index e65cdd5..58d0692 100644
--- a/device-types/net/description.tex
+++ b/device-types/net/description.tex
@@ -2411,6 +2411,74 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi
 of the driver's records. In such cases, the driver should allocate additional
 space for the \field{command-specific-result} buffer.
 
+\subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Operation / Flow filter}
+
+A network device can support one or more flow filter rules. Each flow filter rule
+is applied by matching a packet and then taking an action, such as directing the packet
+to a specific receiveq or dropping the packet. An example of a match is
+matching on specific source and destination IP addresses.
+
+A flow filter rule is a device resource object that consists of a key,
+a processing priority, and an action to either direct a packet to a
+receive queue or drop the packet.
+
+Each rule uses a classifier. The key is matched against the packet using
+a classifier, defining which fields in the packet are matched.
+A classifier resource object consists of one or more field selectors, each with
+a type that specifies the header fields to be matched against, and a mask.
+The mask can match whole fields or parts of a field in a header. Each
+rule resource object depends on the classifier resource object.
+
+When a packet is received, relevant fields are extracted
+(in the same way) from both the packet and the key according to the
+classifier. The resulting field contents are then compared -
+if they are identical the rule action is taken, if they are not, the rule is ignored.
+
+Multiple flow filter rules are part of a group. The rule resource object
+depends on the group. Each rule within a
+group has a rule priority, and each group also has a group priority. For a
+packet, a group with the highest priority is selected first. Within a group,
+rules are applied from highest to lowest priority, until one of the rules
+matches the packet and an action is taken. If all the rules within a group
+are ignored, the group with the next highest priority is selected, and so on.
+
+The driver controls the flow filter rule, classifier and group resource objects using
+administration commands described in
+\ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects}.
+
+\paragraph{Packet processing order}\label{sec:sec:Device Types / Network Device / Device Operation / Flow filter / Packet processing order}
+
+Note that flow filter rules are applied after MAC/VLAN filtering. Flow filter
+rules take precedence over steering: if a flow filter rule results in an action,
+the steering configuration does not apply. The steering configuration only applies
+to packets for which no flow filter rule action was performed. For example,
+incoming packets can be processed in the following order:
+
+\begin{itemize}
+\item apply steering configuration received using control virtqueue commands
+      VIRTIO_NET_CTRL_RX, VIRTIO_NET_CTRL_MAC and VIRTIO_NET_CTRL_VLAN.
+\item apply flow filter rules if any.
+\item if no filter rule applied, apply steering configuration received using command
+      VIRTIO_NET_CTRL_MQ_RSS_CONFIG or as per automatic receive steering.
+\end{itemize}
+
+Some incoming packet processing examples:
+\begin{itemize}
+\item If the packet is dropped by the flow filter rule, RSS
+      steering is ignored for the packet.
+\item If the packet is directed to a specific receiveq using flow filter rule,
+      the RSS steering is ignored for the packet.
+\item If a packet is dropped due to the VIRTIO_NET_CTRL_MAC configuration,
+      both flow filter rules and the RSS steering are ignored for the packet.
+\item If a packet does not match any flow filter rules,
+      the RSS steering is used to select the receiveq for the packet (if enabled).
+\item If there are two flow filter groups configured as group_A and group_B
+      with respective group priorities as 4, and 5; flow filter rules of
+      group_B are applied first having highest group priority, if there is a match,
+      the flow filter rules of group_A are ignored; if there is no match for
+      the flow filter rules in group_B, the flow filter rules of next level group_A are applied.
+\end{itemize}
+
 \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
 Types / Network Device / Legacy Interface: Framing Requirements}
 
-- 
2.34.1