packed-ring: add missing articles to sentences

There are several sentence structures used throughout the text where an
article is missing.  For example:

  ... allocated by driver.

or

  Driver then notifies the device.

Standards documents normally use complete sentences so this patch adds
the missing articles required before the noun ("driver"):

  ... allocated by the driver.

or

  The driver then notifies the device.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Fixes: https://github.com/oasis-tcs/virtio-spec/issues/7
Approved-by: https://www.oasis-open.org/committees/ballot.php?id=3184

1 files changed, 45 insertions, 45 deletions

diff --git a/packed-ring.tex b/packed-ring.tex
index 4b3d9d9..211a989 100644
--- a/packed-ring.tex
+++ b/packed-ring.tex
@@ -10,7 +10,7 @@ feature bit.
 Packed virtqueues support up to $2^{15}$ entries each.
 
 With current transports, virtqueues are located in guest memory
-allocated by driver.
+allocated by the driver.
 Each packed virtqueue consists of three parts:
 
 \begin{itemize}
@@ -19,7 +19,7 @@ Each packed virtqueue consists of three parts:
 \item Device Event Suppression - occupies the Device Area
 \end{itemize}
 
-Where Descriptor Ring in turn consists of descriptors,
+Where the Descriptor Ring in turn consists of descriptors,
 and where each descriptor can contain the following parts:
 
 \begin{itemize}
@@ -39,35 +39,35 @@ the buffer into the Descriptor Ring.  The descriptor(s) are
 associated with a buffer by means of a Buffer ID stored within
 the descriptor.
 
-Driver then notifies the device. When the device has finished
+The driver then notifies the device. When the device has finished
 processing the buffer, it writes a used device descriptor
 including the Buffer ID into the Descriptor Ring (overwriting a
 driver descriptor previously made available), and sends an
 interrupt.
 
-Descriptor Ring is used in a circular manner: driver writes
-descriptors into the ring in order. After reaching end of ring,
-the next descriptor is placed at head of the ring.  Once ring is
-full of driver descriptors, driver stops sending new requests and
-waits for device to start processing descriptors and to write out
+The Descriptor Ring is used in a circular manner: the driver writes
+descriptors into the ring in order. After reaching the end of the ring,
+the next descriptor is placed at the head of the ring.  Once the ring is
+full of driver descriptors, the driver stops sending new requests and
+waits for the device to start processing descriptors and to write out
 some used descriptors before making new driver descriptors
 available.
 
-Similarly, device reads descriptors from the ring in order and
+Similarly, the device reads descriptors from the ring in order and
 detects that a driver descriptor has been made available.  As
 processing of descriptors is completed used descriptors are
 written by the device back into the ring.
 
 Note: after reading driver descriptors and starting their
-processing in order, device might complete their processing out
+processing in order, the device might complete their processing out
 of order.  Used device descriptors are written in the order
 in which their processing is complete.
 
-Device Event Suppression data structure is write-only by the
+The Device Event Suppression data structure is write-only by the
 device. It includes information for reducing the number of
 device events - i.e. driver notifications to device.
 
-Driver Event Suppression data structure is read-only by the
+The Driver Event Suppression data structure is read-only by the
 device. It includes information for reducing the number of
 driver events - i.e. device interrupts to driver.
 
@@ -77,13 +77,13 @@ Each of the driver and the device are expected to maintain,
 internally, a single-bit ring wrap counter initialized to 1.
 
 The counter maintained by the driver is called the Driver
-Ring Wrap Counter. Driver changes the value of this counter
+Ring Wrap Counter. The driver changes the value of this counter
 each time it makes available the
 last descriptor in the ring (after making the last descriptor
 available).
 
 The counter maintained by the device is called the Device Ring Wrap
-Counter.  Device changes the value of this counter
+Counter.  The device changes the value of this counter
 each time it uses the last descriptor in
 the ring (after marking the last descriptor used).
 
@@ -91,20 +91,20 @@ It is easy to see that the Driver Ring Wrap Counter in the driver matches
 the Device Ring Wrap Counter in the device when both are processing the same
 descriptor, or when all available descriptors have been used.
 
-To mark a descriptor as available and used, both driver and
-device use the following two flags:
+To mark a descriptor as available and used, both the driver and
+the device use the following two flags:
 \begin{lstlisting}
 #define VIRTQ_DESC_F_AVAIL     (1 << 7)
 #define VIRTQ_DESC_F_USED      (1 << 15)
 \end{lstlisting}
 
-To mark a descriptor as available, driver sets the
+To mark a descriptor as available, the driver sets the
 VIRTQ_DESC_F_AVAIL bit in Flags to match the internal Driver
 Ring Wrap Counter.  It also sets the VIRTQ_DESC_F_USED bit to match the
 \emph{inverse} value (i.e. to not match the internal Driver Ring
 Wrap Counter).
 
-To mark a descriptor as used, device sets the
+To mark a descriptor as used, the device sets the
 VIRTQ_DESC_F_USED bit in Flags to match the internal Device
 Ring Wrap Counter.  It also sets the VIRTQ_DESC_F_AVAIL bit to match the
 \emph{same} value.
@@ -126,15 +126,15 @@ possible.
 
 Writes of device and driver descriptors can generally be
 reordered, but each side (driver and device) are only required to
-poll (or test) a single location in memory: next device descriptor after
+poll (or test) a single location in memory: the next device descriptor after
 the one they processed previously, in circular order.
 
-Sometimes device needs to only write out a single used descriptor
+Sometimes the device needs to only write out a single used descriptor
 after processing a batch of multiple available descriptors.  As
 described in more detail below, this can happen when using
 descriptor chaining or with in-order
-use of descriptors.  In this case, device writes out a used
-descriptor with buffer id of the last descriptor in the group.
+use of descriptors.  In this case, the device writes out a used
+descriptor with the buffer id of the last descriptor in the group.
 After processing the used descriptor, both device and driver then
 skip forward in the ring the number of the remaining descriptors
 in the group until processing (reading for the driver and writing
@@ -143,7 +143,7 @@ for the device) the next used descriptor.
 \subsection{Write Flag}
 \label{sec:Packed Virtqueues / Write Flag}
 
-In an available descriptor, VIRTQ_DESC_F_WRITE bit within Flags
+In an available descriptor, the VIRTQ_DESC_F_WRITE bit within Flags
 is used to mark a descriptor as corresponding to a write-only or
 read-only element of a buffer.
 
@@ -198,9 +198,9 @@ size.
 \subsection{Next Flag: Descriptor Chaining}
 \label{sec:Packed Virtqueues / Next Flag: Descriptor Chaining}
 
-The packed ring format allows driver to supply
+The packed ring format allows the driver to supply
 a scatter/gather list to the device
-by using multiple descriptors, and setting the VIRTQ_DESC_F_NEXT in
+by using multiple descriptors, and setting the VIRTQ_DESC_F_NEXT bit in
 Flags for all but the last available descriptor.
 
 \begin{lstlisting}
@@ -219,9 +219,9 @@ Note: all flags, including VIRTQ_DESC_F_AVAIL, VIRTQ_DESC_F_USED,
 VIRTQ_DESC_F_WRITE must be set/cleared correctly in all
 descriptors in the list, not just the first one.
 
-Device only writes out a single used descriptor for the whole
+The device only writes out a single used descriptor for the whole
 list. It then skips forward according to the number of
-descriptors in the list. Driver needs to keep track of the size
+descriptors in the list. The driver needs to keep track of the size
 of the list corresponding to each buffer ID, to be able to skip
 to where the next used descriptor is written by the device.
 
@@ -240,7 +240,7 @@ should be ignored by drivers.
 Some devices benefit by concurrently dispatching a large number
 of large requests. The VIRTIO_F_INDIRECT_DESC feature allows this. To increase
 ring capacity the driver can store a (read-only by the device) table of indirect
-descriptors anywhere in memory, and insert a descriptor in main
+descriptors anywhere in memory, and insert a descriptor in the main
 virtqueue (with \field{Flags} bit VIRTQ_DESC_F_INDIRECT on) that refers to
 a buffer element
 containing this indirect descriptor table; \field{addr} and \field{len}
@@ -262,9 +262,9 @@ struct pvirtq_indirect_descriptor_table {
 };
 \end{lstlisting}
 
-The first descriptor is located at start of the indirect
+The first descriptor is located at the start of the indirect
 descriptor table, additional indirect descriptors come
-immediately afterwards. \field{Flags} bit VIRTQ_DESC_F_WRITE is the
+immediately afterwards. The VIRTQ_DESC_F_WRITE \field{flags} bit is the
 only valid flag for descriptors in the indirect table. Others
 are reserved and are ignored by the device.
 Buffer ID is also reserved and is ignored by the device.
@@ -282,8 +282,8 @@ devices to notify the use of a batch of buffers to the driver by
 only writing out a single used descriptor with the Buffer ID
 corresponding to the last descriptor in the batch.
 
-Device then skips forward in the ring according to the size of
-the batch. Driver needs to look up the used Buffer ID and
+The device then skips forward in the ring according to the size of
+the batch. The driver needs to look up the used Buffer ID and
 calculate the batch size to be able to advance to where the next
 used descriptor will be written by the device.
 
@@ -312,13 +312,13 @@ in the ring.
 In many systems driver and device notifications involve
 significant overhead. To mitigate this overhead,
 each virtqueue includes two identical structures used for
-controlling notifications between device and driver.
+controlling notifications between the device and the driver.
 
-Driver Event Suppression structure is read-only by the
+The Driver Event Suppression structure is read-only by the
 device and controls the events sent by the device
 to the driver (e.g. interrupts).
 
-Device Event Suppression structure is read-only by
+The Device Event Suppression structure is read-only by
 the driver and controls the events sent by the driver
 to the device (e.g. IO).
 
@@ -352,9 +352,9 @@ matches this value and a descriptor is
 made available/used respectively.
 \end{description}
 
-After writing out some descriptors, both device and driver
+After writing out some descriptors, both the device and the driver
 are expected to consult the relevant structure to find out
-whether interrupt/notification should be sent.
+whether an interrupt/notification should be sent.
 
 \subsubsection{Structure Size and Alignment}
 \label{sec:Packed Virtqueues / Structure Size and Alignment}
@@ -385,7 +385,7 @@ part of the virtqueue.
 
 Queue Size corresponds to the maximum number of descriptors in the
 virtqueue\footnote{For example, if Queue Size is 4 then at most 4 buffers
-can be queued at any given time.}.  Queue Size value does not
+can be queued at any given time.}.  The Queue Size value does not
 have to be a power of 2 unless enforced by the transport.
 
 \drivernormative{\subsection}{Virtqueues}{Basic Facilities of a
@@ -400,7 +400,7 @@ The device MUST start processing driver descriptors in the order
 in which they appear in the ring.
 The device MUST start writing device descriptors into the ring in
 the order in which they complete.
-Device MAY reorder descriptor writes once they are started.
+The device MAY reorder descriptor writes once they are started.
 
 \subsection{The Virtqueue Descriptor Format}\label{sec:Basic
 Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue
@@ -449,16 +449,16 @@ struct pvirtq_event_suppress {
 A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT
 read a device-writable buffer.
 A device MUST NOT use a descriptor unless it observes
-VIRTQ_DESC_F_AVAIL bit in its \field{flags} being changed
+the VIRTQ_DESC_F_AVAIL bit in its \field{flags} being changed
 (e.g. as compared to the initial zero value).
 A device MUST NOT change a descriptor after changing it's
-VIRTQ_DESC_F_USED bit in its \field{flags}.
+the VIRTQ_DESC_F_USED bit in its \field{flags}.
 
 \drivernormative{\subsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / PAcked Virtqueues / The Virtqueue Descriptor Table}
 A driver MUST NOT change a descriptor unless it observes
-VIRTQ_DESC_F_USED bit in its \field{flags} being changed.
+the VIRTQ_DESC_F_USED bit in its \field{flags} being changed.
 A driver MUST NOT change a descriptor after changing
-VIRTQ_DESC_F_AVAIL bit in its \field{flags}.
+the VIRTQ_DESC_F_AVAIL bit in its \field{flags}.
 When notifying the device, driver MUST set
 \field{next_off} and
 \field{next_wrap} to match the next descriptor
@@ -549,8 +549,8 @@ For each buffer element, b:
 \item Calculate the flags as follows:
 \begin{enumerate}
 \item If b is device-writable, set the VIRTQ_DESC_F_WRITE bit to 1, otherwise 0
-\item Set VIRTQ_DESC_F_AVAIL bit to the current value of the Driver Ring Wrap Counter
-\item Set VIRTQ_DESC_F_USED bit to inverse value
+\item Set the VIRTQ_DESC_F_AVAIL bit to the current value of the Driver Ring Wrap Counter
+\item Set the VIRTQ_DESC_F_USED bit to inverse value
 \end{enumerate}
 \item Perform a memory barrier to ensure that the descriptor has
       been initialized