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 add or delete.
2. It belongs to a flow filter group (group has priority).
3. Each flow filter is identified using a unique identifier(id),
has priority, match fields, destination(rq) and action(allow/drop).
4. Flow filter has optionally mask too.
This patch adds theory of operation for flow filter functionality.
Fixes:
https://github.com/oasis-tcs/virtio-spec/issues/179Signed-off-by: Heng Qi <
hengqi@linux.alibaba.com>
Signed-off-by: Parav Pandit <
parav@nvidia.com>
---
changelog:
v1->v2:
- fixed comments from Heng
- grammar corrections
- spelling corrections
---
device-types/net/description.tex | 116 ++++++++++++++++++++++++++++++-
1 file changed, 115 insertions(+), 1 deletion(-)
diff --git a/device-types/net/description.tex b/device-types/net/description.tex
index 76585b0..b7adfb8 100644
--- a/device-types/net/description.tex
+++ b/device-types/net/description.tex
@@ -10,7 +10,9 @@ \section{Network Device}\label{sec:Device Types / Network Device}
removes these packets from the transmit virtqueue and sends them to
the link. The device may have a control virtqueue. The driver
uses the control virtqueue to dynamically manipulate various
-features of the initialized device.
+features of the initialized device. The device may have flow filter
+virtqueues. The driver uses flow filter virtqueues to steer specific
+receive packets to a specific destination such as specified receiveq.
\subsection{Device ID}\label{sec:Device Types / Network Device / Device ID}
@@ -33,6 +35,9 @@ \subsection{Virtqueues}\label{sec:Device Types / Network Device / Virtqueues}
controlq is optional; it only exists if VIRTIO_NET_F_CTRL_VQ is
negotiated.
+The flow filter virtqueues are optional; it may exists only if VIRTIO_NET_F_FLOW_FILTER
+is negotiated and if the device reports such capability.
+
\subsection{Feature bits}\label{sec:Device Types / Network Device / Feature bits}
\begin{description}
@@ -119,6 +124,8 @@ \subsection{Feature bits}\label{sec:Device Types / Network Device / Feature bits
device with the same MAC address.
\item[VIRTIO_NET_F_SPEED_DUPLEX(63)] Device reports speed and duplex.
+
+\item[VIRTIO_NET_F_FLOW_FILTER(64)] Device supports flow filter requests.
\end{description}
\subsubsection{Feature bit requirements}\label{sec:Device Types / Network Device / Feature bits / Feature bit requirements}
@@ -150,6 +157,7 @@ \subsubsection{Feature bit requirements}\label{sec:Device Types / Network Device
\item[VIRTIO_NET_F_RSS] Requires VIRTIO_NET_F_CTRL_VQ.
\item[VIRTIO_NET_F_VQ_NOTF_COAL] Requires VIRTIO_NET_F_CTRL_VQ.
\item[VIRTIO_NET_F_HASH_TUNNEL] Requires VIRTIO_NET_F_CTRL_VQ along with VIRTIO_NET_F_RSS or VIRTIO_NET_F_HASH_REPORT.
+\item[VIRTIO_NET_F_FLOW_FILTER] Requires VIRTIO_NET_F_CTRL_VQ.
\end{description}
\subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network Device / Feature bits / Legacy Interface: Feature bits}
@@ -1141,6 +1149,112 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network
#define VIRTIO_NET_HASH_REPORT_UDPv6_EX 9
\end{lstlisting}
+\subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Operation / Flow Filter}
+
+To forward a received packet to a specific receiveq or to drop the packet based
+on one or more fields of the packet, the device supports flow filter
+functionality. The flow filter can match the packet for a flow, take an action
+such as forward the packet to the specific receiveq or drop the packet.
+For example, the driver can request the device to forward received packets
+which match to a specific source and destination IP addresses and
+TCP ports to a specific receiveq.
+
+Each flow filter consists of one or more match key, a flow filter priority,
+a flow filter identifier, an action to forward a packet to the destination
+or to drop the packet.
+
+The match fields also optionally consist of a match mask. When a mask is
+specified for the flow filter, first the packet fields are masked before
+matching with the fields of the flow filter.
+
+Each flow filter is independent of each other. The driver can add, replace
+and delete a flow filter in the device using a flow filter request.
+
+The device indicates the flow filter capabilities to the driver. These
+capabilities include various maximum device limits, supported transports and
+supported packet match fields. The driver enables the transport for flow
+filter requests using a control virtqueue command.
+
+The device supports transporting flow filter requests on either the control
+virtqueue or on the flow filter virtqueues or on both. However, device
+supports enabling flow filter request only on one type of virtqueue
+at a time, i.e. either control virtqueue or flow filter virtqueues.
+Once the driver sets the flow filter request transport in the device,
+the driver can send flow filter request using the enabled transport.
+
+The flow filters are grouped using a flow filter group. Each flow filter
+group has a priority. The device first applies the flow filters of the highest
+priority group to the received packet. If there is no match for the
+flow filters of such a group for the packet, the flow filters of the next
+priority group are applied, until there is a match for the packet from such
+a group or the last group has reached.
+
+The flow filter group can have one or more flow filters. Within a flow
+filter group, a packet may find a match to multiple flow filters. In such
+scenario, a flow filter with the highest priority is applied first to the
+packet, if there is no match, the next higher priority flow filter is applied.
+
+\paragraph{Flow Filter Virtqueue}\label{sec:sec:Device Types / Network Device / Device Operation / Flow Filter / Flow Filter Virtqueue}
+
+The flow filter virtqueues are dedicated virtqueues which transport the
+flow filter requests. The driver adds flow filter request to the flow
+filter virtqueue, the device removes such a request from the virtqueue
+and executes it, when the request is completed by the device, the device
+updates the result of it to the driver.
+
+The flow filter virtqueues are optional. The device may choose to support
+flow filters requests either on the control virtqueue or on the flow filter
+virtqueues or both.
+
+If the VIRTIO_F_RING_DYNAMIC is negotiated, the driver can create the
+flow filter virtqueues after the driver has finished the device
+initialization.
+
+The device can support one or more flow filter virtqueues. The driver
+can choose one to up to supported number of virtqueues to send
+flow filter requests.
+
+If the VIRTIO_F_RING_DYNAMIC is not negotiated, the flow filter
+virtqueues must be created during device initialization phase.
+
+\paragraph{Packet Processing Order}\label{sec:sec:Device Types / Network Device / Device Operation / Flow Filter / Packet Processing Order}
+
+Whichever filtering and steering functionality is enabled, they are
+applied in the following order for the received packet:
+
+\begin{itemize}
+\item apply device configuration done using control virtqueue commands
+ VIRTIO_NET_CTRL_RX, VIRTIO_NET_CTRL_MAC and VIRTIO_NET_CTRL_VLAN.
+\item apply flow filter configuration done using flow filter requests.
+\item apply device configuration done using command
+ VIRTIO_NET_CTRL_MQ_RSS_CONFIG.
+\end{itemize}
+
+While processing a received packet, at any stage if the packet is dropped,
+the next level of processing is omitted.
+
+When a flow filter is matched for the packet, it also stops the processing
+of the packet for next stage.
+
+Few examples are:
+\begin{itemize}
+\item If the packet is dropped by the flow filter configuration, RSS
+ configuration is not applied to such a packet.
+\item If the packet is forwarded to a specific receiveq using flow filters,
+ RSS configuration is not applied to such a packet due to a match on the
+ flow filter request.
+\item If the packet is dropped due to VIRTIO_NET_CTRL_MAC configuration,
+ flow filters or RSS configuration is not applied to such a packet.
+\item If the packet does not find any match in any of the flow filter groups,
+ next level RSS device configuration is applied if its exists.
+\item If there are three flow filter groups configured as group_A, group_B
+ and group_C with respective priorities as 4, 5, and 6; flow filters of
+ group_C is applied first having highest group priority, if there is a match,
+ flow filters of group_B and group_A are skipped; if there is no match for
+ the flow filters in group_C, the flow filters of next level group_B are applied.
+\end{itemize}
+
+\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting Promiscuous Mode}%old label for latexdiff
\subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue}
The driver uses the control virtqueue (if VIRTIO_NET_F_CTRL_VQ is
--
2.34.1