Skip to contentSkip to conversation

admin: Fix requirements wording inconsistencies

PATCH Superseded Peter Hilber 2 participants 6 messages May 22, 2024 – Jun 5, 2024

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

v2 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.

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 | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

base-commit: 71fe8e907c9d20c53e8327bea99360cb3c529ade

Signature · 1 line
2.43.0
#1 lore raw

PATCH v2 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 queues".

Fixes bf1d6b0d24ae8 ("admin: conformance clauses")

---

Notes:
v2:

Be specific about case without order constraints (Parav Pandit).

 admin.tex | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
admin.tex +2 -1
index 0803c269e5c4..fdbf2ac5a93b 100644
@@ -457,7 +457,8 @@ \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
+strict request ordering for commands placed on different
+queues, 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
 first command by the device to be completed before submitting
Signature · 1 line
2.43.0
#2 lore raw

Re: [PATCH v2 1/2] admin: Refer to "no order constraints" only for different queues

Quoted 35 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 queues".

Fixes bf1d6b0d24ae8 ("admin: conformance clauses")

---

Notes:
v2:

Be specific about case without order constraints (Parav Pandit).

admin.tex | 3 ++-

1 file changed, 2 insertions(+), 1 deletion(-)
admin.tex +0 -0
index 0803c269e5c4..fdbf2ac5a93b 100644
@@ -457,7 +457,8 @@ \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

admin.tex \section{Administration Virtqueues}\label{sec:Basic Facilities of a Virtio Devic · line 461

Quoted 3 lines
admin.tex +2 -1
-strict request ordering for commands, because they will be
+strict request ordering for commands placed on different
+queues, because they will be

Should we use "virtqueues" instead of "queues" since we use it throughout the paragraph?

However, out of curiosity, how would the device impose an order to commands on different virtqueues?

I'm a little confused. Also, the example we have next doesn't talk about different virtqueues, so I don't know if we should modify it as well.

Thanks,
Stefano

Quoted 7 lines

consumed with no order constraints. For example, if consistency is required then the driver can wait for the processing of a first command by the device to be completed before submitting

Signature · 1 line
2.43.0
#3 lore raw

Re: [PATCH v2 1/2] admin: Refer to "no order constraints" only for different queues

Quoted 28 lines · Stefano Garzarella
Quoted 27 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 queues".

Fixes bf1d6b0d24ae8 ("admin: conformance clauses")

---

Notes:
   v2:

   Be specific about case without order constraints (Parav Pandit).

admin.tex | 3 ++-

1 file changed, 2 insertions(+), 1 deletion(-)
Quoted 13 lines

admin.tex \section{Administration Virtqueues}\label{sec:Basic Facilities of a Virtio Devic · line 461

Quoted 11 lines
admin.tex +0 -0
index 0803c269e5c4..fdbf2ac5a93b 100644
@@ -457,7 +457,8 @@ \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

admin.tex +2 -1
-strict request ordering for commands, because they will be
+strict request ordering for commands placed on different
+queues, because they will be

Should we use "virtqueues" instead of "queues" since we use it throughout the paragraph?

I will change "queues" to "virtqueues".

Quoted 2 lines

However, out of curiosity, how would the device impose an order to commands on different virtqueues?

I don't know.

Quoted 2 lines

I'm a little confused. Also, the example we have next doesn't talk about different virtqueues, so I don't know if we should modify it as well.

I will narrow down the example to refer to different virtqueues.

Thanks for the review,

Peter

Quoted 12 lines

Thanks,
Stefano

Quoted 7 lines

consumed with no order constraints.  For example, if consistency is required then the driver can wait for the processing of a first command by the device to be completed before submitting --
2.43.0

#4 lore raw

PATCH v2 2/2 admin: Fix driver requirement subject

In reply to Peter Hilber

The 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.

Fixes bf1d6b0d24ae8 ("admin: conformance clauses")
---
 admin.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
admin.tex +1 -1
index fdbf2ac5a93b..3fc732b153e0 100644
@@ -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
Reviewed-by on v2 2/2
#5 lore raw

Re: [PATCH v2 2/2] admin: Fix driver requirement subject

Quoted 4 lines · Peter Hilber

The driver-normative section for Group administration commands contains a requirement on the *device*. This requirement only makes sense as a requirement on the driver.

Quoted 8 lines

Fix this by making the driver the requirement subject.

Fixes bf1d6b0d24ae8 ("admin: conformance clauses")

---
admin.tex | 2 +-

1 file changed, 1 insertion(+), 1 deletion(-)

LGTM:

Quoted 18 lines
admin.tex +0 -0
index fdbf2ac5a93b..3fc732b153e0 100644
@@ -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.

admin.tex +1 -1
-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