Feedback: CCW: Separate normative and descriptive sections.

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

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

1 files changed, 46 insertions, 19 deletions

diff --git a/content.tex b/content.tex
index c072832..9de50bc 100644
--- a/content.tex
+++ b/content.tex
@@ -2188,9 +2188,6 @@ Bytes & Description & Contents \\
 \hline
 \end{tabular}
 
-A driver for virtio-ccw devices MUST check for a control unit
-type of 0x3832 and MUST ignore the device type and model.
-
 In addition to the basic channel commands, virtio-ccw defines a
 set of channel commands related to configuration and operation of
 virtio:
@@ -2210,6 +2207,8 @@ virtio:
 #define CCW_CMD_SET_VIRTIO_REV 0x83
 \end{lstlisting}
 
+\devicenormative{Virtio Transport Options / Virtio over channel I/O / Basic Concepts}
+
 The virtio-ccw device acts like a normal channel device, as specified
 in \hyperref[intro:S390 PoP]{[S390 PoP]} and \hyperref[intro:S390 Common I/O]{[S390 Common I/O]}. In particular:
 
@@ -2225,10 +2224,16 @@ in \hyperref[intro:S390 PoP]{[S390 PoP]} and \hyperref[intro:S390 Common I/O]{[S
   device MUST present a check condition if the transmitted data does
   not contain enough data to process the command. If the driver submitted
   a buffer that was too long, the device SHOULD accept the command.
-  The driver SHOULD attempt to provide the correct length even if it
-  suppresses length checks.
 \end{itemize}
 
+\drivernormative{Virtio Transport Options / Virtio over channel I/O / Basic Concepts}
+
+A driver for virtio-ccw devices MUST check for a control unit
+type of 0x3832 and MUST ignore the device type and model.
+
+A driver SHOULD attempt to provide the correct length in a channel
+command even if it suppresses length checks for that command.
+
 \subsection{Device Initialization}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization}
 
 virtio-ccw uses several channel commands to set up a device.
@@ -2267,30 +2272,36 @@ The following values are supported:
 Note that a change in the virtio standard does not necessarily
 correspond to a change in the virtio-ccw revision.
 
+\devicenormative{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting the Virtio Revision}
+
 A device MUST post a unit check with command reject for any \field{revision}
 it does not support. For any invalid combination of \field{revision}, \field{length}
 and \field{data}, it MUST post a unit check with command reject as well. A
 non-transitional device MUST reject revision id 0.
 
-A driver SHOULD start with trying to set the highest revision it
-supports and continue with lower revisions if it gets a command reject.
-
-A driver MUST NOT issue any other virtio-ccw specific channel commands
-prior to setting the revision.
-
 A device MUST answer with command reject to any virtio-ccw specific
 channel command that is not contained in the revision selected by the
 driver.
 
-After a revision has been successfully selected by the driver, it
-MUST NOT attempt to select a different revision. A device MUST answer
-to any such attempt with a command reject.
+A device MUST answer with command reject to any attempt to select a different revision
+after a revision has been successfully selected by the driver.
 
 A device MUST treat the revision as unset from the time the associated
 subchannel has been enabled until a revision has been successfully set
 by the driver. This implies that revisions are not persistent across
 disabling and enabling of the associated subchannel.
 
+\drivernormative{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting the Virtio Revision}
+
+A driver SHOULD start with trying to set the highest revision it
+supports and continue with lower revisions if it gets a command reject.
+
+A driver MUST NOT issue any other virtio-ccw specific channel commands
+prior to setting the revision.
+
+After a revision has been successfully selected by the driver, it
+MUST NOT attempt to select a different revision.
+
 \paragraph{Legacy Interfaces: A Note on Setting the Virtio Revision}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting the Virtio Revision / Legacy Interfaces: A Note on Setting the Virtio Revision}
 
 A legacy device will not support the CCW_CMD_SET_VIRTIO_REV and answer
@@ -2339,6 +2350,9 @@ struct vq_info_block {
 \field{desc}, \field{avail} and \field{used} contain the guest addresses for the descriptor table,
 available ring and used ring for queue \field{index}, respectively. The actual
 virtqueue size (number of allocated buffers) is transmitted in \field{num}.
+
+\devicenormative{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue}
+
 \field{res0} is reserved and MUST be ignored by the device.
 
 \paragraph{Legacy Interface: A Note on Configuring a Virtqueue}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue / Legacy Interface: A Note on Configuring a Virtqueue}
@@ -2506,6 +2520,7 @@ No padding is added at the end of the structure, it is exactly 25 bytes
 in length.
 
 
+\devicenormative{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting Up Indicators / Setting Up Two-Stage Queue Indicators}
 If the driver has already set up classic queue indicators via the
 CCW_CMD_SET_IND command, the device MUST post a unit check with
 command reject to any subsequent CCW_CMD_SET_IND_ADAPTER command.
@@ -2553,8 +2568,14 @@ For notifying the driver of virtqueue buffers, the device sets the
 bit in the guest-provided indicator area at the corresponding offset.
 The guest-provided summary indicator is set to 0x01. An adapter I/O
 interrupt for the corresponding interruption subclass is generated.
+
+\devicenormative{Virtio Transport Options / Virtio over channel I/O / Device Operation / Host->Guest Notification / Notification via Adapter I/O Interrupts}
+
 The device SHOULD only generate an adapter I/O interrupt if the
-summary indicator had not been set prior to notification. The driver
+summary indicator had not been set prior to notification.
+
+\drivernormative{Virtio Transport Options / Virtio over channel I/O / Device Operation / Host->Guest Notification / Notification via Adapter I/O Interrupts}
+The driver
 MUST clear the summary indicator after receiving an adapter I/O
 interrupt before it processes the queue indicators.
 
@@ -2585,20 +2606,26 @@ GPR  &   Input Value     & Output Value \\
 \hline
 \end{tabular}
 
+\devicenormative{Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification}
 The device MUST ignore bits 0-31 (counting from the left) of GPR2.
 This aligns passing the subchannel ID with the way it is passed
 for the existing I/O instructions.
 
-Host cookie is an optional per-virtqueue 64 bit value that MAY be
-used by the hypervisor to speed up the notification execution.
-For each notification, the output value is returned in GPR2 and
-SHOULD be passed in GPR4 for the next notification:
+The device MAY return a 64-bit host cookie in GPR2 to speed up the
+notification execution.
 
+\drivernormative{Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification}
+
+For each notification, the driver SHOULD use GPR4 to pass the host cookie received in GPR2 from the previous notication.
+
+\begin{note}
+For example:
 \begin{lstlisting}
 info->cookie = do_notify(schid,
                          virtqueue_get_queue_index(vq),
                          info->cookie);
 \end{lstlisting}
+\end{note}
 
 \subsubsection{Resetting Devices}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Operation / Resetting Devices}