admin: Fix requirements wording inconsistencies
v3 cover admin: Fix requirements wording inconsistencies
I stumbled over some inconsistencies in the administration virtqueue requirements wording. These patches should fix them.
I think they could be considered editorial fixes.
v3:
- Refer to "virtqueue" as such (Stefano Garzarella).
- Narrow down example to have different virtqueues (Stefano Garzarella).
v2:
- Be specific about case without order constraints (Parav Pandit).
Peter Hilber (2):
admin: Refer to "no order constraints" only for different queues
admin: Fix driver requirement subject
admin.tex | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-)
base-commit: 71fe8e907c9d20c53e8327bea99360cb3c529ade
Signature · 1 line
2.43.0
PATCH v3 1/2 admin: Refer to "no order constraints" only for different queues
The non-normative section says that administration virtqueue commands "will be consumed with no order constraints". But actually, the requirements stipulate a total order for all commands in the same virtqueue:
The device MUST process commands on a given administration virtqueue in the order in which they are queued.
If multiple administration virtqueues have been configured, device MAY process commands on distinct virtqueues with no order constraints.
Fix this by narrowing down the scope of the sentence to "commands placed on different virtqueues". Also, narrow down the following example to one with different virtqueues, and reword the example to better fit the narrowed sense.
---
Notes:
v3:
- Refer to "virtqueue" as such (Stefano Garzarella).
- Narrow down example to have different virtqueues (Stefano Garzarella).
v2:
Be specific about case without order constraints (Parav Pandit).
admin.tex | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-)
admin.tex +5 -4
@@ -457,11 +457,12 @@ \section{Administration Virtqueues}\label{sec:Basic Facilities of a Virtio Devic The driver enqueues requests to an arbitrary administration virtqueue, and they are used by the device on that same virtqueue. It is the responsibility of the driver to ensure -strict request ordering for commands, because they will be -consumed with no order constraints. For example, if consistency -is required then the driver can wait for the processing of a +strict request ordering for commands placed on different +virtqueues, because they will be +consumed with no order constraints. For example, +the driver must wait for the processing of a first command by the device to be completed before submitting -another command depending on the first one. +another command depending on the first one to a different virtqueue. Administration virtqueues are used as follows: \begin{itemize}
Signature · 1 line
2.43.0
Re: [PATCH v3 1/2] admin: Refer to "no order constraints" only for different queues
Quoted 26 lines · Peter Hilber
The non-normative section says that administration virtqueue commands "will be consumed with no order constraints". But actually, the requirements stipulate a total order for all commands in the same virtqueue:
The device MUST process commands on a given administration virtqueue in the order in which they are queued.
If multiple administration virtqueues have been configured, device MAY process commands on distinct virtqueues with no order constraints.
Fix this by narrowing down the scope of the sentence to "commands placed on different virtqueues". Also, narrow down the following example to one with different virtqueues, and reword the example to better fit the narrowed sense.
Fixes bf1d6b0d24ae8 ("admin: conformance clauses")Signed-off-by Peter Hilber <[email protected]>---
Notes:
v3:- Refer to "virtqueue" as such (Stefano Garzarella).
Quoted 8 lines
- Narrow down example to have different virtqueues (Stefano Garzarella).
v2:
Be specific about case without order constraints (Parav Pandit).
admin.tex | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
LGTM!
Quoted 25 lines
admin.tex +0
-0@@ -457,11 +457,12 @@ \section{Administration Virtqueues}\label{sec:Basic Facilities of a Virtio DevicThe driver enqueues requests to an arbitrary administration virtqueue, and they are used by the device on that same virtqueue. It is the responsibility of the driver to ensure
admin.tex +4
-3-strict request ordering for commands, because they will be -consumed with no order constraints. For example, if consistency -is required then the driver can wait for the processing of a +strict request ordering for commands placed on different +virtqueues, because they will be +consumed with no order constraints. For example, +the driver must wait for the processing of afirst command by the device to be completed before submitting
admin.tex +1
-1-another command depending on the first one. +another command depending on the first one to a different virtqueue.Administration virtqueues are used as follows:
\begin{itemize}Signature · 1 line
2.43.0
PATCH v3 2/2 admin: Fix driver requirement subject
In reply to Peter HilberThe driver-normative section for Group administration commands contains a requirement on the *device*. This requirement only makes sense as a requirement on the driver.
Fix this by making the driver the requirement subject.
--- admin.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
admin.tex +1 -1
@@ -583,7 +583,7 @@ \section{Administration Virtqueues}\label{sec:Basic Facilities of a Virtio Devic of \field{struct virtio_admin_cmd} that are a multiple of 64 bit in length. -The device MUST supply both device-readable or device-writeable parts +The driver MUST supply both device-readable or device-writeable parts of \field{struct virtio_admin_cmd} that are larger than zero in length. However, \field{command_specific_data} and \field{command_specific_result} MAY be zero in length, unless
Signature · 1 line
2.43.0