[PATCH RFC 3/4] virtio-net: updates to virtio_net_hdr for IPsec support

[Srujana Challa <schalla@marvell.com>]

Introduces new fields(8 bytes) to the the virtio_net_hdr
structure, enabling IPsec processing.

Signed-off-by: Srujana Challa <schalla@marvell.com>
---
 device-types/net/description.tex | 38 +++++++++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/device-types/net/description.tex b/device-types/net/description.tex
index ace2538..5ebb28a 100644
--- a/device-types/net/description.tex
+++ b/device-types/net/description.tex
@@ -453,6 +453,7 @@ \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O
 #define VIRTIO_NET_HDR_F_NEEDS_CSUM    1
 #define VIRTIO_NET_HDR_F_DATA_VALID    2
 #define VIRTIO_NET_HDR_F_RSC_INFO      4
+#define VIRTIO_NET_HDR_F_SECURITY      8
         u8 flags;
 #define VIRTIO_NET_HDR_GSO_NONE        0
 #define VIRTIO_NET_HDR_GSO_TCPV4       1
@@ -469,6 +470,10 @@ \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O
         le32 hash_value;        (Only if VIRTIO_NET_F_HASH_REPORT negotiated)
         le16 hash_report;       (Only if VIRTIO_NET_F_HASH_REPORT negotiated)
         le16 padding_reserved;  (Only if VIRTIO_NET_F_HASH_REPORT negotiated)
+        struct security_hdr {
+                le32 resource_id;
+                le16 resource_type;
+        };
 };
 \end{lstlisting}
 
@@ -492,6 +497,8 @@ \subsubsection{Legacy Interface: Device Operation}\label{sec:Device Types / Netw
 Historically, some devices put
 the total descriptor length there, even though no data was
 actually written.
+
+\field{resource_id} and \field{resource_type} are valid only when IPsec is enabled.
 \end{note}
 
 \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / Device Operation / Packet Transmission}
@@ -653,6 +660,15 @@ \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De
 The driver MUST NOT set the VIRTIO_NET_HDR_F_DATA_VALID and
 VIRTIO_NET_HDR_F_RSC_INFO bits in \field{flags}.
 
+If the device supports \hyperref[par:Device Types / Network Device / Device Operation / IPsec Operation]{IPsec Operation},
+the driver may set VIRTIO_NET_HDR_F_SECURITY bit in \field{flags}, if so:
+\begin{enumerate}
+\item the driver MUST create IPsec Outbound resource object
+\hyperref[par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-ENC-SA]{VIRTIO_NET_RESOURCE_OBJ_IPSEC_OUTB_SA}
+\item the driver MUST set \field{resource_id} to a valid IPsec outbound
+      resource object ID.
+\end{enumerate}
+
 \devicenormative{\paragraph}{Packet Transmission}{Device Types / Network Device / Device Operation / Packet Transmission}
 The device MUST ignore \field{flag} bits that it does not recognize.
 
@@ -684,6 +700,10 @@ \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De
 
 If VIRTIO_NET_HDR_F_NEEDS_CSUM is not set, the device MUST NOT
 rely on the packet checksum being correct.
+
+If VIRTIO_NET_HDR_F_SECURITY bit in \field{flags} is not set, the
+device MUST NOT use the \field{resource_id} and \field{resource_type}.
+
 \paragraph{Packet Transmission Interrupt}\label{sec:Device Types / Network Device / Device Operation / Packet Transmission / Packet Transmission Interrupt}
 
 Often a driver will suppress transmission virtqueue interrupts
@@ -728,7 +748,7 @@ \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi
   \end{itemize}
 \item If VIRTIO_NET_F_MRG_RXBUF is negotiated, each buffer MUST be at
 least size of \field{struct virtio_net_hdr},
-i.e. 20 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 12 bytes if not.
+i.e. 28 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 20 bytes if not.
 \end{itemize}
 
 \begin{note}
@@ -736,8 +756,8 @@ \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi
 \end{note}
 
 When calculating the size of \field{struct virtio_net_hdr}, the driver
-MUST consider all the fields inclusive up to \field{padding_reserved},
-i.e. 20 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 12 bytes if not.
+MUST consider all the fields inclusive up to \field{security_hdr},
+i.e. 28 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 20 bytes if not.
 
 If VIRTIO_NET_F_MQ is negotiated, each of receiveq1\ldots receiveqN
 that will be used SHOULD be populated with receive buffers.
@@ -906,6 +926,14 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network
 checksum (in case of multiple encapsulated protocols, one level
 of checksums is validated).
 
+The device SHOULD set the VIRTIO_NET_HDR_F_SECURITY bit in the \field{flags}
+if the packet is gone through the IPsec processing. Otherwise, it should
+be cleared.
+
+The device SHOULD set the VIRTIO_NET_HDR_F_DATA_VALID bit in the \field{flags}
+for IPsec packets only upon successful completion of IPsec processing.
+Otherwise, it should be cleared.
+
 \drivernormative{\paragraph}{Processing of Incoming
 Packets}{Device Types / Network Device / Device Operation /
 Processing of Incoming Packets}
@@ -928,6 +956,10 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network
 VIRTIO_NET_HDR_F_DATA_VALID is set, the driver MUST NOT
 rely on the packet checksum being correct.
 
+If VIRTIO_NET_HDR_F_SECURITY bit is set in the \field{flags},
+the driver SHOULD treat the packet as an error packet if the
+VIRTIO_NET_HDR_F_DATA_VALID bit is not set in the \field{flags}.
+
 \paragraph{Hash calculation for incoming packets}
 \label{sec:Device Types / Network Device / Device Operation / Processing of Incoming Packets / Hash calculation for incoming packets}
 
-- 
2.25.1