OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

# virtio-comment message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: [PATCH] content.tex: virtio-scsi review (VIRTIO-106)

• From: Paolo Bonzini <pbonzini@redhat.com>
• To: virtio@lists.oasis-open.org
• Date: Mon, 5 May 2014 14:57:27 +0200

As prompted by Rusty, add a few more MUST/SHOULD items for both devices
and drivers.  Clarify semantics of max_channel/max_id/max_lun, task_attr

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
content.tex | 63 +++++++++++++++++++++++++++++++++++++++++++------------------
1 file changed, 45 insertions(+), 18 deletions(-)

diff --git a/content.tex b/content.tex
index 58c3ebc..8b570ef 100644
--- a/content.tex
+++ b/content.tex
@@ -4374,11 +4374,13 @@ This section relies on definitions from \hyperref[intro:SAM]{SAM}.
\item[VIRTIO_SCSI_F_INOUT (0)] A single request can include both

-\item[VIRTIO_SCSI_F_HOTPLUG (1)] The host SHOULD enable
-    hot-plug/hot-unplug of new LUNs and targets on the SCSI bus.
+\item[VIRTIO_SCSI_F_HOTPLUG (1)] The host SHOULD enable reporting of
+    hot-plug and hot-unplug events for LUNs and targets on the SCSI bus.
+    The guest SHOULD handle hot-plug and hot-unplug events.

\item[VIRTIO_SCSI_F_CHANGE (2)] The host will report changes to LUN
-    parameters via a VIRTIO_SCSI_T_PARAM_CHANGE event.
+    parameters via a VIRTIO_SCSI_T_PARAM_CHANGE event; the guest
+    SHOULD handle them.
\end{description}

\subsection{Device configuration layout}\label{sec:Device Types / SCSI Host Device / Device configuration layout}
@@ -4422,17 +4424,20 @@ struct virtio_scsi_config {

\item[\field{sense_size}] is the maximum size of the sense data that the
device will write. The default value is written by the device
-    and will always be 96, but the driver can modify it. It is
+    and MUST be 96, but the driver can modify it. It is
restored to the default when the device is reset.

\item[\field{cdb_size}] is the maximum size of the CDB that the driver will
-    write. The default value is written by the device and will
-    always be 32, but the driver can likewise modify it. It is
+    write. The default value is written by the device and MUST
+    be 32, but the driver can likewise modify it. It is
restored to the default when the device is reset.

-\item[\field{max_channel}, \field{max_target} and \field{max_lun}] can be used by the driver
-    as hints to constrain scanning the logical units on the
-    host.
+\item[\field{max_channel}, \field{max_target} and \field{max_lun}] can be
+    used by the driver as hints to constrain scanning the logical units
+    on the host to channel/target/logical unit numbers that are less than
+    or equal to the value of the fields.  \field{max_channel} SHOULD
+    be zero.  \field{max_target} SHOULD be less than or equal to 255.
+    \field{max_lun} SHOULD be less than or equal to 16383.
\end{description}

\drivernormative{\subsubsection}{Device configuration layout}{Device Types / SCSI Host Device / Device configuration layout}
@@ -4457,7 +4462,7 @@ according to the native endian of the guest rather than

\devicenormative{\subsection}{Device Initialization}{Device Types / SCSI Host Device / Device Initialization}

-On initialization the device SHOULD first discover the
+On initialization the driver SHOULD first discover the
device's virtqueues.

If the driver uses the eventq, the driver SHOULD place at least one
@@ -4532,12 +4537,17 @@ target.

\field{id} is the command identifier (tag'').

-the task attribute as in the table above, but all task attributes
-MAY be mapped to SIMPLE by the device; \field{crn} may also be provided
-by clients, but is generally expected to be 0. The maximum CRN
-value defined by the protocol is 255, since CRN is stored in an
-8-bit integer.
+all task attributes MAY be mapped to SIMPLE by the device.  Some commands
+are defined by SCSI standards as "implicit head of queue"; for such
+commands, all task attributes MAY also be mapped to HEAD OF QUEUE.
+Drivers and applications SHOULD NOT send a command with the ORDERED
+task attribute if the command has an implicit HEAD OF QUEUE attribute,
+because whether the ORDERED task attribute is honored is vendor-specific.
+
+\field{crn} may also be provided by clients, but is generally expected
+to be 0. The maximum CRN value defined by the protocol is 255, since
+CRN is stored in an 8-bit integer.

All of these fields are defined in \hyperref[intro:SAM]{SAM}. They are always
device-readable, as are \field{cdb} and \field{dataout}. \field{cdb_size} is
@@ -4568,8 +4578,9 @@ The device MUST write the \field{response} byte as one of the following:
byte is filled with a SCSI status code (not necessarily
GOOD'').

-\item[VIRTIO_SCSI_S_OVERRUN] if the content of the CDB requires
-  transferring more data than is available in the data buffers.
+\item[VIRTIO_SCSI_S_OVERRUN] if the content of the CDB (such as the
+  allocation length, parameter length or transfer size) requires
+  more data than is available in the datain and dataout buffers.

\item[VIRTIO_SCSI_S_ABORTED] if the request was cancelled due to an
@@ -4600,6 +4611,10 @@ The device MUST write the \field{response} byte as one of the following:
VIRTIO_SCSI_S_FAILURE.
\end{description}

+All commands must be completed before the virtio-scsi device is
+reset or unplugged.  The device MAY choose to abort them, or if
+it does not do so MUST pick the VIRTIO_SCSI_S_FAILURE response.
+
\drivernormative{\paragraph}{Device Operation: Request Queues}{Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues}

\field{task_attr}, \field{prio} and \field{crn} SHOULD be zero.
@@ -4686,6 +4701,18 @@ struct virtio_scsi_ctrl_tmf
device in \field{response}. The command-specific response
values map 1-to-1 with those defined in \hyperref[intro:SAM]{SAM}.

+  Task management function can affect the response value for commands that
+  are in the request queue and have not been completed yet.  For example,
+  the device MUST complete all active commands on a logical unit
+  or target (possibly with a VIRTIO_SCSI_S_RESET response code)
+  upon receiving a "logical unit reset" or "I_T nexus reset" TMF.
+  Similarly, the device MUST complete the selected commands (possibly
+  with a VIRTIO_SCSI_S_ABORTED response code) upon receiving an "abort
+  task" or "abort task set" TMF.  Such effects MUST take place before
+  the TMF itself is completed, and the device MUST use memory barriers
+  appropriately in order to ensure that the driver sees these writes
+  in the correct order.
+