VIRTIO-72: SHOULD/should

Signed-off-by: Rusty Russell <rusty@au1.ibm.com>

git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio@321 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652

2 files changed, 43 insertions, 35 deletions

diff --git a/conformance.tex b/conformance.tex
index 04e6a85..dbbfc7d 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -4,7 +4,7 @@
 \chapter{Conformance}
 
 This chapter lists the conformance targets and clauses for each; this
-also forms a useful checklist which authors should check for their
+also forms a useful checklist which authors are asked to consult for their
 implementations!
 
 \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
@@ -228,6 +228,8 @@ An SCSI host device MUST conform to the following normative statements:
 
 \begin{itemize}
 \item \ref{devicenormative:Device Types / SCSI Host Device / Device configuration layout}
+\item \ref{devicenormative:Device Types / SCSI Host Device / Device Initialization}
+\item \ref{devicenormative:Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues}
 \item \ref{devicenormative:Device Types / SCSI Host Device / Device Operation / Device Operation: eventq}
 \end{itemize}
 
diff --git a/content.tex b/content.tex
index 022450a..67961b3 100644
--- a/content.tex
+++ b/content.tex
@@ -478,7 +478,7 @@ If the VIRTIO_RING_F_EVENT_IDX feature bit is not negotiated,
 the \field{flags} field in the available ring offers a crude mechanism for the driver to inform
 the device that it doesn't want interrupts when buffers are used.  Otherwise
 \field{used_event} is a more performant alterative where the driver
-specifies how much progress the device should make before interrupting.
+specifies how far the device can progress before interrupting.
 
 Neither of these interrupt suppression methods are reliable, as they
 are not explicitly synchronized with the device, but they serve as
@@ -626,7 +626,7 @@ variation to remove Linux assumptions) in \ref{sec:virtio-ring.h}~\nameref{sec:v
 
 We start with an overview of device initialization, then expand on the
 details of the device and how each step is preformed.  This section
-should be read along with the bus-specific section which describes
+is best read along with the bus-specific section which describes
 how to communicate with the specific device.
 
 \section{Device Initialization}\label{sec:General Initialization And Device Operation / Device Initialization}
@@ -2040,7 +2040,7 @@ The driver will typically initialize the virtual queue in the following way:
    \field{QueueSel}.
 
 \item Check if the queue is not already in use: read \field{QueueReady},
-   returned value should be zero (0x0).
+   and expect a returned value of zero (0x0).
 
 \item Read maximum queue size (number of elements) from
    \field{QueueNumMax}. If the returned value is zero (0x0) the
@@ -2188,8 +2188,8 @@ nor behaviour:
     flags.
     Writing non-zero values to this register sets the status flags,
     indicating the OS/driver progress. Writing zero (0x0) to this
-    register triggers a device reset. This should include
-    setting \field{QueuePFN} to zero (0x0) for all queues in the device.
+    register triggers a device reset. The device MUST
+    set \field{QueuePFN} to zero (0x0) for all queues in the device.
     Also see \ref{sec:General Initialization And Device Operation / Device Initialization}~\nameref{sec:General Initialization And Device Operation / Device Initialization}.
   }
   \hline
@@ -2211,7 +2211,7 @@ The virtual queue is configured as follows:
    \field{QueueSel}.
 
 \item Check if the queue is not already in use: read \field{QueuePFN},
-   returned value should be zero (0x0).
+   expecting a returned value of zero (0x0).
 
 \item Read maximum queue size (number of elements) from
    \field{QueueNumMax}. If the returned value is zero (0x0) the
@@ -2802,7 +2802,7 @@ them no further.
 The virtio network device is a virtual ethernet card, and is the
 most complex of the devices supported so far by virtio. It has
 enhanced rapidly and demonstrates clearly how support for new
-features should be added to an existing device. Empty buffers are
+features are added to an existing device. Empty buffers are
 placed in one virtqueue for receiving packets, and outgoing
 packets are enqueued into another for transmission in that order.
 A third command queue is used to control advanced filtering
@@ -3068,7 +3068,7 @@ the different features the driver negotiated.
     and
 
   \item \field{csum_offset} indicates how many bytes after the csum_start the
-    new (16 bit ones' complement) checksum should be placed.
+    new (16 bit ones' complement) checksum is placed by the device.
 
   \item The TCP checksum field in the packet is set to the sum
     of the TCP pseudo header, so that replacing it by the ones'
@@ -3198,7 +3198,7 @@ Processing packet involves:
   this packet is spread over (including this one). This allows
   receipt of large packets without having to allocate large
   buffers. In this case, there will be at least \field{num_buffers} in
-  the used ring, and they should be chained together to form a
+  the used ring, and the device chains them together to form a
   single packet. The other buffers will not begin with a struct
   virtio_net_hdr.
 
@@ -3603,7 +3603,7 @@ device except where noted.
 \end{description}
 
 VIRTIO_BLK_F_FLUSH was also called VIRTIO_BLK_F_WCE: Legacy drivers
-should only negotiate this feature if they are capable of sending
+MUST only negotiate this feature if they are capable of sending
 VIRTIO_BLK_T_FLUSH commands.
 
 \subsubsection{Device configuration layout}\label{sec:Device Types / Block Device / Feature bits / Device configuration layout}
@@ -3668,8 +3668,8 @@ according to the native endian of the guest rather than
 \subsubsection{Legacy Interface: Device Initialization}\label{sec:Device Types / Block Device / Device Initialization / Legacy Interface: Device Initialization}
 
 The \field{reserved} field used to be called \field{writeback}.  If the
-VIRTIO_BLK_F_CONFIG_WCE feature is offered, the cache mode should be
-read from \field{writeback} if available; the
+VIRTIO_BLK_F_CONFIG_WCE feature is offered, the cache mode can be
+read from \field{writeback}; the
 driver can also write to the field in order to toggle the cache
 between writethrough (0) and writeback (1) mode.  If the feature is
 not available, the driver can instead look at the result of
@@ -3810,7 +3810,7 @@ write can be derived from the total size of the request buffers.
 and indicates the buffer for scsi sense data.
 
 \field{data_len} is only present for scsi packet command
-requests, this field is deprecated, and should be ignored by the
+requests, this field is deprecated, and SHOULD be ignored by the
 driver. Historically, devices copied data length there.
 
 \field{sense_len} is only present for scsi packet command
@@ -3925,7 +3925,7 @@ according to the native endian of the guest rather than
 \begin{enumerate}
 \item If the VIRTIO_CONSOLE_F_EMERG_WRITE feature is offered,
   \field{emerg_wr} field of the configuration can be written at any time.
-  Thus it should work for very early boot debugging output as well as
+  Thus it works for very early boot debugging output as well as
   catastophic OS failures (eg. virtio ring corruption).
 
 \item If the VIRTIO_CONSOLE_F_SIZE feature is negotiated, the driver
@@ -4263,7 +4263,7 @@ as follows:
   Each statistic consists of a 16 bit
   tag and a 64 bit value. All statistics are optional and the
   driver chooses which ones to supply. To guarantee backwards
-  compatibility, unsupported statistics should be omitted.
+  compatibility, the driver SHOULD omit unsupported statistics.
 
 \begin{lstlisting}
 struct virtio_balloon_stat {
@@ -4347,7 +4347,7 @@ 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
+\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_CHANGE (2)] The host will report changes to LUN
@@ -4383,12 +4383,10 @@ struct virtio_scsi_config {
     segments and \field{seg_max} output segments.
 
 \item[\field{max_sectors}] is a hint to the driver about the maximum transfer
-    size it should use.
+    size to use.
 
-\item[\field{cmd_per_lun}] is a hint to the driver about the maximum number of
-    linked commands it should send to one LUN. The actual value
-    to be used is the minimum of \field{cmd_per_lun} and the virtqueue
-    size.
+\item[\field{cmd_per_lun}] is 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
@@ -4415,6 +4413,10 @@ struct virtio_scsi_config {
 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
@@ -4426,17 +4428,17 @@ 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.
 
-\subsection{Device Initialization}\label{sec:Device Types / SCSI Host Device / Device Initialization}
+\devicenormative{\subsection}{Device Initialization}{Device Types / SCSI Host Device / Device Initialization}
 
-The initialization routine should first of all discover the
+On initialization the device SHOULD first discover the
 device's virtqueues.
 
-If the driver uses the eventq, it should then place at least a
+If the driver uses the eventq, the driver SHOULD place at least one
 buffer in the eventq.
 
-The driver can immediately issue requests (for example, INQUIRY
-or REPORT LUNS) or task management functions (for example, I_T
-RESET).
+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}
 
@@ -4526,11 +4528,12 @@ exceeds the size of \field{datain} means that \field{dataout} was
 processed partially and \field{datain} was not processed at
 all.
 
-The \field{status} byte is written by the device to be the status code as
+\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 \field{response} byte is written by the device to be one of the
-following:
+The device MUST write the \field{response} byte as one of the following:
 
 \begin{description}
 
@@ -4555,13 +4558,13 @@ following:
   (severed link).
 
 \item[VIRTIO_SCSI_S_TARGET_FAILURE] if the target is suffering a
-  failure and the driver should not retry on other paths.
+  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 should work.
+  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
@@ -4574,6 +4577,9 @@ following:
 
 \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
@@ -4738,7 +4744,7 @@ 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
-should be enough.
+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
@@ -4983,5 +4989,5 @@ transitional drivers MUST accept the following:
 
 \item[UNUSED (30)] Bit 30 is used by qemu's implementation to check
   for experimental early versions of virtio which did not perform
-  correct feature negotiation, and should not be used.
+  correct feature negotiation, and SHOULD NOT be negotiated.
 \end{description}