Skip to contentSkip to conversation

content: add vendor specific cfg type

PATCH In review Michael S. Tsirkin 3 participants 9 messages Oct 28, 2019 – Nov 27, 2019 1 message not in the archive

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 content: add vendor specific cfg type

Vendors might want to add their own capability in the PCI capability list. However, Virtio already uses the vendor specific capability ID (0x09) for its own purposes.

Provide a structure for vendor specific extensions.

---
 content.tex | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
content.tex +80 -0
index b1ea9b9..8a79b03 100644
@@ -691,6 +691,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
 #define VIRTIO_PCI_CAP_PCI_CFG           5
 /* Shared memory region */
 #define VIRTIO_PCI_CAP_SHARED_MEMORY_CFG 8
+/* Vendor-specific data */
+#define VIRTIO_PCI_CAP_VENDOR_CFG        9
 \end{lstlisting}
 
         Any other value is reserved for future use.
@@ -1099,6 +1101,84 @@ \subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Vi
 
 The \field{cap.id} MUST be unique for any one device instance.
 
+\devicenormative{\paragraph}{Device-specific configuration}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Shared memory capability}
+
+The region defined by the combination of the \field {cap.offset},
+\field {cap.offset_hi}, and \field {cap.length}, \field
+{cap.length_hi} fields MUST be contained within the declared bar.
+
+The \field{cap.id} MUST be unique for any one device instance.
+
+\subsubsection{Vendor data capability}\label{sec:Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The optional Vendor data capability allows the device to present
+vendor-specific data to the driver, without
+conflicts, for debugging and/or reporting purposes,
+and without conflicting with standard functionality.
+
+This capability augments but does not replace the standard
+subsystem ID and subsystem vendor ID fields
+(offsets 0x2C and 0x2E in the PCI configuration space header)
+as specified by \hyperref[intro:PCI]{[PCI]}.
+
+Vendor data capability is enumerated on the PCI transport
+as a VIRTIO_PCI_CAP_VENDOR_CFG capability.
+
+The capability has the following structure:
+\begin{lstlisting}
+struct virtio_pci_vndr_data {
+        u8 cap_vndr;    /* Generic PCI field: PCI_CAP_ID_VNDR */
+        u8 cap_next;    /* Generic PCI field: next ptr. */
+        u8 cap_len;     /* Generic PCI field: capability length */
+        u8 cfg_type;    /* Identifies the structure. */
+        u16 vendor_id;  /* Identifies the vendor-specific format. */
+	/* For Vendor Definition */
+	/* Pads structure to a multiple of 4 bytes */
+	/* Reads must not have side effects */
+};
+\end{lstlisting}
+
+Where \field{vendor_id} identifies the PCI-SIG assigned Vendor ID
+as specified by \hyperref[intro:PCI]{[PCI]}.
+
+Note that the capability size is required to be a multiple of 4.
+
+To make it safe for a generic driver to access the capability,
+reads from this capability MUST NOT have any side effects.
+
+\devicenormative{\subsection}{Vendor data capability}{Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The device SHOULD present the PCI subsystem vendor ID matching
+the device vendor, at offset 0x2C in its PCI configuration space
+header.
+
+Devices CAN present \field{vendor_id} that does not match
+either the PCI Vendor ID or the PCI Subsystem Vendor ID.
+
+Devices CAN present multiple Vendor data capabilities with
+either different or identical \field{vendor_id} values.
+
+The value \field{vendor_id} MUST NOT equal 0x1AF4.
+
+The size of the Vendor data capability MUST be a multiple of 4 bytes.
+
+Reads of the Vendor data capability by the driver MUST NOT have any
+side effects.
+
+\drivernormative{\subsection}{Vendor data capability}{Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The driver SHOULD NOT use the Vendor data capability except
+for debugging and reporting purposes.
+
+The driver MUST qualify the \field{vendor_id} before
+interpreting or writing into the Vendor data capability.
+
 \subsubsection{PCI configuration access capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability}
 
 The VIRTIO_PCI_CAP_PCI_CFG capability
Signature · 7 lines
MST


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
#1 lore raw
Quoted 8 lines · Michael S. Tsirkin

Vendors might want to add their own capability in the PCI capability list. However, Virtio already uses the vendor specific capability ID (0x09) for its own purposes.

Provide a structure for vendor specific extensions.

Quoted 104 lines
---
 content.tex | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
content.tex +80 -0
index b1ea9b9..8a79b03 100644
@@ -691,6 +691,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
 #define VIRTIO_PCI_CAP_PCI_CFG           5
 /* Shared memory region */
 #define VIRTIO_PCI_CAP_SHARED_MEMORY_CFG 8
+/* Vendor-specific data */
+#define VIRTIO_PCI_CAP_VENDOR_CFG        9
 \end{lstlisting}
 
         Any other value is reserved for future use.
@@ -1099,6 +1101,84 @@ \subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Vi
 
 The \field{cap.id} MUST be unique for any one device instance.
 
+\devicenormative{\paragraph}{Device-specific configuration}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Shared memory capability}
+
+The region defined by the combination of the \field {cap.offset},
+\field {cap.offset_hi}, and \field {cap.length}, \field
+{cap.length_hi} fields MUST be contained within the declared bar.
+
+The \field{cap.id} MUST be unique for any one device instance.
+
+\subsubsection{Vendor data capability}\label{sec:Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The optional Vendor data capability allows the device to present
+vendor-specific data to the driver, without
+conflicts, for debugging and/or reporting purposes,
+and without conflicting with standard functionality.
+
+This capability augments but does not replace the standard
+subsystem ID and subsystem vendor ID fields
+(offsets 0x2C and 0x2E in the PCI configuration space header)
+as specified by \hyperref[intro:PCI]{[PCI]}.
+
+Vendor data capability is enumerated on the PCI transport
+as a VIRTIO_PCI_CAP_VENDOR_CFG capability.
+
+The capability has the following structure:
+\begin{lstlisting}
+struct virtio_pci_vndr_data {
+        u8 cap_vndr;    /* Generic PCI field: PCI_CAP_ID_VNDR */
+        u8 cap_next;    /* Generic PCI field: next ptr. */
+        u8 cap_len;     /* Generic PCI field: capability length */
+        u8 cfg_type;    /* Identifies the structure. */
+        u16 vendor_id;  /* Identifies the vendor-specific format. */
+	/* For Vendor Definition */
+	/* Pads structure to a multiple of 4 bytes */
+	/* Reads must not have side effects */
+};
+\end{lstlisting}
+
+Where \field{vendor_id} identifies the PCI-SIG assigned Vendor ID
+as specified by \hyperref[intro:PCI]{[PCI]}.
+
+Note that the capability size is required to be a multiple of 4.
+
+To make it safe for a generic driver to access the capability,
+reads from this capability MUST NOT have any side effects.
+
+\devicenormative{\subsection}{Vendor data capability}{Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The device SHOULD present the PCI subsystem vendor ID matching
+the device vendor, at offset 0x2C in its PCI configuration space
+header.
+
+Devices CAN present \field{vendor_id} that does not match
+either the PCI Vendor ID or the PCI Subsystem Vendor ID.
+
+Devices CAN present multiple Vendor data capabilities with
+either different or identical \field{vendor_id} values.
+
+The value \field{vendor_id} MUST NOT equal 0x1AF4.
+
+The size of the Vendor data capability MUST be a multiple of 4 bytes.
+
+Reads of the Vendor data capability by the driver MUST NOT have any
+side effects.
+
+\drivernormative{\subsection}{Vendor data capability}{Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The driver SHOULD NOT use the Vendor data capability except
+for debugging and reporting purposes.
+
+The driver MUST qualify the \field{vendor_id} before
+interpreting or writing into the Vendor data capability.
+
 \subsubsection{PCI configuration access capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability}
 
 The VIRTIO_PCI_CAP_PCI_CFG capability
Signature · 1 line
MST

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

#2 lore raw
In reply to Michael S. Tsirkin
Quoted 4 lines · Michael S. Tsirkin

Vendors might want to add their own capability in the PCI capability list. However, Virtio already uses the vendor specific capability ID (0x09) for its own purposes.

Did some vendor express that need, or do we only assume it so far? IOW: Do we know at least once concrete use case?

Quoted 89 lines

Provide a structure for vendor specific extensions.

---
  content.tex | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++
  1 file changed, 80 insertions(+)
content.tex +66 -0
index b1ea9b9..8a79b03 100644
@@ -691,6 +691,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
  #define VIRTIO_PCI_CAP_PCI_CFG           5
  /* Shared memory region */
  #define VIRTIO_PCI_CAP_SHARED_MEMORY_CFG 8
+/* Vendor-specific data */
+#define VIRTIO_PCI_CAP_VENDOR_CFG        9
  \end{lstlisting}
 
          Any other value is reserved for future use.
@@ -1099,6 +1101,84 @@ \subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Vi
 
  The \field{cap.id} MUST be unique for any one device instance.
 
+\devicenormative{\paragraph}{Device-specific configuration}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Shared memory capability}
+
+The region defined by the combination of the \field {cap.offset},
+\field {cap.offset_hi}, and \field {cap.length}, \field
+{cap.length_hi} fields MUST be contained within the declared bar.
+
+The \field{cap.id} MUST be unique for any one device instance.
+
+\subsubsection{Vendor data capability}\label{sec:Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The optional Vendor data capability allows the device to present
+vendor-specific data to the driver, without
+conflicts, for debugging and/or reporting purposes,
+and without conflicting with standard functionality.
+
+This capability augments but does not replace the standard
+subsystem ID and subsystem vendor ID fields
+(offsets 0x2C and 0x2E in the PCI configuration space header)
+as specified by \hyperref[intro:PCI]{[PCI]}.
+
+Vendor data capability is enumerated on the PCI transport
+as a VIRTIO_PCI_CAP_VENDOR_CFG capability.
+
+The capability has the following structure:
+\begin{lstlisting}
+struct virtio_pci_vndr_data {
+        u8 cap_vndr;    /* Generic PCI field: PCI_CAP_ID_VNDR */
+        u8 cap_next;    /* Generic PCI field: next ptr. */
+        u8 cap_len;     /* Generic PCI field: capability length */
+        u8 cfg_type;    /* Identifies the structure. */
+        u16 vendor_id;  /* Identifies the vendor-specific format. */
+	/* For Vendor Definition */
+	/* Pads structure to a multiple of 4 bytes */
+	/* Reads must not have side effects */
+};
+\end{lstlisting}
+
+Where \field{vendor_id} identifies the PCI-SIG assigned Vendor ID
+as specified by \hyperref[intro:PCI]{[PCI]}.
+
+Note that the capability size is required to be a multiple of 4.
+
+To make it safe for a generic driver to access the capability,
+reads from this capability MUST NOT have any side effects.
+
+\devicenormative{\subsection}{Vendor data capability}{Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The device SHOULD present the PCI subsystem vendor ID matching
+the device vendor, at offset 0x2C in its PCI configuration space
+header.
+
+Devices CAN present \field{vendor_id} that does not match
+either the PCI Vendor ID or the PCI Subsystem Vendor ID.
+
+Devices CAN present multiple Vendor data capabilities with
+either different or identical \field{vendor_id} values.
+
+The value \field{vendor_id} MUST NOT equal 0x1AF4.
+
+The size of the Vendor data capability MUST be a multiple of 4 bytes.

content.tex \subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Vi · line 1177

Quoted 10 lines
content.tex +10 -0
+
+Reads of the Vendor data capability by the driver MUST NOT have any
+side effects.
+
+\drivernormative{\subsection}{Vendor data capability}{Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The driver SHOULD NOT use the Vendor data capability except
+for debugging and reporting purposes.

Every vendor is free to mess up the device behavior by adding more to this than the spec defines. Still, I'm undecided if this shouldn't be stronger.

Jan

Quoted 8 lines
content.tex +4 -0
+
+The driver MUST qualify the \field{vendor_id} before
+interpreting or writing into the Vendor data capability.
+
  \subsubsection{PCI configuration access capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability}
 
  The VIRTIO_PCI_CAP_PCI_CFG capability
Signature · 6 lines
Siemens AG, Corporate Technology, CT RDA IOT SES-DE
Corporate Competence Center Embedded Linux

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 
#3 lore raw
Quoted 8 lines · Jan Kiszka
Quoted 4 lines · Michael S. Tsirkin

Vendors might want to add their own capability in the PCI capability list. However, Virtio already uses the vendor specific capability ID (0x09) for its own purposes.

Did some vendor express that need, or do we only assume it so far? IOW: Do we know at least once concrete use case?

Good point, I should have added this in the log.

I know of a device that implements virtio and has a bug.

Device is a transitional one so can not have vendor specific
subsystem IDs (that violates the SHOULD below. Do we want to qualify that this recommendation is for non-transitional devices?). While that specific device can't be fixed like this on bare metal, it creates a consistent way for future devices to trigger vendor/device specific quirks,
and it creates an option for the hypervisor to add the capability.

Quoted 102 lines
Quoted 86 lines

Provide a structure for vendor specific extensions.

---
  content.tex | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++
  1 file changed, 80 insertions(+)
content.tex +66 -0
index b1ea9b9..8a79b03 100644
@@ -691,6 +691,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
  #define VIRTIO_PCI_CAP_PCI_CFG           5
  /* Shared memory region */
  #define VIRTIO_PCI_CAP_SHARED_MEMORY_CFG 8
+/* Vendor-specific data */
+#define VIRTIO_PCI_CAP_VENDOR_CFG        9
  \end{lstlisting}
          Any other value is reserved for future use.
@@ -1099,6 +1101,84 @@ \subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Vi
  The \field{cap.id} MUST be unique for any one device instance.
+\devicenormative{\paragraph}{Device-specific configuration}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Shared memory capability}
+
+The region defined by the combination of the \field {cap.offset},
+\field {cap.offset_hi}, and \field {cap.length}, \field
+{cap.length_hi} fields MUST be contained within the declared bar.
+
+The \field{cap.id} MUST be unique for any one device instance.
+
+\subsubsection{Vendor data capability}\label{sec:Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The optional Vendor data capability allows the device to present
+vendor-specific data to the driver, without
+conflicts, for debugging and/or reporting purposes,
+and without conflicting with standard functionality.
+
+This capability augments but does not replace the standard
+subsystem ID and subsystem vendor ID fields
+(offsets 0x2C and 0x2E in the PCI configuration space header)
+as specified by \hyperref[intro:PCI]{[PCI]}.
+
+Vendor data capability is enumerated on the PCI transport
+as a VIRTIO_PCI_CAP_VENDOR_CFG capability.
+
+The capability has the following structure:
+\begin{lstlisting}
+struct virtio_pci_vndr_data {
+        u8 cap_vndr;    /* Generic PCI field: PCI_CAP_ID_VNDR */
+        u8 cap_next;    /* Generic PCI field: next ptr. */
+        u8 cap_len;     /* Generic PCI field: capability length */
+        u8 cfg_type;    /* Identifies the structure. */
+        u16 vendor_id;  /* Identifies the vendor-specific format. */
+	/* For Vendor Definition */
+	/* Pads structure to a multiple of 4 bytes */
+	/* Reads must not have side effects */
+};
+\end{lstlisting}
+
+Where \field{vendor_id} identifies the PCI-SIG assigned Vendor ID
+as specified by \hyperref[intro:PCI]{[PCI]}.
+
+Note that the capability size is required to be a multiple of 4.
+
+To make it safe for a generic driver to access the capability,
+reads from this capability MUST NOT have any side effects.
+
+\devicenormative{\subsection}{Vendor data capability}{Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The device SHOULD present the PCI subsystem vendor ID matching
+the device vendor, at offset 0x2C in its PCI configuration space
+header.
+
+Devices CAN present \field{vendor_id} that does not match
+either the PCI Vendor ID or the PCI Subsystem Vendor ID.
+
+Devices CAN present multiple Vendor data capabilities with
+either different or identical \field{vendor_id} values.
+
+The value \field{vendor_id} MUST NOT equal 0x1AF4.
+
+The size of the Vendor data capability MUST be a multiple of 4 bytes.

content.tex \subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Vi · line 1175

Quoted 10 lines
content.tex +10 -0
+
+Reads of the Vendor data capability by the driver MUST NOT have any
+side effects.
+
+\drivernormative{\subsection}{Vendor data capability}{Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The driver SHOULD NOT use the Vendor data capability except
+for debugging and reporting purposes.

Every vendor is free to mess up the device behavior by adding more to this than the spec defines. Still, I'm undecided if this shouldn't be stronger.

Jan

Quoted 11 lines
Quoted 7 lines
content.tex +4 -0
+
+The driver MUST qualify the \field{vendor_id} before
+interpreting or writing into the Vendor data capability.
+
  \subsubsection{PCI configuration access capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability}
  The VIRTIO_PCI_CAP_PCI_CFG capability
 
Signature · 2 lines
Siemens AG, Corporate Technology, CT RDA IOT SES-DE
Corporate Competence Center Embedded Linux

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

#4 lore raw
Quoted 10 lines · On Mon, 25 Nov 2019 03:11:43 -0500 "Michael S. Tsirkin" <[email protected]> wrote:
Quoted 8 lines · Jan Kiszka
Quoted 4 lines · Michael S. Tsirkin

Vendors might want to add their own capability in the PCI capability list. However, Virtio already uses the vendor specific capability ID (0x09) for its own purposes.

Did some vendor express that need, or do we only assume it so far? IOW: Do we know at least once concrete use case?

Quoted 7 lines

Good point, I should have added this in the log.

I know of a device that implements virtio and has a bug.

Device is a transitional one so can not have vendor specific subsystem IDs (that violates the SHOULD below. Do we want to qualify that this recommendation is for non-transitional devices?). While that

What about adding some notes on top that vendor specific subsystem IDs are not for transitional devices? That would also catch the case in the other update.

Quoted 24 lines

specific device can't be fixed like this on bare metal, it creates a consistent way for future devices to trigger vendor/device specific quirks,
and it creates an option for the hypervisor to add the capability.

Quoted 20 lines
Quoted 20 lines

Provide a structure for vendor specific extensions.

---
  content.tex | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++
  1 file changed, 80 insertions(+)

+\devicenormative{\subsection}{Vendor data capability}{Virtio

content.tex +11 -0
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The device SHOULD present the PCI subsystem vendor ID matching
+the device vendor, at offset 0x2C in its PCI configuration space
+header.
+
+Devices CAN present \field{vendor_id} that does not match
+either the PCI Vendor ID or the PCI Subsystem Vendor ID.
+
+Devices CAN present multiple Vendor data capabilities with
Quoted 8 lines
Quoted 8 lines

content.tex \subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Vi · line 1170

Quoted 8 lines
content.tex +8 -0
+either different or identical \field{vendor_id} values.
+
+The value \field{vendor_id} MUST NOT equal 0x1AF4.
+
+The size of the Vendor data capability MUST be a multiple of 4 bytes.
+
+Reads of the Vendor data capability by the driver MUST NOT have any
+side effects.

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

#5 lore raw
Quoted 17 lines · Cornelia Huck
Quoted 14 lines · On Mon, 25 Nov 2019 03:11:43 -0500 "Michael S. Tsirkin" <[email protected]> wrote:
Quoted 8 lines · Jan Kiszka
Quoted 4 lines · Michael S. Tsirkin

Vendors might want to add their own capability in the PCI capability list. However, Virtio already uses the vendor specific capability ID (0x09) for its own purposes.

Did some vendor express that need, or do we only assume it so far? IOW: Do we know at least once concrete use case?

Good point, I should have added this in the log.

I know of a device that implements virtio and has a bug.

Quoted 7 lines
Quoted 3 lines

Device is a transitional one so can not have vendor specific subsystem IDs (that violates the SHOULD below. Do we want to qualify that this recommendation is for non-transitional devices?). While that

What about adding some notes on top that vendor specific subsystem IDs are not for transitional devices? That would also catch the case in the other update.

I'm still trying to figure out a good wording though. A full description would need to describe the legacy tricks with subsystem device ID etc. That's a lot of text. Certainly doable but
maybe I'll just drop the subsystem vendor ID part for now, treat that as a different subject?

Quoted 24 lines
Quoted 24 lines

specific device can't be fixed like this on bare metal, it creates a consistent way for future devices to trigger vendor/device specific quirks,
and it creates an option for the hypervisor to add the capability.

Quoted 20 lines
Quoted 20 lines

Provide a structure for vendor specific extensions.

---
  content.tex | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++
  1 file changed, 80 insertions(+)

+\devicenormative{\subsection}{Vendor data capability}{Virtio

content.tex +11 -0
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The device SHOULD present the PCI subsystem vendor ID matching
+the device vendor, at offset 0x2C in its PCI configuration space
+header.
+
+Devices CAN present \field{vendor_id} that does not match
+either the PCI Vendor ID or the PCI Subsystem Vendor ID.
+
+Devices CAN present multiple Vendor data capabilities with
Quoted 8 lines
Quoted 8 lines
Quoted 8 lines

content.tex \subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Vi · line 1170

Quoted 8 lines
content.tex +8 -0
+either different or identical \field{vendor_id} values.
+
+The value \field{vendor_id} MUST NOT equal 0x1AF4.
+
+The size of the Vendor data capability MUST be a multiple of 4 bytes.
+
+Reads of the Vendor data capability by the driver MUST NOT have any
+side effects.

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

#6 lore raw
Quoted 18 lines · Michael S. Tsirkin
Quoted 17 lines · Cornelia Huck
Quoted 14 lines · On Mon, 25 Nov 2019 03:11:43 -0500 "Michael S. Tsirkin" <[email protected]> wrote:
Quoted 8 lines · Jan Kiszka
Quoted 4 lines · Michael S. Tsirkin

Vendors might want to add their own capability in the PCI capability list. However, Virtio already uses the vendor specific capability ID (0x09) for its own purposes.

Did some vendor express that need, or do we only assume it so far? IOW: Do we know at least once concrete use case?

Good point, I should have added this in the log.

I know of a device that implements virtio and has a bug.

Quoted 7 lines
Quoted 7 lines
Quoted 3 lines

Device is a transitional one so can not have vendor specific subsystem IDs (that violates the SHOULD below. Do we want to qualify that this recommendation is for non-transitional devices?). While that

What about adding some notes on top that vendor specific subsystem IDs are not for transitional devices? That would also catch the case in the other update.

So how about I just skip the following chunk when I commit?

	+The device SHOULD present the PCI subsystem vendor ID matching
	+the device vendor, at offset 0x2C in its PCI configuration space
	+header.

that seems to belong to the other ballot that I have withdrawn.

Minor enough that I don't feel we need to redo the whole ballot, right?.

Signature · 7 lines
MST


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 
#7 lore raw
Quoted 30 lines · On Wed, 27 Nov 2019 08:23:44 -0500 "Michael S. Tsirkin" <[email protected]> wrote:
Quoted 18 lines · Michael S. Tsirkin
Quoted 17 lines · Cornelia Huck
Quoted 14 lines · On Mon, 25 Nov 2019 03:11:43 -0500 "Michael S. Tsirkin" <[email protected]> wrote:
Quoted 8 lines · Jan Kiszka
Quoted 4 lines · Michael S. Tsirkin

Vendors might want to add their own capability in the PCI capability list. However, Virtio already uses the vendor specific capability ID (0x09) for its own purposes.

Did some vendor express that need, or do we only assume it so far? IOW: Do we know at least once concrete use case?

Good point, I should have added this in the log.

I know of a device that implements virtio and has a bug.

Quoted 7 lines
Quoted 7 lines
Quoted 3 lines

Device is a transitional one so can not have vendor specific subsystem IDs (that violates the SHOULD below. Do we want to qualify that this recommendation is for non-transitional devices?). While that

What about adding some notes on top that vendor specific subsystem IDs are not for transitional devices? That would also catch the case in the other update.

So how about I just skip the following chunk when I commit?

Quoted 9 lines
	+The device SHOULD present the PCI subsystem vendor ID matching
	+the device vendor, at offset 0x2C in its PCI configuration space
	+header.

that seems to belong to the other ballot that I have withdrawn.

Minor enough that I don't feel we need to redo the whole ballot, right?.

I think that's fine.

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

A message that is not in the archive (sent off-list or not yet received): [email protected]

#9 lore raw
Quoted 33 lines · Christophe de Dinechin
Quoted 33 lines · Michael S. Tsirkin

Vendors might want to add their own capability in the PCI capability list. However, Virtio already uses the vendor specific capability ID (0x09) for its own purposes.

Provide a structure for vendor specific extensions.

---
content.tex | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++

1 file changed, 80 insertions(+)
content.tex +2 -0
index b1ea9b9..8a79b03 100644
@@ -691,6 +691,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
 #define VIRTIO_PCI_CAP_PCI_CFG           5
 /* Shared memory region */
 #define VIRTIO_PCI_CAP_SHARED_MEMORY_CFG 8
+/* Vendor-specific data */
+#define VIRTIO_PCI_CAP_VENDOR_CFG        9
 \end{lstlisting}
 
        Any other value is reserved for future use.
@@ -1099,6 +1101,84 @@ \subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Vi
 

The \field{cap.id} MUST be unique for any one device instance.

Quoted 7 lines

content.tex \subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Vi · line 1108

Quoted 5 lines

+\devicenormative{\paragraph}{Device-specific configuration}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Shared memory capability}

content.tex +4 -0
+
+The region defined by the combination of the \field {cap.offset},
+\field {cap.offset_hi}, and \field {cap.length}, \field
+{cap.length_hi} fields MUST be contained within the declared bar.

Uppercase BAR?

\field{bar} I think.

But really this is from "shared memory: Define PCI capability" that I somehow failed to apply properly :(

Quoted 103 lines
Quoted 31 lines
content.tex +31 -0
+
+The \field{cap.id} MUST be unique for any one device instance.
+
+\subsubsection{Vendor data capability}\label{sec:Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The optional Vendor data capability allows the device to present
+vendor-specific data to the driver, without
+conflicts, for debugging and/or reporting purposes,
+and without conflicting with standard functionality.
+
+This capability augments but does not replace the standard
+subsystem ID and subsystem vendor ID fields
+(offsets 0x2C and 0x2E in the PCI configuration space header)
+as specified by \hyperref[intro:PCI]{[PCI]}.
+
+Vendor data capability is enumerated on the PCI transport
+as a VIRTIO_PCI_CAP_VENDOR_CFG capability.
+
+The capability has the following structure:
+\begin{lstlisting}
+struct virtio_pci_vndr_data {
+        u8 cap_vndr;    /* Generic PCI field: PCI_CAP_ID_VNDR */
+        u8 cap_next;    /* Generic PCI field: next ptr. */
+        u8 cap_len;     /* Generic PCI field: capability length */
+        u8 cfg_type;    /* Identifies the structure. */
+        u16 vendor_id;  /* Identifies the vendor-specific format. */
+	/* For Vendor Definition */
+	/* Pads structure to a multiple of 4 bytes */
+	/* Reads must not have side effects */

content.tex \subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Vi · line 1149

Quoted 10 lines
content.tex +10 -0
+};
+\end{lstlisting}
+
+Where \field{vendor_id} identifies the PCI-SIG assigned Vendor ID
+as specified by \hyperref[intro:PCI]{[PCI]}.
+
+Note that the capability size is required to be a multiple of 4.
+
+To make it safe for a generic driver to access the capability,
+reads from this capability MUST NOT have any side effects.

I think the intent is that this includes the capability payload, not just the generic fields. Worth spelling out?

Quoted 18 lines
content.tex +18 -0
+
+\devicenormative{\subsection}{Vendor data capability}{Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The device SHOULD present the PCI subsystem vendor ID matching
+the device vendor, at offset 0x2C in its PCI configuration space
+header.
+
+Devices CAN present \field{vendor_id} that does not match
+either the PCI Vendor ID or the PCI Subsystem Vendor ID.
+
+Devices CAN present multiple Vendor data capabilities with
+either different or identical \field{vendor_id} values.
+
+The value \field{vendor_id} MUST NOT equal 0x1AF4.
+
+The size of the Vendor data capability MUST be a multiple of 4 bytes.

content.tex \subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Vi · line 1177

Quoted 10 lines
content.tex +10 -0
+
+Reads of the Vendor data capability by the driver MUST NOT have any
+side effects.
+
+\drivernormative{\subsection}{Vendor data capability}{Virtio
+Transport Options / Virtio Over PCI Bus / PCI Device Layout /
+Vendor data capability}
+
+The driver SHOULD NOT use the Vendor data capability except
+for debugging and reporting purposes.

What is the rationale for this restriction?

For example, would it be OK for a vendor to expose the presence of a particular firmware bugfix, so that the driver could disable some bug workaround? You seem to hint that this is the intent in a later response, but on initial reading, it was not clear to me that such usage would fit under “debugging” or “reporting”.

(I’m quite new here, so feel free to ignore if it’s clear to everybody else)

Quoted 18 lines
content.tex +4 -0
+
+The driver MUST qualify the \field{vendor_id} before
+interpreting or writing into the Vendor data capability.
+

\subsubsection{PCI configuration access capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability}

The VIRTIO_PCI_CAP_PCI_CFG capability

Signature · 9 lines
MST


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.
Quoted 9 lines
Quoted 9 lines

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/

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php