[PATCH 1/6] VIRTIO-81: MUST vs must

[Rusty Russell <rusty@au1.ibm.com>]

Clean up the remaining lowercase "musts".  We actually introduce a
new normative section in the balloon; for the rest we clarify them
one way or another.

Signed-off-by: Rusty Russell <rusty@au1.ibm.com>
---
 conformance.tex |  1 +
 content.tex     | 70 ++++++++++++++++++++++++++++++++++++---------------------
 newdevice.tex   |  4 ++--
 3 files changed, 48 insertions(+), 27 deletions(-)

diff --git a/conformance.tex b/conformance.tex
index 0ea012a..04e6a85 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -282,6 +282,7 @@ Feature Bits / Legacy Interface: A Note on Feature Bits}
 \item Section \ref{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation}
 \item Section \ref{sec:Device Types / Console Device / Device configuration layout / Legacy Interface: Device configuration layout}
 \item Section \ref{sec:Device Types / Console Device / Device Operation / Legacy Interface: Device Operation}
+\item Section \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation}
 \item Section \ref{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics / Legacy Interface: Memory Statistics}
 \item Section \ref{sec:Device Types / SCSI Host Device / Device configuration layout / Legacy Interface: Device configuration layout}
 \item Section \ref{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues / Legacy Interface: Device Operation: Request Queues}
diff --git a/content.tex b/content.tex
index a509b20..cb40ae0 100644
--- a/content.tex
+++ b/content.tex
@@ -348,6 +348,9 @@ of descriptors.  The device MAY have a reasonable limit of descriptors
 it will allow in a chain.
 
 \drivernormative{\subsubsection}{Message Framing}{Basic Facilities of a Virtio Device / Message Framing}
+The driver MUST place any device-writable descriptor elements after
+any device-readable descriptor elements.
+
 The driver SHOULD NOT use an excessive number of descriptors to
 describe a buffer.
 
@@ -748,7 +751,7 @@ available ring buffer wrapping around: this is not possible since
 the ring buffer is the same size as the descriptor table, so step
 (1) will prevent such a condition.
 
-In addition, the maximum queue size is 32768 (it must be a power
+In addition, the maximum queue size is 32768 (the highest power
 of 2 which fits in 16 bits), so the 16-bit \field{idx} value can always
 distinguish between a full and empty buffer.
 
@@ -758,7 +761,7 @@ What follows is the requirements of each stage in more detail.
 
 A buffer consists of zero or more device-readable physically-contiguous
 elements followed by zero or more physically-contiguous
-device-writable elements (it must have at least one element). This
+device-writable elements (each has at least one element). This
 algorithm maps it into the descriptor table to form a descriptor
 chain:
 
@@ -899,7 +902,7 @@ Virtio devices are commonly implemented as PCI devices.
 A Virtio device can be implemented as any kind of PCI device:
 a Conventional PCI device or a PCI Express
 device.  To assure designs meet the latest level
-requirements, designers of Virtio Over PCI devices must refer to
+requirements, see 
 the PCI-SIG home page at \url{http://www.pcisig.com} for any
 approved changes.
 
@@ -1277,7 +1280,7 @@ the same Queue Notify address for all queues.
 \devicenormative{\paragraph}{Notification capability}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability}
 The device MUST present at least one notification capability.
 
-The \field{cap.offset} must be 2-byte aligned.  
+The \field{cap.offset} MUST be 2-byte aligned.  
 
 The device MUST either present \field{notify_off_multiplier} as an even power of 2,
 or present \field{notify_off_multiplier} as 0.
@@ -1342,7 +1345,7 @@ any device type which has a device specific structure.
 
 \devicenormative{\paragraph}{Device specific structure}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Device specific structure}
 
-The \field{offset} for the device specific structure must be 4-byte aligned.
+The \field{offset} for the device specific structure MUST be 4-byte aligned.
 
 \subsubsection{PCI configuration access capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability}
 
@@ -1396,7 +1399,7 @@ at BAR selected by \field{cap.bar} and store the first \field{cap.length} bytes
 \drivernormative{\paragraph}{PCI configuration access capability}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability}
 
 The driver MUST NOT write a \field{cap.offset} which is not
-a multiple of \field{cap.length} (ie. all accesses must be aligned).
+a multiple of \field{cap.length} (ie. all accesses MUST be aligned).
 
 \subsubsection{Legacy Interfaces: A Note on PCI Device Layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Legacy Interfaces: A Note on PCI Device Layout}
 
@@ -2184,7 +2187,7 @@ nor behaviour:
 \end{longtable}
 
 The virtual queue page size is defined by writing to \field{GuestPageSize},
-as written by the guest. This must be done before the
+as written by the guest. The driver MUST do this before the
 virtual queues are configured.
 
 The virtual queue layout follows
@@ -3110,7 +3113,7 @@ VIRTIO_NET_F_MRG_RXBUF case.
 \drivernormative{\paragraph}{Packet Transmission}{Device Types / Network Device / Device Operation / Packet Transmission}
 
 If a driver has not negotiated VIRTIO_NET_F_CSUM, \field{flags} MUST be zero and
-the packet must be fully checksummed.
+the packet MUST be fully checksummed.
 
 If a driver negotiated the VIRTIO_NET_F_MRG_RXBUF feature, it MUST include
 \field{num_buffers} in the header, and it MUST set the value to zero.  If a driver
@@ -3691,12 +3694,15 @@ higher numbers indicate more important requests.
 
 If the device has VIRTIO_BLK_F_BARRIER
 feature the high bit (VIRTIO_BLK_T_BARRIER) indicates that this
-request acts as a barrier and that all preceeding 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
+request acts as a barrier and that all preceeding requests SHOULD be
+complete before this one, and all following requests SHOULD NOT be
+started until this is complete.
+
+\begin{note} A barrier does not flush
 caches in the underlying backend device in host, and thus does not
-serve as data consistency guarantee. Driver must use FLUSH request to
-flush the host cache.
+serve as data consistency guarantee.  Only a VIRTIO_BLK_T_FLUSH request
+does that.
+\end{note}
 
 If the device has VIRTIO_BLK_F_SCSI feature, it can also support
 scsi packet command requests, each of these requests is of form:
@@ -3729,7 +3735,7 @@ does not distinguish between them:
 \end{lstlisting}
 
 The \field{cmd} field is only present for scsi packet command requests,
-and indicates the command to perform. This field must reside in a
+and indicates the command to perform. This field MUST reside in a
 single, separate device-readable buffer; command length can be derived
 from the length of this buffer.
 
@@ -3967,7 +3973,7 @@ which has not been created with a previous VIRTIO_CONSOLE_DEVICE_ADD.
 
 \drivernormative{\paragraph}{Multiport Device Operation}{Device Types / Console Device / Device Operation / Multiport Device Operation}
 
-The driver must send a VIRTIO_CONSOLE_DEVICE_READY message if
+The driver MUST send a VIRTIO_CONSOLE_DEVICE_READY message if
 VIRTIO_CONSOLE_F_MULTIPORT is negotiated.
 
 Upon receipt of a VIRTIO_CONSOLE_CONSOLE_PORT message, the driver
@@ -4054,7 +4060,7 @@ guest memory statistics to the host.
 
 \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Feature bits}
 \begin{description}
-\item[VIRTIO_BALLOON_F_MUST_TELL_HOST (0)] Host must be told before
+\item[VIRTIO_BALLOON_F_MUST_TELL_HOST (0)] Host MUST be told before
     pages from the balloon are used.
 
 \item[VIRTIO_BALLOON_F_STATS_VQ (1)] A virtqueue for reporting guest
@@ -4098,10 +4104,9 @@ configuration change interrupt.
 
 \begin{enumerate}
 \item \field{num_pages} configuration field is examined. If this is
-  greater than the \field{actual} number of pages, memory must be given
-  to the balloon. If it is less than \field{actual},
-  memory may be taken back from the balloon for general
-  use.
+  greater than the \field{actual} number of pages, the balloon wants
+  more memory from the guest.  If it is less than \field{actual},
+  the balloon doesn't need it all.
 
 \item To supply memory to the balloon (aka. inflate):
   \begin{enumerate}
@@ -4118,22 +4123,37 @@ configuration change interrupt.
     This descriptor is added to the deflateq.
 
   \item If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the
-    guest may not use these requested pages until that descriptor
-    in the deflateq has been used by the device.
+    guest informs the device of pages before it uses them.
 
-  \item Otherwise, the guest may begin to re-use pages previously
+  \item Otherwise, the guest MAY begin to re-use pages previously
     given to the balloon before the device has acknowledged their
     withdrawal.\footnote{In this case, deflation advice is merely a courtesy
 }
   \end{enumerate}
 
 \item In either case, once the device has completed the inflation or
-  deflation, \field{actual} should be
-  updated to reflect the new number of pages in the balloon.\footnote{As updates to device-specific configuration space are not atomic, this field
+  deflation, the driver updates \field{actual} to reflect the new number of pages in the balloon.\footnote{As updates to device-specific configuration space are not atomic, this field
 isn't particularly reliable, but can be used to diagnose buggy guests.
 }
 \end{enumerate}
 
+\drivernormative{\subsubsection}{Device Operation}{Device Types / Memory Balloon Device / Device Operation}
+The driver SHOULD supply pages to the balloon when \field{num_pages} is
+greater than \field{actual}.
+
+The driver MAY use pages from the balloon when \field{num_pages} is
+less than \field{actual}.
+
+The driver MUST use the deflateq to inform the device of pages that it
+wants to use from the balloon.
+
+If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the
+driver MUST wait until the device has used the deflateq descriptor
+before using the pages.
+
+The driver MUST update \field{actual} after changing the number
+of pages in the balloon.
+
 \subsubsection{Memory Statistics}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics}
 
 The stats virtqueue is atypical because communication is driven
diff --git a/newdevice.tex b/newdevice.tex
index 5e07b79..c7e6221 100644
--- a/newdevice.tex
+++ b/newdevice.tex
@@ -22,8 +22,8 @@ configuration information (the network device does this for filtering,
 otherwise the table in the config space could potentially be very
 large).
 
-Devices must not assume that configuration fields over 32 bits wide
-are atomically writable by the driver.
+Remember that configuration fields over 32 bits wide might not be
+atomically writable by the driver.
 
 \section{What Device Number?}\label{sec:Creating New Device Types / What Device Number?}
 
-- 
1.8.3.2