virtio-comment

From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>

This series formalises the idea of shared memory regions I'd
previously discussed and is intended for use with virtio-fs.

I've split it into five parts:

a) A general definition of the idea

b) An addition of an 'id' field to allow multiple distinct
capabilities of the same type.

c) An addition of a 64bit capability type.

d) A definition on virtio-pci using the layout previously
discussed.

e) A definition on virtio-mmio.

v6:
Modifications from Cornelia's review

Dr. David Alan Gilbert (5):
shared memory: Define shared memory regions
pci: Define id field
pci: Define virtio_pci_cap64
shared memory: Define PCI capability
shared memory: Define mmio registers

conformance.tex | 1 +
content.tex | 83 +++++++++++++++++++++++++++++++++++++++++++++++--
shared-mem.tex | 42 +++++++++++++++++++++++++
3 files changed, 124 insertions(+), 2 deletions(-)
create mode 100644 shared-mem.tex

--
2.21.0

From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>

Define the requirements and idea behind shared memory regions.

Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
---
conformance.tex | 1 +
content.tex | 2 ++
shared-mem.tex | 42 ++++++++++++++++++++++++++++++++++++++++++
3 files changed, 45 insertions(+)
create mode 100644 shared-mem.tex

diff --git a/conformance.tex b/conformance.tex
index 42f702a..4524237 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -197,6 +197,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
\item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / Used Buffer Notification Suppression}
\item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}
\item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / Available Buffer Notification Suppression}
+\item \ref{devicenormative:Basic Facilities of a Virtio Device / Shared Memory Regions}
\item \ref{devicenormative:Reserved Feature Bits}
\end{itemize}

diff --git a/content.tex b/content.tex
index 8f0498e..6433226 100644
--- a/content.tex
+++ b/content.tex
@@ -371,6 +371,8 @@ \subsection{Driver notifications} \label{sec:Virtqueues / Driver notifications}
has been negotiated, these notifications would then have
identical \field{next_off} and \field{next_wrap} values.

+\input{shared-mem.tex}
+
\chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}

We start with an overview of device initialization, then expand on the
diff --git a/shared-mem.tex b/shared-mem.tex
new file mode 100644
index 0000000..6e6f6c4
--- /dev/null
+++ b/shared-mem.tex
@@ -0,0 +1,42 @@
+\section{Shared Memory Regions}\label{sec:Basic Facilities of a Virtio Device / Shared Memory Regions}
+
+Shared memory regions are an additional facility
+available to devices that need a region of memory that's
+continuously shared between the device and the driver, rather
+than passed between them in the way virtqueue elements are.
+
+Example uses include shared caches and version pools for versioned
+data structures.
+
+The memory region is allocated by the device and presented to the
+driver. Where the device is implemented in software on a host,
+this arrangement allows the memory region to be allocated by
+a library on the host, which the device may not have full control
+over.
+
+A device may have multiple shared memory regions associated with
+it. Each region has a \field{shmid} to identify it, the meaning
+of which is device-specific.
+
+Enumeration and location of shared memory regions is performed
+in a transport-specific way.
+
+Memory consistency rules vary depending on the region and the
+device and they will be specified as required by each device.
+
+\subsection{Addressing within regions}\label{sec:Basic Facilities of a Virtio Device / Shared Memory Regions / Addressing within regions }
+
+References into shared memory regions are represented as offsets from
+the beginning of the region instead of absolute memory addresses.
+Offsets are used both for references between structures stored
+within shared memory and for requests placed in virtqueues that
+refer to shared memory.
+The \field{shmid} may be explicit or may be inferred from the
+context of the reference.
+
+\devicenormative{\subsection}{Shared Memory Regions}{Basic Facilities of a Virtio
+Device / Shared Memory Regions}
+Shared memory regions MUST NOT expose shared memory regions which
+are used to control the operation of the device, nor to stream
+data.
+
--
2.21.0

From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>

Define the requirements and idea behind shared memory regions.

Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
---
conformance.tex | 1 +
content.tex | 2 ++
shared-mem.tex | 42 ++++++++++++++++++++++++++++++++++++++++++
3 files changed, 45 insertions(+)
create mode 100644 shared-mem.tex

diff --git a/conformance.tex b/conformance.tex
index 42f702a..4524237 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -197,6 +197,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
\item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / Used Buffer Notification Suppression}
\item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}
\item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / Available Buffer Notification Suppression}
+\item \ref{devicenormative:Basic Facilities of a Virtio Device / Shared Memory Regions}
\item \ref{devicenormative:Reserved Feature Bits}
\end{itemize}

diff --git a/content.tex b/content.tex
index 8f0498e..6433226 100644
--- a/content.tex
+++ b/content.tex
@@ -371,6 +371,8 @@ \subsection{Driver notifications} \label{sec:Virtqueues / Driver notifications}
has been negotiated, these notifications would then have
identical \field{next_off} and \field{next_wrap} values.

+\input{shared-mem.tex}
+
\chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}

We start with an overview of device initialization, then expand on the
diff --git a/shared-mem.tex b/shared-mem.tex
new file mode 100644
index 0000000..6e6f6c4
--- /dev/null
+++ b/shared-mem.tex
@@ -0,0 +1,42 @@
+\section{Shared Memory Regions}\label{sec:Basic Facilities of a Virtio Device / Shared Memory Regions}
+
+Shared memory regions are an additional facility
+available to devices that need a region of memory that's
+continuously shared between the device and the driver, rather
+than passed between them in the way virtqueue elements are.
+
+Example uses include shared caches and version pools for versioned
+data structures.
+
+The memory region is allocated by the device and presented to the
+driver. Where the device is implemented in software on a host,
+this arrangement allows the memory region to be allocated by
+a library on the host, which the device may not have full control
+over.
+
+A device may have multiple shared memory regions associated with
+it. Each region has a \field{shmid} to identify it, the meaning
+of which is device-specific.
+
+Enumeration and location of shared memory regions is performed
+in a transport-specific way.
+
+Memory consistency rules vary depending on the region and the
+device and they will be specified as required by each device.
+
+\subsection{Addressing within regions}\label{sec:Basic Facilities of a Virtio Device / Shared Memory Regions / Addressing within regions }
+
+References into shared memory regions are represented as offsets from
+the beginning of the region instead of absolute memory addresses.
+Offsets are used both for references between structures stored
+within shared memory and for requests placed in virtqueues that
+refer to shared memory.
+The \field{shmid} may be explicit or may be inferred from the
+context of the reference.
+
+\devicenormative{\subsection}{Shared Memory Regions}{Basic Facilities of a Virtio
+Device / Shared Memory Regions}
+Shared memory regions MUST NOT expose shared memory regions which
+are used to control the operation of the device, nor to stream
+data.
+
--
2.21.0

From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>

For the virtio-fs device we require multiple large shared memory
regions. Differentiate these by an 'id' field in the base capability.

Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
---
content.tex | 12 ++++++++++--
1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/content.tex b/content.tex
index 6433226..fafa532 100644
--- a/content.tex
+++ b/content.tex
@@ -651,7 +651,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
u8 cap_len; /* Generic PCI field: capability length */
u8 cfg_type; /* Identifies the structure. */
u8 bar; /* Where to find it. */
- u8 padding[3]; /* Pad to full dword. */
+ u8 id; /* Multiple capabilities of the same type */
+ u8 padding[2]; /* Pad to full dword. */
le32 offset; /* Offset within bar. */
le32 length; /* Length of the structure, in bytes. */
};
@@ -697,7 +698,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
The device MAY offer more than one structure of any type - this makes it
possible for the device to expose multiple interfaces to drivers. The order of
the capabilities in the capability list specifies the order of preference
- suggested by the device.
+ suggested by the device. A device may specify that this ordering mechanism be
+ overridden by the use of the \field{id} field.
\begin{note}
For example, on some hypervisors, notifications using IO accesses are
faster than memory accesses. In this case, the device would expose two
@@ -716,6 +718,12 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option

Any other value is reserved for future use.

+\item[\field{id}]
+ Used by some device types to uniquely identify multiple capabilities
+ of a certain type. If the device type does not specify the meaning of
+ this field, its contents are undefined.
+
+
\item[\field{offset}]
indicates where the structure begins relative to the base address associated
with the BAR. The alignment requirements of \field{offset} are indicated
--
2.21.0

From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>

For the virtio-fs device we require multiple large shared memory
regions. Differentiate these by an 'id' field in the base capability.

Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
---
content.tex | 12 ++++++++++--
1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/content.tex b/content.tex
index 6433226..fafa532 100644
--- a/content.tex
+++ b/content.tex
@@ -651,7 +651,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
u8 cap_len; /* Generic PCI field: capability length */
u8 cfg_type; /* Identifies the structure. */
u8 bar; /* Where to find it. */
- u8 padding[3]; /* Pad to full dword. */
+ u8 id; /* Multiple capabilities of the same type */
+ u8 padding[2]; /* Pad to full dword. */
le32 offset; /* Offset within bar. */
le32 length; /* Length of the structure, in bytes. */
};
@@ -697,7 +698,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
The device MAY offer more than one structure of any type - this makes it
possible for the device to expose multiple interfaces to drivers. The order of
the capabilities in the capability list specifies the order of preference
- suggested by the device.
+ suggested by the device. A device may specify that this ordering mechanism be
+ overridden by the use of the \field{id} field.
\begin{note}
For example, on some hypervisors, notifications using IO accesses are
faster than memory accesses. In this case, the device would expose two
@@ -716,6 +718,12 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option

Any other value is reserved for future use.

+\item[\field{id}]
+ Used by some device types to uniquely identify multiple capabilities
+ of a certain type. If the device type does not specify the meaning of
+ this field, its contents are undefined.
+
+
\item[\field{offset}]
indicates where the structure begins relative to the base address associated
with the BAR. The alignment requirements of \field{offset} are indicated
--
2.21.0

On Wed, 10 Jul 2019 19:32:09 +0100
"Dr. David Alan Gilbert (git)" <dgilbert@redhat.com> wrote:

> From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>
>
> For the virtio-fs device we require multiple large shared memory
> regions. Differentiate these by an 'id' field in the base capability.
>
> Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
> ---
> content.tex | 12 ++++++++++--
> 1 file changed, 10 insertions(+), 2 deletions(-)

Reviewed-by: Cornelia Huck <cohuck@redhat.com>

On Wed, 10 Jul 2019 19:32:09 +0100
"Dr. David Alan Gilbert (git)" <dgilbert@redhat.com> wrote:

> From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>
>
> For the virtio-fs device we require multiple large shared memory
> regions. Differentiate these by an 'id' field in the base capability.
>
> Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
> ---
> content.tex | 12 ++++++++++--
> 1 file changed, 10 insertions(+), 2 deletions(-)

Reviewed-by: Cornelia Huck <cohuck@redhat.com>

From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>

Define 'virtio_pci_cap64' to allow capabilities to describe
memory regions larger than, or with an offset larger than 4GiB.

This will be used by the shared memory region capability.

Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
---
content.tex | 17 +++++++++++++++++
1 file changed, 17 insertions(+)

diff --git a/content.tex b/content.tex
index fafa532..d481359 100644
--- a/content.tex
+++ b/content.tex
@@ -746,6 +746,23 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
\end{note}
\end{description}

+A variant of this type, struct virtio_pci_cap64, is defined for
+those capaibilites that require offsets or lengths larger than
+4GiB:
+
+\begin{lstlisting}
+struct virtio_pci_cap64 {
+ struct virtio_pci_cap cap;
+ u32 offset_hi;
+ u32 length_hi;
+};
+\end{lstlisting}
+
+Given that the \field{cap.length} and \field{cap.offset} fields
+are only 32 bit, the additional \field{offset_hi} and \field {length_hi}
+fields provide the most significant 32 bits of a total 64 bit offset and
+length within the bar specified by \field{cap.bar}.
+
\drivernormative{\subsubsection}{Virtio Structure PCI Capabilities}{Virtio Transport Options / Virtio Over PCI Bus / Virtio Structure PCI Capabilities}

The driver MUST ignore any vendor-specific capability structure which has
--
2.21.0

From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>

Define 'virtio_pci_cap64' to allow capabilities to describe
memory regions larger than, or with an offset larger than 4GiB.

This will be used by the shared memory region capability.

Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
---
content.tex | 17 +++++++++++++++++
1 file changed, 17 insertions(+)

diff --git a/content.tex b/content.tex
index fafa532..d481359 100644
--- a/content.tex
+++ b/content.tex
@@ -746,6 +746,23 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
\end{note}
\end{description}

+A variant of this type, struct virtio_pci_cap64, is defined for
+those capaibilites that require offsets or lengths larger than
+4GiB:
+
+\begin{lstlisting}
+struct virtio_pci_cap64 {
+ struct virtio_pci_cap cap;
+ u32 offset_hi;
+ u32 length_hi;
+};
+\end{lstlisting}
+
+Given that the \field{cap.length} and \field{cap.offset} fields
+are only 32 bit, the additional \field{offset_hi} and \field {length_hi}
+fields provide the most significant 32 bits of a total 64 bit offset and
+length within the bar specified by \field{cap.bar}.
+
\drivernormative{\subsubsection}{Virtio Structure PCI Capabilities}{Virtio Transport Options / Virtio Over PCI Bus / Virtio Structure PCI Capabilities}

The driver MUST ignore any vendor-specific capability structure which has
--
2.21.0

From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>

Define the PCI capability used for enumerating shared memory regions.

Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
---
content.tex | 22 ++++++++++++++++++++++
1 file changed, 22 insertions(+)

diff --git a/content.tex b/content.tex
index d481359..1476b0e 100644
--- a/content.tex
+++ b/content.tex
@@ -689,6 +689,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
#define VIRTIO_PCI_CAP_DEVICE_CFG 4
/* PCI configuration access */
#define VIRTIO_PCI_CAP_PCI_CFG 5
+/* Shared memory region */
+#define VIRTIO_PCI_CAP_SHARED_MEMORY_CFG 8
\end{lstlisting}

Any other value is reserved for future use.
@@ -1077,6 +1079,26 @@ \subsubsection{Device-specific configuration}\label{sec:Virtio Transport Options

The \field{offset} for the device-specific configuration MUST be 4-byte aligned.

+\subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Shared memory capability}
+
+Shared memory regions \ref{sec:Basic Facilities of a Virtio
+Device / Shared Memory Regions} are enumerated on the PCI transport
+as a sequence of VIRTIO_PCI_CAP_SHARED_MEMORY_CFG capabilities, one per region.
+
+The capability is defined by a struct virtio_pci_cap64 and
+utilises the \field{cap.id} to allow multiple shared memory
+regions per device.
+The identifier in \field{cap.id} does not denote a certain order of
+preference; it is only used to uniquely identify a region.
+
+\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{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
--
2.21.0

From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>

Define the PCI capability used for enumerating shared memory regions.

Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
---
content.tex | 22 ++++++++++++++++++++++
1 file changed, 22 insertions(+)

diff --git a/content.tex b/content.tex
index d481359..1476b0e 100644
--- a/content.tex
+++ b/content.tex
@@ -689,6 +689,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
#define VIRTIO_PCI_CAP_DEVICE_CFG 4
/* PCI configuration access */
#define VIRTIO_PCI_CAP_PCI_CFG 5
+/* Shared memory region */
+#define VIRTIO_PCI_CAP_SHARED_MEMORY_CFG 8
\end{lstlisting}

Any other value is reserved for future use.
@@ -1077,6 +1079,26 @@ \subsubsection{Device-specific configuration}\label{sec:Virtio Transport Options

The \field{offset} for the device-specific configuration MUST be 4-byte aligned.

+\subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Shared memory capability}
+
+Shared memory regions \ref{sec:Basic Facilities of a Virtio
+Device / Shared Memory Regions} are enumerated on the PCI transport
+as a sequence of VIRTIO_PCI_CAP_SHARED_MEMORY_CFG capabilities, one per region.
+
+The capability is defined by a struct virtio_pci_cap64 and
+utilises the \field{cap.id} to allow multiple shared memory
+regions per device.
+The identifier in \field{cap.id} does not denote a certain order of
+preference; it is only used to uniquely identify a region.
+
+\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{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
--
2.21.0

On Wed, 10 Jul 2019 19:32:11 +0100
"Dr. David Alan Gilbert (git)" <dgilbert@redhat.com> wrote:

> From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>
>
> Define the PCI capability used for enumerating shared memory regions.
>
> Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
> ---
> content.tex | 22 ++++++++++++++++++++++
> 1 file changed, 22 insertions(+)
>

(...)

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

Sorry about not noticing that before, but doesn't that need to be
referenced in the conformance section somewhere?

> +
> +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{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

Otherwise, looks good.

* Cornelia Huck (cohuck@redhat.com) wrote:
> On Wed, 10 Jul 2019 19:32:11 +0100
> "Dr. David Alan Gilbert (git)" <dgilbert@redhat.com> wrote:
>
> > From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>
> >
> > Define the PCI capability used for enumerating shared memory regions.
> >
> > Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
> > ---
> > content.tex | 22 ++++++++++++++++++++++
> > 1 file changed, 22 insertions(+)
> >
>
> (...)
>
> > +\devicenormative{\paragraph}{Device-specific configuration}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Shared memory capability}
>
> Sorry about not noticing that before, but doesn't that need to be
> referenced in the conformance section somewhere?

OK, new version coming up.

Dave

> > +
> > +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{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
>
> Otherwise, looks good.
--
Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK

* Cornelia Huck (cohuck@redhat.com) wrote:
> On Wed, 10 Jul 2019 19:32:11 +0100
> "Dr. David Alan Gilbert (git)" <dgilbert@redhat.com> wrote:
>
> > From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>
> >
> > Define the PCI capability used for enumerating shared memory regions.
> >
> > Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
> > ---
> > content.tex | 22 ++++++++++++++++++++++
> > 1 file changed, 22 insertions(+)
> >
>
> (...)
>
> > +\devicenormative{\paragraph}{Device-specific configuration}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Shared memory capability}
>
> Sorry about not noticing that before, but doesn't that need to be
> referenced in the conformance section somewhere?

OK, new version coming up.

Dave

> > +
> > +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{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
>
> Otherwise, looks good.
--
Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK

On Wed, 10 Jul 2019 19:32:11 +0100
"Dr. David Alan Gilbert (git)" <dgilbert@redhat.com> wrote:

> From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>
>
> Define the PCI capability used for enumerating shared memory regions.
>
> Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
> ---
> content.tex | 22 ++++++++++++++++++++++
> 1 file changed, 22 insertions(+)
>

(...)

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

Sorry about not noticing that before, but doesn't that need to be
referenced in the conformance section somewhere?

> +
> +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{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

Otherwise, looks good.

From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>

Define an MMIO interface to discover and map shared
memory regions.

Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
---
content.tex | 30 ++++++++++++++++++++++++++++++
1 file changed, 30 insertions(+)

diff --git a/content.tex b/content.tex
index 1476b0e..ee0d7c9 100644
--- a/content.tex
+++ b/content.tex
@@ -1736,6 +1736,33 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
selected by writing to \field{QueueSel}.
}
\hline
+ \mmioreg{SHMSel}{Shared memory id}{0x0ac}{W}{%
+ Writing to this register selects the shared memory region \ref{sec:Basic Facilities of a Virtio Device / Shared Memory Regions}
+ following operations on \field{SHMLenLow}, \field{SHMLenHigh},
+ \field{SHMBaseLow} and \field{SHMBaseHigh} apply to.
+ }
+ \hline
+ \mmiodreg{SHMLenLow}{SHMLenHigh}{Shared memory region 64 bit long length}{0x0b0}{0x0xb4}{R}{%
+ These registers return the length of the shared memory
+ region in bytes, as defined by the device for the region selected by
+ the \field{SHMSel} register. The lower 32 bits of the length
+ are read from \field{SHMLenLow} and the higher 32 bits from
+ \field{SHMLenHigh}. Reading from a non-existent
+ region (i.e. where the ID written to \field{SHMSel} is unused)
+ results in a length of -1.
+ }
+ \hline
+ \mmiodreg{SHMBaseLow}{SHMBaseHigh}{Shared memory region 64 bit long physical address}{0x0b8}{0x0xbc}{R}{%
+ The driver reads these registers to discover the base address
+ of the region in physical address space. This address is
+ chosen by the device (or other part of the VMM).
+ The lower 32 bits of the address are read from \field{SHMBaseLow}
+ with the higher 32 bits from \field{SHMBaseHigh}. Reading
+ from a non-existent region (i.e. where the ID written to
+ \field{SHMSel} is unused) results in a base address of
+ 0xffffffffffffffff.
+ }
+ \hline
\mmioreg{ConfigGeneration}{Configuration atomicity value}{0x0fc}{R}{
Reading from this register returns a value describing a version of the device-specific configuration space (see \field{Config}).
The driver can then access the configuration space and, when finished, read \field{ConfigGeneration} again.
@@ -1825,6 +1852,9 @@ \subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virti
and if its value is zero (0x0) MUST abort initialization and
MUST NOT access any other register.

+Drivers not expecting shared memory MUST NOT use the shared
+memory registers.
+
Further initialization MUST follow the procedure described in
\ref{sec:General Initialization And Device Operation / Device Initialization}~\nameref{sec:General Initialization And Device Operation / Device Initialization}.

--
2.21.0

From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>

Define an MMIO interface to discover and map shared
memory regions.

Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
---
content.tex | 30 ++++++++++++++++++++++++++++++
1 file changed, 30 insertions(+)

diff --git a/content.tex b/content.tex
index 1476b0e..ee0d7c9 100644
--- a/content.tex
+++ b/content.tex
@@ -1736,6 +1736,33 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
selected by writing to \field{QueueSel}.
}
\hline
+ \mmioreg{SHMSel}{Shared memory id}{0x0ac}{W}{%
+ Writing to this register selects the shared memory region \ref{sec:Basic Facilities of a Virtio Device / Shared Memory Regions}
+ following operations on \field{SHMLenLow}, \field{SHMLenHigh},
+ \field{SHMBaseLow} and \field{SHMBaseHigh} apply to.
+ }
+ \hline
+ \mmiodreg{SHMLenLow}{SHMLenHigh}{Shared memory region 64 bit long length}{0x0b0}{0x0xb4}{R}{%
+ These registers return the length of the shared memory
+ region in bytes, as defined by the device for the region selected by
+ the \field{SHMSel} register. The lower 32 bits of the length
+ are read from \field{SHMLenLow} and the higher 32 bits from
+ \field{SHMLenHigh}. Reading from a non-existent
+ region (i.e. where the ID written to \field{SHMSel} is unused)
+ results in a length of -1.
+ }
+ \hline
+ \mmiodreg{SHMBaseLow}{SHMBaseHigh}{Shared memory region 64 bit long physical address}{0x0b8}{0x0xbc}{R}{%
+ The driver reads these registers to discover the base address
+ of the region in physical address space. This address is
+ chosen by the device (or other part of the VMM).
+ The lower 32 bits of the address are read from \field{SHMBaseLow}
+ with the higher 32 bits from \field{SHMBaseHigh}. Reading
+ from a non-existent region (i.e. where the ID written to
+ \field{SHMSel} is unused) results in a base address of
+ 0xffffffffffffffff.
+ }
+ \hline
\mmioreg{ConfigGeneration}{Configuration atomicity value}{0x0fc}{R}{
Reading from this register returns a value describing a version of the device-specific configuration space (see \field{Config}).
The driver can then access the configuration space and, when finished, read \field{ConfigGeneration} again.
@@ -1825,6 +1852,9 @@ \subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virti
and if its value is zero (0x0) MUST abort initialization and
MUST NOT access any other register.

+Drivers not expecting shared memory MUST NOT use the shared
+memory registers.
+
Further initialization MUST follow the procedure described in
\ref{sec:General Initialization And Device Operation / Device Initialization}~\nameref{sec:General Initialization And Device Operation / Device Initialization}.

--
2.21.0