OASIS Virtual I/O Device (VIRTIO) TC

Those changes do not add nor remove any features and constitutes only error correction and editorial changes. * Extra clarifications for QueueReady and ConfigGeneration * Added alignment requirement section, to formalise hidden assumptions about register accesses Signed-off-by: Pawel Moll <pawel.moll@arm.com> --- content.tex 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/content.tex b/content.tex index 17ba3b8..9220691 100644 --- a/content.tex +++ b/content.tex @@ -1997,8 +1997,8 @@ All register values are organized as Little Endian. } hline mmioreg{QueueReady}{Virtual queue ready bit}{0x044}{RW}{% - Writing one (0x1) to this register notifies the device that the - virtual queue is ready to be used. Reading from this register + Writing one (0x1) to this register notifies the device that it can + execute requests from this virtual queue. Reading from this register returns the last value written to it. Both read and write accesses apply to the queue selected by writing to field{QueueSel}. } @@ -2058,7 +2058,11 @@ All register values are organized as Little Endian. } hline mmioreg{ConfigGeneration}{Configuration atomicity value}{0x0fc}{R}{ - Changes every time the configuration noticeably changes (see
ef {sec:Basic Facilities of a Virtio Device / Device Configuration Space}. + Reading from this register returns a value describing a version of the device-specific configuration space (see field{Config}). + The driver can then access the configuration space and, when finished, read field{ConfigGeneration} again. + If no part of the configuration space has changed between these two field{ConfigGeneration} reads, the returned values are identical. + If the values are different, the configuration space accesses were not atomic and the driver has to perform the operations again. + See also
ef {sec:Basic Facilities of a Virtio Device / Device Configuration Space}. } hline mmioreg{Config}{Configuration space}{0x100+}{RW}{ @@ -2083,9 +2087,10 @@ do not represent events which took place MUST be zero. Upon reset, the device MUST clear all bits in field{InterruptStatus} and ready bits in the field{QueueReady} register for all queues in the device. -The device MUST change field{ConfigGeneration} if there is any risk of a -device seeing an inconsistent configuration state, but it MAY only change the value -after a configuration read operation. +The device MUST change value returned in field{ConfigGeneration} if there is any risk of a +driver seeing an inconsistent configuration state. + +The device MUST NOT access virtual queue contents when field{QueueReady} is zero (0x0). drivernormative{subsubsection}{MMIO Device Register Layout}{Virtio Transport Options / Virtio Over MMIO / MMIO Device Register Layout} The driver MUST NOT access memory locations not described in the @@ -2094,6 +2099,15 @@ table
ef{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Register MUST NOT write to the read-only registers (direction R) and MUST NOT read from the write-only registers (direction W). +The driver MUST only use 32 bit wide and aligned reads and writes to access the control registers +described in table
ef{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Register Layout}. +For the device-specific configuration space, the driver MUST use 8 bit wide accesses for +8 bit wide fields, 16 bit wide and aligned accesses for 16 bit wide fields and 32 bit wide and +aligned accesses for 32 and 64 bit wide fields. + +The driver MAY use other accesses for the device-specific configuration space, +depending on the device type. + The driver MUST ignore a device with field{MagicValue} which is not 0x74726976, although it MAY report an error. -- 1.9.1

On Tue, Aug 05, 2014 at 02:23:55PM +0100, Pawel Moll wrote: > Those changes do not add nor remove any features and constitutes > only error correction and editorial changes. > > * Extra clarifications for QueueReady and ConfigGeneration > * Added alignment requirement section, to formalise > hidden assumptions about register accesses > > Signed-off-by: Pawel Moll <pawel.moll@arm.com> > --- > content.tex 26 ++++++++++++++++++++------ > 1 file changed, 20 insertions(+), 6 deletions(-) > > diff --git a/content.tex b/content.tex > index 17ba3b8..9220691 100644 > --- a/content.tex > +++ b/content.tex > @@ -1997,8 +1997,8 @@ All register values are organized as Little Endian. > } > hline > mmioreg{QueueReady}{Virtual queue ready bit}{0x044}{RW}{% > - Writing one (0x1) to this register notifies the device that the > - virtual queue is ready to be used. Reading from this register > + Writing one (0x1) to this register notifies the device that it can > + execute requests from this virtual queue. Reading from this register > returns the last value written to it. Both read and write > accesses apply to the queue selected by writing to field{QueueSel}. > } > @@ -2058,7 +2058,11 @@ All register values are organized as Little Endian. > } > hline > mmioreg{ConfigGeneration}{Configuration atomicity value}{0x0fc}{R}{ > - Changes every time the configuration noticeably changes (see
ef {sec:Basic Facilities of a Virtio Device / Device Configuration Space}. > + Reading from this register returns a value describing a version of the device-specific configuration space (see field{Config}). > + The driver can then access the configuration space and, when finished, read field{ConfigGeneration} again. > + If no part of the configuration space has changed between these two field{ConfigGeneration} reads, the returned values are identical. > + If the values are different, the configuration space accesses were not atomic and the driver has to perform the operations again. > + See also
ef {sec:Basic Facilities of a Virtio Device / Device Configuration Space}. > } > hline > mmioreg{Config}{Configuration space}{0x100+}{RW}{ > @@ -2083,9 +2087,10 @@ do not represent events which took place MUST be zero. > Upon reset, the device MUST clear all bits in field{InterruptStatus} and ready bits in the > field{QueueReady} register for all queues in the device. > > -The device MUST change field{ConfigGeneration} if there is any risk of a > -device seeing an inconsistent configuration state, but it MAY only change the value > -after a configuration read operation. > +The device MUST change value returned in field{ConfigGeneration} if there is any risk of a > +driver seeing an inconsistent configuration state. > + > +The device MUST NOT access virtual queue contents when field{QueueReady} is zero (0x0). > > drivernormative{subsubsection}{MMIO Device Register Layout}{Virtio Transport Options / Virtio Over MMIO / MMIO Device Register Layout} > The driver MUST NOT access memory locations not described in the > @@ -2094,6 +2099,15 @@ table
ef{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Register > MUST NOT write to the read-only registers (direction R) and > MUST NOT read from the write-only registers (direction W). > > +The driver MUST only use 32 bit wide and aligned reads and writes to access the control registers > +described in table
ef{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Register Layout}. > +For the device-specific configuration space, the driver MUST use 8 bit wide accesses for > +8 bit wide fields, 16 bit wide and aligned accesses for 16 bit wide fields and 32 bit wide and > +aligned accesses for 32 and 64 bit wide fields. > + > +The driver MAY use other accesses for the device-specific configuration space, > +depending on the device type. > + Could you please clarify what this last phrase means? Do you perhaps mean device MAY accept other accesses? > The driver MUST ignore a device with field{MagicValue} which is not 0x74726976, > although it MAY report an error. > > -- > 1.9.1 > > > --------------------------------------------------------------------- > To unsubscribe from this mail list, you must leave the OASIS TC that > generates this mail. Follow this link to all your TCs in OASIS at: > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

On Sat, 2014-08-09 at 23:42 +0100, Michael S. Tsirkin wrote: > > +The driver MAY use other accesses for the device-specific configuration space, > > +depending on the device type. > > + > > Could you please clarify what this last phrase means? > Do you perhaps mean device MAY accept other accesses? Oh damn, forgot to remove it, it's replaced by the one enumerating sizes. Had a rather bad week, sorry. Posting v3 now. Pawel

Those changes do not add nor remove any features and constitutes only error correction and editorial changes. * Extra clarifications for QueueReady and ConfigGeneration * Added alignment requirement section, to formalise hidden assumptions about register accesses Signed-off-by: Pawel Moll <pawel.moll@arm.com> --- content.tex 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/content.tex b/content.tex index 17ba3b8..5bfb082 100644 --- a/content.tex +++ b/content.tex @@ -1997,8 +1997,8 @@ All register values are organized as Little Endian. } hline mmioreg{QueueReady}{Virtual queue ready bit}{0x044}{RW}{% - Writing one (0x1) to this register notifies the device that the - virtual queue is ready to be used. Reading from this register + Writing one (0x1) to this register notifies the device that it can + execute requests from this virtual queue. Reading from this register returns the last value written to it. Both read and write accesses apply to the queue selected by writing to field{QueueSel}. } @@ -2058,7 +2058,11 @@ All register values are organized as Little Endian. } hline mmioreg{ConfigGeneration}{Configuration atomicity value}{0x0fc}{R}{ - Changes every time the configuration noticeably changes (see
ef {sec:Basic Facilities of a Virtio Device / Device Configuration Space}. + Reading from this register returns a value describing a version of the device-specific configuration space (see field{Config}). + The driver can then access the configuration space and, when finished, read field{ConfigGeneration} again. + If no part of the configuration space has changed between these two field{ConfigGeneration} reads, the returned values are identical. + If the values are different, the configuration space accesses were not atomic and the driver has to perform the operations again. + See also
ef {sec:Basic Facilities of a Virtio Device / Device Configuration Space}. } hline mmioreg{Config}{Configuration space}{0x100+}{RW}{ @@ -2083,9 +2087,10 @@ do not represent events which took place MUST be zero. Upon reset, the device MUST clear all bits in field{InterruptStatus} and ready bits in the field{QueueReady} register for all queues in the device. -The device MUST change field{ConfigGeneration} if there is any risk of a -device seeing an inconsistent configuration state, but it MAY only change the value -after a configuration read operation. +The device MUST change value returned in field{ConfigGeneration} if there is any risk of a +driver seeing an inconsistent configuration state. + +The device MUST NOT access virtual queue contents when field{QueueReady} is zero (0x0). drivernormative{subsubsection}{MMIO Device Register Layout}{Virtio Transport Options / Virtio Over MMIO / MMIO Device Register Layout} The driver MUST NOT access memory locations not described in the @@ -2094,6 +2099,12 @@ table
ef{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Register MUST NOT write to the read-only registers (direction R) and MUST NOT read from the write-only registers (direction W). +The driver MUST only use 32 bit wide and aligned reads and writes to access the control registers +described in table
ef{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Register Layout}. +For the device-specific configuration space, the driver MUST use 8 bit wide accesses for +8 bit wide fields, 16 bit wide and aligned accesses for 16 bit wide fields and 32 bit wide and +aligned accesses for 32 and 64 bit wide fields. + The driver MUST ignore a device with field{MagicValue} which is not 0x74726976, although it MAY report an error. -- 1.9.1

On Mon, Aug 11, 2014 at 09:53:37AM +0100, Pawel Moll wrote: > Those changes do not add nor remove any features and constitutes > only error correction and editorial changes. > > * Extra clarifications for QueueReady and ConfigGeneration > * Added alignment requirement section, to formalise > hidden assumptions about register accesses > > Signed-off-by: Pawel Moll <pawel.moll@arm.com> OK, I'll pack everything up and start a ballot on including these changes in the final 1.0 standard. > --- > content.tex 23 +++++++++++++++++------ > 1 file changed, 17 insertions(+), 6 deletions(-) > > diff --git a/content.tex b/content.tex > index 17ba3b8..5bfb082 100644 > --- a/content.tex > +++ b/content.tex > @@ -1997,8 +1997,8 @@ All register values are organized as Little Endian. > } > hline > mmioreg{QueueReady}{Virtual queue ready bit}{0x044}{RW}{% > - Writing one (0x1) to this register notifies the device that the > - virtual queue is ready to be used. Reading from this register > + Writing one (0x1) to this register notifies the device that it can > + execute requests from this virtual queue. Reading from this register > returns the last value written to it. Both read and write > accesses apply to the queue selected by writing to field{QueueSel}. > } > @@ -2058,7 +2058,11 @@ All register values are organized as Little Endian. > } > hline > mmioreg{ConfigGeneration}{Configuration atomicity value}{0x0fc}{R}{ > - Changes every time the configuration noticeably changes (see
ef {sec:Basic Facilities of a Virtio Device / Device Configuration Space}. > + Reading from this register returns a value describing a version of the device-specific configuration space (see field{Config}). > + The driver can then access the configuration space and, when finished, read field{ConfigGeneration} again. > + If no part of the configuration space has changed between these two field{ConfigGeneration} reads, the returned values are identical. > + If the values are different, the configuration space accesses were not atomic and the driver has to perform the operations again. > + See also
ef {sec:Basic Facilities of a Virtio Device / Device Configuration Space}. > } > hline > mmioreg{Config}{Configuration space}{0x100+}{RW}{ > @@ -2083,9 +2087,10 @@ do not represent events which took place MUST be zero. > Upon reset, the device MUST clear all bits in field{InterruptStatus} and ready bits in the > field{QueueReady} register for all queues in the device. > > -The device MUST change field{ConfigGeneration} if there is any risk of a > -device seeing an inconsistent configuration state, but it MAY only change the value > -after a configuration read operation. > +The device MUST change value returned in field{ConfigGeneration} if there is any risk of a > +driver seeing an inconsistent configuration state. > + > +The device MUST NOT access virtual queue contents when field{QueueReady} is zero (0x0). > > drivernormative{subsubsection}{MMIO Device Register Layout}{Virtio Transport Options / Virtio Over MMIO / MMIO Device Register Layout} > The driver MUST NOT access memory locations not described in the > @@ -2094,6 +2099,12 @@ table
ef{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Register > MUST NOT write to the read-only registers (direction R) and > MUST NOT read from the write-only registers (direction W). > > +The driver MUST only use 32 bit wide and aligned reads and writes to access the control registers > +described in table
ef{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Register Layout}. > +For the device-specific configuration space, the driver MUST use 8 bit wide accesses for > +8 bit wide fields, 16 bit wide and aligned accesses for 16 bit wide fields and 32 bit wide and > +aligned accesses for 32 and 64 bit wide fields. > + > The driver MUST ignore a device with field{MagicValue} which is not 0x74726976, > although it MAY report an error. > > -- > 1.9.1 > > > --------------------------------------------------------------------- > To unsubscribe from this mail list, you must leave the OASIS TC that > generates this mail. Follow this link to all your TCs in OASIS at: > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php