Skip to contentSkip to conversation

transport-pci: msix register desc improve

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

lore
Share & tools
lore
#0 lore raw

cover transport-pci: msix register desc improve

Problem:

Current wording queue_msix_vector and config_msix_vector says "for MSI-X", which is bit confusing.

config_msix_vector and queue_msix_vector are the msix vector number for configuration change and queue related interrupts.

Hence, reword it.

---
changelog:
v0->v1:
- added 'here'
- dropped 'receiving'
- dropped already merged patch for empty line

Parav Pandit (2):
transport-pci: Improve config msix vector description
transport-pci: Improve queue msix vector register desc

 transport-pci.tex | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
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/
#1 lore raw

PATCH 1/2 transport-pci: Improve config msix vector description

config_msix_vector is the register that holds the MSI-X vector number for receiving configuration change related interrupts.

It is not "for MSI-X".

Hence, replace the confusing text with appropriate one.

---
changelog:
v0->v1:
- added 'here'
- dropped 'receiving'

---
 transport-pci.tex | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
transport-pci.tex +2 -1
index 42be072..cb9fadd 100644
@@ -343,7 +343,8 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
         Driver Feature Bits selected by \field{driver_feature_select}.
 
 \item[\field{config_msix_vector}]
-        The driver sets the Configuration Vector for MSI-X.
+        The driver writes an MSI-X vector number here for Configuration change
+        interrupts.
 
 \item[\field{num_queues}]
         The device specifies the maximum number of virtqueues supported here.
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/
#2 lore raw

[virtio-comment] Re: [PATCH 1/2] transport-pci: Improve config msix vector description

Quoted 24 lines · Parav Pandit

config_msix_vector is the register that holds the MSI-X vector number for receiving configuration change related interrupts.

It is not "for MSI-X".

Hence, replace the confusing text with appropriate one.

---
changelog:
v0->v1:
- added 'here'
- dropped 'receiving'

---
 transport-pci.tex | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
transport-pci.tex +0 -0
index 42be072..cb9fadd 100644

transport-pci.tex \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport · line 347

Quoted 6 lines
transport-pci.tex +2 -1
@@ -343,7 +343,8 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
         Driver Feature Bits selected by \field{driver_feature_select}.
 
 \item[\field{config_msix_vector}]
-        The driver sets the Configuration Vector for MSI-X.
+        The driver writes an MSI-X vector number here for Configuration change
+        interrupts.

Hmm I think it's "the vector", not an. And the order of words is unusual. We also don't normally use "writes here". Would

Used by the driver to set the MSI-X vector number for Configuration change interrupts.

be equally acceptable?

Quoted 4 lines
transport-pci.tex +0 -0
 \item[\field{num_queues}]
         The device specifies the maximum number of virtqueues supported here.
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/

#3 lore raw

[virtio-comment] Re: [PATCH 1/2] transport-pci: Improve config msix vector description

Quoted 35 lines · Michael S. Tsirkin
Quoted 24 lines · Parav Pandit

config_msix_vector is the register that holds the MSI-X vector number for receiving configuration change related interrupts.

It is not "for MSI-X".

Hence, replace the confusing text with appropriate one.

---
changelog:
v0->v1:
- added 'here'
- dropped 'receiving'

---
 transport-pci.tex | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
transport-pci.tex +0 -0
index 42be072..cb9fadd 100644

transport-pci.tex \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport · line 347

Quoted 6 lines
transport-pci.tex +2 -1
@@ -343,7 +343,8 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
         Driver Feature Bits selected by \field{driver_feature_select}.
 
 \item[\field{config_msix_vector}]
-        The driver sets the Configuration Vector for MSI-X.
+        The driver writes an MSI-X vector number here for Configuration change
+        interrupts.

Hmm I think it's "the vector", not an. And the order of words is unusual. We also don't normally use "writes here". Would

Quoted 1 line

Used by the driver to set the MSI-X vector number for Configuration change interrupts.

or even Configuration change notification interrupts

this is what we call them elsewhere

Quoted 7 lines

be equally acceptable?

Quoted 4 lines
transport-pci.tex +0 -0
 \item[\field{num_queues}]
         The device specifies the maximum number of virtqueues supported here.
Signature · 1 line
2.26.2

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

#4 lore raw

[virtio-comment] Re: [virtio-dev] Re: [PATCH 1/2] transport-pci: Improve config msix vector description

In reply to Michael S. Tsirkin
Quoted 34 lines · Michael S. Tsirkin
Quoted 24 lines · Parav Pandit

config_msix_vector is the register that holds the MSI-X vector number for receiving configuration change related interrupts.

It is not "for MSI-X".

Hence, replace the confusing text with appropriate one.

---
changelog:
v0->v1:
- added 'here'
- dropped 'receiving'

---
  transport-pci.tex | 3 ++-
  1 file changed, 2 insertions(+), 1 deletion(-)
transport-pci.tex +0 -0
index 42be072..cb9fadd 100644

transport-pci.tex \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport · line 347

Quoted 6 lines
transport-pci.tex +2 -1
@@ -343,7 +343,8 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
          Driver Feature Bits selected by \field{driver_feature_select}.
 
  \item[\field{config_msix_vector}]
-        The driver sets the Configuration Vector for MSI-X.
+        The driver writes an MSI-X vector number here for Configuration change
+        interrupts.

Hmm I think it's "the vector", not an. And the order of words is unusual. We also don't normally use "writes here". Would

Quoted 3 lines

Used by the driver to set the MSI-X vector number for Configuration change interrupts.

be equally acceptable?

Is it better also explain what is a MSI-X vector number here? Like saying the offset in the table or the slot number?

Thanks,
Zhu Lingshan

Quoted 11 lines
Quoted 6 lines
transport-pci.tex +0 -0
  \item[\field{num_queues}]
          The device specifies the maximum number of virtqueues supported here.
Signature · 1 line
2.26.2

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

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/

#5 lore raw

[virtio-comment] Re: [virtio-dev] Re: [PATCH 1/2] transport-pci: Improve config msix vector description

Quoted 36 lines · Lingshan
Quoted 33 lines · Michael S. Tsirkin
Quoted 24 lines · Parav Pandit

config_msix_vector is the register that holds the MSI-X vector number for receiving configuration change related interrupts.

It is not "for MSI-X".

Hence, replace the confusing text with appropriate one.

---
changelog:
v0->v1:
- added 'here'
- dropped 'receiving'

---
  transport-pci.tex | 3 ++-
  1 file changed, 2 insertions(+), 1 deletion(-)
transport-pci.tex +0 -0
index 42be072..cb9fadd 100644

transport-pci.tex \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport · line 346

Quoted 5 lines
transport-pci.tex +2 -1
@@ -343,7 +343,8 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
          Driver Feature Bits selected by \field{driver_feature_select}.
  \item[\field{config_msix_vector}]
-        The driver sets the Configuration Vector for MSI-X.
+        The driver writes an MSI-X vector number here for Configuration change
+        interrupts.

Hmm I think it's "the vector", not an. And the order of words is unusual. We also don't normally use "writes here". Would

Quoted 8 lines
Quoted 3 lines

Used by the driver to set the MSI-X vector number for Configuration change interrupts.

be equally acceptable?

Is it better also explain what is a MSI-X vector number here? Like saying the offset in the table or the slot number?

Thanks,
Zhu Lingshan

It does, in fact, refer to the MSI-X entry. Vector is in fact the
contents of the entry. The mixup between vector and entry dates back to
PCI spec which has text like
While more accurately termed “per-entry masking”, masking an MSI-X Table entry is still referred to as “vector masking” so similar descriptions can be used for both MSI and MSI- X.

Quoted 11 lines
Quoted 11 lines
Quoted 6 lines
transport-pci.tex +0 -0
  \item[\field{num_queues}]
          The device specifies the maximum number of virtqueues supported here.
Signature · 1 line
2.26.2

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

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

#6 lore raw

[virtio-comment] RE: [virtio-dev] Re: [PATCH 1/2] transport-pci: Improve config msix vector description

Quoted 7 lines

From: Michael S. Tsirkin <[email protected]>
Sent: Wednesday, April 19, 2023 7:27 AM

On Wed, Apr 19, 2023 at 04:25:13PM +0800, Zhu, Lingshan wrote:

Quoted 9 lines
Quoted 1 line
Quoted 1 line
Quoted 1 line

+ The driver writes an MSI-X vector number here for Configuration

change

Quoted 5 lines
Quoted 5 lines
Quoted 1 line

+ interrupts.

Hmm I think it's "the vector", not an. And the order of words is unusual. We also don't normally use "writes here". Would

Used by the driver to set the MSI-X vector number for Configuration

change interrupts.

Quoted 1 line
Quoted 1 line

To keep the text consistent with rest of the fields and to address below comment about MSI-X table entry reference,

As:
The driver writes the MSI-X table entry index in this field for Configuration change notification interrupts.

Similar to,
The driver writes this to accept feature bits offered by ...

#7 lore raw

PATCH 2/2 transport-pci: Improve queue msix vector register desc

In reply to Parav Pandit

queue_msix_vector register is for receiving interrupts from the device for the virtqueue.

"for MSI-X" is confusing term.

Also it is the register that driver "writes" to, similar to many other registers such as queue_desc, queue_driver etc.

Hence, replace the verb from use to write.

---
changelog:
v0->v1:
- added 'here'
- dropped 'receiving'

---
 transport-pci.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
transport-pci.tex +1 -1
index cb9fadd..00669b5 100644
@@ -367,7 +367,7 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
         A 0 means the queue is unavailable.
 
 \item[\field{queue_msix_vector}]
-        The driver uses this to specify the queue vector for MSI-X.
+        The driver writes an MSI-X vector number here for virtqueue interrupts.
 
 \item[\field{queue_enable}]
         The driver uses this to selectively prevent the device from executing requests from this virtqueue.
Signature · 6 lines
2.26.2


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
#8 lore raw

[virtio-comment] Re: [PATCH 2/2] transport-pci: Improve queue msix vector register desc

Quoted 26 lines · Parav Pandit

queue_msix_vector register is for receiving interrupts from the device for the virtqueue.

"for MSI-X" is confusing term.

Also it is the register that driver "writes" to, similar to many other registers such as queue_desc, queue_driver etc.

Hence, replace the verb from use to write.

---
changelog:
v0->v1:
- added 'here'
- dropped 'receiving'

---
 transport-pci.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
transport-pci.tex +0 -0
index cb9fadd..00669b5 100644

transport-pci.tex \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport · line 370

Quoted 5 lines
transport-pci.tex +1 -1
@@ -367,7 +367,7 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
         A 0 means the queue is unavailable.
 
 \item[\field{queue_msix_vector}]
-        The driver uses this to specify the queue vector for MSI-X.
+        The driver writes an MSI-X vector number here for virtqueue interrupts.

Here it's *the* specific queue not just some queue. And in fact we call them virtqueue notifications, not interrupts elsewhere. So how about:

Used by the driver to set the MSI-X vector number for the virtqueue notifications.

Quoted 4 lines
transport-pci.tex +0 -0
 \item[\field{queue_enable}]
         The driver uses this to selectively prevent the device from executing requests from this virtqueue.
Signature · 1 line
2.26.2

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

#9 lore raw

[virtio-comment] Re: [PATCH 2/2] transport-pci: Improve queue msix vector register desc

Quoted 37 lines · Michael S. Tsirkin
Quoted 26 lines · Parav Pandit

queue_msix_vector register is for receiving interrupts from the device for the virtqueue.

"for MSI-X" is confusing term.

Also it is the register that driver "writes" to, similar to many other registers such as queue_desc, queue_driver etc.

Hence, replace the verb from use to write.

---
changelog:
v0->v1:
- added 'here'
- dropped 'receiving'

---
 transport-pci.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
transport-pci.tex +0 -0
index cb9fadd..00669b5 100644

transport-pci.tex \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport · line 370

Quoted 5 lines
transport-pci.tex +1 -1
@@ -367,7 +367,7 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
         A 0 means the queue is unavailable.
 
 \item[\field{queue_msix_vector}]
-        The driver uses this to specify the queue vector for MSI-X.
+        The driver writes an MSI-X vector number here for virtqueue interrupts.

Here it's *the* specific queue not just some queue. And in fact we call them virtqueue notifications, not interrupts elsewhere. So how about:

Quoted 1 line

Used by the driver to set the MSI-X vector number for the virtqueue notifications.

or even "the virtqueue notification interrupts".

Quoted 5 lines
Quoted 5 lines
transport-pci.tex +0 -0
 \item[\field{queue_enable}]
         The driver uses this to selectively prevent the device from executing requests from this virtqueue.
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/

#10 lore raw
In reply to Parav Pandit

Hi Michael,

Quoted 11 lines

From: Parav Pandit <[email protected]>
Sent: Tuesday, April 11, 2023 3:42 PM

Problem:

Current wording queue_msix_vector and config_msix_vector says "for MSI-X", which is bit confusing.

config_msix_vector and queue_msix_vector are the msix vector number for configuration change and queue related interrupts.

Quoted 8 lines

Hence, reword it.

---
changelog:
v0->v1:
- added 'here'
- dropped 'receiving'
- dropped already merged patch for empty line

If you do not have further comments, can you please take this rewording change forward?

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/