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
and task management functions.
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
device-readable and device-writable data buffers.
-\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'').
-\field{task_attr} defines
-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.
+\field{task_attr} defines the task attribute as in the table above, but
+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
ABORT TASK or ABORT TASK SET task management function.
@@ -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.
+
\item Asynchronous notification query.
\begin{lstlisting}
#define VIRTIO_SCSI_T_AN_QUERY 1
--
1.9.0