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

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 <> ---  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.  egin{lstlisting}  #define VIRTIO_SCSI_T_AN_QUERY
1 --  1.9.0