[PATCH 6/7] virtio-net: Add flow filter requests

[Parav Pandit <parav@nvidia.com>]

Define generic flow filter add and delete requests and its transport
using a control virtqueue command and flow filter virtqueue(s).

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>
---
 device-types/net/description.tex | 117 +++++++++++++++++++++++++++++++
 1 file changed, 117 insertions(+)

diff --git a/device-types/net/description.tex b/device-types/net/description.tex
index a3cbb29..a96e47a 100644
--- a/device-types/net/description.tex
+++ b/device-types/net/description.tex
@@ -1447,6 +1447,98 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 The \field{sport} is valid when VIRTIO_NET_FF_SRC_UDP_PORT is set.
 This \field{dport} is valid when VIRTIO_NET_FF_DST_UDP_PORT is set.
 
+\paragraph{Flow Filter Request}
+\label{sec:Device Types / Network Device / Device Operation / Flow Filter / Flow Filter Request}
+
+Two flow filter requests are supported by the device.
+
+\begin{itemize}
+\item Add or replace a flow filter using a request \field{struct virtio_net_ff_add}.
+
+\item Delete an existing flow filter using a request \field{struct virtio_net_ff_del}.
+
+\end{itemize}
+
+\begin{lstlisting}
+struct virtio_net_ff_match_field {
+        struct virtio_net_ff_match_type type;
+        struct virtio_net_ff_match_value value;
+};
+
+struct virtio_net_ff_match_fields {
+        le32 num_entries;
+        struct virtio_net_ff_match_field match_entries[];
+};
+
+#define VIRTIO_NET_FF_DEST_RQ 0
+
+struct virtio_net_ff_dest {
+        u8 dest_type;
+        u8 reserved[3];
+        union {
+                le16 vq_index;
+                le32 reserved1;
+        };
+};
+
+struct virtio_net_ff_action {
+        u8 action;
+        u8 reserved[7];
+};
+
+#define VIRTIO_NET_FF_ACTION_DROP 0
+#define VIRTIO_NET_FF_ACTION_FORWARD 1
+
+struct virtio_net_ff_add {
+        u8 op;
+        u8 priority;	/* higher the value, higher priority */
+        u16 group_id;
+        le32 id;
+        struct virtio_net_ff_match_fields match;
+        struct virtio_net_ff_dest dest;
+        struct virtio_net_ff_action action;
+
+        struct virtio_net_ff_match_fields mask;	/* optional */
+};
+
+struct virtio_net_ff_del {
+        u8 op;
+        u8 padding[3];
+        le32 id;
+};
+
+#define VIRTIO_NET_FF_REQ__ADD 0
+#define VIRTIO_NET_FF_REQ__DEL 1
+
+struct virtio_net_ff_req_result {
+        le16 status;
+};
+
+#define VIRTIO_NET_FF_RESULT_OK 0
+#define VIRTIO_NET_FF_RESULT_ERR 1
+
+struct virtio_net_ff_req {
+        /* Device-readable part */
+        union {
+                struct virtio_net_ff_add add;
+                struct virtio_net_ff_del del;
+        };
+        /* Device-writable part */
+        struct virtio_net_ff_req_result result;
+};
+\end{lstlisting}
+
+When the flow filter request is sent using a flow filter virtqueue,
+the descriptors points to \field{struct virtio_net_ff_req}.
+
+In the field \field{match_entries}, for each of the array entry the
+field \field{value} and \field{type} are in the format described in
+\ref{sec:Device Types / Network Device / Device Operation / Flow Filter / Match Types and Fields}.
+
+When the device completes the request, \field{status} is updated
+by the device; when the request is successful, \field{status} is VIRTIO_NET_FF_RESULT_OK,
+when there is an error, \field{status} is VIRTIO_NET_FF_RESULT_ERR.
+
 \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
@@ -2125,6 +2217,7 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi
  #define VIRTIO_NET_CTRL_FF_GROUP_ADD 2
  #define VIRTIO_NET_CTRL_FF_GROUP_DEL 3
  #define VIRTIO_NET_CTRL_FF_TRANSPORT_MODE_SET 4
+ #define VIRTIO_NET_CTRL_FF_REQ 5
 \end{lstlisting}
 
 \subparagraph{Flow Filter Capabilities Get}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Flow Filter / Flow Filter Capabilities Get}
@@ -2241,6 +2334,30 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi
 \field{mode} is set to 1, it indicates that the driver will use
 flow filter virtqueue(s) for transporting flow filter requests.
 
+\subparagraph{Flow Filter Requests}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Flow Filter / Flow Filter Requests}
+
+When the driver has successfully set flow filter transport mode as control
+virtqueue using command VIRTIO_NET_CTRL_FF_TRANSPORT_MODE_SET, the
+flow filter requests are transported using command
+VIRTIO_NET_CTRL_FF_REQ over a control virtqueue.
+
+\begin{lstlisting}
+struct virtio_net_ctrl_ff_req {
+        union {
+                struct virtio_net_ff_add add;
+                struct virtio_net_ff_del del;
+        };
+};
+
+\end{lstlisting}
+
+The \field{command-specific-data} is in format of
+\field{struct virtio_net_ctrl_ff_req}.
+
+When the flow filter request command is successful, the
+\field{command-specific-result} is in format of
+\field{struct virtio_net_ff_req_result}.
+
 \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
 Types / Network Device / Legacy Interface: Framing Requirements}
 
-- 
2.34.1