- Stratos-dev - op-lists.linaro.org

Re: [PATCH V3 Resend] virtio-transport: Clarify requirements

by Michael S. Tsirkin

On Mon, May 20, 2024 at 09:42:02AM +0000, Parav Pandit wrote: > Michael, > > > From: Viresh Kumar <viresh.kumar(a)linaro.org> > > Sent: Monday, May 20, 2024 3:00 PM > > To: virtio-comment(a)lists.linux.dev; virtio-dev(a)lists.linux.dev > > There is still cross posting to virtio-dev. Well we say "do not do this" in the list subscription form. Viresh, what gives? > Is the list open to community now? It's been open for a week. I think it's fair to say whoever wanted to subscribe, has subscribed. > If not, can you please send out the guidance and timeline to open it on virtio-comment list? > > This way contributors can avoid resending it multiple times. > > > Cc: Viresh Kumar <viresh.kumar(a)linaro.org>; Vincent Guittot > > <vincent.guittot(a)linaro.org>; Alex Bennée <alex.bennee(a)linaro.org>; stratos- > > dev(a)op-lists.linaro.org; Manos Pitsidianakis > > <manos.pitsidianakis(a)linaro.org>; Cornelia Huck <cohuck(a)redhat.com>; > > Michael S. Tsirkin <mst(a)redhat.com> > > Subject: [PATCH V3 Resend] virtio-transport: Clarify requirements > > > > The virtio documentation currently doesn't define any generic requirements > > that are applicable to all transports. They can be useful while adding support > > for a new transport. > > > > This commit tries to define the same. > > > > Reviewed-by: Alex Bennée <alex.bennee(a)linaro.org> > > Signed-off-by: Viresh Kumar <viresh.kumar(a)linaro.org> > > --- > > V2->V3: > > - Minor fixes. > > - Added Reviewed by from Alex. > > > > V1->V2: > > - Lot of changes after discussions with Alex and Cornelia. > > - Almost a rewrite of the first commit. > > - Add Transport normative sections. > > > > commands.tex | 3 +- > > conformance.tex | 14 +++++++++ > > content.tex | 78 > > +++++++++++++++++++++++++++++++++++++++++++++++-- > > 3 files changed, 92 insertions(+), 3 deletions(-) > > > > diff --git a/commands.tex b/commands.tex index > > 25ea8ee3bc78..b64b14424bd2 100644 > > --- a/commands.tex > > +++ b/commands.tex > > @@ -7,7 +7,8 @@ > > % How we format a field name > > \newcommand{\field}[1]{\emph{#1}} > > > > -% Mark a normative section (driver or device) > > +% Mark a normative section (driver or device, or transport) > > +\newcommand{\transportnormative}[3]{#1{Transport Requirements: > > +#2}\label{transportnormative:#3}} > > \newcommand{\drivernormative}[3]{#1{Driver Requirements: > > #2}\label{drivernormative:#3}} > > \newcommand{\devicenormative}[3]{#1{Device Requirements: > > #2}\label{devicenormative:#3}} \newcounter{clausecounter} diff --git > > a/conformance.tex b/conformance.tex index dc00e84e75ae..4a873169ce63 > > 100644 > > --- a/conformance.tex > > +++ b/conformance.tex > > @@ -11,6 +11,10 @@ \section{Conformance Targets}\label{sec:Conformance > > / Conformance Targets} > > > > Conformance targets: > > \begin{description} > > +\item[Transport] A transport MUST conform to one conformance clauses: > > + \begin{itemize} > > + \item Clause \ref{sec:Conformance / Transport Conformance}. > > + \end{itemize} > > \item[Driver] A driver MUST conform to four conformance clauses: > > \begin{itemize} > > \item Clause \ref{sec:Conformance / Driver Conformance}. > > @@ -66,6 +70,14 @@ \section{Conformance Targets}\label{sec:Conformance > > / Conformance Targets} > > \end{itemize} > > \end{description} > > > > +\conformance{\section}{Transport Conformance}\label{sec:Conformance / > > +Transport Conformance} > > + > > +A transport MUST conform to the following normative statements: > > + > > +\begin{itemize} > > +\item \ref{transportnormative:Virtio Transport Options / Virtio > > +Transport Requirements} \end{itemize} > > + > > \conformance{\section}{Driver Conformance}\label{sec:Conformance / Driver > > Conformance} > > > > A driver MUST conform to the following normative statements: > > @@ -93,6 +105,7 @@ \section{Conformance Targets}\label{sec:Conformance > > / Conformance Targets} \item \ref{drivernormative:Basic Facilities of a Virtio > > Device / Packed Virtqueues / Supplying Buffers to The Device / Sending > > Available Buffer Notifications} \item \ref{drivernormative:General Initialization > > And Device Operation / Device Initialization} \item > > \ref{drivernormative:General Initialization And Device Operation / Device > > Cleanup} > > +\item \ref{drivernormative:Virtio Transport Options / Virtio Transport > > +Requirements} > > \item \ref{drivernormative:Reserved Feature Bits} \end{itemize} > > > > @@ -172,6 +185,7 @@ \section{Conformance > > Targets}\label{sec:Conformance / Conformance Targets} \item > > \ref{devicenormative:Basic Facilities of a Virtio Device / Packed Virtqueues / > > The Virtqueue Descriptor Table} \item \ref{devicenormative:Basic Facilities of > > a Virtio Device / Packed Virtqueues / Scatter-Gather Support} \item > > \ref{devicenormative:Basic Facilities of a Virtio Device / Shared Memory > > Regions} > > +\item \ref{devicenormative:Virtio Transport Options / Virtio Transport > > +Requirements} > > \item \ref{devicenormative:Reserved Feature Bits} \end{itemize} > > > > diff --git a/content.tex b/content.tex > > index 0a62dce5f65f..a79993b5ed69 100644 > > --- a/content.tex > > +++ b/content.tex > > @@ -631,8 +631,82 @@ \section{Device Cleanup}\label{sec:General > > Initialization And Device Operation / > > > > \chapter{Virtio Transport Options}\label{sec:Virtio Transport Options} > > > > -Virtio can use various different buses, thus the standard is split -into virtio > > general and bus-specific sections. > > +Devices and drivers can use different transport methods to enable > > +interaction, for example PCI, MMIO, or Channel I/O. The transport > > +methods define various aspects of the communication between the device > > +and the driver, like device discovery, exchanging capabilities, > > +interrupt handling, data transfer, etc. For example, in a host/guest > > +architecture, the host might expose a device to the guest on a PCI bus, > > +and the guest will use a PCI-specific driver to interact with it. > > + > > +The standard is split into sections describing general virtio > > +implementation and transport-specific sections. > > + > > +\section{Virtio Transport Requirements}\label{sec:Virtio Transport > > +Options / Virtio Transport Requirements} > > + > > +\transportnormative{\subsection}{Virtio Transport Requirements}{Virtio > > +Transport Options / Virtio Transport Requirements} The transport MUST > > +provide a mechanism for the driver to discover the device. > > + > > +The transport MUST provide a mechanism for the driver to identify the > > +device type. > > + > > +The transport MUST provide a mechanism for communicating virtqueue > > +configurations between the device and the driver. > > + > > +The transport MUST allow multiple virtqueues per device. The number of > > +virtqueues for a pair of device-driver are governed by the individual > > +device protocol. > > + > > +The transport MUST provide a mechanism that the device and the driver > > +use to access memory for implementing virtqueues. > > + > > +The transport MUST provide a mechanism for the device to notify the > > +driver and a mechanism for the driver to notify the device, for example > > +regarding availability of a buffer on the virtqueue. > > + > > +The transport MAY provide a mechanism for the driver to initiate a > > +reset of the virtqueues and device. > > + > > +The transport SHOULD provide a mechanism for the driver to read the > > +device status. The transport MUST provide a mechanism for the driver to > > +change the device status. > > + > > +The transport MUST provide a mechanism to implement config space > > +between the device and the driver. > > + > > +\devicenormative{\subsection}{Virtio Transport Requirements}{Virtio > > +Transport Options / Virtio Transport Requirements} > > + > > +The device MUST keep any data associated with a device-initiated > > +transaction accessible to the driver until the driver acknowledges the > > +transaction to be complete. > > + > > +The device MUST NOT access the contents of a virtqueue before the > > +driver notifies, in a transport defined way, the device that the > > +virtqueue is ready to be accessed. > > + > > +The device MUST NOT access or modify buffers on a virtqueue after it > > +has notified the driver about their availability. > > + > > +The device MUST reset the virtqueues if requested by the driver, in a > > +transport defined way, if the transport provides such a method. > > + > > +\drivernormative{\subsection}{Virtio Transport Requirements}{Virtio > > +Transport Options / Virtio Transport Requirements} > > + > > +The driver MUST acknowledge device notifications, as mandated by the > > +transport. > > + > > +The driver MUST NOT access virtqueue contents before the device > > +notifies about the readiness of the same. > > + > > +The driver MUST NOT access buffers, after it has added them to the > > +virtqueue and notified the device about their availability. The driver > > +MAY access them after the device has processed them and notified the > > +driver of their availability, in a transport defined way. > > + > > +The driver MAY ask the device to reset the virtqueues if, for example, > > +the driver times out waiting for a notification from the device for a > > +previously queued request. > > > > \input{transport-pci.tex} > > \input{transport-mmio.tex} > > -- > > 2.31.1.272.g89b43f80a514 > > >

6 months, 3 weeks

2
1
0 0

Re: [PATCH V3 Resend] virtio-transport: Clarify requirements

by Michael S. Tsirkin

On Mon, May 20, 2024 at 12:29:35PM +0000, Parav Pandit wrote: > > > From: Michael S. Tsirkin <mst(a)redhat.com> > > Sent: Monday, May 20, 2024 5:55 PM > > > > On Mon, May 20, 2024 at 09:42:02AM +0000, Parav Pandit wrote: > > > Michael, > > > > > > > From: Viresh Kumar <viresh.kumar(a)linaro.org> > > > > Sent: Monday, May 20, 2024 3:00 PM > > > > To: virtio-comment(a)lists.linux.dev; virtio-dev(a)lists.linux.dev > > > > > > There is still cross posting to virtio-dev. > > > > Well we say "do not do this" in the list subscription form. > > Viresh, what gives? > > > > > Is the list open to community now? > > > > It's been open for a week. I think it's fair to say whoever wanted to subscribe, > > has subscribed. > > > True. I meant to ask that do contributors need to wait for patch [1] to be merged before posting patches here? > You indicated there might be voting in [2], so trying to find what is next for contributors? > > [1] https://lore.kernel.org/virtio-comment/te6tzbegqky7uz4skrag3yowet3phtq6nn7t… > [2] https://lore.kernel.org/virtio-comment/te6tzbegqky7uz4skrag3yowet3phtq6nn7t… I think we can assume existing contributors are aware of the process and we do not need to vote. I spent a day on it but could not fix the voting scripts yet. > > > If not, can you please send out the guidance and timeline to open it on virtio- > > comment list? > > > > > > This way contributors can avoid resending it multiple times. > > > > > > > Cc: Viresh Kumar <viresh.kumar(a)linaro.org>; Vincent Guittot > > > > <vincent.guittot(a)linaro.org>; Alex Bennée <alex.bennee(a)linaro.org>; > > > > stratos- dev(a)op-lists.linaro.org; Manos Pitsidianakis > > > > <manos.pitsidianakis(a)linaro.org>; Cornelia Huck <cohuck(a)redhat.com>; > > > > Michael S. Tsirkin <mst(a)redhat.com> > > > > Subject: [PATCH V3 Resend] virtio-transport: Clarify requirements > > > > > > > > The virtio documentation currently doesn't define any generic > > > > requirements that are applicable to all transports. They can be > > > > useful while adding support for a new transport. > > > > > > > > This commit tries to define the same. > > > > > > > > Reviewed-by: Alex Bennée <alex.bennee(a)linaro.org> > > > > Signed-off-by: Viresh Kumar <viresh.kumar(a)linaro.org> > > > > --- > > > > V2->V3: > > > > - Minor fixes. > > > > - Added Reviewed by from Alex. > > > > > > > > V1->V2: > > > > - Lot of changes after discussions with Alex and Cornelia. > > > > - Almost a rewrite of the first commit. > > > > - Add Transport normative sections. > > > > > > > > commands.tex | 3 +- > > > > conformance.tex | 14 +++++++++ > > > > content.tex | 78 > > > > +++++++++++++++++++++++++++++++++++++++++++++++-- > > > > 3 files changed, 92 insertions(+), 3 deletions(-) > > > > > > > > diff --git a/commands.tex b/commands.tex index > > > > 25ea8ee3bc78..b64b14424bd2 100644 > > > > --- a/commands.tex > > > > +++ b/commands.tex > > > > @@ -7,7 +7,8 @@ > > > > % How we format a field name > > > > \newcommand{\field}[1]{\emph{#1}} > > > > > > > > -% Mark a normative section (driver or device) > > > > +% Mark a normative section (driver or device, or transport) > > > > +\newcommand{\transportnormative}[3]{#1{Transport Requirements: > > > > +#2}\label{transportnormative:#3}} > > > > \newcommand{\drivernormative}[3]{#1{Driver Requirements: > > > > #2}\label{drivernormative:#3}} > > > > \newcommand{\devicenormative}[3]{#1{Device Requirements: > > > > #2}\label{devicenormative:#3}} \newcounter{clausecounter} diff > > > > --git a/conformance.tex b/conformance.tex index > > > > dc00e84e75ae..4a873169ce63 > > > > 100644 > > > > --- a/conformance.tex > > > > +++ b/conformance.tex > > > > @@ -11,6 +11,10 @@ \section{Conformance > > > > Targets}\label{sec:Conformance / Conformance Targets} > > > > > > > > Conformance targets: > > > > \begin{description} > > > > +\item[Transport] A transport MUST conform to one conformance clauses: > > > > + \begin{itemize} > > > > + \item Clause \ref{sec:Conformance / Transport Conformance}. > > > > + \end{itemize} > > > > \item[Driver] A driver MUST conform to four conformance clauses: > > > > \begin{itemize} > > > > \item Clause \ref{sec:Conformance / Driver Conformance}. > > > > @@ -66,6 +70,14 @@ \section{Conformance > > > > Targets}\label{sec:Conformance / Conformance Targets} > > > > \end{itemize} > > > > \end{description} > > > > > > > > +\conformance{\section}{Transport Conformance}\label{sec:Conformance > > > > +/ Transport Conformance} > > > > + > > > > +A transport MUST conform to the following normative statements: > > > > + > > > > +\begin{itemize} > > > > +\item \ref{transportnormative:Virtio Transport Options / Virtio > > > > +Transport Requirements} \end{itemize} > > > > + > > > > \conformance{\section}{Driver Conformance}\label{sec:Conformance / > > > > Driver Conformance} > > > > > > > > A driver MUST conform to the following normative statements: > > > > @@ -93,6 +105,7 @@ \section{Conformance > > > > Targets}\label{sec:Conformance / Conformance Targets} \item > > > > \ref{drivernormative:Basic Facilities of a Virtio Device / Packed > > > > Virtqueues / Supplying Buffers to The Device / Sending Available > > > > Buffer Notifications} \item \ref{drivernormative:General > > > > Initialization And Device Operation / Device Initialization} \item > > > > \ref{drivernormative:General Initialization And Device Operation / > > > > Device Cleanup} > > > > +\item \ref{drivernormative:Virtio Transport Options / Virtio > > > > +Transport Requirements} > > > > \item \ref{drivernormative:Reserved Feature Bits} \end{itemize} > > > > > > > > @@ -172,6 +185,7 @@ \section{Conformance > > > > Targets}\label{sec:Conformance / Conformance Targets} \item > > > > \ref{devicenormative:Basic Facilities of a Virtio Device / Packed > > > > Virtqueues / The Virtqueue Descriptor Table} \item > > > > \ref{devicenormative:Basic Facilities of a Virtio Device / Packed > > > > Virtqueues / Scatter-Gather Support} \item > > > > \ref{devicenormative:Basic Facilities of a Virtio Device / Shared > > > > Memory Regions} > > > > +\item \ref{devicenormative:Virtio Transport Options / Virtio > > > > +Transport Requirements} > > > > \item \ref{devicenormative:Reserved Feature Bits} \end{itemize} > > > > > > > > diff --git a/content.tex b/content.tex index > > > > 0a62dce5f65f..a79993b5ed69 100644 > > > > --- a/content.tex > > > > +++ b/content.tex > > > > @@ -631,8 +631,82 @@ \section{Device Cleanup}\label{sec:General > > > > Initialization And Device Operation / > > > > > > > > \chapter{Virtio Transport Options}\label{sec:Virtio Transport > > > > Options} > > > > > > > > -Virtio can use various different buses, thus the standard is split > > > > -into virtio general and bus-specific sections. > > > > +Devices and drivers can use different transport methods to enable > > > > +interaction, for example PCI, MMIO, or Channel I/O. The transport > > > > +methods define various aspects of the communication between the > > > > +device and the driver, like device discovery, exchanging > > > > +capabilities, interrupt handling, data transfer, etc. For example, > > > > +in a host/guest architecture, the host might expose a device to the > > > > +guest on a PCI bus, and the guest will use a PCI-specific driver to interact > > with it. > > > > + > > > > +The standard is split into sections describing general virtio > > > > +implementation and transport-specific sections. > > > > + > > > > +\section{Virtio Transport Requirements}\label{sec:Virtio Transport > > > > +Options / Virtio Transport Requirements} > > > > + > > > > +\transportnormative{\subsection}{Virtio Transport > > > > +Requirements}{Virtio Transport Options / Virtio Transport > > > > +Requirements} The transport MUST provide a mechanism for the driver to > > discover the device. > > > > + > > > > +The transport MUST provide a mechanism for the driver to identify > > > > +the device type. > > > > + > > > > +The transport MUST provide a mechanism for communicating virtqueue > > > > +configurations between the device and the driver. > > > > + > > > > +The transport MUST allow multiple virtqueues per device. The number > > > > +of virtqueues for a pair of device-driver are governed by the > > > > +individual device protocol. > > > > + > > > > +The transport MUST provide a mechanism that the device and the > > > > +driver use to access memory for implementing virtqueues. > > > > + > > > > +The transport MUST provide a mechanism for the device to notify the > > > > +driver and a mechanism for the driver to notify the device, for > > > > +example regarding availability of a buffer on the virtqueue. > > > > + > > > > +The transport MAY provide a mechanism for the driver to initiate a > > > > +reset of the virtqueues and device. > > > > + > > > > +The transport SHOULD provide a mechanism for the driver to read the > > > > +device status. The transport MUST provide a mechanism for the > > > > +driver to change the device status. > > > > + > > > > +The transport MUST provide a mechanism to implement config space > > > > +between the device and the driver. > > > > + > > > > +\devicenormative{\subsection}{Virtio Transport Requirements}{Virtio > > > > +Transport Options / Virtio Transport Requirements} > > > > + > > > > +The device MUST keep any data associated with a device-initiated > > > > +transaction accessible to the driver until the driver acknowledges > > > > +the transaction to be complete. > > > > + > > > > +The device MUST NOT access the contents of a virtqueue before the > > > > +driver notifies, in a transport defined way, the device that the > > > > +virtqueue is ready to be accessed. > > > > + > > > > +The device MUST NOT access or modify buffers on a virtqueue after > > > > +it has notified the driver about their availability. > > > > + > > > > +The device MUST reset the virtqueues if requested by the driver, in > > > > +a transport defined way, if the transport provides such a method. > > > > + > > > > +\drivernormative{\subsection}{Virtio Transport Requirements}{Virtio > > > > +Transport Options / Virtio Transport Requirements} > > > > + > > > > +The driver MUST acknowledge device notifications, as mandated by > > > > +the transport. > > > > + > > > > +The driver MUST NOT access virtqueue contents before the device > > > > +notifies about the readiness of the same. > > > > + > > > > +The driver MUST NOT access buffers, after it has added them to the > > > > +virtqueue and notified the device about their availability. The > > > > +driver MAY access them after the device has processed them and > > > > +notified the driver of their availability, in a transport defined way. > > > > + > > > > +The driver MAY ask the device to reset the virtqueues if, for > > > > +example, the driver times out waiting for a notification from the > > > > +device for a previously queued request. > > > > > > > > \input{transport-pci.tex} > > > > \input{transport-mmio.tex} > > > > -- > > > > 2.31.1.272.g89b43f80a514 > > > > > > >

6 months, 3 weeks

1
0
0 0

[PATCH V2] virtio-transport: Clarify requirements

by Viresh Kumar

The virtio documentation currently doesn't define any generic requirements that are applicable to all transports. They can be useful while adding support for a new transport. This commit tries to define the same. Signed-off-by: Viresh Kumar <viresh.kumar(a)linaro.org> --- V1->V2: - Lot of changes after discussions with Alex and Cornelia. - Almost a rewrite of the first commit. - Add Transport normative sections. commands.tex | 1 + conformance.tex | 14 +++++++++ content.tex | 78 +++++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 91 insertions(+), 2 deletions(-) diff --git a/commands.tex b/commands.tex index 25ea8ee3bc78..692ef0833a88 100644 --- a/commands.tex +++ b/commands.tex @@ -8,6 +8,7 @@ \newcommand{\field}[1]{\emph{#1}} % Mark a normative section (driver or device) +\newcommand{\transportnormative}[3]{#1{Transport Requirements: #2}\label{transportnormative:#3}} \newcommand{\drivernormative}[3]{#1{Driver Requirements: #2}\label{drivernormative:#3}} \newcommand{\devicenormative}[3]{#1{Device Requirements: #2}\label{devicenormative:#3}} \newcounter{clausecounter} diff --git a/conformance.tex b/conformance.tex index dc00e84e75ae..9bb1c9e2f6ec 100644 --- a/conformance.tex +++ b/conformance.tex @@ -11,6 +11,10 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} Conformance targets: \begin{description} +\item[Transport] A transport MUST conform to following conformance clauses: + \begin{itemize} + \item Clause \ref{sec:Conformance / Transport Conformance}. + \end{itemize} \item[Driver] A driver MUST conform to four conformance clauses: \begin{itemize} \item Clause \ref{sec:Conformance / Driver Conformance}. @@ -66,6 +70,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \end{itemize} \end{description} +\conformance{\section}{Transport Conformance}\label{sec:Conformance / Transport Conformance} + +A transport MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{transportnormative:Virtio Transport Options / Virtio Transport Requirements} +\end{itemize} + \conformance{\section}{Driver Conformance}\label{sec:Conformance / Driver Conformance} A driver MUST conform to the following normative statements: @@ -93,6 +105,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Sending Available Buffer Notifications} \item \ref{drivernormative:General Initialization And Device Operation / Device Initialization} \item \ref{drivernormative:General Initialization And Device Operation / Device Cleanup} +\item \ref{drivernormative:Virtio Transport Options / Virtio Transport Requirements} \item \ref{drivernormative:Reserved Feature Bits} \end{itemize} @@ -172,6 +185,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue Descriptor Table} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Packed Virtqueues / Scatter-Gather Support} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Shared Memory Regions} +\item \ref{devicenormative:Virtio Transport Options / Virtio Transport Requirements} \item \ref{devicenormative:Reserved Feature Bits} \end{itemize} diff --git a/content.tex b/content.tex index 0a62dce5f65f..a79993b5ed69 100644 --- a/content.tex +++ b/content.tex @@ -631,8 +631,82 @@ \section{Device Cleanup}\label{sec:General Initialization And Device Operation / \chapter{Virtio Transport Options}\label{sec:Virtio Transport Options} -Virtio can use various different buses, thus the standard is split -into virtio general and bus-specific sections. +Devices and drivers can use different transport methods to enable +interaction, for example PCI, MMIO, or Channel I/O. The transport +methods define various aspects of the communication between the device +and the driver, like device discovery, exchanging capabilities, +interrupt handling, data transfer, etc. For example, in a host/guest +architecture, the host might expose a device to the guest on a PCI bus, +and the guest will use a PCI-specific driver to interact with it. + +The standard is split into sections describing general virtio +implementation and transport-specific sections. + +\section{Virtio Transport Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements} + +\transportnormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options / Virtio Transport Requirements} +The transport MUST provide a mechanism for the driver to discover the +device. + +The transport MUST provide a mechanism for the driver to identify the +device type. + +The transport MUST provide a mechanism for communicating virtqueue +configurations between the device and the driver. + +The transport MUST allow multiple virtqueues per device. The number of +virtqueues for a pair of device-driver are governed by the individual +device protocol. + +The transport MUST provide a mechanism that the device and the driver +use to access memory for implementing virtqueues. + +The transport MUST provide a mechanism for the device to notify the +driver and a mechanism for the driver to notify the device, for example +regarding availability of a buffer on the virtqueue. + +The transport MAY provide a mechanism for the driver to initiate a +reset of the virtqueues and device. + +The transport SHOULD provide a mechanism for the driver to read the +device status. The transport MUST provide a mechanism for the driver to +change the device status. + +The transport MUST provide a mechanism to implement config space between +the device and the driver. + +\devicenormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options / Virtio Transport Requirements} + +The device MUST keep any data associated with a device-initiated +transaction accessible to the driver until the driver acknowledges the +transaction to be complete. + +The device MUST NOT access the contents of a virtqueue before the +driver notifies, in a transport defined way, the device that the +virtqueue is ready to be accessed. + +The device MUST NOT access or modify buffers on a virtqueue after it has +notified the driver about their availability. + +The device MUST reset the virtqueues if requested by the driver, in a +transport defined way, if the transport provides such a method. + +\drivernormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options / Virtio Transport Requirements} + +The driver MUST acknowledge device notifications, as mandated by the +transport. + +The driver MUST NOT access virtqueue contents before the device notifies +about the readiness of the same. + +The driver MUST NOT access buffers, after it has added them to the +virtqueue and notified the device about their availability. The driver +MAY access them after the device has processed them and notified the +driver of their availability, in a transport defined way. + +The driver MAY ask the device to reset the virtqueues if, for example, +the driver times out waiting for a notification from the device for a +previously queued request. \input{transport-pci.tex} \input{transport-mmio.tex} -- 2.31.1.272.g89b43f80a514

8 months, 2 weeks

3
6
0 0

[PATCH V3] virtio-transport: Clarify requirements

by Viresh Kumar

The virtio documentation currently doesn't define any generic requirements that are applicable to all transports. They can be useful while adding support for a new transport. This commit tries to define the same. Reviewed-by: Alex Bennée <alex.bennee(a)linaro.org> Signed-off-by: Viresh Kumar <viresh.kumar(a)linaro.org> --- V2->V3: - Minor fixes. - Added Reviewed by from Alex. V1->V2: - Lot of changes after discussions with Alex and Cornelia. - Almost a rewrite of the first commit. - Add Transport normative sections. commands.tex | 3 +- conformance.tex | 14 +++++++++ content.tex | 78 +++++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 92 insertions(+), 3 deletions(-) diff --git a/commands.tex b/commands.tex index 25ea8ee3bc78..b64b14424bd2 100644 --- a/commands.tex +++ b/commands.tex @@ -7,7 +7,8 @@ % How we format a field name \newcommand{\field}[1]{\emph{#1}} -% Mark a normative section (driver or device) +% Mark a normative section (driver or device, or transport) +\newcommand{\transportnormative}[3]{#1{Transport Requirements: #2}\label{transportnormative:#3}} \newcommand{\drivernormative}[3]{#1{Driver Requirements: #2}\label{drivernormative:#3}} \newcommand{\devicenormative}[3]{#1{Device Requirements: #2}\label{devicenormative:#3}} \newcounter{clausecounter} diff --git a/conformance.tex b/conformance.tex index dc00e84e75ae..4a873169ce63 100644 --- a/conformance.tex +++ b/conformance.tex @@ -11,6 +11,10 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} Conformance targets: \begin{description} +\item[Transport] A transport MUST conform to one conformance clauses: + \begin{itemize} + \item Clause \ref{sec:Conformance / Transport Conformance}. + \end{itemize} \item[Driver] A driver MUST conform to four conformance clauses: \begin{itemize} \item Clause \ref{sec:Conformance / Driver Conformance}. @@ -66,6 +70,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \end{itemize} \end{description} +\conformance{\section}{Transport Conformance}\label{sec:Conformance / Transport Conformance} + +A transport MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{transportnormative:Virtio Transport Options / Virtio Transport Requirements} +\end{itemize} + \conformance{\section}{Driver Conformance}\label{sec:Conformance / Driver Conformance} A driver MUST conform to the following normative statements: @@ -93,6 +105,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Sending Available Buffer Notifications} \item \ref{drivernormative:General Initialization And Device Operation / Device Initialization} \item \ref{drivernormative:General Initialization And Device Operation / Device Cleanup} +\item \ref{drivernormative:Virtio Transport Options / Virtio Transport Requirements} \item \ref{drivernormative:Reserved Feature Bits} \end{itemize} @@ -172,6 +185,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue Descriptor Table} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Packed Virtqueues / Scatter-Gather Support} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Shared Memory Regions} +\item \ref{devicenormative:Virtio Transport Options / Virtio Transport Requirements} \item \ref{devicenormative:Reserved Feature Bits} \end{itemize} diff --git a/content.tex b/content.tex index 0a62dce5f65f..a79993b5ed69 100644 --- a/content.tex +++ b/content.tex @@ -631,8 +631,82 @@ \section{Device Cleanup}\label{sec:General Initialization And Device Operation / \chapter{Virtio Transport Options}\label{sec:Virtio Transport Options} -Virtio can use various different buses, thus the standard is split -into virtio general and bus-specific sections. +Devices and drivers can use different transport methods to enable +interaction, for example PCI, MMIO, or Channel I/O. The transport +methods define various aspects of the communication between the device +and the driver, like device discovery, exchanging capabilities, +interrupt handling, data transfer, etc. For example, in a host/guest +architecture, the host might expose a device to the guest on a PCI bus, +and the guest will use a PCI-specific driver to interact with it. + +The standard is split into sections describing general virtio +implementation and transport-specific sections. + +\section{Virtio Transport Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements} + +\transportnormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options / Virtio Transport Requirements} +The transport MUST provide a mechanism for the driver to discover the +device. + +The transport MUST provide a mechanism for the driver to identify the +device type. + +The transport MUST provide a mechanism for communicating virtqueue +configurations between the device and the driver. + +The transport MUST allow multiple virtqueues per device. The number of +virtqueues for a pair of device-driver are governed by the individual +device protocol. + +The transport MUST provide a mechanism that the device and the driver +use to access memory for implementing virtqueues. + +The transport MUST provide a mechanism for the device to notify the +driver and a mechanism for the driver to notify the device, for example +regarding availability of a buffer on the virtqueue. + +The transport MAY provide a mechanism for the driver to initiate a +reset of the virtqueues and device. + +The transport SHOULD provide a mechanism for the driver to read the +device status. The transport MUST provide a mechanism for the driver to +change the device status. + +The transport MUST provide a mechanism to implement config space between +the device and the driver. + +\devicenormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options / Virtio Transport Requirements} + +The device MUST keep any data associated with a device-initiated +transaction accessible to the driver until the driver acknowledges the +transaction to be complete. + +The device MUST NOT access the contents of a virtqueue before the +driver notifies, in a transport defined way, the device that the +virtqueue is ready to be accessed. + +The device MUST NOT access or modify buffers on a virtqueue after it has +notified the driver about their availability. + +The device MUST reset the virtqueues if requested by the driver, in a +transport defined way, if the transport provides such a method. + +\drivernormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options / Virtio Transport Requirements} + +The driver MUST acknowledge device notifications, as mandated by the +transport. + +The driver MUST NOT access virtqueue contents before the device notifies +about the readiness of the same. + +The driver MUST NOT access buffers, after it has added them to the +virtqueue and notified the device about their availability. The driver +MAY access them after the device has processed them and notified the +driver of their availability, in a transport defined way. + +The driver MAY ask the device to reset the virtqueues if, for example, +the driver times out waiting for a notification from the device for a +previously queued request. \input{transport-pci.tex} \input{transport-mmio.tex} -- 2.31.1.272.g89b43f80a514

10 months

1
0
0 0

[PATCH] virtio-transport: Clarify requirements

by Viresh Kumar

The virtio documentation currently doesn't define any generic requirements that are applicable to all transports. They can be useful while adding support for a new transport. This commit tries to define the same. Signed-off-by: Viresh Kumar <viresh.kumar(a)linaro.org> --- content.tex | 48 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/content.tex b/content.tex index 0a62dce5f65f..d4d5e7d7045b 100644 --- a/content.tex +++ b/content.tex @@ -631,8 +631,52 @@ \section{Device Cleanup}\label{sec:General Initialization And Device Operation / \chapter{Virtio Transport Options}\label{sec:Virtio Transport Options} -Virtio can use various different buses, thus the standard is split -into virtio general and bus-specific sections. +The virtio devices are exposed to the guest as if they are physical +devices using a specific transport method, like PCI, MMIO or Channel +I/O. The transport methods define various aspects of the communication +between the device and the driver, like device discovery, exchanging +capabilities, interrupt handling, data transfer, etc.. Virtio can use +various different buses, thus the standard is split into virtio general +and bus-specific sections. + +\section{Virtio Transport Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements} + +\devicenormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options} + +The device MUST present each event, in a transport defined way, from the +moment it takes place until the driver acknowledges the event. + +The device MUST NOT access virtqueue's contents before the driver +notifies that the queue is ready for access, in a transport defined way. + +The device MUST NOT access buffers on the virtqueue, after it has +modified them and notified the driver about their availability. + +The device MUST reset the virtqueues if requested by the driver, in a +transport defined way. + +\drivernormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options} + +The driver MUST NOT access guest memory locations outside what's made +available by the device to the driver. + +The driver MUST NOT write to the read-only memory area and MUST NOT read +from the write-only memory area. + +The driver MUST acknowledge events presented by the device, as mandated +by the transport. + +The driver MUST NOT access virtqueue contents before the device notifies +about the readiness of the same. + +The driver MUST NOT access buffers, after it has added them to the +virtqueue and notified the device about their availability. The driver +MAY access them after the device has processed them and notified the +driver of their availability, in a transport defined way. + +The driver MAY ask the device to reset the virtqueues if, for example, +the driver times out waiting for a notification from the device for a +previously queued request. \input{transport-pci.tex} \input{transport-mmio.tex} -- 2.31.1.272.g89b43f80a514

10 months, 2 weeks

4
13
0 0

[PATCH] virtio-transport: Clarify requirements

by Viresh Kumar

The virtio documentation currently doesn't define any generic requirements that are applicable to all transports. These may be useful while adding support for a new transport. This commit tries to define the same. Signed-off-by: Viresh Kumar <viresh.kumar(a)linaro.org> --- Alex, Sending it to Stratos list first to get some initial feedback. content.tex | 48 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/content.tex b/content.tex index 0a62dce5f65f..489028b6ef3f 100644 --- a/content.tex +++ b/content.tex @@ -631,8 +631,52 @@ \section{Device Cleanup}\label{sec:General Initialization And Device Operation / \chapter{Virtio Transport Options}\label{sec:Virtio Transport Options} -Virtio can use various different buses, thus the standard is split -into virtio general and bus-specific sections. +The virtio devices are exposed to the guest as if they are physical +devices using a specific transport method, like PCI, MMIO or Channel +I/O. The transport methods define various aspects of communication +between the device and the driver, like device discovery, exchanging +capabilities, interrupt handling, and data transfer. Virtio can use +various different buses, thus the standard is split into virtio general +and bus-specific sections. + +\section{Virtio Transport Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements} + +\devicenormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options} + +The device MUST present each event, in a transport defined way, from the +moment it takes place until the driver acknowledges the interrupt, in a +transport defined way. + +The device MUST NOT access virtqueue contents before the driver notifies +that the queue is ready for access, in a transport defined way. + +The device MUST NOT access buffers previously modified on the queue by +it, after it has notified the driver about their availability. + +The device MUST reset the virtqueues if asked by the driver, in a +transport defined way. + +\drivernormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options} + +The driver MUST NOT access memory locations outside what's presented by +the device. + +The driver MUST NOT write to the read-only registers and MUST NOT read +from the write-only registers. + +The driver MUST acknowledge events presented by the device, as mandated +by the transport. + +The driver MUST NOT access virtqueue contents before the device notifies +that the queue is ready for access, in a transport defined way. + +The driver MUST NOT access buffers previously added to the queue by the +driver, after it has notified the device about their availability. The +driver MAY access the same after the device has processed them and +notified the same to the driver, in a transport defined way. + +The driver MAY ask the device to reset the virtqueues, in a transport +defined way. \input{transport-pci.tex} \input{transport-mmio.tex} -- 2.31.1.272.g89b43f80a514

1 year, 1 month

3
6
0 0

vhost-device-rng crashes on QEMU > 7.2.0

by Mathieu Poirier

Hey guys, I tried to start the vhost-device-rng daemon with QEMU v8.1.0 when I noticed that upon startup QEMU crashes [1]. The last known good version is v7.2.0. A bisect session between the two tags yielded this commit [2]. In that patch the hunk that starts at line 1176 adds a call to virtio_pci_set_guest_notifier() with a second parameter of VIRTIO_CONFIG_IRQ_IDX, which is -1. That call trickles down to function vhost_user_get_vq_index() [3] where the assert is generated. I am guessing that all the pci based vhost-devices would be affected by this change, hence this email. Has anyone seen this when using a version of QEMU that is higher than v7.2.0? To reproduce, start the vhost-device-rng with: $ ./vhost-device-rng --socket-path=$(PATH_TO_SOCKET)/rng.sock -c 1 -m 512 -p 1000 And in another shell start qemu v8.1.0 with something that looks like this[4], with line 7 to 10 being the most important. Here I'm using RNG but I suppose any of the vhost-devices would be affected by this. I'll wait to hear back from you guys before I make a fool of myself on the QEMU failing list. Thanks, Mathieu [1]. https://pastebin.linaro.org/view/4d39b814 [2]. 1680542862ed virtio-pci: add support for configure interrupt [3]. https://github.com/qemu/qemu/blob/v8.0.0/hw/virtio/vhost-user.c#L2152 [4]. https://pastebin.linaro.org/view/a15db9b0

1 year, 1 month

2
3
0 0

[PATCH V3 1/3] xen-ioctl: Privatize config_irqfd()

by Viresh Kumar

It isn't required to be exposed to client modules, privatize it. Signed-off-by: Viresh Kumar <viresh.kumar(a)linaro.org> --- V3: New commit crates/xen-ioctls/src/xdm/xdm.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/xen-ioctls/src/xdm/xdm.rs b/crates/xen-ioctls/src/xdm/xdm.rs index 3aa5289794fe..06b589967dde 100644 --- a/crates/xen-ioctls/src/xdm/xdm.rs +++ b/crates/xen-ioctls/src/xdm/xdm.rs @@ -242,7 +242,7 @@ impl XenDeviceModelHandle { do_dm_op(&self.fd, domid, &mut privcmd_dm_op_buffers) } - pub fn config_irqfd( + fn config_irqfd( &self, fd: EventFd, domid: u16, -- 2.31.1.272.g89b43f80a514

1 year, 1 month

2
3
0 0

[PATCH 1/2] xen-ioctl: Fix IOCTL macro for irqfd

by Viresh Kumar

The kernel's irqfd macro has changed a bit. Make a corresponding change here too. Signed-off-by: Viresh Kumar <viresh.kumar(a)linaro.org> --- Mathieu, You can apply these patches now. Thanks. crates/xen-ioctls/src/private.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/crates/xen-ioctls/src/private.rs b/crates/xen-ioctls/src/private.rs index 59a75f67f18d..50833e750f2d 100644 --- a/crates/xen-ioctls/src/private.rs +++ b/crates/xen-ioctls/src/private.rs @@ -12,7 +12,7 @@ use libc::{c_ulong, c_void, ioctl, mmap, munmap, MAP_SHARED, PROT_READ, PROT_WRI use std::fs::OpenOptions; use std::io::Error; use std::os::unix::io::AsRawFd; -use vmm_sys_util::ioctl::_IOC_NONE; +use vmm_sys_util::ioctl::{_IOC_NONE, _IOC_WRITE}; use crate::xdm::types::{PrivcmdDeviceModelIrqFd, PrivcmdDeviceModelOp}; use crate::xfm::types::{PrivCmdMmapBatchV2, PrivCmdMmapResource}; @@ -74,12 +74,11 @@ ioctl_ioc_nr!( ); /* - * #define IOCTL_PRIVCMD_IRQFD \ - * _IOC(_IOC_NONE, 'P', 8, sizeof(privcmd_irqfd_t)) + * #define IOCTL_PRIVCMD_IRQFD _IOW('P', 8, privcmd_irqfd_t) */ ioctl_ioc_nr!( IOCTL_PRIVCMD_IRQFD, - _IOC_NONE, + _IOC_WRITE, XEN_PRIVCMD_TYPE, 8 as u32, std::mem::size_of::<PrivcmdDeviceModelIrqFd>() as u32 -- 2.31.1.272.g89b43f80a514

1 year, 1 month

2
2
0 0

[PATCH V4 0/4] xen: privcmd: Add ioeventfd and fix irqfd support

by Viresh Kumar

Hello, Now that irqfd support (backend to guest interrupt) is already merged, this series solves the other part of the problem, i.e. ioeventfd (guest to backend interrupt). More details inside the commits. Arnd reported few issues with the ioctl macro usage and argument's layout, fixed them for irqfd too, which was added recently. -- Viresh V3->V4: - Use __u64 for indirect pointers in an ioctl command's arguments. - Use u64_to_user_ptr() in kernel driver to access the same. - Use _IOW() macro instead of the internal one: _IOC(). V2->V3: - Remove explicit barriers and depend on spin lock instead to take care of it. - Move check for empty ioeventfds list to privcmd_ioeventfd_deassign(), which could earlier call ioreq_free() even when the list wasn't empty and so we returned without printing a warning in v1 earlier. V2 implemented it incorrectly. V1->V2: - Increment irq_info refcnt only for valid info. - Use u64 type for addr. - Add comments for use of barriers. - Use spin lock instead of mutex as we need to use them in irq handler. - Add a warning when kioreq is getting freed and ioeventfds list isn't empty. - Use struct_size(). - Validate number of vcpus as well. Viresh Kumar (4): xen: Make struct privcmd_irqfd's layout architecture independent xen: irqfd: Use _IOW instead of the internal _IOC() macro xen: evtchn: Allow shared registration of IRQ handers xen: privcmd: Add support for ioeventfd drivers/xen/Kconfig | 8 +- drivers/xen/events/events_base.c | 3 +- drivers/xen/evtchn.c | 2 +- drivers/xen/privcmd.c | 407 +++++++++++++++++++++++++++++- include/uapi/xen/privcmd.h | 22 +- include/xen/interface/hvm/ioreq.h | 51 ++++ 6 files changed, 482 insertions(+), 11 deletions(-) create mode 100644 include/xen/interface/hvm/ioreq.h -- 2.31.1.272.g89b43f80a514

1 year, 1 month

2
8
0 0

2024

2023

2022

2021

2020

Stratos-dev