[PATCH v7 10/13] virtio-net: Add flow filter rule resource

[Parav Pandit <parav@nvidia.com>]

Define flow filter rule resource consist of
one or more match key, mask entries and one or more actions.

Currently it covers the most common filter types and value
of Ethernet header, IP addresses, TCP and UDP ports.

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:
- plenty of grammar corrections suggested by Cornelia
- adapt to generic device resource framework
v2->v3:
- removed references to flow filter virtqueues
- removed one partial sentence
- added text for delete request
- aligned request and opcode values to just say request in the defines
v1->v2:
- squashed with match fields definition patch of v1
- added length to the flexible array definition struct to benefit
  from future runtime length bound checkers listed in
  https://people.kernel.org/kees/bounded-flexible-arrays-in-c
- renamed value to key
- addressed comments from Satananda
- merged destination and action to one struct
v0->v1:
- reworded add flow request text to consider optional mask
- replaced respond with set
- added mask flag to the type
---
 device-types/net/description.tex | 165 ++++++++++++++++++++++++++++++-
 1 file changed, 164 insertions(+), 1 deletion(-)

diff --git a/device-types/net/description.tex b/device-types/net/description.tex
index 05979e7..b9d0378 100644
--- a/device-types/net/description.tex
+++ b/device-types/net/description.tex
@@ -485,6 +485,8 @@ \subsection{Device Resources}\label{sec:Device Types / Network Device / Device R
 \hline \hline
 0x0200 & VIRTIO_NET_RESOURCE_FF_GROUP & Flow filter group \\
 \hline
+0x0201 & VIRTIO_NET_RESOURCE_FF_RULE & Flow filter rule \\
+\hline
 \end{tabularx}
 
 \subsubsection{Flow Filter Group}\label{sec:Device Types / Network Device / Device Resources / Flow Filter Group}
@@ -499,6 +501,95 @@ \subsubsection{Flow Filter Group}\label{sec:Device Types / Network Device / Devi
 };
 \end{lstlisting}
 
+\subsubsection{Flow Filter Rule}\label{sec:Device Types / Network Device / Device Resources / Flow Filter Rule}
+
+Each flow filter rule resource consist of one or more match entries and
+one or more actions. The packet is matched against one or more match
+entries of type \field{struct virtio_ff_match_entry}. When the packet
+matches to all the match entries of \field{struct virtio_ff_match_entries},
+the device applies one or more actions of \field{struct virtio_ff_actions}.
+
+\begin{lstlisting}
+struct virtio_ff_match_entry {
+        le16 type;
+        u8 key_len; /* length of key */
+        u8 mask_len; /* length of mask */
+        le64 fields_bmap;
+        u8 key[];
+        u8 mask[]; /* optional, only present when mask_len > 0 */
+};
+
+struct virtio_ff_match_entries {
+       u8 num_entries; /* indicates number of valid entries */
+       u8 reserved[7];
+       struct virtio_ff_match_entry entries[];
+};
+\end{lstlisting}
+
+\field{num_entries} indidates the number of valid array entries \field{entries}.
+For each of the valid entry in \field{entries}, fields \field{type}
+and \field{key} are in the format described in
+\ref{par:Device Types / Network Device / Device Operation / Flow Filter / Match Types and Keys}.
+\field{key_len} represents the length of field \field{key}.
+When \field{mask_len} is non zero, \field{mask} is present and has
+exact same format as \field{key} and \field{mask_len} represents the length
+of the field \field{mask}.
+
+\begin{lstlisting}
+#define VIRTIO_NET_FF_DEST_TYPE_RX_VQ 0
+
+struct virtio_ff_action_forward {
+        u8 dest_type;
+        u8 reserved[3];
+        union {
+                le16 vq_index;
+                le32 reserved1;
+        };
+};
+
+#define VIRTIO_NET_FF_ACTION_DROP 0
+#define VIRTIO_NET_FF_ACTION_FORWARD 1
+
+struct virtio_ff_action {
+        u8 action;
+        u8 len; /* indicates the length of value in bytes */
+        u8 value[];
+};
+
+struct virtio_ff_actions {
+        u8 num_actions; /* indicates number of valid actions */
+        u8 reserved[7];
+        struct virtio_ff_action actions[];
+};
+\end{lstlisting}
+
+\field{num_actions} indicates valid number of array entries of \field{actions}
+to apply when the packet matches all the supplied match entries; these
+\field{actions} are applied sequentially to the packet.
+
+For the device resource VIRTIO_NET_RESOURCE_FF_RULE, the
+\field{resource_specific_data} is in the format of
+\field{struct virtio_net_resource_ff_rule}.
+
+When \field{action} is set to VIRTIO_NET_FF_ACTION_DROP, the matching packet
+will be dropped by the device.
+
+When \field{action} is set to VIRTIO_NET_FF_ACTION_FORWARD, \field{value} is
+in format of \field{struct virtio_ff_action_forward} and the matching packet
+will be forwarded to the specified destination, i.e. when \field{dest_type}
+is VIRTIO_NET_FF_DEST_TYPE_RX_VQ, it is forwarded to the specified receive
+virtqueue.
+
+\begin{lstlisting}
+struct virtio_net_resource_ff_rule {
+        le32 group_id;
+        u8 priority;	/* higher priority rules are processed first */
+        u8 reserved[3];
+        struct virtio_ff_match_entries match_entries;
+        struct virtio_ff_actions actions;
+};
+\end{lstlisting}
+
 \subsection{Device Operation}\label{sec:Device Types / Network Device / Device Operation}
 
 Packets are transmitted by placing them in the
@@ -2510,7 +2601,8 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 
 \paragraph{Match Types and Keys}\label{par:Device Types / Network Device / Device Operation / Flow Filter / Match Types and Keys}
 
-The \field{type} for \field{struct virtio_net_ff_match_type_cap} corresponds to following table:
+The \field{type} for \field{struct virtio_net_ff_match_type_cap} and \field{struct virtio_ff_match_entry}
+corresponds to following table:
 
 \begin{tabular}{|l|l|l|}
 \hline
@@ -2553,6 +2645,21 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 \hline
 \end{tabular}
 
+For the \field{type} of VIRTIO_NET_FF_ETH_HDR, the match entries
+\field{key} and \field{mask} are in following format:
+
+\begin{lstlisting}
+struct virtio_net_ff_match_eth_hdr {
+        u8 dmac[6];
+        u8 smac[6];
+        le16 ether_type;
+};
+\end{lstlisting}
+
+\field{dmac} is valid when VIRTIO_NET_FF_DST_MAC is set.
+\field{smac} is valid when VIRTIO_NET_FF_SRC_MAC is set.
+\field{ether_type} is valid when VIRTIO_NET_FF_ETHER_TYPE is set.
+
 For the \field{type} of VIRTIO_NET_FF_VLAN_TAG_HDR, VLAN tag fields
 are represented by a bitmap in \field{fields_bmap} as follows:
 
@@ -2581,6 +2688,20 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 \hline
 \end{tabular}
 
+For the \field{type} of VIRTIO_NET_FF_IPV4_HDR, the match entries
+\field{key} and \field{mask} are in following format:
+
+\begin{lstlisting}
+struct virtio_net_ff_match_ipv4_hdr {
+        le32 reserved[3];
+        le32 sip;
+        le32 dip;
+};
+\end{lstlisting}
+
+\field{sip} is valid when VIRTIO_NET_FF_SRC_IPV4 is set.
+\field{dip} is valid when VIRTIO_NET_FF_DST_IPV4 is set.
+
 For the \field{type} of VIRTIO_NET_FF_IPV6_HDR, header fields
 are represented by a bitmap in \field{fields_bmap} as follows:
 
@@ -2596,6 +2717,20 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 \hline
 \end{tabular}
 
+For the \field{type} of VIRTIO_NET_FF_IPV4_HDR, the match entries
+\field{key} and \field{mask} are in following format:
+
+\begin{lstlisting}
+struct virtio_net_ff_match_ipv6_hdr {
+        le32 reserved[2];
+        u8 sip[16];
+        u8 dip[16];
+};
+\end{lstlisting}
+
+\field{sip} is valid when VIRTIO_NET_FF_SRC_IPV6 is set.
+\field{dip} is valid when VIRTIO_NET_FF_DST_IPV6 is set.
+
 For the \field{type} of VIRTIO_NET_FF_TCP_HDR, header fields
 are represented by a bitmap in \field{fields_bmap} as follows:
 
@@ -2611,6 +2746,20 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 \hline
 \end{tabular}
 
+For the \field{type} of VIRTIO_NET_FF_TCP_HDR, the match entries
+\field{key} and \field{mask} are in following format:
+
+\begin{lstlisting}
+struct virtio_ndr_ff_match_tcp_hdr {
+        le16 sport;
+        le16 dport;
+        le32 reserved[4];
+};
+\end{lstlisting}
+
+\field{sport} is valid when VIRTIO_NET_FF_SRC_TCP_PORT is set.
+\field{dport} is valid when VIRTIO_NET_FF_DST_TCP_PORT is set.
+
 For the \field{type} of VIRTIO_NET_FF_UDP_HDR, header fields
 are represented by a bitmap in \field{fields_bmap} as follows:
 
@@ -2626,6 +2775,20 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 \hline
 \end{tabular}
 
+For the \field{type} of VIRTIO_NET_FF_UDP_HDR, the match entries
+\field{key} and \field{mask} are in following format:
+
+\begin{lstlisting}
+struct virtio_ndr_ff_match_udp_hdr {
+        le16 sport;
+        le16 dport;
+        le32 reserved;
+};
+\end{lstlisting}
+
+\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.
+
 \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
 Types / Network Device / Legacy Interface: Framing Requirements}
 
-- 
2.34.1