From d71f9f169a68ac0a058bab5c61ef0fcf1eed2382 Mon Sep 17 00:00:00 2001 From: rusty Date: Thu, 22 May 2014 04:43:28 +0000 Subject: 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. (As per minutes of meeting 2014-05-20: https://lists.oasis-open.org/archives/virtio/201405/msg00034.html ) Signed-off-by: Paolo Bonzini Signed-off-by: Rusty Russell git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio@372 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 63 +++++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 45 insertions(+), 18 deletions(-) diff --git a/content.tex b/content.tex index 7e88411..71c3de1 100644 --- a/content.tex +++ b/content.tex @@ -4415,11 +4415,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. \item[VIRTIO_SCSI_F_T10_PI (3)] The extended fields for T10 protection information (DIF/DIX) are included in the SCSI request header. @@ -4466,17 +4468,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} @@ -4501,7 +4506,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 @@ -4585,12 +4590,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. The CDB is included in \field{cdb} and its size, \field{cdb_size}, is taken from the configuration space. @@ -4642,8 +4652,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. @@ -4674,6 +4685,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. @@ -4760,6 +4775,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 -- cgit v1.2.3