device-types/multiple: replace queues with enqueues

PATCH In review Parav Pandit 3 participants 6 messages Apr 11, 2023 – Apr 19, 2023

Share & tools

Parav Pandit

author

2023-04-11 20:05 UTC #0 lore raw

PATCH 1/1 device-types/multiple: replace queues with enqueues

Queue is a verb and noun both. Replacing it with enqueue avoids ambiguity around plural queues noun vs verb; similar to virtio fs device description.

Signed-off-by Parav Pandit <[email protected]>

---
 device-types/blk/description.tex   | 2 +-
 device-types/gpio/description.tex  | 4 ++--
 device-types/i2c/description.tex   | 2 +-
 device-types/scsi/description.tex  | 2 +-
 device-types/vsock/description.tex | 2 +-
 5 files changed, 6 insertions(+), 6 deletions(-)

device-types/blk/description.tex +1 -1

index 517b012..f04c932 100644
@@ -427,7 +427,7 @@ \subsubsection{Legacy Interface: Device Initialization}\label{sec:Device Types /
 
 \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Operation}
 
-The driver queues requests to the virtqueues, and they are used by
+The driver enqueues requests to the virtqueues, and they are used by
 the device (not necessarily in order). Each request except
 VIRTIO_BLK_T_ZONE_APPEND is of form:

device-types/gpio/description.tex +2 -2

index 8e5c7f0..d51fbe1 100644
@@ -358,7 +358,7 @@ \subsubsection{requestq Operation: Set IRQ Type}\label{sec:Device Types / GPIO D
 \subsubsection{requestq Operation: Message Flow}\label{sec:Device Types / GPIO Device / requestq Operation / Message Flow}
 
 \begin{itemize}
-\item The driver queues \field{struct virtio_gpio_request} and
+\item The driver enqueues \field{struct virtio_gpio_request} and
     \field{virtio_gpio_response} buffers to the \field{requestq} virtqueue,
     after filling all fields of the \field{struct virtio_gpio_request} buffer as
     defined by the specific message type.

@@ -458,7 +458,7 @@ \subsection{Device Operation: eventq}\label{sec:Device Types / GPIO Device / eve
 
 The \field{eventq} virtqueue is used by the driver to unmask the interrupts and
 used by the device to notify the driver of newly sensed interrupts. In order to
-unmask interrupt on a GPIO line, the driver queues a pair of buffers,
+unmask interrupt on a GPIO line, the driver enqueues a pair of buffers,
 \field{struct virtio_gpio_irq_request} (filled by driver) and \field{struct
 virtio_gpio_irq_response} (to be filled by device later), to the \field{eventq}
 virtqueue. A separate pair of buffers must be queued for each GPIO line, the

device-types/i2c/description.tex +1 -1

index 5d407cb..861529a 100644
@@ -47,7 +47,7 @@ \subsection{Device Operation}\label{sec:Device Types / I2C Adapter Device / Devi
 
 \subsubsection{Device Operation: Request Queue}\label{sec:Device Types / I2C Adapter Device / Device Operation: Request Queue}
 
-The driver queues requests to the virtqueue, and they are used by the
+The driver enqueues requests to the virtqueue, and they are used by the
 device. The request is the representation of segments of an I2C
 transaction. Each request is of the form:

device-types/scsi/description.tex +1 -1

index 904c4a7..478b558 100644
@@ -158,7 +158,7 @@ \subsection{Device Operation}\label{sec:Device Types / SCSI Host Device / Device
 
 \subsubsection{Device Operation: Request Queues}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues}
 
-The driver queues requests to an arbitrary request queue, and
+The driver enqueues requests to an arbitrary request queue, and
 they are used by the device on that same queue. It is the
 responsibility of the driver to ensure strict request ordering
 for commands placed on different queues, because they will be

device-types/vsock/description.tex +1 -1

index 105bb30..07909d6 100644
@@ -218,7 +218,7 @@ \subsubsection{Buffer Space Management}\label{sec:Device Types / Socket Device /
 \field{buf_alloc} and \field{fwd_cnt} fields.
 
 \subsubsection{Receive and Transmit}\label{sec:Device Types / Socket Device / Device Operation / Receive and Transmit}
-The driver queues outgoing packets on the tx virtqueue and incoming packet
+The driver enqueues outgoing packets on the tx virtqueue and incoming packet
 receive buffers on the rx virtqueue. Packets are of the following form:
 
 \begin{lstlisting}

Signature · 18 lines

2.26.2


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Parav Pandit

author

2023-04-19 01:54 UTC #1 lore raw

Quoted 9 lines

From: Parav Pandit <[email protected]>
Sent: Tuesday, April 11, 2023 4:04 PM
Queue is a verb and noun both. Replacing it with enqueue avoids ambiguity around plural queues noun vs verb; similar to virtio fs device description.
Suggested-by Michael S. Tsirkin <[email protected]>
Signed-off-by Parav Pandit <[email protected]>

Can you please take this reword change also forward?

---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]

Michael S. Tsirkin

Acked-by on v1 1/1

2023-04-19 07:17 UTC #2 lore raw

In reply to Parav Pandit

Quoted 5 lines · Parav Pandit

Queue is a verb and noun both. Replacing it with enqueue avoids ambiguity around plural queues noun vs verb; similar to virtio fs device description.
Suggested-by Michael S. Tsirkin <[email protected]>

Heh, kind of. but ok.

Quoted 1 line

Signed-off-by Parav Pandit <[email protected]>

Take this example:
-The driver queues requests to the virtqueues, and they are used by +The driver enqueues requests to the virtqueues, and they are used by clearly an improvement.

we could be more formal and switch to "adds" or even "makes available" but hey, small steps.

Acked-by Michael S. Tsirkin <[email protected]>

Cornelia I think this can go in directly. If you agree pls commit.

Quoted 84 lines

---
 device-types/blk/description.tex   | 2 +-
 device-types/gpio/description.tex  | 4 ++--
 device-types/i2c/description.tex   | 2 +-
 device-types/scsi/description.tex  | 2 +-
 device-types/vsock/description.tex | 2 +-
 5 files changed, 6 insertions(+), 6 deletions(-)

device-types/blk/description.tex +1 -1

index 517b012..f04c932 100644
@@ -427,7 +427,7 @@ \subsubsection{Legacy Interface: Device Initialization}\label{sec:Device Types /
 
 \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Operation}
 
-The driver queues requests to the virtqueues, and they are used by
+The driver enqueues requests to the virtqueues, and they are used by
 the device (not necessarily in order). Each request except
 VIRTIO_BLK_T_ZONE_APPEND is of form:

device-types/gpio/description.tex +2 -2

index 8e5c7f0..d51fbe1 100644
@@ -358,7 +358,7 @@ \subsubsection{requestq Operation: Set IRQ Type}\label{sec:Device Types / GPIO D
 \subsubsection{requestq Operation: Message Flow}\label{sec:Device Types / GPIO Device / requestq Operation / Message Flow}
 
 \begin{itemize}
-\item The driver queues \field{struct virtio_gpio_request} and
+\item The driver enqueues \field{struct virtio_gpio_request} and
     \field{virtio_gpio_response} buffers to the \field{requestq} virtqueue,
     after filling all fields of the \field{struct virtio_gpio_request} buffer as
     defined by the specific message type.

@@ -458,7 +458,7 @@ \subsection{Device Operation: eventq}\label{sec:Device Types / GPIO Device / eve
 
 The \field{eventq} virtqueue is used by the driver to unmask the interrupts and
 used by the device to notify the driver of newly sensed interrupts. In order to
-unmask interrupt on a GPIO line, the driver queues a pair of buffers,
+unmask interrupt on a GPIO line, the driver enqueues a pair of buffers,
 \field{struct virtio_gpio_irq_request} (filled by driver) and \field{struct
 virtio_gpio_irq_response} (to be filled by device later), to the \field{eventq}
 virtqueue. A separate pair of buffers must be queued for each GPIO line, the

device-types/i2c/description.tex +1 -1

index 5d407cb..861529a 100644
@@ -47,7 +47,7 @@ \subsection{Device Operation}\label{sec:Device Types / I2C Adapter Device / Devi
 
 \subsubsection{Device Operation: Request Queue}\label{sec:Device Types / I2C Adapter Device / Device Operation: Request Queue}
 
-The driver queues requests to the virtqueue, and they are used by the
+The driver enqueues requests to the virtqueue, and they are used by the
 device. The request is the representation of segments of an I2C
 transaction. Each request is of the form:

device-types/scsi/description.tex +1 -1

index 904c4a7..478b558 100644
@@ -158,7 +158,7 @@ \subsection{Device Operation}\label{sec:Device Types / SCSI Host Device / Device
 
 \subsubsection{Device Operation: Request Queues}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues}
 
-The driver queues requests to an arbitrary request queue, and
+The driver enqueues requests to an arbitrary request queue, and
 they are used by the device on that same queue. It is the
 responsibility of the driver to ensure strict request ordering
 for commands placed on different queues, because they will be

device-types/vsock/description.tex +1 -1

index 105bb30..07909d6 100644
@@ -218,7 +218,7 @@ \subsubsection{Buffer Space Management}\label{sec:Device Types / Socket Device /
 \field{buf_alloc} and \field{fwd_cnt} fields.
 
 \subsubsection{Receive and Transmit}\label{sec:Device Types / Socket Device / Device Operation / Receive and Transmit}
-The driver queues outgoing packets on the tx virtqueue and incoming packet
+The driver enqueues outgoing packets on the tx virtqueue and incoming packet
 receive buffers on the rx virtqueue. Packets are of the following form:
 
 \begin{lstlisting}

Signature · 1 line

2.26.2

This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Cornelia Huck

2023-04-19 13:33 UTC #3 lore raw

In reply to Parav Pandit

Quoted 3 lines · Parav Pandit

Queue is a verb and noun both. Replacing it with enqueue avoids ambiguity around plural queues noun vs verb; similar to virtio fs device description.

Personally, I don't think this patch adds much, but I don't really mind it, either.

Quoted 11 lines

Signed-off-by Parav Pandit <[email protected]>

---
 device-types/blk/description.tex   | 2 +-
 device-types/gpio/description.tex  | 4 ++--
 device-types/i2c/description.tex   | 2 +-
 device-types/scsi/description.tex  | 2 +-
 device-types/vsock/description.tex | 2 +-
 5 files changed, 6 insertions(+), 6 deletions(-)

(...)

device-types/vsock/description.tex \subsubsection{Buffer Space Management}\label{sec:Device Types / Socket Device / · line 221

Quoted 10 lines

device-types/vsock/description.tex +1 -1

index 105bb30..07909d6 100644
@@ -218,7 +218,7 @@ \subsubsection{Buffer Space Management}\label{sec:Device Types / Socket Device /
 \field{buf_alloc} and \field{fwd_cnt} fields.
 
 \subsubsection{Receive and Transmit}\label{sec:Device Types / Socket Device / Device Operation / Receive and Transmit}
-The driver queues outgoing packets on the tx virtqueue and incoming packet
+The driver enqueues outgoing packets on the tx virtqueue and incoming packet

"queues (...) on" reads natural to me, but I'd use "to" with "enqueues"... can any native speakers comment?

device-types/vsock/description.tex \subsubsection{Buffer Space Management}\label{sec:Device Types / Socket Device / · line 224

Quoted 3 lines

device-types/vsock/description.tex +0 -0

 receive buffers on the rx virtqueue. Packets are of the following form:
 
 \begin{lstlisting}

---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]

Parav Pandit

author

2023-04-19 13:35 UTC #4 lore raw

Quoted 35 lines

From: Cornelia Huck <[email protected]>
Sent: Wednesday, April 19, 2023 9:33 AM
Quoted 3 lines · Parav Pandit
Queue is a verb and noun both. Replacing it with enqueue avoids ambiguity around plural queues noun vs verb; similar to virtio fs device description.
Personally, I don't think this patch adds much, but I don't really mind it, either.
Quoted 11 lines
Suggested-by Michael S. Tsirkin <[email protected]>
Signed-off-by Parav Pandit <[email protected]>
---
 device-types/blk/description.tex   | 2 +-
 device-types/gpio/description.tex  | 4 ++--
 device-types/i2c/description.tex   | 2 +-
 device-types/scsi/description.tex  | 2 +-
device-types/vsock/description.tex | 2 +-
 5 files changed, 6 insertions(+), 6 deletions(-)
(...)
Quoted 7 lines
device-types/vsock/description.tex +0 -0
index 105bb30..07909d6 100644
@@ -218,7 +218,7 @@ \subsubsection{Buffer Space
Management}\label{sec:Device Types / Socket Device / \field{buf_alloc} and
\field{fwd_cnt} fields.
Quoted 1 line

Quoted 7 lines

device-types/vsock/description.tex
Quoted 5 lines
\subsubsection{Receive and Transmit}\label{sec:Device Types / Socket
Device / Device Operation / Receive and Transmit} -The driver queues outgoing packets on the tx virtqueue and incoming packet
device-types/vsock/description.tex +2 -0
+The driver enqueues outgoing packets on the tx virtqueue and incoming
+packet
"queues (...) on" reads natural to me, but I'd use "to" with "enqueues"...

Yes, I agree.
The driver enqueues outgoing packets to the tx virtqueue reads better to me.

Quoted 6 lines

can any
native speakers comment?
Quoted 3 lines
receive buffers on the rx virtqueue. Packets are of the following form:
\begin{lstlisting}

This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.

Michael S. Tsirkin

2023-04-19 16:15 UTC #5 lore raw

Quoted 42 lines · Parav Pandit

Quoted 35 lines
From: Cornelia Huck <[email protected]>
Sent: Wednesday, April 19, 2023 9:33 AM
Quoted 3 lines · Parav Pandit
Queue is a verb and noun both. Replacing it with enqueue avoids ambiguity around plural queues noun vs verb; similar to virtio fs device description.
Personally, I don't think this patch adds much, but I don't really mind it, either.
Quoted 11 lines
Suggested-by Michael S. Tsirkin <[email protected]>
Signed-off-by Parav Pandit <[email protected]>
---
 device-types/blk/description.tex   | 2 +-
 device-types/gpio/description.tex  | 4 ++--
 device-types/i2c/description.tex   | 2 +-
 device-types/scsi/description.tex  | 2 +-
device-types/vsock/description.tex | 2 +-
 5 files changed, 6 insertions(+), 6 deletions(-)
(...)
Quoted 7 lines
device-types/vsock/description.tex +0 -0
index 105bb30..07909d6 100644
@@ -218,7 +218,7 @@ \subsubsection{Buffer Space
Management}\label{sec:Device Types / Socket Device / \field{buf_alloc} and
\field{fwd_cnt} fields.
Quoted 1 line
Quoted 7 lines
device-types/vsock/description.tex
Quoted 5 lines
\subsubsection{Receive and Transmit}\label{sec:Device Types / Socket
Device / Device Operation / Receive and Transmit} -The driver queues outgoing packets on the tx virtqueue and incoming packet
device-types/vsock/description.tex +2 -0
+The driver enqueues outgoing packets on the tx virtqueue and incoming
+packet
"queues (...) on" reads natural to me, but I'd use "to" with "enqueues"...

Quoted 2 lines

Yes, I agree.
The driver enqueues outgoing packets to the tx virtqueue reads better to me.

Quoted 6 lines

Quoted 6 lines
can any
native speakers comment?
Quoted 3 lines
receive buffers on the rx virtqueue. Packets are of the following form:
\begin{lstlisting}

---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]