[PATCH v9 11/13] virtio-net: Add flow filter device and driver requirements

[Parav Pandit <parav@nvidia.com>]

Add device and driver flow filter requirements.

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179
Signed-off-by: Heng Qi <hengqi@linux.alibaba.com>
Signed-off-by: Parav Pandit <parav@nvidia.com>
---
changelog:
v6->v7:
- added device normatives for valid ranges
- rebased to use capabilities and resources
v5->v6:
- removed white spaces from end of line
- added missing conformance links
v2->v3:
- removed dependency on the dynamic queue creation as the
  infrastructure is not yet ready
v1->v2:
- fixed comments from Heng
- fixed spelling from initializaton to initialization
- added more requirements for multiple actions
v0->v1:
- addressed comments from Satananda
- added device requirement to return non zero value in fields_bmap
- added device requirement to not repeat filter type in response
- added driver requirement to order filter match field as it
  appears in the packet
- added device requirement to fail group delete command on existing
  flow entries
---
 device-types/net/description.tex        | 123 ++++++++++++++++++++++++
 device-types/net/device-conformance.tex |   1 +
 device-types/net/driver-conformance.tex |   1 +
 3 files changed, 125 insertions(+)

diff --git a/device-types/net/description.tex b/device-types/net/description.tex
index b9d0378..268e448 100644
--- a/device-types/net/description.tex
+++ b/device-types/net/description.tex
@@ -2789,6 +2789,129 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 \field{sport} is valid when VIRTIO_NET_FF_SRC_UDP_PORT is set.
 \field{dport} is valid when VIRTIO_NET_FF_DST_UDP_PORT is set.
 
+\devicenormative{\paragraph}{Flow Filter}{Device Types / Network Device / Device Operation / Flow Filter}
+
+When the device supports flow filter operations,
+\begin{itemize}
+\item the device MUST set VIRTIO_NET_FF_RESOURCE_CAP and VIRTIO_NET_FF_MATCH_CAP
+capabilities in the \field{supported_caps} in
+VIRTIO_ADMIN_CMD_CAP_SUPPORT_QUERY command.
+\item the device MUST support VIRTIO_ADMIN_CMD_RESOURCE_ADD,
+VIRTIO_ADMIN_CMD_RESOURCE_MODIFY, VIRTIO_ADMIN_CMD_RESOURCE_QUERY,
+VIRTIO_ADMIN_CMD_RESOURCE_REMOVE administration commands for resource type
+VIRTIO_NET_RESOURCE_FF_GROUP and VIRTIO_NET_RESOURCE_FF_RULE.
+\end{itemize}
+
+When the VIRTIO_NET_FF_RESOURCE_CAP or VIRTIO_NET_FF_MATCH_CAP capability
+is disabled, the device MUST respond \field{status} as
+VIRTIO_ADMIN_STATUS_Q_INVALID_OPCODE for commands
+VIRTIO_ADMIN_CMD_RESOURCE_ADD,
+VIRTIO_ADMIN_CMD_RESOURCE_MODIFY, VIRTIO_ADMIN_CMD_RESOURCE_QUERY,
+and VIRTIO_ADMIN_CMD_RESOURCE_REMOVE for resource \field{type} of
+VIRTIO_NET_RESOURCE_FF_GROUP and VIRTIO_NET_RESOURCE_FF_RULE.
+
+When the command VIRTIO_ADMIN_CMD_CAP_SUPPORT_QUERY completes successfully,
+the device MUST NOT repeat \field{type} in the \field{types}.
+
+The device MUST set \field{status} to VIRTIO_ADMIN_STATUS_EINVAL for the command
+VIRTIO_ADMIN_CMD_RESOURCE_ADD for the resource \field{type} of
+VIRTIO_NET_RESOURCE_FF_GROUP if a flow filter group already exists
+with supplied \field{priority}.
+
+The device MUST set \field{status} to VIRTIO_ADMIN_STATUS_ENOSPC for the command
+VIRTIO_ADMIN_CMD_RESOURCE_ADD for the resource \field{type} of
+VIRTIO_NET_RESOURCE_FF_GROUP if the flow filter groups in the device
+exceeds more than the value reported in the device capability
+VIRTIO_NET_RESOURCE_FF_GROUP in field \field{groups.max_limit}.
+
+The device MUST set \field{status} to VIRTIO_ADMIN_STATUS_EBUSY for the command
+VIRTIO_ADMIN_CMD_RESOURCE_REMOVE for flow filter group resource when the flow
+filter group has one or more flow filter rules linked to the flow filter group.
+
+The device MUST fail the command VIRTIO_ADMIN_CMD_RESOURCE_ADD for the
+flow filter rule resource,
+\begin{itemize}
+\item if \field{match} contains duplicate \field{type},
+\item if \field{vq_index} in the \field{dest} is not a valid receive
+      virtqueue index,
+\item if \field{priority} is greater than or equal to
+      \field{max_ff_rules_priorities_per_group},
+\item if \field{id} is greater than or equal to \field{rules.max_limit}.
+\item if \field{num_entries} of \field{match_entries.entries} is greater than
+      \field{max_match_fields}.
+\item if \field{num_actions} of \field{actions} is greater than
+      \field{max_actions}.
+\end{itemize}
+
+When the flow filter forwards the packet to the virtqueue identfied by
+\field{vq_index} and if the receive virtqueue is reset, the device
+MUST drop such packets.
+
+The device MUST apply the actions of \field{struct virtio_flow_action} in same
+order as it is supplied by the driver when \field{num_entries} is greater than 1.
+
+The device MUST follow received packet processing ordering chain as following:
+\begin{itemize}
+\item Device configuration done using control virtqueue commands VIRTIO_NET_CTRL_RX,
+   VIRTIO_NET_CTRL_MAC and VIRTIO_NET_CTRL_VLAN.
+\item Flow filters programmed using flow filters functionality.
+\item Device configuration done using VIRTIO_NET_CTRL_MQ_RSS_CONFIG command.
+\end{itemize}
+
+When processing a packet, if the packet is dropped at any stage, the device
+MUST omit processing of next level.
+
+When the device matches the flow filter rule for the packet and if the match is
+successful, the device MUST STOP the filter processing chain, i.e. next level
+of processing MUST not be done.
+
+For multiple flow filter groups, the device MUST follow
+received packet processing ordering chain as following:
+apply all the flow filter rules of the highest priority group;
+if the match is successful, skip rules of all the lower priority group,
+if there is no match, the next higher priority group's rules are
+applied.
+
+Within a flow filter group, the device MUST apply the rules with the
+highest priority first; if there is a match, skip rules of all the lower
+priorities; if there is no match, the next higher priority rule is applied.
+
+When the driver has added multiple flow filter rules with same \field{priority}
+and for a packet if multiple flow filters MAY match such that it MAY result
+in different \field{action} or different \field{dest}, the device MUST apply
+the flow filter rule which is added first.
+
+When the device drops the packet due to the configuration done using the control
+virtqueue commands VIRTIO_NET_CTRL_RX or VIRTIO_NET_CTRL_MAC or VIRTIO_NET_CTRL_VLAN,
+the device MUST stop processing this packet for flow filters processing.
+
+When the device perform flow filter match operations and if the operation
+result did not have any match, the receive packet processing continues to next level,
+i.e. to apply configuration done using VIRTIO_NET_CTRL_MQ_RSS_CONFIG command.
+
+\drivernormative{\paragraph}{Flow Filter}{Device Types / Network Device / Device Operation / Flow Filter}
+
+The driver must enable VIRTIO_NET_FF_RESOURCE_CAP and VIRTIO_NET_FF_MATCH_CAP
+capabilities to use flow filter operations.
+
+The driver SHOULD NOT add multiple flow filters with same \field{priority}
+in a flow filter group, with overlapping match values.
+
+The driver SHOULD use different priority for different flow filters
+if multiple of the flow filters MAY match for a packet.
+
+The driver SHOULD set the \field{type} in \field{match_entries} as that of
+the order appears in the packet.
+
+The driver MUST NOT set \field{num_entries} in \field{struct virtio_ff_action}
+to more than \field{max_actions} supplied by the device in the
+\field{virtio_net_ctrl_ff_caps}.
+
+The driver SHOULD NOT remove flow filter group using command
+VIRTIO_ADMIN_CMD_RESOURCE_REMOVE when one or more flow filter rules are linked to
+the flow filter group; the driver SHOULD remove flow filter group only after
+all the flow filter rules are removed.
+
 \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
 Types / Network Device / Legacy Interface: Framing Requirements}
 
diff --git a/device-types/net/device-conformance.tex b/device-types/net/device-conformance.tex
index 52526e4..8da520a 100644
--- a/device-types/net/device-conformance.tex
+++ b/device-types/net/device-conformance.tex
@@ -16,4 +16,5 @@
 \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}
 \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Inner Header Hash}
 \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics}
+\item \ref{devicenormative:Device Types / Network Device / Device Operation / Flow Filter}
 \end{itemize}
diff --git a/device-types/net/driver-conformance.tex b/device-types/net/driver-conformance.tex
index c693c4f..79c3572 100644
--- a/device-types/net/driver-conformance.tex
+++ b/device-types/net/driver-conformance.tex
@@ -16,4 +16,5 @@
 \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}
 \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Inner Header Hash}
 \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics}
+\item \ref{drivernormative:Device Types / Network Device / Device Operation / Flow Filter}
 \end{itemize}
-- 
2.34.1