Virtio SCSI Controller Device Spec ================================== The virtio controller device groups together one or more simple virtual devices (ie. disk), and allows communicating to these devices using the SCSI protocol. A controller device represents a SCSI host with many targets attached. The virtio controller services two kinds of requests: - command requests for a logical unit; - task management functions related to a logical unit, target or command. The controller is also able to send out notifications about added and removed devices. v4: First public version Configuration ------------- Subsystem Device ID TBD Virtqueues 0..n-1:one requestq per target n:control transmitq n+1:control receiveq Feature bits VIRTIO_SCSI_F_INOUT - Whether a single request can include both read-only and write-only data buffers. Device configuration layout struct virtio_scsi_config { u32 num_targets; } num_targets is the number of targets, and the id of the virtqueue used for the control receiveq. Device initialization --------------------- The initialization routine should first of all discover the controller's control virtqueues. The driver should then place at least a buffer in the control receiveq. Buffers returned by the device on the control receiveq may be referred to as "events" in the rest of the document. The driver can immediately issue requests (for example, INQUIRY or REPORT LUNS) or task management functions (for example, I_T RESET). Device operation: request queue ------------------------------- The driver queues requests to the virtqueue, and they are used by the device (not necessarily in order). Requests have the following format: struct virtio_scsi_req { u32 type; ... u8 response; } #define VIRTIO_SCSI_T_BARRIER 0x80000000 The type identifies the remaining fields. The value VIRTIO_SCSI_T_BARRIER can be ORed in the type as well. This bit indicates that this request acts as a barrier and that all preceding requests must be complete before this one, and all following requests must not be started until this is complete. Note that a barrier does not flush caches in the underlying backend device in host, and thus does not serve as data consistency guarantee. The driver must send a SYNCHRONIZE CACHE command to flush the host cache. Valid response values are defined separately for each command. - Task management function #define VIRTIO_SCSI_T_TMF 0 #define VIRTIO_SCSI_T_TMF_ABORT_TASK_SET 1 #define VIRTIO_SCSI_T_TMF_I_T_NEXUS_RESET 4 #define VIRTIO_SCSI_T_TMF_LOGICAL_UNIT_RESET 5 #define VIRTIO_SCSI_T_TMF_QUERY_TASK_SET 7 #define VIRTIO_SCSI_T_TMF_LOGICAL_UNIT_DETACH (1 << 24) struct virtio_scsi_req_tmf { u32 subtype; u8 lun[8]; u8 additional[]; u8 response; } /* command-specific response values */ #define VIRTIO_SCSI_S_FUNCTION_COMPLETE 0 #define VIRTIO_SCSI_S_NO_TARGET 1 #define VIRTIO_SCSI_S_TARGET_FAILURE 2 #define VIRTIO_SCSI_S_FUNCTION_SUCCEEDED 3 #define VIRTIO_SCSI_S_FUNCTION_REJECTED 4 #define VIRTIO_SCSI_S_INCORRECT_LUN 5 The type is VIRTIO_SCSI_T_LUN_INFO, possibly with the VIRTIO_SCSI_T_BARRIER bit ORed in. The subtype and lun field are filled in by the driver, the additional and response field is filled in by the device. Unknown LUNs are ignored; also, the lun field is ignored for the I_T NEXUS RESET command. Task management functions accepting an I_T_L_Q nexus (ABORT TASK, QUERY TASK) are only accessible through the control transmitq. Task management functions not in the above list are not accessible in this version of the specification. Future versions may allow access to them through additional features. VIRTIO_SCSI_T_TMF_LOGICAL_UNIT_DETACH asks the device to make the logical unit (and the target as well if this is the last logical unit) disappear. It takes an I_T_L nexus. This non-standard TMF should be used in response to a host request to shutdown a target or LUN, after having placed the LUN in a clean state. The outcome of the task management function is written by the device in the response field. A value of VIRTIO_SCSI_S_NO_TARGET means that (even though the virtqueue exists) there is no target with this number. Other return values map 1-to-1 with those defined in SAM. - SCSI command #define VIRTIO_SCSI_T_CMD 1 struct virtio_scsi_req_cmd { u32 type; u32 ioprio; u8 lun[8]; u64 id; u32 num_dataout, num_datain; char cdb[]; char data[][num_dataout+num_datain]; u8 sense[]; u32 sense_len; u32 residual; u8 status; u8 response; }; /* command-specific response values */ #define VIRTIO_SCSI_S_OK 0 #define VIRTIO_SCSI_S_NO_TARGET 1 #define VIRTIO_SCSI_S_UNDERRUN 6 #define VIRTIO_SCSI_S_ABORTED 7 #define VIRTIO_SCSI_S_FAILURE 8 The type field must be VIRTIO_SCSI_T_CMD, possibly with the VIRTIO_SCSI_T_BARRIER bit ORed in. The ioprio field will indicate the priority of this request, with higher values corresponding to higher priorities. The lun field addresses a logical unit in the target. The id field is the command identifier as defined in SAM. All of these fields are always read-only. The cdb, data and sense fields must reside in separate buffers. The cdb field is always read-only. The data buffers may be either read-only or write-only, depending on the request, with the read-only buffers coming first. The sense buffer is always write-only. The request shall have num_dataout read-only data buffers and num_datain write-only data buffers. One of these two values must be zero if the VIRTIO_SCSI_F_INOUT has not been negotiated. Remaining fields are filled in by the device. The sense_len field indicates the number of bytes actually written to the sense buffer, while the residual field indicates the residual size, calculated as data_length - number_of_transferred_bytes. The status byte is written by the device to be the SCSI status code. The response byte is written by the device to be one of the following: - VIRTIO_SCSI_S_OK when the request was completed and the status byte is filled with a SCSI status code (not necessarily "GOOD"). - VIRTIO_SCSI_S_NO_TARGET is returned if there is no target with this number. - VIRTIO_SCSI_S_UNDERRUN if the content of the CDB requires transferring more data than is available in the data buffers. - VIRTIO_SCSI_S_ABORTED if the request was cancelled due to a LUN reset, target reset or another task management function. - VIRTIO_SCSI_S_FAILURE for other host or guest error. - Asynchronous notification query #define VIRTIO_SCSI_T_AN_QUERY 2 struct virtio_scsi_an_subscribe { u8 lun[8]; u32 event_requested; u32 event_actual; } #define VIRTIO_SCSI_EVT_ASYNC_MEDIA_CHANGE 16 By sending this command, the driver asks the controller which events it can report, as described in Annex A of the SCSI MMC specification. The driver writes the events it is interested in into the event_requested; the device responds by writing the events that it supports into event_actual. The lun and event_requested fields are written by the driver. The event_actual and response fields are written by the device. Valid values of the response byte are VIRTIO_SCSI_S_OK, VIRTIO_SCSI_S_NO_TARGET, VIRTIO_SCSI_S_FAILURE (with the same meaning as above). - Asynchronous notification subscription #define VIRTIO_SCSI_T_AN_SUBSCRIBE 3 struct virtio_scsi_an_subscribe { u8 lun[8]; u32 event_requested; u32 event_actual; } #define VIRTIO_SCSI_EVT_ASYNC_MEDIA_CHANGE 16 By sending this command, the driver asks the controller to report events as described in Annex A of the SCSI MMC specification. The driver writes the events it is interested in into the event_requested; the device responds by writing the events that it supports into event_actual. The lun and event_requested fields are written by the driver. The event_actual and response fields are written by the device. Valid values of the response byte are VIRTIO_SCSI_S_OK, VIRTIO_SCSI_S_NO_TARGET, VIRTIO_SCSI_S_FAILURE (with the same meaning as above). Device operation: control transmitq ----------------------------------- Currently, the control transmitq is only used to send out-of-band task management functions. This allows the driver to abort tasks even when a target's virtqueue is full. Note that, in contrast, sending TMF on the request virtqueues allows setting the VIRTIO_SCSI_T_BARRIER bit; no similar functionality is provided by the control transmitq. Requests have the following format: struct virtio_scsi_ctrl { u32 type; ... u8 response; } The type identifies the remaining fields. The following commands are defined: - Task management function #define VIRTIO_SCSI_T_TMF 0 #define VIRTIO_SCSI_T_TMF_ABORT_TASK 0 #define VIRTIO_SCSI_T_TMF_ABORT_TASK_SET 1 #define VIRTIO_SCSI_T_TMF_I_T_NEXUS_RESET 4 #define VIRTIO_SCSI_T_TMF_LOGICAL_UNIT_RESET 5 #define VIRTIO_SCSI_T_TMF_QUERY_TASK 6 #define VIRTIO_SCSI_T_TMF_QUERY_TASK_SET 7 #define VIRTIO_SCSI_T_TMF_LOGICAL_UNIT_DETACH (1 << 24) struct virtio_scsi_ctrl_tmf { u32 subtype; u32 target; u8 lun[8]; u64 id; u8 additional[]; u8 response; } /* command-specific response values */ #define VIRTIO_SCSI_S_FUNCTION_COMPLETE 0 #define VIRTIO_SCSI_S_NO_TARGET 1 #define VIRTIO_SCSI_S_FAILURE 2 #define VIRTIO_SCSI_S_FUNCTION_SUCCEEDED 3 #define VIRTIO_SCSI_S_FUNCTION_REJECTED 4 #define VIRTIO_SCSI_S_INCORRECT_LUN 5 The type is VIRTIO_SCSI_T_TMF. All fields but the last one are filled by the driver, the response field is filled in by the device. The id command must match the id in a SCSI command. Irrelevant fields for the requested TMF are ignored. VIRTIO_SCSI_T_TMF_LOGICAL_UNIT_DETACH asks the device to make the logical unit (and the target as well if this is the last logical unit) disappear. It takes an I_T_L nexus. This non-standard TMF should be used in response to a host request to shutdown a target or LUN, after having placed the LUN in a clean state. The outcome of the task management function is written by the device in the response field. VIRTIO_SCSI_S_NO_TARGET is returned if there is no target with this number. Other return values map 1-to-1 with those defined in SAM. Device operation: control receiveq ---------------------------------- The control receiveq is used by the device to report information on devices that are attached to the controller. The driver should always leave a few (?) buffers ready in the control receiveq. The device may end up dropping events if it finds no buffer ready. Buffers are placed in the control receiveq and filled by the device when interesting events occur. Events have the following format: #define VIRTIO_SCSI_T_EVENTS_MISSED 0x80000000 struct virtio_scsi_ctrl_recv { u32 event; u8 event-specific-data[]; u8 event-specific-data-ret[]; } If bit 31 is set in the event, the device failed to report an event due to missing buffers. In this case, the driver should poll the logical units for unit attention conditions, and/or do whatever form of bus scan is appropriate for the guest operating system. The following events are defined: - Transport reset #define VIRTIO_SCSI_T_TRANSPORT_RESET 0 struct virtio_scsi_reset { u32 target; u8 lun[8]; u32 reason; } #define VIRTIO_SCSI_EVT_RESET_HARD 1 #define VIRTIO_SCSI_EVT_RESET_RESCAN 2 #define VIRTIO_SCSI_EVT_RESET_SHUTDOWN 4 #define VIRTIO_SCSI_EVT_RESET_REMOVED 8 By sending this event, the controller signals that a logical unit on a target has been reset, including the case of a new device appearing or disappearing on the bus. The device fills in all three fields. By convention, a LUN field referring to a well-known LUN means that the event affects all LUNs enumerated by the target. The reason value is one of the four #define values appearing above. VIRTIO_SCSI_EVT_RESET_REMOVED is used if the target or logical unit is no longer able to receive commands. VIRTIO_SCSI_EVT_RESET_HARD is used if the logical unit has been reset, but is still present. VIRTIO_SCSI_EVT_RESET_RESCAN is used if a target or logical unit has just appeared on the controller. VIRTIO_SCSI_EVT_RESET_SHUTDOWN is used when the host wants to initiate a graceful shutdown of a logical unit. Events should also be reported via sense codes or response codes, with the exception of newly appeared targets: - VIRTIO_SCSI_EVT_RESET_HARD sense UNIT ATTENTION asc POWER ON, RESET OR BUS DEVICE RESET OCCURRED - VIRTIO_SCSI_EVT_RESET_RESCAN sense UNIT ATTENTION asc REPORTED LUNS DATA HAS CHANGED - VIRTIO_SCSI_EVT_RESET_SHUTDOWN sense UNIT ATTENTION asc TARGET OPERATING CONDITIONS HAVE CHANGED ascq 0x80 (vendor specific) - VIRTIO_SCSI_EVT_RESET_REMOVED sense ILLEGAL REQUEST asc LOGICAL UNIT NOT SUPPORTED However, in general events should be more easily handled by the driver than sense codes. - Asynchronous notification #define VIRTIO_SCSI_T_MEDIA_CHANGE 1 struct virtio_scsi_reset { u32 target; u8 lun[8]; u32 event; } #define VIRTIO_SCSI_EVT_ASYNC_MEDIA_CHANGE 1 By sending this event, the controller signals that an event was fired from a physical interface. The device only sends events that the driver has subscribed to via the "Asynchronous notification subscription" command. All fields are written by the device.