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

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

by Viresh Kumar

On 29-05-24, 12:42, Stefano Garzarella wrote: > mmm, I had interpreted this statement as if we could: > > The transport MAY provide a mechanism for the driver to initiate a > reset of the virtqueues and device. > > IIUC device reset is always supported (see `\section{Device Reset}` in > content.txt) and it's transport specific. While single virtqueue reset > depends on VIRTIO_F_RING_RESET. Done, thanks. -- viresh

6 months, 2 weeks

1
0
0 0

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

by Viresh Kumar

On 29-05-24, 13:12, Matias Ezequiel Vara Larsen wrote: > > +The driver doesn't 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. > > + > > I think last sentence could be rewritten as: > - The driver accesses queued buffers after the device has processed them > and notified the driver of their availability. This mechanism is > transport defined. > > > > +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. > > > > I would rewrite last sentence as: > - The driver asks 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. > > > With that, LGTM! Done. Thanks. -- viresh

6 months, 2 weeks

1
0
0 0

[PATCH V3 Resend] 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

6 months, 2 weeks

3
5
0 0

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

by Viresh Kumar

Dropped virtio-dev list. On 20-05-24, 12:20, Stefano Garzarella wrote: > I haven't followed v1 and v2, so apologies in advance if my comments have > already been discussed. No issues. > On Mon, May 20, 2024 at 02:59:40PM GMT, Viresh Kumar wrote: > > +\transportnormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options / Virtio Transport Requirements} > > +The transport MUST provide a mechanism for the driver to discover the > > +device. > > This seems a little too stringent. For example, does MMIO offer a discovery > mechanism? IIRC we have to pass the address via device tree or kernel > command line. Right. Is converting this to SHOULD okay or do you suggest some other change ? > > +The transport MUST provide a mechanism to implement config space > > "configuration space" Sure. > > 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 > > Should we also talk about the possibility of resetting the entire device? Do we support that today ? Maybe we can if the maintainers agree. -- viresh

6 months, 3 weeks

1
0
0 0

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

2024

2023

2022

2021

2020

Stratos-dev May 2024