[virtio-comment] [PATCH 1/6] virtio-scsi: Maintain scsi device spec in separate file

[Parav Pandit <parav@nvidia.com>]

Move virtio-scsi device specification to its own file similar to
recent virtio devices.

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/153
Signed-off-by: Parav Pandit <parav@nvidia.com>
---
 content.tex     | 711 +-----------------------------------------------
 virtio-scsi.tex | 711 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 712 insertions(+), 710 deletions(-)
 create mode 100644 virtio-scsi.tex

diff --git a/content.tex b/content.tex
index 96f4723..1652165 100644
--- a/content.tex
+++ b/content.tex
@@ -6822,716 +6822,7 @@ \subsubsection{Free Page Reporting}\label{sec:Device Types / Memory Balloon Devi
 MUST NOT modify the the content of a reported page to a value other than
 \field{poison_val}.
 
-\section{SCSI Host Device}\label{sec:Device Types / SCSI Host Device}
-
-The virtio SCSI host device groups together one or more virtual
-logical units (such as disks), and allows communicating to them
-using the SCSI protocol. An instance of the device represents a
-SCSI host to which many targets and LUNs are attached.
-
-The virtio SCSI device services two kinds of requests:
-\begin{itemize}
-\item command requests for a logical unit;
-
-\item task management functions related to a logical unit, target or
-  command.
-\end{itemize}
-
-The device is also able to send out notifications about added and
-removed logical units. Together, these capabilities provide a
-SCSI transport protocol that uses virtqueues as the transfer
-medium. In the transport protocol, the virtio driver acts as the
-initiator, while the virtio SCSI host provides one or more
-targets that receive and process the requests.
-
-This section relies on definitions from \hyperref[intro:SAM]{SAM}.
-
-\subsection{Device ID}\label{sec:Device Types / SCSI Host Device / Device ID}
-  8
-
-\subsection{Virtqueues}\label{sec:Device Types / SCSI Host Device / Virtqueues}
-
-\begin{description}
-\item[0] controlq
-\item[1] eventq
-\item[2\ldots n] request queues
-\end{description}
-
-\subsection{Feature bits}\label{sec:Device Types / SCSI Host Device / Feature bits}
-
-\begin{description}
-\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 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; 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.
-\end{description}
-
-\subsection{Device configuration layout}\label{sec:Device Types / SCSI Host Device / Device configuration layout}
-
-  All fields of this configuration are always available.
-
-\begin{lstlisting}
-struct virtio_scsi_config {
-        le32 num_queues;
-        le32 seg_max;
-        le32 max_sectors;
-        le32 cmd_per_lun;
-        le32 event_info_size;
-        le32 sense_size;
-        le32 cdb_size;
-        le16 max_channel;
-        le16 max_target;
-        le32 max_lun;
-};
-\end{lstlisting}
-
-\begin{description}
-\item[\field{num_queues}] is the total number of request virtqueues exposed by
-    the device. The driver MAY use only one request queue,
-    or it can use more to achieve better performance.
-
-\item[\field{seg_max}] is the maximum number of segments that can be in a
-    command. A bidirectional command can include \field{seg_max} input
-    segments and \field{seg_max} output segments.
-
-\item[\field{max_sectors}] is a hint to the driver about the maximum transfer
-    size to use.
-
-\item[\field{cmd_per_lun}] tells the driver the maximum number of
-    linked commands it can send to one LUN.
-
-\item[\field{event_info_size}] is the maximum size that the device will fill
-    for buffers that the driver places in the eventq. It is
-    written by the device depending on the set of negotiated
-    features.
-
-\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 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 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 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}
-
-The driver MUST NOT write to device configuration fields other than
-\field{sense_size} and \field{cdb_size}.
-
-The driver MUST NOT send more than \field{cmd_per_lun} linked commands
-to one LUN, and MUST NOT send more than the virtqueue size number of
-linked commands to one LUN.
-
-\devicenormative{\subsubsection}{Device configuration layout}{Device Types / SCSI Host Device / Device configuration layout}
-
-On reset, the device MUST set \field{sense_size} to 96 and
-\field{cdb_size} to 32.
-
-\subsubsection{Legacy Interface: Device configuration layout}\label{sec:Device Types / SCSI Host Device / Device configuration layout / Legacy Interface: Device configuration layout}
-When using the legacy interface, transitional devices and drivers
-MUST format the fields in struct virtio_scsi_config
-according to the native endian of the guest rather than
-(necessarily when not using the legacy interface) little-endian.
-
-\devicenormative{\subsection}{Device Initialization}{Device Types / SCSI Host Device / Device Initialization}
-
-On initialization the driver SHOULD first discover the
-device's virtqueues.
-
-If the driver uses the eventq, the driver SHOULD place at least one
-buffer in the eventq.
-
-The driver MAY immediately issue requests\footnote{For example, INQUIRY
-or REPORT LUNS.} or task management functions\footnote{For example, I_T
-RESET.}.
-
-\subsection{Device Operation}\label{sec:Device Types / SCSI Host Device / Device Operation}
-
-Device operation consists of operating request queues, the control
-queue and the event queue.
-
-\paragraph{Legacy Interface: Device Operation}\label{sec:Device
-Types / SCSI Host Device / Device Operation / Legacy
-Interface: Device Operation}
-When using the legacy interface, the driver SHOULD ignore the
-used length values.
-\begin{note}
-Historically, devices put the total descriptor length,
-or the total length of device-writable buffers there,
-even when only part of the buffers were actually written.
-\end{note}
-
-\subsubsection{Device Operation: Request Queues}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues}
-
-The driver queues requests to an arbitrary request queue, and
-they are used by the device on that same queue. It is the
-responsibility of the driver to ensure strict request ordering
-for commands placed on different queues, because they will be
-consumed with no order constraints.
-
-Requests have the following format:
-
-\begin{lstlisting}
-struct virtio_scsi_req_cmd {
-        // Device-readable part
-        u8 lun[8];
-        le64 id;
-        u8 task_attr;
-        u8 prio;
-        u8 crn;
-        u8 cdb[cdb_size];
-        // The next three fields are only present if VIRTIO_SCSI_F_T10_PI
-        // is negotiated.
-        le32 pi_bytesout;
-        le32 pi_bytesin;
-        u8 pi_out[pi_bytesout];
-        u8 dataout[];
-
-        // Device-writable part
-        le32 sense_len;
-        le32 residual;
-        le16 status_qualifier;
-        u8 status;
-        u8 response;
-        u8 sense[sense_size];
-        // The next field is only present if VIRTIO_SCSI_F_T10_PI
-        // is negotiated
-        u8 pi_in[pi_bytesin];
-        u8 datain[];
-};
-
-
-/* command-specific response values */
-#define VIRTIO_SCSI_S_OK                0
-#define VIRTIO_SCSI_S_OVERRUN           1
-#define VIRTIO_SCSI_S_ABORTED           2
-#define VIRTIO_SCSI_S_BAD_TARGET        3
-#define VIRTIO_SCSI_S_RESET             4
-#define VIRTIO_SCSI_S_BUSY              5
-#define VIRTIO_SCSI_S_TRANSPORT_FAILURE 6
-#define VIRTIO_SCSI_S_TARGET_FAILURE    7
-#define VIRTIO_SCSI_S_NEXUS_FAILURE     8
-#define VIRTIO_SCSI_S_FAILURE           9
-
-/* task_attr */
-#define VIRTIO_SCSI_S_SIMPLE            0
-#define VIRTIO_SCSI_S_ORDERED           1
-#define VIRTIO_SCSI_S_HEAD              2
-#define VIRTIO_SCSI_S_ACA               3
-\end{lstlisting}
-
-\field{lun} addresses the REPORT LUNS well-known logical unit, or
-a target and logical unit in the virtio-scsi device's SCSI domain.
-When used to address the REPORT LUNS logical unit, \field{lun} is 0xC1,
-0x01 and six zero bytes.  The virtio-scsi device SHOULD implement the
-REPORT LUNS well-known logical unit.
-
-When used to address a target and logical unit, the only supported format
-for \field{lun} is: first byte set to 1, second byte set to target,
-third and fourth byte representing a single level LUN structure, followed
-by four zero bytes. With this representation, a virtio-scsi device can
-serve up to 256 targets and 16384 LUNs per target.  The device MAY also
-support having a well-known logical units in the third and fourth byte.
-
-\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.  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.
-
-All of these fields are defined in \hyperref[intro:SAM]{SAM} and are
-always device-readable.
-
-\field{pi_bytesout} determines the size of the \field{pi_out} field
-in bytes.  If it is nonzero, the \field{pi_out} field contains outgoing
-protection information for write operations.  \field{pi_bytesin} determines
-the size of the \field{pi_in} field in the device-writable section, in bytes.
-All three fields are only present if VIRTIO_SCSI_F_T10_PI has been negotiated.
-
-The remainder of the device-readable part is the data output buffer,
-\field{dataout}.
-
-\field{sense} and subsequent fields are always device-writable. \field{sense_len}
-indicates the number of bytes actually written to the sense
-buffer.
-
-\field{residual} indicates the residual size,
-calculated as ``data_length - number_of_transferred_bytes'', for
-read or write operations. For bidirectional commands, the
-number_of_transferred_bytes includes both read and written bytes.
-A \field{residual} that is less than the size of \field{datain} means that
-\field{dataout} was processed entirely. A \field{residual} that
-exceeds the size of \field{datain} means that \field{dataout} was
-processed partially and \field{datain} was not processed at
-all.
-
-If the \field{pi_bytesin} is nonzero, the \field{pi_in} field contains
-incoming protection information for read operations.  \field{pi_in} is
-only present if VIRTIO_SCSI_F_T10_PI has been negotiated\footnote{There
-  is no separate residual size for \field{pi_bytesout} and
-  \field{pi_bytesin}.  It can be computed from the \field{residual} field,
-  the size of the data integrity information per sector, and the sizes
-  of \field{pi_out}, \field{pi_in}, \field{dataout} and \field{datain}.}.
-
-The remainder of the device-writable part is the data input buffer,
-\field{datain}.
-
-
-\devicenormative{\paragraph}{Device Operation: Request Queues}{Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues}
-
-The device MUST write the \field{status} byte as the status code as
-defined in \hyperref[intro:SAM]{SAM}.
-
-The device MUST write the \field{response} byte as one of the following:
-
-\begin{description}
-
-\item[VIRTIO_SCSI_S_OK] when the request was completed and the \field{status}
-  byte is filled with a SCSI status code (not necessarily
-  ``GOOD'').
-
-\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.
-
-\item[VIRTIO_SCSI_S_BAD_TARGET] if the request was never processed
-  because the target indicated by \field{lun} does not exist.
-
-\item[VIRTIO_SCSI_S_RESET] if the request was cancelled due to a bus
-  or device reset (including a task management function).
-
-\item[VIRTIO_SCSI_S_TRANSPORT_FAILURE] if the request failed due to a
-  problem in the connection between the host and the target
-  (severed link).
-
-\item[VIRTIO_SCSI_S_TARGET_FAILURE] if the target is suffering a
-  failure and to tell the driver not to retry on other paths.
-
-\item[VIRTIO_SCSI_S_NEXUS_FAILURE] if the nexus is suffering a failure
-  but retrying on other paths might yield a different result.
-
-\item[VIRTIO_SCSI_S_BUSY] if the request failed but retrying on the
-  same path is likely to work.
-
-\item[VIRTIO_SCSI_S_FAILURE] for other host or driver error. In
-  particular, if neither \field{dataout} nor \field{datain} is empty, and the
-  VIRTIO_SCSI_F_INOUT feature has not been negotiated, the
-  request will be immediately returned with a response equal to
-  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.
-
-Upon receiving a VIRTIO_SCSI_S_TARGET_FAILURE response, the driver
-SHOULD NOT retry the request on other paths.
-
-\paragraph{Legacy Interface: Device Operation: Request Queues}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues / Legacy Interface: Device Operation: Request Queues}
-When using the legacy interface, transitional devices and drivers
-MUST format the fields in struct virtio_scsi_req_cmd
-according to the native endian of the guest rather than
-(necessarily when not using the legacy interface) little-endian.
-
-\subsubsection{Device Operation: controlq}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: controlq}
-
-The controlq is used for other SCSI transport operations.
-Requests have the following format:
-
-{
-\lstset{escapechar=\$}
-\begin{lstlisting}
-struct virtio_scsi_ctrl {
-        le32 type;
-$\ldots$
-        u8 response;
-};
-
-/* response values valid for all commands */
-#define VIRTIO_SCSI_S_OK                       0
-#define VIRTIO_SCSI_S_BAD_TARGET               3
-#define VIRTIO_SCSI_S_BUSY                     5
-#define VIRTIO_SCSI_S_TRANSPORT_FAILURE        6
-#define VIRTIO_SCSI_S_TARGET_FAILURE           7
-#define VIRTIO_SCSI_S_NEXUS_FAILURE            8
-#define VIRTIO_SCSI_S_FAILURE                  9
-#define VIRTIO_SCSI_S_INCORRECT_LUN            12
-\end{lstlisting}
-}
-
-The \field{type} identifies the remaining fields.
-
-The following commands are defined:
-
-\begin{itemize}
-\item Task management function.
-\begin{lstlisting}
-#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_CLEAR_ACA            2
-#define VIRTIO_SCSI_T_TMF_CLEAR_TASK_SET       3
-#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
-
-struct virtio_scsi_ctrl_tmf {
-        // Device-readable part
-        le32 type;
-        le32 subtype;
-        u8   lun[8];
-        le64 id;
-        // Device-writable part
-        u8   response;
-};
-
-/* command-specific response values */
-#define VIRTIO_SCSI_S_FUNCTION_COMPLETE        0
-#define VIRTIO_SCSI_S_FUNCTION_SUCCEEDED       10
-#define VIRTIO_SCSI_S_FUNCTION_REJECTED        11
-\end{lstlisting}
-
-  The \field{type} is VIRTIO_SCSI_T_TMF; \field{subtype} defines which
-  task management function. All
-  fields except \field{response} are filled by the driver.
-
-  Other fields which are irrelevant for the requested TMF
-  are ignored but they are still present. \field{lun}
-  is in the same format specified for request queues; the
-  single level LUN is ignored when the task management function
-  addresses a whole I_T nexus. When relevant, the value of \field{id}
-  is matched against the id values passed on the requestq.
-
-  The outcome of the task management function is written by the
-  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 successfully 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
-
-struct virtio_scsi_ctrl_an {
-    // Device-readable part
-    le32 type;
-    u8   lun[8];
-    le32 event_requested;
-    // Device-writable part
-    le32 event_actual;
-    u8   response;
-};
-
-#define VIRTIO_SCSI_EVT_ASYNC_OPERATIONAL_CHANGE  2
-#define VIRTIO_SCSI_EVT_ASYNC_POWER_MGMT          4
-#define VIRTIO_SCSI_EVT_ASYNC_EXTERNAL_REQUEST    8
-#define VIRTIO_SCSI_EVT_ASYNC_MEDIA_CHANGE        16
-#define VIRTIO_SCSI_EVT_ASYNC_MULTI_HOST          32
-#define VIRTIO_SCSI_EVT_ASYNC_DEVICE_BUSY         64
-\end{lstlisting}
-
-  By sending this command, the driver asks the device which
-  events the given LUN can report, as described in paragraphs 6.6
-  and A.6 of \hyperref[intro:SCSI MMC]{SCSI MMC}. The driver writes the
-  events it is interested in into \field{event_requested}; the device
-  responds by writing the events that it supports into
-  \field{event_actual}.
-
-  The \field{type} is VIRTIO_SCSI_T_AN_QUERY. \field{lun} and \field{event_requested}
-  are written by the driver. \field{event_actual} and \field{response}
-  fields are written by the device.
-
-  No command-specific values are defined for the \field{response} byte.
-
-\item Asynchronous notification subscription.
-\begin{lstlisting}
-#define VIRTIO_SCSI_T_AN_SUBSCRIBE                2
-
-struct virtio_scsi_ctrl_an {
-        // Device-readable part
-        le32 type;
-        u8   lun[8];
-        le32 event_requested;
-        // Device-writable part
-        le32 event_actual;
-        u8   response;
-};
-\end{lstlisting}
-
-  By sending this command, the driver asks the specified LUN to
-  report events for its physical interface, again as described in
-   \hyperref[intro:SCSI MMC]{SCSI MMC}. The driver writes the events it is
-  interested in into \field{event_requested}; the device responds by
-  writing the events that it supports into \field{event_actual}.
-
-  Event types are the same as for the asynchronous notification
-  query message.
-
-  The \field{type} is VIRTIO_SCSI_T_AN_SUBSCRIBE. \field{lun} and
-  \field{event_requested} are written by the driver.
-  \field{event_actual} and \field{response} are written by the device.
-
-  No command-specific values are defined for the response byte.
-\end{itemize}
-
-\paragraph{Legacy Interface: Device Operation: controlq}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: controlq / Legacy Interface: Device Operation: controlq}
-
-When using the legacy interface, transitional devices and drivers
-MUST format the fields in struct virtio_scsi_ctrl, struct
-virtio_scsi_ctrl_tmf, struct virtio_scsi_ctrl_an and struct
-virtio_scsi_ctrl_an
-according to the native endian of the guest rather than
-(necessarily when not using the legacy interface) little-endian.
-
-
-\subsubsection{Device Operation: eventq}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: eventq}
-
-The eventq is populated by the driver for the device to report information on logical
-units that are attached to it. In general, the device will not
-queue events to cope with an empty eventq, and will end up
-dropping events if it finds no buffer ready. However, when
-reporting events for many LUNs (e.g. when a whole target
-disappears), the device can throttle events to avoid dropping
-them. For this reason, placing 10-15 buffers on the event queue
-is sufficient.
-
-Buffers returned by the device on the eventq will be referred to
-as ``events'' in the rest of this section. Events have the
-following format:
-
-\begin{lstlisting}
-#define VIRTIO_SCSI_T_EVENTS_MISSED   0x80000000
-
-struct virtio_scsi_event {
-        // Device-writable part
-        le32 event;
-        u8  lun[8];
-        le32 reason;
-};
-\end{lstlisting}
-
-The devices sets bit 31 in \field{event} to report lost events
-due to missing buffers.
-
-The meaning of \field{reason} depends on the
-contents of \field{event}. The following events are defined:
-
-\begin{itemize}
-\item No event.
-\begin{lstlisting}
-#define VIRTIO_SCSI_T_NO_EVENT         0
-\end{lstlisting}
-
-  This event is fired in the following cases:
-
-\begin{itemize}
-\item When the device detects in the eventq a buffer that is
-    shorter than what is indicated in the configuration field, it
-    MAY use it immediately and put this dummy value in \field{event}.
-    A well-written driver will never observe this
-    situation.
-
-\item When events are dropped, the device MAY signal this event as
-    soon as the drivers makes a buffer available, in order to
-    request action from the driver. In this case, of course, this
-    event will be reported with the VIRTIO_SCSI_T_EVENTS_MISSED
-    flag.
-\end{itemize}
-
-\item Transport reset
-\begin{lstlisting}
-#define VIRTIO_SCSI_T_TRANSPORT_RESET  1
-
-#define VIRTIO_SCSI_EVT_RESET_HARD         0
-#define VIRTIO_SCSI_EVT_RESET_RESCAN       1
-#define VIRTIO_SCSI_EVT_RESET_REMOVED      2
-\end{lstlisting}
-
-  By sending this event, the device 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
-  fields. \field{event} is set to
-  VIRTIO_SCSI_T_TRANSPORT_RESET. \field{lun} addresses a
-  logical unit in the SCSI host.
-
-  The \field{reason} value is one of the three \#define values appearing
-  above:
-
-  \begin{description}
-  \item[VIRTIO_SCSI_EVT_RESET_REMOVED] (``LUN/target removed'') is used
-    if the target or logical unit is no longer able to receive
-    commands.
-
-  \item[VIRTIO_SCSI_EVT_RESET_HARD] (``LUN hard reset'') is used if the
-    logical unit has been reset, but is still present.
-
-  \item[VIRTIO_SCSI_EVT_RESET_RESCAN] (``rescan LUN/target'') is used if
-    a target or logical unit has just appeared on the device.
-  \end{description}
-
-  The ``removed'' and ``rescan'' events can happen when
-  VIRTIO_SCSI_F_HOTPLUG feature was negotiated; when sent for LUN 0,
-  they MAY apply to the entire target so the driver can ask the
-  initiator to rescan the target to detect this.
-
-  Events will also be reported via sense codes (this obviously
-  does not apply to newly appeared buses or targets, since the
-  application has never discovered them):
-
-  \begin{itemize}
-  \item ``LUN/target removed'' maps to sense key ILLEGAL REQUEST, asc
-    0x25, ascq 0x00 (LOGICAL UNIT NOT SUPPORTED)
-
-  \item ``LUN hard reset'' maps to sense key UNIT ATTENTION, asc 0x29
-    (POWER ON, RESET OR BUS DEVICE RESET OCCURRED)
-
-  \item ``rescan LUN/target'' maps to sense key UNIT ATTENTION, asc
-    0x3f, ascq 0x0e (REPORTED LUNS DATA HAS CHANGED)
-  \end{itemize}
-
-  The preferred way to detect transport reset is always to use
-  events, because sense codes are only seen by the driver when it
-  sends a SCSI command to the logical unit or target. However, in
-  case events are dropped, the initiator will still be able to
-  synchronize with the actual state of the controller if the
-  driver asks the initiator to rescan of the SCSI bus. During the
-  rescan, the initiator will be able to observe the above sense
-  codes, and it will process them as if it the driver had
-  received the equivalent event.
-
-  \item Asynchronous notification
-\begin{lstlisting}
-#define VIRTIO_SCSI_T_ASYNC_NOTIFY     2
-\end{lstlisting}
-
-  By sending this event, the device signals that an asynchronous
-  event was fired from a physical interface.
-
-  All fields are written by the device. \field{event} is set to
-  VIRTIO_SCSI_T_ASYNC_NOTIFY. \field{lun} addresses a logical
-  unit in the SCSI host. \field{reason} is a subset of the
-  events that the driver has subscribed to via the ``Asynchronous
-  notification subscription'' command.
-
-  \item LUN parameter change
-\begin{lstlisting}
-#define VIRTIO_SCSI_T_PARAM_CHANGE  3
-\end{lstlisting}
-
-  By sending this event, the device signals a change in the configuration parameters
-  of a logical unit, for example the capacity or cache mode.
-  \field{event} is set to VIRTIO_SCSI_T_PARAM_CHANGE.
-  \field{lun} addresses a logical unit in the SCSI host.
-
-  The same event SHOULD also be reported as a unit attention condition.
-  \field{reason} contains the additional sense code and additional sense code qualifier,
-  respectively in bits 0\ldots 7 and 8\ldots 15.
-  \begin{note}
-  For example, a change in capacity will be reported as asc 0x2a, ascq 0x09
-  (CAPACITY DATA HAS CHANGED).
-  \end{note}
-
-  For MMC devices (inquiry type 5) there would be some overlap between this
-  event and the asynchronous notification event, so for simplicity the host never
-  reports this event for MMC devices.
-\end{itemize}
-
-\drivernormative{\paragraph}{Device Operation: eventq}{Device Types / SCSI Host Device / Device Operation / Device Operation: eventq}
-
-The driver SHOULD keep the eventq populated with buffers.  These
-buffers MUST be device-writable, and SHOULD be at least
-\field{event_info_size} bytes long, and MUST be at least the size of
-struct virtio_scsi_event.
-
-If \field{event} has bit 31 set, 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 and SHOULD poll for asynchronous events manually using SCSI commands.
-
-When receiving a VIRTIO_SCSI_T_TRANSPORT_RESET message with
-\field{reason} set to VIRTIO_SCSI_EVT_RESET_REMOVED or
-VIRTIO_SCSI_EVT_RESET_RESCAN for LUN 0, the driver SHOULD ask the
-initiator to rescan the target, in order to detect the case when an
-entire target has appeared or disappeared.
-
-\devicenormative{\paragraph}{Device Operation: eventq}{Device Types / SCSI Host Device / Device Operation / Device Operation: eventq}
-
-The device MUST set bit 31 in \field{event} if events were lost due to
-missing buffers, and it MAY use a VIRTIO_SCSI_T_NO_EVENT event to report
-this.
-
-The device MUST NOT send VIRTIO_SCSI_T_TRANSPORT_RESET messages
-with \field{reason} set to VIRTIO_SCSI_EVT_RESET_REMOVED or
-VIRTIO_SCSI_EVT_RESET_RESCAN unless VIRTIO_SCSI_F_HOTPLUG was negotiated.
-
-The device MUST NOT report VIRTIO_SCSI_T_PARAM_CHANGE for MMC devices.
-
-\paragraph{Legacy Interface: Device Operation: eventq}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: eventq / Legacy Interface: Device Operation: eventq}
-When using the legacy interface, transitional devices and drivers
-MUST format the fields in struct virtio_scsi_event
-according to the native endian of the guest rather than
-(necessarily when not using the legacy interface) little-endian.
-
-\subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
-Types / SCSI Host Device / Legacy Interface: Framing Requirements}
-
-When using legacy interfaces, transitional drivers which have not
-negotiated VIRTIO_F_ANY_LAYOUT MUST use a single descriptor for the
-\field{lun}, \field{id}, \field{task_attr}, \field{prio},
-\field{crn} and \field{cdb} fields, and MUST only use a single
-descriptor for the \field{sense_len}, \field{residual},
-\field{status_qualifier}, \field{status}, \field{response} and
-\field{sense} fields.
-
+\input{virtio-scsi.tex}
 \input{virtio-gpu.tex}
 \input{virtio-input.tex}
 \input{virtio-crypto.tex}
diff --git a/virtio-scsi.tex b/virtio-scsi.tex
new file mode 100644
index 0000000..df83607
--- /dev/null
+++ b/virtio-scsi.tex
@@ -0,0 +1,711 @@
+\section{SCSI Host Device}\label{sec:Device Types / SCSI Host Device}
+
+The virtio SCSI host device groups together one or more virtual
+logical units (such as disks), and allows communicating to them
+using the SCSI protocol. An instance of the device represents a
+SCSI host to which many targets and LUNs are attached.
+
+The virtio SCSI device services two kinds of requests:
+\begin{itemize}
+\item command requests for a logical unit;
+
+\item task management functions related to a logical unit, target or
+  command.
+\end{itemize}
+
+The device is also able to send out notifications about added and
+removed logical units. Together, these capabilities provide a
+SCSI transport protocol that uses virtqueues as the transfer
+medium. In the transport protocol, the virtio driver acts as the
+initiator, while the virtio SCSI host provides one or more
+targets that receive and process the requests.
+
+This section relies on definitions from \hyperref[intro:SAM]{SAM}.
+
+\subsection{Device ID}\label{sec:Device Types / SCSI Host Device / Device ID}
+  8
+
+\subsection{Virtqueues}\label{sec:Device Types / SCSI Host Device / Virtqueues}
+
+\begin{description}
+\item[0] controlq
+\item[1] eventq
+\item[2\ldots n] request queues
+\end{description}
+
+\subsection{Feature bits}\label{sec:Device Types / SCSI Host Device / Feature bits}
+
+\begin{description}
+\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 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; 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.
+\end{description}
+
+\subsection{Device configuration layout}\label{sec:Device Types / SCSI Host Device / Device configuration layout}
+
+  All fields of this configuration are always available.
+
+\begin{lstlisting}
+struct virtio_scsi_config {
+        le32 num_queues;
+        le32 seg_max;
+        le32 max_sectors;
+        le32 cmd_per_lun;
+        le32 event_info_size;
+        le32 sense_size;
+        le32 cdb_size;
+        le16 max_channel;
+        le16 max_target;
+        le32 max_lun;
+};
+\end{lstlisting}
+
+\begin{description}
+\item[\field{num_queues}] is the total number of request virtqueues exposed by
+    the device. The driver MAY use only one request queue,
+    or it can use more to achieve better performance.
+
+\item[\field{seg_max}] is the maximum number of segments that can be in a
+    command. A bidirectional command can include \field{seg_max} input
+    segments and \field{seg_max} output segments.
+
+\item[\field{max_sectors}] is a hint to the driver about the maximum transfer
+    size to use.
+
+\item[\field{cmd_per_lun}] tells the driver the maximum number of
+    linked commands it can send to one LUN.
+
+\item[\field{event_info_size}] is the maximum size that the device will fill
+    for buffers that the driver places in the eventq. It is
+    written by the device depending on the set of negotiated
+    features.
+
+\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 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 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 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}
+
+The driver MUST NOT write to device configuration fields other than
+\field{sense_size} and \field{cdb_size}.
+
+The driver MUST NOT send more than \field{cmd_per_lun} linked commands
+to one LUN, and MUST NOT send more than the virtqueue size number of
+linked commands to one LUN.
+
+\devicenormative{\subsubsection}{Device configuration layout}{Device Types / SCSI Host Device / Device configuration layout}
+
+On reset, the device MUST set \field{sense_size} to 96 and
+\field{cdb_size} to 32.
+
+\subsubsection{Legacy Interface: Device configuration layout}\label{sec:Device Types / SCSI Host Device / Device configuration layout / Legacy Interface: Device configuration layout}
+When using the legacy interface, transitional devices and drivers
+MUST format the fields in struct virtio_scsi_config
+according to the native endian of the guest rather than
+(necessarily when not using the legacy interface) little-endian.
+
+\devicenormative{\subsection}{Device Initialization}{Device Types / SCSI Host Device / Device Initialization}
+
+On initialization the driver SHOULD first discover the
+device's virtqueues.
+
+If the driver uses the eventq, the driver SHOULD place at least one
+buffer in the eventq.
+
+The driver MAY immediately issue requests\footnote{For example, INQUIRY
+or REPORT LUNS.} or task management functions\footnote{For example, I_T
+RESET.}.
+
+\subsection{Device Operation}\label{sec:Device Types / SCSI Host Device / Device Operation}
+
+Device operation consists of operating request queues, the control
+queue and the event queue.
+
+\paragraph{Legacy Interface: Device Operation}\label{sec:Device
+Types / SCSI Host Device / Device Operation / Legacy
+Interface: Device Operation}
+When using the legacy interface, the driver SHOULD ignore the
+used length values.
+\begin{note}
+Historically, devices put the total descriptor length,
+or the total length of device-writable buffers there,
+even when only part of the buffers were actually written.
+\end{note}
+
+\subsubsection{Device Operation: Request Queues}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues}
+
+The driver queues requests to an arbitrary request queue, and
+they are used by the device on that same queue. It is the
+responsibility of the driver to ensure strict request ordering
+for commands placed on different queues, because they will be
+consumed with no order constraints.
+
+Requests have the following format:
+
+\begin{lstlisting}
+struct virtio_scsi_req_cmd {
+        // Device-readable part
+        u8 lun[8];
+        le64 id;
+        u8 task_attr;
+        u8 prio;
+        u8 crn;
+        u8 cdb[cdb_size];
+        // The next three fields are only present if VIRTIO_SCSI_F_T10_PI
+        // is negotiated.
+        le32 pi_bytesout;
+        le32 pi_bytesin;
+        u8 pi_out[pi_bytesout];
+        u8 dataout[];
+
+        // Device-writable part
+        le32 sense_len;
+        le32 residual;
+        le16 status_qualifier;
+        u8 status;
+        u8 response;
+        u8 sense[sense_size];
+        // The next field is only present if VIRTIO_SCSI_F_T10_PI
+        // is negotiated
+        u8 pi_in[pi_bytesin];
+        u8 datain[];
+};
+
+
+/* command-specific response values */
+#define VIRTIO_SCSI_S_OK                0
+#define VIRTIO_SCSI_S_OVERRUN           1
+#define VIRTIO_SCSI_S_ABORTED           2
+#define VIRTIO_SCSI_S_BAD_TARGET        3
+#define VIRTIO_SCSI_S_RESET             4
+#define VIRTIO_SCSI_S_BUSY              5
+#define VIRTIO_SCSI_S_TRANSPORT_FAILURE 6
+#define VIRTIO_SCSI_S_TARGET_FAILURE    7
+#define VIRTIO_SCSI_S_NEXUS_FAILURE     8
+#define VIRTIO_SCSI_S_FAILURE           9
+
+/* task_attr */
+#define VIRTIO_SCSI_S_SIMPLE            0
+#define VIRTIO_SCSI_S_ORDERED           1
+#define VIRTIO_SCSI_S_HEAD              2
+#define VIRTIO_SCSI_S_ACA               3
+\end{lstlisting}
+
+\field{lun} addresses the REPORT LUNS well-known logical unit, or
+a target and logical unit in the virtio-scsi device's SCSI domain.
+When used to address the REPORT LUNS logical unit, \field{lun} is 0xC1,
+0x01 and six zero bytes.  The virtio-scsi device SHOULD implement the
+REPORT LUNS well-known logical unit.
+
+When used to address a target and logical unit, the only supported format
+for \field{lun} is: first byte set to 1, second byte set to target,
+third and fourth byte representing a single level LUN structure, followed
+by four zero bytes. With this representation, a virtio-scsi device can
+serve up to 256 targets and 16384 LUNs per target.  The device MAY also
+support having a well-known logical units in the third and fourth byte.
+
+\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.  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.
+
+All of these fields are defined in \hyperref[intro:SAM]{SAM} and are
+always device-readable.
+
+\field{pi_bytesout} determines the size of the \field{pi_out} field
+in bytes.  If it is nonzero, the \field{pi_out} field contains outgoing
+protection information for write operations.  \field{pi_bytesin} determines
+the size of the \field{pi_in} field in the device-writable section, in bytes.
+All three fields are only present if VIRTIO_SCSI_F_T10_PI has been negotiated.
+
+The remainder of the device-readable part is the data output buffer,
+\field{dataout}.
+
+\field{sense} and subsequent fields are always device-writable. \field{sense_len}
+indicates the number of bytes actually written to the sense
+buffer.
+
+\field{residual} indicates the residual size,
+calculated as ``data_length - number_of_transferred_bytes'', for
+read or write operations. For bidirectional commands, the
+number_of_transferred_bytes includes both read and written bytes.
+A \field{residual} that is less than the size of \field{datain} means that
+\field{dataout} was processed entirely. A \field{residual} that
+exceeds the size of \field{datain} means that \field{dataout} was
+processed partially and \field{datain} was not processed at
+all.
+
+If the \field{pi_bytesin} is nonzero, the \field{pi_in} field contains
+incoming protection information for read operations.  \field{pi_in} is
+only present if VIRTIO_SCSI_F_T10_PI has been negotiated\footnote{There
+  is no separate residual size for \field{pi_bytesout} and
+  \field{pi_bytesin}.  It can be computed from the \field{residual} field,
+  the size of the data integrity information per sector, and the sizes
+  of \field{pi_out}, \field{pi_in}, \field{dataout} and \field{datain}.}.
+
+The remainder of the device-writable part is the data input buffer,
+\field{datain}.
+
+
+\devicenormative{\paragraph}{Device Operation: Request Queues}{Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues}
+
+The device MUST write the \field{status} byte as the status code as
+defined in \hyperref[intro:SAM]{SAM}.
+
+The device MUST write the \field{response} byte as one of the following:
+
+\begin{description}
+
+\item[VIRTIO_SCSI_S_OK] when the request was completed and the \field{status}
+  byte is filled with a SCSI status code (not necessarily
+  ``GOOD'').
+
+\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.
+
+\item[VIRTIO_SCSI_S_BAD_TARGET] if the request was never processed
+  because the target indicated by \field{lun} does not exist.
+
+\item[VIRTIO_SCSI_S_RESET] if the request was cancelled due to a bus
+  or device reset (including a task management function).
+
+\item[VIRTIO_SCSI_S_TRANSPORT_FAILURE] if the request failed due to a
+  problem in the connection between the host and the target
+  (severed link).
+
+\item[VIRTIO_SCSI_S_TARGET_FAILURE] if the target is suffering a
+  failure and to tell the driver not to retry on other paths.
+
+\item[VIRTIO_SCSI_S_NEXUS_FAILURE] if the nexus is suffering a failure
+  but retrying on other paths might yield a different result.
+
+\item[VIRTIO_SCSI_S_BUSY] if the request failed but retrying on the
+  same path is likely to work.
+
+\item[VIRTIO_SCSI_S_FAILURE] for other host or driver error. In
+  particular, if neither \field{dataout} nor \field{datain} is empty, and the
+  VIRTIO_SCSI_F_INOUT feature has not been negotiated, the
+  request will be immediately returned with a response equal to
+  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.
+
+Upon receiving a VIRTIO_SCSI_S_TARGET_FAILURE response, the driver
+SHOULD NOT retry the request on other paths.
+
+\paragraph{Legacy Interface: Device Operation: Request Queues}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues / Legacy Interface: Device Operation: Request Queues}
+When using the legacy interface, transitional devices and drivers
+MUST format the fields in struct virtio_scsi_req_cmd
+according to the native endian of the guest rather than
+(necessarily when not using the legacy interface) little-endian.
+
+\subsubsection{Device Operation: controlq}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: controlq}
+
+The controlq is used for other SCSI transport operations.
+Requests have the following format:
+
+{
+\lstset{escapechar=\$}
+\begin{lstlisting}
+struct virtio_scsi_ctrl {
+        le32 type;
+$\ldots$
+        u8 response;
+};
+
+/* response values valid for all commands */
+#define VIRTIO_SCSI_S_OK                       0
+#define VIRTIO_SCSI_S_BAD_TARGET               3
+#define VIRTIO_SCSI_S_BUSY                     5
+#define VIRTIO_SCSI_S_TRANSPORT_FAILURE        6
+#define VIRTIO_SCSI_S_TARGET_FAILURE           7
+#define VIRTIO_SCSI_S_NEXUS_FAILURE            8
+#define VIRTIO_SCSI_S_FAILURE                  9
+#define VIRTIO_SCSI_S_INCORRECT_LUN            12
+\end{lstlisting}
+}
+
+The \field{type} identifies the remaining fields.
+
+The following commands are defined:
+
+\begin{itemize}
+\item Task management function.
+\begin{lstlisting}
+#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_CLEAR_ACA            2
+#define VIRTIO_SCSI_T_TMF_CLEAR_TASK_SET       3
+#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
+
+struct virtio_scsi_ctrl_tmf {
+        // Device-readable part
+        le32 type;
+        le32 subtype;
+        u8   lun[8];
+        le64 id;
+        // Device-writable part
+        u8   response;
+};
+
+/* command-specific response values */
+#define VIRTIO_SCSI_S_FUNCTION_COMPLETE        0
+#define VIRTIO_SCSI_S_FUNCTION_SUCCEEDED       10
+#define VIRTIO_SCSI_S_FUNCTION_REJECTED        11
+\end{lstlisting}
+
+  The \field{type} is VIRTIO_SCSI_T_TMF; \field{subtype} defines which
+  task management function. All
+  fields except \field{response} are filled by the driver.
+
+  Other fields which are irrelevant for the requested TMF
+  are ignored but they are still present. \field{lun}
+  is in the same format specified for request queues; the
+  single level LUN is ignored when the task management function
+  addresses a whole I_T nexus. When relevant, the value of \field{id}
+  is matched against the id values passed on the requestq.
+
+  The outcome of the task management function is written by the
+  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 successfully 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
+
+struct virtio_scsi_ctrl_an {
+    // Device-readable part
+    le32 type;
+    u8   lun[8];
+    le32 event_requested;
+    // Device-writable part
+    le32 event_actual;
+    u8   response;
+};
+
+#define VIRTIO_SCSI_EVT_ASYNC_OPERATIONAL_CHANGE  2
+#define VIRTIO_SCSI_EVT_ASYNC_POWER_MGMT          4
+#define VIRTIO_SCSI_EVT_ASYNC_EXTERNAL_REQUEST    8
+#define VIRTIO_SCSI_EVT_ASYNC_MEDIA_CHANGE        16
+#define VIRTIO_SCSI_EVT_ASYNC_MULTI_HOST          32
+#define VIRTIO_SCSI_EVT_ASYNC_DEVICE_BUSY         64
+\end{lstlisting}
+
+  By sending this command, the driver asks the device which
+  events the given LUN can report, as described in paragraphs 6.6
+  and A.6 of \hyperref[intro:SCSI MMC]{SCSI MMC}. The driver writes the
+  events it is interested in into \field{event_requested}; the device
+  responds by writing the events that it supports into
+  \field{event_actual}.
+
+  The \field{type} is VIRTIO_SCSI_T_AN_QUERY. \field{lun} and \field{event_requested}
+  are written by the driver. \field{event_actual} and \field{response}
+  fields are written by the device.
+
+  No command-specific values are defined for the \field{response} byte.
+
+\item Asynchronous notification subscription.
+\begin{lstlisting}
+#define VIRTIO_SCSI_T_AN_SUBSCRIBE                2
+
+struct virtio_scsi_ctrl_an {
+        // Device-readable part
+        le32 type;
+        u8   lun[8];
+        le32 event_requested;
+        // Device-writable part
+        le32 event_actual;
+        u8   response;
+};
+\end{lstlisting}
+
+  By sending this command, the driver asks the specified LUN to
+  report events for its physical interface, again as described in
+   \hyperref[intro:SCSI MMC]{SCSI MMC}. The driver writes the events it is
+  interested in into \field{event_requested}; the device responds by
+  writing the events that it supports into \field{event_actual}.
+
+  Event types are the same as for the asynchronous notification
+  query message.
+
+  The \field{type} is VIRTIO_SCSI_T_AN_SUBSCRIBE. \field{lun} and
+  \field{event_requested} are written by the driver.
+  \field{event_actual} and \field{response} are written by the device.
+
+  No command-specific values are defined for the response byte.
+\end{itemize}
+
+\paragraph{Legacy Interface: Device Operation: controlq}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: controlq / Legacy Interface: Device Operation: controlq}
+
+When using the legacy interface, transitional devices and drivers
+MUST format the fields in struct virtio_scsi_ctrl, struct
+virtio_scsi_ctrl_tmf, struct virtio_scsi_ctrl_an and struct
+virtio_scsi_ctrl_an
+according to the native endian of the guest rather than
+(necessarily when not using the legacy interface) little-endian.
+
+
+\subsubsection{Device Operation: eventq}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: eventq}
+
+The eventq is populated by the driver for the device to report information on logical
+units that are attached to it. In general, the device will not
+queue events to cope with an empty eventq, and will end up
+dropping events if it finds no buffer ready. However, when
+reporting events for many LUNs (e.g. when a whole target
+disappears), the device can throttle events to avoid dropping
+them. For this reason, placing 10-15 buffers on the event queue
+is sufficient.
+
+Buffers returned by the device on the eventq will be referred to
+as ``events'' in the rest of this section. Events have the
+following format:
+
+\begin{lstlisting}
+#define VIRTIO_SCSI_T_EVENTS_MISSED   0x80000000
+
+struct virtio_scsi_event {
+        // Device-writable part
+        le32 event;
+        u8  lun[8];
+        le32 reason;
+};
+\end{lstlisting}
+
+The devices sets bit 31 in \field{event} to report lost events
+due to missing buffers.
+
+The meaning of \field{reason} depends on the
+contents of \field{event}. The following events are defined:
+
+\begin{itemize}
+\item No event.
+\begin{lstlisting}
+#define VIRTIO_SCSI_T_NO_EVENT         0
+\end{lstlisting}
+
+  This event is fired in the following cases:
+
+\begin{itemize}
+\item When the device detects in the eventq a buffer that is
+    shorter than what is indicated in the configuration field, it
+    MAY use it immediately and put this dummy value in \field{event}.
+    A well-written driver will never observe this
+    situation.
+
+\item When events are dropped, the device MAY signal this event as
+    soon as the drivers makes a buffer available, in order to
+    request action from the driver. In this case, of course, this
+    event will be reported with the VIRTIO_SCSI_T_EVENTS_MISSED
+    flag.
+\end{itemize}
+
+\item Transport reset
+\begin{lstlisting}
+#define VIRTIO_SCSI_T_TRANSPORT_RESET  1
+
+#define VIRTIO_SCSI_EVT_RESET_HARD         0
+#define VIRTIO_SCSI_EVT_RESET_RESCAN       1
+#define VIRTIO_SCSI_EVT_RESET_REMOVED      2
+\end{lstlisting}
+
+  By sending this event, the device 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
+  fields. \field{event} is set to
+  VIRTIO_SCSI_T_TRANSPORT_RESET. \field{lun} addresses a
+  logical unit in the SCSI host.
+
+  The \field{reason} value is one of the three \#define values appearing
+  above:
+
+  \begin{description}
+  \item[VIRTIO_SCSI_EVT_RESET_REMOVED] (``LUN/target removed'') is used
+    if the target or logical unit is no longer able to receive
+    commands.
+
+  \item[VIRTIO_SCSI_EVT_RESET_HARD] (``LUN hard reset'') is used if the
+    logical unit has been reset, but is still present.
+
+  \item[VIRTIO_SCSI_EVT_RESET_RESCAN] (``rescan LUN/target'') is used if
+    a target or logical unit has just appeared on the device.
+  \end{description}
+
+  The ``removed'' and ``rescan'' events can happen when
+  VIRTIO_SCSI_F_HOTPLUG feature was negotiated; when sent for LUN 0,
+  they MAY apply to the entire target so the driver can ask the
+  initiator to rescan the target to detect this.
+
+  Events will also be reported via sense codes (this obviously
+  does not apply to newly appeared buses or targets, since the
+  application has never discovered them):
+
+  \begin{itemize}
+  \item ``LUN/target removed'' maps to sense key ILLEGAL REQUEST, asc
+    0x25, ascq 0x00 (LOGICAL UNIT NOT SUPPORTED)
+
+  \item ``LUN hard reset'' maps to sense key UNIT ATTENTION, asc 0x29
+    (POWER ON, RESET OR BUS DEVICE RESET OCCURRED)
+
+  \item ``rescan LUN/target'' maps to sense key UNIT ATTENTION, asc
+    0x3f, ascq 0x0e (REPORTED LUNS DATA HAS CHANGED)
+  \end{itemize}
+
+  The preferred way to detect transport reset is always to use
+  events, because sense codes are only seen by the driver when it
+  sends a SCSI command to the logical unit or target. However, in
+  case events are dropped, the initiator will still be able to
+  synchronize with the actual state of the controller if the
+  driver asks the initiator to rescan of the SCSI bus. During the
+  rescan, the initiator will be able to observe the above sense
+  codes, and it will process them as if it the driver had
+  received the equivalent event.
+
+  \item Asynchronous notification
+\begin{lstlisting}
+#define VIRTIO_SCSI_T_ASYNC_NOTIFY     2
+\end{lstlisting}
+
+  By sending this event, the device signals that an asynchronous
+  event was fired from a physical interface.
+
+  All fields are written by the device. \field{event} is set to
+  VIRTIO_SCSI_T_ASYNC_NOTIFY. \field{lun} addresses a logical
+  unit in the SCSI host. \field{reason} is a subset of the
+  events that the driver has subscribed to via the ``Asynchronous
+  notification subscription'' command.
+
+  \item LUN parameter change
+\begin{lstlisting}
+#define VIRTIO_SCSI_T_PARAM_CHANGE  3
+\end{lstlisting}
+
+  By sending this event, the device signals a change in the configuration parameters
+  of a logical unit, for example the capacity or cache mode.
+  \field{event} is set to VIRTIO_SCSI_T_PARAM_CHANGE.
+  \field{lun} addresses a logical unit in the SCSI host.
+
+  The same event SHOULD also be reported as a unit attention condition.
+  \field{reason} contains the additional sense code and additional sense code qualifier,
+  respectively in bits 0\ldots 7 and 8\ldots 15.
+  \begin{note}
+  For example, a change in capacity will be reported as asc 0x2a, ascq 0x09
+  (CAPACITY DATA HAS CHANGED).
+  \end{note}
+
+  For MMC devices (inquiry type 5) there would be some overlap between this
+  event and the asynchronous notification event, so for simplicity the host never
+  reports this event for MMC devices.
+\end{itemize}
+
+\drivernormative{\paragraph}{Device Operation: eventq}{Device Types / SCSI Host Device / Device Operation / Device Operation: eventq}
+
+The driver SHOULD keep the eventq populated with buffers.  These
+buffers MUST be device-writable, and SHOULD be at least
+\field{event_info_size} bytes long, and MUST be at least the size of
+struct virtio_scsi_event.
+
+If \field{event} has bit 31 set, 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 and SHOULD poll for asynchronous events manually using SCSI commands.
+
+When receiving a VIRTIO_SCSI_T_TRANSPORT_RESET message with
+\field{reason} set to VIRTIO_SCSI_EVT_RESET_REMOVED or
+VIRTIO_SCSI_EVT_RESET_RESCAN for LUN 0, the driver SHOULD ask the
+initiator to rescan the target, in order to detect the case when an
+entire target has appeared or disappeared.
+
+\devicenormative{\paragraph}{Device Operation: eventq}{Device Types / SCSI Host Device / Device Operation / Device Operation: eventq}
+
+The device MUST set bit 31 in \field{event} if events were lost due to
+missing buffers, and it MAY use a VIRTIO_SCSI_T_NO_EVENT event to report
+this.
+
+The device MUST NOT send VIRTIO_SCSI_T_TRANSPORT_RESET messages
+with \field{reason} set to VIRTIO_SCSI_EVT_RESET_REMOVED or
+VIRTIO_SCSI_EVT_RESET_RESCAN unless VIRTIO_SCSI_F_HOTPLUG was negotiated.
+
+The device MUST NOT report VIRTIO_SCSI_T_PARAM_CHANGE for MMC devices.
+
+\paragraph{Legacy Interface: Device Operation: eventq}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: eventq / Legacy Interface: Device Operation: eventq}
+When using the legacy interface, transitional devices and drivers
+MUST format the fields in struct virtio_scsi_event
+according to the native endian of the guest rather than
+(necessarily when not using the legacy interface) little-endian.
+
+\subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
+Types / SCSI Host Device / Legacy Interface: Framing Requirements}
+
+When using legacy interfaces, transitional drivers which have not
+negotiated VIRTIO_F_ANY_LAYOUT MUST use a single descriptor for the
+\field{lun}, \field{id}, \field{task_attr}, \field{prio},
+\field{crn} and \field{cdb} fields, and MUST only use a single
+descriptor for the \field{sense_len}, \field{residual},
+\field{status_qualifier}, \field{status}, \field{response} and
+\field{sense} fields.
+
+
-- 
2.26.2


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/