Skip to content

Commit 9e7fb5a

Browse files
committed
virtio-msg: eliminate non-ascii characters
Smart quotes and em-dashes snuck into the doc. Upstream seems to only use ASCII so eliminate these. Signed-off-by: Bill Mills <bill.mills@linaro.org>
1 parent 8ca7557 commit 9e7fb5a

1 file changed

Lines changed: 29 additions & 29 deletions

File tree

transport-msg.tex

Lines changed: 29 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ \subsubsection{High-Level Architecture}
5151
firmware calls),
5252
\item Dynamic hotplug notifications (optionally via \busref{EVENT_DEVICE}).
5353
\end{itemize}
54-
Once a device is identifiedregardless of discovery methodthe bus typically
54+
Once a device is identified, regardless of discovery method, the bus typically
5555
uses \msgref{GET_DEVICE_INFO} to read its device ID and vendor ID, then
5656
\emph{registers} that device with the host OS so the usual virtio driver
5757
probe can occur.
@@ -122,7 +122,7 @@ \subsubsection{Transport Revisions and Maximum Message Size}
122122
\end{itemize}
123123

124124
These parameters \emph{MAY} vary between bus instances within the same system.
125-
The driver obtains a buss revision, maximum message size and list of features
125+
The driver obtains a bus's revision, maximum message size and list of features
126126
through an \emph{implementation-defined} mechanism, which could be:
127127
\begin{itemize}
128128
\item A device tree or firmware method providing bus configuration,
@@ -134,7 +134,7 @@ \subsubsection{Transport Revisions and Maximum Message Size}
134134
After learning these parameters, the driver \emph{MUST} respect them for all
135135
messages involving that bus instance. For example, it \emph{MUST NOT} send a
136136
message exceeding the \textbf{maximum message size}, and it \emph{MUST} avoid
137-
using advanced features or messages unavailable in the buss advertised
137+
using advanced features or messages unavailable in the bus's advertised
138138
\textbf{transport revision}.
139139

140140
\paragraph{virtio-msg revisions}
@@ -174,7 +174,7 @@ \subsubsection{Device Numbers and Enumeration}
174174
\end{itemize}
175175

176176
Once a bus confirms that a given device number is valid (regardless of the method),
177-
it typically issues \msgref{GET_DEVICE_INFO} to retrieve the devices Device ID
177+
it typically issues \msgref{GET_DEVICE_INFO} to retrieve the device's Device ID
178178
and vendor ID. The bus can then register the device with the host OS to initiate
179179
the usual Virtio driver binding process.
180180

@@ -197,7 +197,7 @@ \subsubsection{Configuration Generation Count}
197197
necessarily start at 0 and \emph{SHOULD NOT} reset to 0 on device reset.
198198

199199
\begin{itemize}
200-
\item If the drivers generation count does not match the devices current
200+
\item If the driver's generation count does not match the device's current
201201
count, the \msgref{SET_CONFIG} request \emph{MUST} be rejected by the
202202
device.
203203
\item The driver may have received \msgref{EVENT_CONFIG} messages
@@ -222,7 +222,7 @@ \subsubsection{Feature Negotiation Blocks}
222222
features 0--31, block 1 for features 32--63, etc.).
223223
\item \textbf{Number of Blocks}: How many blocks the driver wishes to retrieve
224224
or modify in a single message.
225-
\item \textbf{Feature Data}: The 32 bits values representing a devices
225+
\item \textbf{Feature Data}: The 32 bits values representing a device's
226226
supported or requested feature bits.
227227
\end{itemize}
228228

@@ -406,8 +406,8 @@ \subsubsection{Interaction with Transport Messages}
406406
\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Interaction with Transport}
407407

408408
The bus is also responsible for forwarding device-specific \emph{transport
409-
messages} to the correct device for each device number. Typically, the bus does
410-
not interpret or modify these transport messagesits role is simply to ensure
409+
messages} to the correct device for each device number. Typically the bus does
410+
not interpret or modify these transport messages; its role is simply to ensure
411411
they reach the intended device. If the bus does not rely on messages for device
412412
enumeration or hotplug itself, it \emph{MUST} still be capable of transporting
413413
\msgref{GET_DEVICE_INFO}, \msgref{GET_DEVICE_FEATURES}, \msgref{SET_CONFIG}, etc.
@@ -428,30 +428,30 @@ \subsubsection{Initialization Flow Overview}
428428
A typical device initialization flow includes:
429429
\begin{enumerate}
430430
\item \textbf{Obtain Device Information:}
431-
The driver queries the devices Device ID, vendor ID, feature block count,
431+
The driver queries the device's Device ID, vendor ID, feature block count,
432432
configuration size, and other static parameters of the device using
433433
\msgref{GET_DEVICE_INFO}.
434434
\item \textbf{Negotiate Features:}
435-
The driver retrieves the devices feature bits (\msgref{GET_DEVICE_FEATURES}),
435+
The driver retrieves the device's feature bits (\msgref{GET_DEVICE_FEATURES}),
436436
determines which features it wants to enable, and writes the desired set
437437
with (\msgref{SET_DRIVER_FEATURES}). It then attempts to set the
438438
FEATURES_OK bit in the device status (\msgref{SET_DEVICE_STATUS}) and
439439
verifies that it is set in the return device status.
440440
\item \textbf{Initialize Configuration Space:}
441441
The driver may read (\msgref{GET_CONFIG}) or modify (\msgref{SET_CONFIG})
442-
configuration data, using the devices \emph{Configuration Generation Count}
442+
configuration data, using the device's \emph{Configuration Generation Count}
443443
to prevent race conditions.
444444
\item \textbf{Set Up Virtqueues:}
445445
The driver configures each virtqueue (e.g., number of descriptors, base
446-
addresses) via \msgref{SET_VQUEUE} and verifies each queues readiness
446+
addresses) via \msgref{SET_VQUEUE} and verifies each queue's readiness
447447
(\msgref{GET_VQUEUE}).
448448
\item \textbf{Set Device Status:}
449-
The driver updates the devices status with \msgref{SET_DEVICE_STATUS} to
450-
indicate initialization progress (e.g., from reset to acknowledge,
451-
driver, or driver OK, following Virtio conventions).
449+
The driver updates the device's status with \msgref{SET_DEVICE_STATUS} to
450+
indicate initialization progress (e.g., from "reset" to "acknowledge,"
451+
"driver," or "driver OK," following Virtio conventions).
452452
\end{enumerate}
453453

454-
This sequence may vary slightly depending on the devices requirements, but it
454+
This sequence may vary slightly depending on the device's requirements, but it
455455
serves as a common baseline for virtio-msg transport implementations.
456456

457457
\subsubsection{Device Information}
@@ -466,7 +466,7 @@ \subsubsection{Device Information}
466466
\item \textbf{Vendor ID}: Identifies the vendor or implementation source.
467467
\item \textbf{Number of Feature Bits}: Indicates how many bits (organized in
468468
32-bit blocks) the device uses for feature negotiation.
469-
\item \textbf{Configuration Size}: The total size (in bytes) of the devices
469+
\item \textbf{Configuration Size}: The total size (in bytes) of the device's
470470
configuration space.
471471
\item \textbf{Number of virtqueues}: The maximum number of virtqueues the
472472
device supports.
@@ -488,7 +488,7 @@ \subsubsection{Device Information}
488488
\subsubsection{Feature Negotiation}
489489
\label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features}
490490

491-
The driver reads the devices available features in \textbf{blocks of 32 bits}
491+
The driver reads the device's available features in \textbf{blocks of 32 bits}
492492
using \msgref{GET_DEVICE_FEATURES}, supplying a \emph{block index} and
493493
\emph{number of blocks} to retrieve. The device responds with the feature bits
494494
in that range, filling any out-of-range blocks with zero.
@@ -510,7 +510,7 @@ \subsubsection{Device Configuration}
510510

511511
\paragraph{Reading Configuration}
512512

513-
The driver can read portions of the devices configuration space using
513+
The driver can read portions of the device's configuration space using
514514
\msgref{GET_CONFIG}. It supplies:
515515
\begin{itemize}
516516
\item \textbf{Offset}: The byte offset from the start of the configuration
@@ -531,7 +531,7 @@ \subsubsection{Device Configuration}
531531
\item The \textbf{new configuration data} to be written.
532532
\end{itemize}
533533

534-
If the generation count does not match the devices current value, the device
534+
If the generation count does not match the device's current value, the device
535535
\emph{MUST} reject the update as defined in the \msgref{SET_CONFIG} response.
536536
The driver \emph{SHOULD} then read the updated configuration space and
537537
reattempt if necessary.
@@ -566,18 +566,18 @@ \subsubsection{Virtqueue Configuration}
566566
\subsubsection{Status Information}
567567
\label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information}
568568

569-
During initialization, the driver \emph{MAY} query the devices status via
569+
During initialization, the driver \emph{MAY} query the device's status via
570570
\msgref{GET_DEVICE_STATUS} to check for errors or to see if the device is ready
571571
for feature negotiation or configuration changes. To advance or reset the
572-
devices state, the driver sends \msgref{SET_DEVICE_STATUS} with the desired
573-
status bits (e.g., ACKNOWLEDGE,” “DRIVER,” “DRIVER OK). Setting the devices
572+
device's state, the driver sends \msgref{SET_DEVICE_STATUS} with the desired
573+
status bits (e.g., "ACKNOWLEDGE," "DRIVER," "DRIVER OK"). Setting the device's
574574
status to 0 triggers a device reset, invalidating configuration and
575575
virtqueues.
576576

577577
\subsubsection{Finalizing Initialization}
578578

579579
Once all virtqueues are configured and any required features have been enabled,
580-
the driver typically sets the final status bits (e.g., DRIVER OK) via
580+
the driver typically sets the final status bits (e.g., "DRIVER OK") via
581581
\msgref{SET_DEVICE_STATUS}. At this point, the device is considered fully
582582
initialized, and normal I/O operations can begin using virtio queues.
583583

@@ -651,7 +651,7 @@ \subsubsection{Device Notifications}
651651
\begin{itemize}
652652
\item Signifies that one or more buffers in a specific virtqueue have been
653653
processed or consumed by the device.
654-
\item The driver uses normal virtio methods (e.g., reading the used ring) to
654+
\item The driver uses normal virtio methods (e.g., reading the "used" ring) to
655655
identify which buffers are complete.
656656
\item If a device does not support sending \msgref{EVENT_USED}, the driver
657657
\emph{MAY} rely on standard virtqueue polling mechanisms to detect
@@ -1250,9 +1250,9 @@ \subsubsection{Mandatory Requirements}
12501250
and \msgref{SET_CONFIG}.
12511251
\item A driver \emph{MUST} handle a \msgref{SET_CONFIG} being rejected for a
12521252
mismatched configuration generation count.
1253-
\item A driver \textbf{MUST} initialize each devices virtqueues (where needed)
1253+
\item A driver \textbf{MUST} initialize each device's virtqueues (where needed)
12541254
via \msgref{SET_VQUEUE} before attempting normal I/O and \textbf{SHOULD}
1255-
query the devices status or configuration if an unexpected
1255+
query the device's status or configuration if an unexpected
12561256
\msgref{EVENT_CONFIG} or error arises.
12571257
\end{itemize}
12581258

@@ -1327,7 +1327,7 @@ \subsubsection{Compliance for Different Environments}
13271327
\subsubsection{Conformance Statements}
13281328
\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / Conformance}
13291329

1330-
An implementation \textbf{MUST} meet all MUST requirements stated in:
1330+
An implementation \textbf{MUST} meet all "MUST" requirements stated in:
13311331
\begin{itemize}
13321332
\item \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts} (Basic Concepts)
13331333
\item \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation} (Bus Operation)
@@ -1338,7 +1338,7 @@ \subsubsection{Conformance Statements}
13381338
to claim compliance with the virtio-msg specification.
13391339

13401340
Implementations that do not follow these mandatory rules \emph{MUST NOT} declare
1341-
themselves conformant. Features or messages labeled as optional (\emph{MAY})
1341+
themselves conformant. Features or messages labeled as "optional" (\emph{MAY})
13421342
do not invalidate compliance if omitted, provided all required behaviors are
13431343
still correctly implemented.
13441344

0 commit comments

Comments
 (0)