[PATCH v1 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>

---
changelog:
v0->v1:
- reworded add flow request text to consider optional mask
- replaced respond with set
---
 device-types/net/description.tex | 123 +++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)

diff --git a/device-types/net/description.tex b/device-types/net/description.tex
index 19d1655..cf2836d 100644
--- a/device-types/net/description.tex
+++ b/device-types/net/description.tex
@@ -1452,6 +1452,104 @@ \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_value mask;	/* optional, only exists if mask in type is set to 1. */
+};
+
+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_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
+set to VIRTIO_NET_FF_RESULT_OK, on error, \field{status} is
+set to VIRTIO_NET_FF_RESULT_ERR.
+
+When the driver sets the \field{mask} to 1 in
+\field{struct virtio_net_ff_match_type}, the \field{mask} is present in
+\field{struct virtio_net_ff_match_field}. When the mask is present in
+the flow filter, for the match \field{type}, the mask is applied first to the
+packet fields before comparing the match result.
+
 \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
@@ -2130,6 +2228,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 +2340,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