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@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}
On Fri Nov 3, 2023 at 11:42 AM CET, Viresh Kumar wrote:
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@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.
I get what this is trying to state, but I am worried whether this is a bit ambigious... A driver surely will access driver-private, virtio-unrelated data, right? Also, what does "presented" mean? I wonder whether the following requirements do not already cover what this statement is stating. So maybe this can simply be dropped?
+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.
Is there no escape hatch here? What happens, for example, if the device fails to respond? Can the driver forcibly regain access, for example, by resetting the device? The way the statement is currently written it seems to disallow any recovery from a hung or dead device.
+The driver MAY ask the device to reset the virtqueues, in a transport +defined way. \input{transport-pci.tex} \input{transport-mmio.tex}
For clarification, in case there is any doubt:
Device - the backend running on the host. Driver - the guest kernel driver (frontend).
On 08-11-23, 08:41, Erik Schilling wrote:
On Fri Nov 3, 2023 at 11:42 AM CET, Viresh Kumar wrote:
+The driver MUST NOT access memory locations outside what's presented by +the device.
I get what this is trying to state, but I am worried whether this is a bit ambigious... A driver surely will access driver-private, virtio-unrelated data, right?
Yeah, but that isn't part of backend's memory but the guest itself. The spec doesn't need to talk about such a memory.
Also, what does "presented" mean?
Made available for the frontend to use. This word is used few times in the spec, maybe I should choose a different word here ?
I wonder whether the following requirements do not already cover what this statement is stating. So maybe this can simply be dropped?
The below ones don't talk about invalid access to memory over what is allowed. Or am I missing something ?
+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.
Is there no escape hatch here? What happens, for example, if the device fails to respond? Can the driver forcibly regain access, for example, by resetting the device? The way the statement is currently written it seems to disallow any recovery from a hung or dead device.
There is virtqueue reset option. I guess that's what gets used in such circumstances. Wonder if I should talk about it here.
I should probably have prefixed my last mail with:
All my comments are of minor nature. Your suggestions overall sound fine to me. I am only trying to point out passages where someone amibigious understanding remains - at least when reading each statement with a slightly adversarial stance.
On Wed Nov 8, 2023 at 8:55 AM CET, Viresh Kumar wrote:
For clarification, in case there is any doubt:
Device - the backend running on the host. Driver - the guest kernel driver (frontend).
On 08-11-23, 08:41, Erik Schilling wrote:
On Fri Nov 3, 2023 at 11:42 AM CET, Viresh Kumar wrote:
+The driver MUST NOT access memory locations outside what's presented by +the device.
I get what this is trying to state, but I am worried whether this is a bit ambigious... A driver surely will access driver-private, virtio-unrelated data, right?
Yeah, but that isn't part of backend's memory but the guest itself. The spec doesn't need to talk about such a memory.
Exactly :). But my feeling was that - strictly speaking - the statement may be understood in that way.
Also, what does "presented" mean?
Made available for the frontend to use. This word is used few times in the spec, maybe I should choose a different word here ?
Ok, if it has established use then that is fine. I am a bit confused though... Why do we need to restrict access to memory that is NOT presented? The device won't see memory that was not presented to it by the driver. Or am I misunderstanding the term here? What is the difference between driver-private memory and memory not presented to the device?
I have not found a clear definition of what is meant by "presenting" in the remaining spec. So chances are that I am misunderstanding something here.
I wonder whether the following requirements do not already cover what this statement is stating. So maybe this can simply be dropped?
The below ones don't talk about invalid access to memory over what is allowed. Or am I missing something ?
Hm... Which kind of invalid access is not covered? Data outside of virtqueues but still in a shared page? I guess this may be related to my confusion above.
+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.
Is there no escape hatch here? What happens, for example, if the device fails to respond? Can the driver forcibly regain access, for example, by resetting the device? The way the statement is currently written it seems to disallow any recovery from a hung or dead device.
There is virtqueue reset option. I guess that's what gets used in such circumstances. Wonder if I should talk about it here.
I was mostly pointing out that if reset allows to restore access, then that should probably be mentioned somewhere. Currently you ONLY define that access may happen again after the device cooperated and sent a notification. No other method is legal with this statement.
- Erik
On 08-11-23, 09:19, Erik Schilling wrote:
I should probably have prefixed my last mail with:
All my comments are of minor nature. Your suggestions overall sound fine to me. I am only trying to point out passages where someone amibigious understanding remains - at least when reading each statement with a slightly adversarial stance.
Thanks for your feedback Erik :)
On Wed Nov 8, 2023 at 8:55 AM CET, Viresh Kumar wrote:
For clarification, in case there is any doubt:
Device - the backend running on the host. Driver - the guest kernel driver (frontend).
On 08-11-23, 08:41, Erik Schilling wrote:
On Fri Nov 3, 2023 at 11:42 AM CET, Viresh Kumar wrote:
+The driver MUST NOT access memory locations outside what's presented by +the device.
I get what this is trying to state, but I am worried whether this is a bit ambigious... A driver surely will access driver-private, virtio-unrelated data, right?
Yeah, but that isn't part of backend's memory but the guest itself. The spec doesn't need to talk about such a memory.
Exactly :). But my feeling was that - strictly speaking - the statement may be understood in that way.
Also, what does "presented" mean?
Made available for the frontend to use. This word is used few times in the spec, maybe I should choose a different word here ?
Ok, if it has established use then that is fine. I am a bit confused though... Why do we need to restrict access to memory that is NOT presented? The device won't see memory that was not presented to it by
s/device/driver/ ?
the driver. Or am I misunderstanding the term here? What is the
s/driver/device/ ?
difference between driver-private memory and memory not presented to the device?
I have not found a clear definition of what is meant by "presenting" in the remaining spec. So chances are that I am misunderstanding something here.
Just to clarify, what we are talking about is the device memory accessible at the driver. For a MMIO device, it is a range of length 0x200 per device. The MMIO section also says this:
"The driver MUST NOT access memory locations not described in the table 4.1."
The table here talks about the memory space of 0x200 bytes.
What I am trying to say is that the driver shouldn't try to access anything beyond this 0x200 memory region. Not sure how it works for PCI and Channel I/O though.
I wonder whether the following requirements do not already cover what this statement is stating. So maybe this can simply be dropped?
The below ones don't talk about invalid access to memory over what is allowed. Or am I missing something ?
Hm... Which kind of invalid access is not covered? Data outside of virtqueues but still in a shared page? I guess this may be related to my confusion above.
Maybe that, or maybe outside the shared page too..
There is virtqueue reset option. I guess that's what gets used in such circumstances. Wonder if I should talk about it here.
I was mostly pointing out that if reset allows to restore access, then that should probably be mentioned somewhere. Currently you ONLY define that access may happen again after the device cooperated and sent a notification. No other method is legal with this statement.
Yeah, I should clarify that.
On Wed Nov 8, 2023 at 10:37 AM CET, Viresh Kumar wrote:
On Wed Nov 8, 2023 at 8:55 AM CET, Viresh Kumar wrote:
For clarification, in case there is any doubt:
Device - the backend running on the host. Driver - the guest kernel driver (frontend).
On 08-11-23, 08:41, Erik Schilling wrote:
On Fri Nov 3, 2023 at 11:42 AM CET, Viresh Kumar wrote:
+The driver MUST NOT access memory locations outside what's presented by +the device.
I get what this is trying to state, but I am worried whether this is a bit ambigious... A driver surely will access driver-private, virtio-unrelated data, right?
Yeah, but that isn't part of backend's memory but the guest itself. The spec doesn't need to talk about such a memory.
Exactly :). But my feeling was that - strictly speaking - the statement may be understood in that way.
Also, what does "presented" mean?
Made available for the frontend to use. This word is used few times in the spec, maybe I should choose a different word here ?
Ok, if it has established use then that is fine. I am a bit confused though... Why do we need to restrict access to memory that is NOT presented? The device won't see memory that was not presented to it by
s/device/driver/ ?
Yes.
the driver. Or am I misunderstanding the term here? What is the
s/driver/device/ ?
Also yes... I need more tea...
difference between driver-private memory and memory not presented to the device?
I have not found a clear definition of what is meant by "presenting" in the remaining spec. So chances are that I am misunderstanding something here.
Just to clarify, what we are talking about is the device memory accessible at the driver. For a MMIO device, it is a range of length 0x200 per device. The MMIO section also says this:
"The driver MUST NOT access memory locations not described in the table 4.1."
The table here talks about the memory space of 0x200 bytes.
What I am trying to say is that the driver shouldn't try to access anything beyond this 0x200 memory region. Not sure how it works for PCI and Channel I/O though.
OK. I fear I have no suggestions on how to make that more clear... Maybe just sneaking in a "shared memory" somewhere makes the intent a little more clear. But it still seems to remain somewhat fuzzy...
On Wed, 08 Nov 2023 09:55, Viresh Kumar viresh.kumar@linaro.org wrote:
On 08-11-23, 08:41, Erik Schilling wrote:
On Fri Nov 3, 2023 at 11:42 AM CET, Viresh Kumar wrote:
+The driver MUST NOT access memory locations outside what's presented by +the device.
I get what this is trying to state, but I am worried whether this is a bit ambigious... A driver surely will access driver-private, virtio-unrelated data, right?
Yeah, but that isn't part of backend's memory but the guest itself. The spec doesn't need to talk about such a memory.
Maybe for completeness, you can add "MUST NOT access memory locations of the transport"?
Also, what does "presented" mean?
Made available for the frontend to use. This word is used few times in the spec, maybe I should choose a different word here ?
"Made available" is much more descriptive indeed. I'd also add "[Made available] to be accessed and acknowledged by the driver."
stratos-dev@op-lists.linaro.org
-
Erik Schilling -
Manos Pitsidianakis -
Viresh Kumar