[virtio-dev] [PATCH] virtio-transport: Clarify requirements

The virtio documentation currently doesn't define any generic
requirements that are applicable to all transports. They can be useful
while adding support for a new transport.

This commit tries to define the same.

Signed-off-by: Viresh Kumar <[email protected]>
---
 content.tex | 48 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 46 insertions(+), 2 deletions(-)

diff --git a/content.tex b/content.tex
index 0a62dce5f65f..d4d5e7d7045b 100644
--- a/content.tex
+++ b/content.tex
@@ -631,8 +631,52 @@ \section{Device Cleanup}\label{sec:General Initialization And Device Operation /
 
 \chapter{Virtio Transport Options}\label{sec:Virtio Transport Options}
 
-Virtio can use various different buses, thus the standard is split
-into virtio general and bus-specific sections.
+The virtio devices are exposed to the guest as if they are physical
+devices using a specific transport method, like PCI, MMIO or Channel
+I/O. The transport methods define various aspects of the communication
+between the device and the driver, like device discovery, exchanging
+capabilities, interrupt handling, data transfer, etc.. Virtio can use
+various different buses, thus the standard is split into virtio general
+and bus-specific sections.
+
+\section{Virtio Transport Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements}
+
+\devicenormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options}
+
+The device MUST present each event, in a transport defined way, from the
+moment it takes place until the driver acknowledges the event.
+
+The device MUST NOT access virtqueue's contents before the driver
+notifies that the queue is ready for access, in a transport defined way.
+
+The device MUST NOT access buffers on the virtqueue, after it has
+modified them and notified the driver about their availability.
+
+The device MUST reset the virtqueues if requested by the driver, in a
+transport defined way.
+
+\drivernormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options}
+
+The driver MUST NOT access guest memory locations outside what's made
+available by the device to the driver.
+
+The driver MUST NOT write to the read-only memory area and MUST NOT read
+from the write-only memory area.
+
+The driver MUST acknowledge events presented by the device, as mandated
+by the transport.
+
+The driver MUST NOT access virtqueue contents before the device notifies
+about the readiness of the same.
+
+The driver MUST NOT access buffers, after it has added them to the
+virtqueue and notified the device about their availability. The driver
+MAY access them after the device has processed them and notified the
+driver of their availability, in a transport defined way.
+
+The driver MAY ask the device to reset the virtqueues if, for example,
+the driver times out waiting for a notification from the device for a
+previously queued request.
 
 \input{transport-pci.tex}
 \input{transport-mmio.tex}
-- 
2.31.1.272.g89b43f80a514


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]