virtio-msg: editorial changes from Matias

* drop 'underlying'
* add MUST to Optional Bus Messages
* s/tables/table/
  (Matias suggested s/defines/define/ but there is only one table ATM)
  (Also change table defines to table lists to avoid double "define")
* If the bus adds s/it/its/
* Fix feature {itemize} list
  * drop verb from {Block Index}
  * Also fix s/32 bits values/32 bit values/
* drop \emph{chooses} in two places
* s/defines/defined/ in Endianness section
* add "and the buffer has been added to the used ring of the virtqueue"
* s/in band/in-band and s/out of band event/out-of-band event
* (Did not add "on", the sentience reads ok without it)
* Replace sentence with "it should prevent this feature ..."
* s/standardizes/standardized/
* Fix sentence about PING being optional

Signed-off-by: Bill Mills <bill.mills@linaro.org>

Author: wmamills

transport-msg.tex

@@ -22,8 +22,7 @@ \subsubsection{Purpose}
   \item \textbf{Support multiple bus implementations:}
   Systems may rely on various communication methods such as hypercalls, local
   IPC, network channels, or device trees for enumerating devices. virtio-msg
-  defines a common transport interface suitable for any of these underlying
-  mechanisms.
+  defines a common transport interface suitable for any of these mechanisms.
 
   \item \textbf{Reduce per-bus complexity:}
   Buses can implement a fully message-based workflow (including optional
@@ -95,8 +94,9 @@ \subsubsection{Optional Bus Messages}
 completely message-based approach to enumeration, hotplug, and bus-wide health.
 However, these are \emph{not} mandatory if a bus instance already handles those
 functions via firmware, device tree, or other platform features. The only strict
-requirement is that the bus be able to forward device-specific \emph{transport
-messages} once a device is recognized, so the virtio-msg driver can manage it.
+requirement is that the bus \emph{MUST} be able to forward device-specific
+\emph{transport messages} once a device is recognized, so the virtio-msg driver
+can manage it.
 
 \subsection{Basic Concepts}
 \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts}
@@ -139,7 +139,7 @@ \subsubsection{Transport Revisions and Maximum Message Size}
 
 \paragraph{virtio-msg revisions}
 
-The following tables defines the currently defined virtio-msg revisions:
+The following table lists the currently defined virtio-msg revisions:
 
 \begin{tabular}{ |l|l|l|l| }
 \hline
@@ -153,7 +153,7 @@ \subsubsection{Transport Revisions and Maximum Message Size}
 correspond to a change in the virtio-msg revision.
 
 The maximum message size is from the common transport level point of
-view and includes the headers and payload described here.  If the bus adds it
+view and includes the headers and payload described here.  If the bus adds its
 own overhead (e.x. its own header) this is not included in the maximum message
 size. The maximum useful message size is currently expected to be 274.
 This value is large enough to support a GET_CONFIG or SET_CONFIG message with a
@@ -218,7 +218,7 @@ \subsubsection{Feature Negotiation Blocks}
 \msgref{SET_DRIVER_FEATURES}. Each block corresponds to up to 32 features:
 
 \begin{itemize}
-  \item \textbf{Block Index}: Identifies the starting block (e.g., block 0 for
+  \item \textbf{Block Index}: The starting block (e.g., block 0 for
         features 0--31, block 1 for features 32--63, etc.).
   \item \textbf{Number of Blocks}: How many blocks the driver wishes to retrieve
         or modify in a single message.
@@ -270,7 +270,7 @@ \subsubsection{Bus vs. Transport Messages}
     or assessing bus-wide health (\busref{PING}).
     These messages are \emph{optional} in environments where
     device discovery or state changes occur through other means (e.g., device
-    tree). However, if a bus \emph{chooses} to handle those tasks via messages,
+    tree). However, if a bus chooses to handle those tasks via messages,
     it \emph{should} implement the appropriate bus message definitions.
 
   \item[\textbf{Transport Messages}:]
@@ -295,7 +295,7 @@ \subsubsection{Bus vs. Transport Messages}
 \subsubsection{Endianness}
 \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness}
 
-All encoding of values and fields defines in the virtio-msg messages \emph{MUST}
+All encoding of values and fields defined in the virtio-msg messages \emph{MUST}
 be encoded in little-endian.
 
 \subsubsection{Common Message Format}
@@ -686,7 +686,7 @@ \subsubsection{Device Notifications}
 These notifications may be the result of:
 
 \begin{itemize}
-    \item The same messages received in band on the message channel from the
+    \item The same messages received in-band on the message channel from the
         device side bus.
     \item Manufactured by the driver side bus based on reception of an
         out-of-band (OoB) notification from the device side.  Example OoB
@@ -709,7 +709,8 @@ \subsubsection{Device Notifications}
 \paragraph{EVENT\_USED}
 \begin{itemize}
   \item Signifies that one or more buffers in a specific virtqueue have been
-    processed or consumed by the device.
+    processed or consumed by the device and the buffer has been added to the
+    used ring of the virtqueue.
   \item The driver uses normal virtio methods (e.g., reading the "used" ring) to
     identify which buffers are complete.
   \item If a device does not support sending \msgref{EVENT_USED}, the driver
@@ -831,7 +832,7 @@ \subsubsection{Overview}
 \end{itemize}
 
 The functionality of the following messages \textbf{MUST} be provided by
-in band messages, out of band event notification, or bus implementation based
+in-band messages, out-of-band event notification, or bus implementation based
 polling:
 \begin{itemize}
   \item \msgref{EVENT_AVAIL}
@@ -1115,8 +1116,8 @@ \subsubsection{Overview}
 The \textbf{Next wrap} field is the MSB of the 32 bit value. The
 \textbf{Next offset} field is the other 31 bits. These fields should be 0 if
 the VIRTIO_F_NOTIFICATION_DATA feature has not been negotiated. If the bus
-implementation is using out-of-band notifications, it should refuse to allow
-this feature to be negotiated.
+implementation is using out-of-band notifications, it should prevent this
+feature from being negotiated.
 
 \msgdef{EVENT_USED}
 
@@ -1158,7 +1159,7 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa
 \hline
 \end{tabular}
 
-Bus message IDs below 0x80 are reserved for standardizes (but optional) bus
+Bus message IDs below 0x80 are reserved for standardized (but optional) bus
 messages.  A few are used here and more are expected in the future. Bus message
 IDs below 0x40 are used for request/response messages and 0x40 and above for
 event messages.
@@ -1324,16 +1325,15 @@ \subsubsection{Optional Requirements}
     and \busref{EVENT_DEVICE} for discovering and managing devices in a
     message-driven manner. However, this is not mandatory if other enumeration
     methods (e.g., device tree, ACPI, hypervisor firmware) are used.
-  \item If a bus \emph{chooses} to implement these messages, it \textbf{MUST} do
+  \item If a bus chooses to implement these messages, it \textbf{MUST} do
     so in compliance with their defined formats and semantics (see
     \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages}).
 \end{itemize}
 
 \paragraph{Optional Bus-Level Messages}
 \begin{itemize}
-  \item \busref{PING} for keepalive or health checks is also \emph{MAY}
-    implement. If used, both sides \textbf{MUST} echo the 32-bit data field
-    precisely.
+  \item \busref{PING} \emph{MAY} be implemented for keepalive or health checks.
+    If used, both sides \textbf{MUST} echo the 32-bit data field precisely.
 \end{itemize}
 
 \paragraph{Runtime Notifications}