From db517375409ca452cdb80f6b8f82b349424f36cd Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Sun, 15 Mar 2015 10:03:42 +0000 Subject: legacy: clean up virtqueue layout definitions Generalize "Legacy Interfaces: A Note on Virtqueue Layout" to allow for different alignment requirements. Have pci and ccw refer to that section for legacy devices. Remove the double definition of virtqueue alignment (which referred to legacy, but was not tagged as such) from the ccw section. VIRTIO-129 Signed-off-by: Cornelia Huck Approved unanimously: https://www.oasis-open.org/apps/org/workgroup/virtio/ballot.php?id=2756 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@478 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 41 ++++++++++------------------------------- 1 file changed, 10 insertions(+), 31 deletions(-) diff --git a/content.tex b/content.tex index 1efdcc8..6a8638b 100644 --- a/content.tex +++ b/content.tex @@ -288,7 +288,8 @@ For Legacy Interfaces, several additional restrictions are placed on the virtqueue layout: Each virtqueue occupies two or more physically-contiguous pages -(usually defined as 4096 bytes, but depending on the transport) +(usually defined as 4096 bytes, but depending on the transport; +henceforth referred to as Queue Align) and consists of three parts: \begin{tabular}{|l|l|l|} @@ -301,11 +302,12 @@ The bus-specific Queue Size field controls the total number of bytes for the virtqueue. When using the legacy interface, the transitional driver MUST retrieve the Queue Size field from the device -and MUST allocate the total number of bytes for the virtuqueue -according to the following formula: +and MUST allocate the total number of bytes for the virtqueue +according to the following formula (Queue Align given in qalign and +Queue Size given in qsz): \begin{lstlisting} -#define ALIGN(x) (((x) + PAGE_SIZE) & ~PAGE_SIZE) +#define ALIGN(x) (((x) + qalign) & ~qalign) static inline unsigned virtq_size(unsigned int qsz) { return ALIGN(sizeof(struct virtq_desc)*qsz + sizeof(u16)*(3 + qsz)) @@ -326,7 +328,7 @@ struct virtq { // A ring of available descriptor heads with free-running index. struct virtq_avail avail; - // Padding to the next PAGE_SIZE boundary. + // Padding to the next Queue Align boundary. u8 pad[ Padding ]; // A ring of used descriptor heads with free-running index. @@ -1761,8 +1763,8 @@ The driver typically does this as follows, for each virtqueue a device has: \end{enumerate} \subparagraph{Legacy Interface: A Note on Virtqueue Configuration}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Virtqueue Configuration / Legacy Interface: A Note on Virtqueue Configuration} -When using the legacy interface, the page size for a virtqueue on a PCI virtio -device is defined as 4096 bytes. Driver writes the physical address, divided +When using the legacy interface, the queue layout follows \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout} with an alignment of 4096. +Driver writes the physical address, divided by 4096 to the Queue Address field\footnote{The 4096 is based on the x86 page size, but it's also large enough to ensure that the separate parts of the virtqueue are on separate cache lines. @@ -2585,30 +2587,7 @@ struct vq_info_block_legacy { \end{lstlisting} \field{queue} contains the guest address for queue \field{index}, \field{num} the number of buffers -and \field{align} the alignment. - -\subsubsection{Virtqueue Layout}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Virtqueue Layout} - -The virtqueue is physically contiguous, with padding added to make the -used ring meet the align value: - -\begin{tabular}{|l|l|l|} -\hline -Descriptor Table & Available Ring (\ldots padding\ldots) & Used Ring \\ -\hline -\end{tabular} - -The calculation for total size is as follows: - -\begin{lstlisting} -#define ALIGN(x) (((x) + align) & ~align) -static inline unsigned virtq_size(unsigned int num) -{ - return ALIGN(sizeof(struct virtq_desc)*num - + sizeof(u16)*(3 + num)) - + ALIGN(sizeof(u16)*3 + sizeof(struct virtq_used_elem)*num); -} -\end{lstlisting} +and \field{align} the alignment. The queue layout follows \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout}. \subsubsection{Communicating Status Information}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Communicating Status Information} -- cgit v1.2.3 From 4e0739635b32261aea9c05c17081a20be7c00cb6 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Sun, 15 Mar 2015 10:07:13 +0000 Subject: ccw: allow WRITE_STATUS to fail We want to be able to fail setting a status on the device (e.g. FEATURES_OK if the device can't work with the features negotiated). The easiest way to do that is to allow the device to fail the WRITE_STATUS command by posting a command reject. VIRTIO-116 Signed-off-by: Cornelia Huck Approved unanimously: https://www.oasis-open.org/apps/org/workgroup/virtio/ballot.php?id=2762 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@479 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- conformance.tex | 2 ++ content.tex | 17 +++++++++++++++++ 2 files changed, 19 insertions(+) diff --git a/conformance.tex b/conformance.tex index 29c6ba8..59193e9 100644 --- a/conformance.tex +++ b/conformance.tex @@ -79,6 +79,7 @@ A Channel I/O driver MUST conform to the following normative statements: \begin{itemize} \item \ref{drivernormative:Virtio Transport Options / Virtio over channel I/O / Basic Concepts} \item \ref{drivernormative:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting the Virtio Revision} +\item \ref{drivernormative:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Communicating Status Information} \item \ref{drivernormative:Virtio Transport Options / Virtio over channel I/O / Device Operation / Host->Guest Notification / Notification via Adapter I/O Interrupts} \item \ref{drivernormative:Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification} \end{itemize} @@ -182,6 +183,7 @@ A Channel I/O device MUST conform to the following normative statements: \item \ref{devicenormative:Virtio Transport Options / Virtio over channel I/O / Basic Concepts} \item \ref{devicenormative:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting the Virtio Revision} \item \ref{devicenormative:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue} +\item \ref{devicenormative:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Communicating Status Information} \item \ref{devicenormative:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting Up Indicators / Setting Up Two-Stage Queue Indicators} \item \ref{devicenormative:Virtio Transport Options / Virtio over channel I/O / Device Operation / Host->Guest Notification / Notification via Adapter I/O Interrupts} \item \ref{devicenormative:Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification} diff --git a/content.tex b/content.tex index 6a8638b..1efe93a 100644 --- a/content.tex +++ b/content.tex @@ -2595,6 +2595,23 @@ The driver changes the status of a device via the CCW_CMD_WRITE_STATUS command, which transmits an 8 bit status value. +As described in +\ref{devicenormative:Basic Facilities of a Virtio Device / Feature Bits}, +a device sometimes fails to set the \field{status} field: For example, it +might fail to accept the FEATURES_OK status bit during device initialization. + +\drivernormative{\paragraph}{Communicating Status Information}{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Communicating Status Information} + +If the device posts a unit check with command reject in response to the +CCW_CMD_WRITE_STATUS command, the driver MUST assume that the device failed +to set the status and the \field{status} field retained its previous value. + +\devicenormative{\paragraph}{Communicating Status Information}{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Communicating Status Information} + +If the device fails to set the \field{status} field to the value written by +the driver, the device MUST assure that the \field{status} field is left +unchanged and MUST post a unit check with command reject. + \subsubsection{Handling Device Features}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Handling Device Features} Feature bits are arranged in an array of 32 bit values, making -- cgit v1.2.3 From 1b94350c49c8f0425b32c2581e29787406e53034 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Sun, 15 Mar 2015 10:10:50 +0000 Subject: ccw: clarify basic channel commands "Basic channel commands" seems to be not as clear as it could, so let's spell out which channel commands we refer to. VIRTIO-118 Signed-off-by: Cornelia Huck Approved unanimously: https://www.oasis-open.org/apps/org/workgroup/virtio/ballot.php?id=2763 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@480 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/content.tex b/content.tex index 1efe93a..ba5c63b 100644 --- a/content.tex +++ b/content.tex @@ -2381,8 +2381,14 @@ model corresponding to the attached virtio device's subsystem device ID, accessed via a virtual I/O subchannel and a virtual channel path of type 0x32. This proxy device is discoverable via normal channel subsystem device discovery (usually a STORE -SUBCHANNEL loop) and answers to the basic channel commands, most -importantly SENSE ID. +SUBCHANNEL loop) and answers to the basic channel commands: + +\begin{itemize} +\item NO-OPERATION (0x03) +\item BASIC SENSE (0x04) +\item TRANSFER IN CHANNEL (0x08) +\item SENSE ID (0xe4) +\end{itemize} For a virtio-ccw proxy device, SENSE ID will return the following information: -- cgit v1.2.3 From be298453d27f3b363f02150d264dc08dd9aa6c8f Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Sun, 15 Mar 2015 11:09:53 +0000 Subject: Revert: formatting: mark change manually as changed in cs02 This reverts commit d0ea186fe547a0e7ae4baeb623cf764a3f1ace65. git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@481 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content.tex b/content.tex index ba5c63b..d34685d 100644 --- a/content.tex +++ b/content.tex @@ -4795,7 +4795,7 @@ Requests have the following format: \begin{lstlisting} struct virtio_scsi_ctrl { le32 type; -$\DIFdeltextcstwo{{\textbackslash}ldots}\DIFaddtextcstwo{\ldots}$ +$\ldots$ u8 response; }; -- cgit v1.2.3 From 298278d34b44935768c4e63b010f3c89ddf34580 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Sun, 15 Mar 2015 11:10:13 +0000 Subject: cl: move out cs02 changelog start adding one for cs03 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@482 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-cs02.tex | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ cl-os.tex | 58 ++++++++-------------------------------------------------- 2 files changed, 60 insertions(+), 50 deletions(-) create mode 100644 cl-cs02.tex diff --git a/cl-cs02.tex b/cl-cs02.tex new file mode 100644 index 0000000..61aa6fd --- /dev/null +++ b/cl-cs02.tex @@ -0,0 +1,52 @@ +448 & 22 Dec 2014 & Michael S. Tsirkin & {VIRTIO-120: virtio: +fix used element size + +General ring description lists size for +used ring elements as 4, it must be 8. + +See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}. + } \\ +\hline +449 & 22 Doc 2014 & Cornelia Huck & {VIRTIO-125: block: fixup section levels + The specification for the configuration layout for block devices + should be its own subsection as for all other devices and not be + hidden beneath "Feature bits". + + The normative sections for device operation should appear under + the device operation section. +See \ref{sec:Device Types / Block Device / Device configuration +layout}. + } \\ +\hline +450 & 22 Dec 2014 & Cornelia Huck & {VIRTIO-127: ccw: two-stage +indicators for legacy devices + + Some legacy devices will support two-stage queue indicators +and therefore + won't reject CCW_CMD_SET_IND_ADAPTER. Note this. + +See \ref{sec:Virtio Transport Options / Virtio over channel I/O / +Device Initialization / Setting Up Indicators / Legacy +Interfaces: A Note on Setting Up Indicators}. + } \\ +\hline +452 & 22 Dec 2014 & Michael S. Tsirkin & {VIRTIO-115: +formatting: escape {\textbackslash}ldots in lstlisting + + {\textbackslash}ldots does not work within lstlisting, the result is + {\textbackslash}ldots verbatim in the PDF output. + + To fix, make \$ an escape character, and escape the sequence: + \${\textbackslash}ldots\$ + +See \ref{sec:Device Types / SCSI Host Device / Device Operation / +Device Operation: controlq}. +} \\ +\hline +455,457 & 23 Dec 2014 & Michael S. Tsirkin & {acknowledgements: acknowledge dgilbert + + Acknowledge David Alan Gilbert for reporting VIRTIO-120. + +See \ref{chap:Acknowledgements}. +} \\ +\hline diff --git a/cl-os.tex b/cl-os.tex index 61aa6fd..9abd1f4 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -1,52 +1,10 @@ -448 & 22 Dec 2014 & Michael S. Tsirkin & {VIRTIO-120: virtio: -fix used element size - -General ring description lists size for -used ring elements as 4, it must be 8. - -See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}. - } \\ -\hline -449 & 22 Doc 2014 & Cornelia Huck & {VIRTIO-125: block: fixup section levels - The specification for the configuration layout for block devices - should be its own subsection as for all other devices and not be - hidden beneath "Feature bits". - - The normative sections for device operation should appear under - the device operation section. -See \ref{sec:Device Types / Block Device / Device configuration -layout}. - } \\ -\hline -450 & 22 Dec 2014 & Cornelia Huck & {VIRTIO-127: ccw: two-stage -indicators for legacy devices - - Some legacy devices will support two-stage queue indicators -and therefore - won't reject CCW_CMD_SET_IND_ADAPTER. Note this. - -See \ref{sec:Virtio Transport Options / Virtio over channel I/O / -Device Initialization / Setting Up Indicators / Legacy -Interfaces: A Note on Setting Up Indicators}. +478 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-129: legacy: +clean up virtqueue layout definitions + +Generalize "Legacy Interfaces: A Note on Virtqueue Layout" to allow +for different alignment requirements. Have pci and ccw refer to that +section for legacy devices. Remove the double definition of virtqueue +alignment (which referred to legacy, but was not tagged as such) from +the ccw section. } \\ \hline -452 & 22 Dec 2014 & Michael S. Tsirkin & {VIRTIO-115: -formatting: escape {\textbackslash}ldots in lstlisting - - {\textbackslash}ldots does not work within lstlisting, the result is - {\textbackslash}ldots verbatim in the PDF output. - - To fix, make \$ an escape character, and escape the sequence: - \${\textbackslash}ldots\$ - -See \ref{sec:Device Types / SCSI Host Device / Device Operation / -Device Operation: controlq}. -} \\ -\hline -455,457 & 23 Dec 2014 & Michael S. Tsirkin & {acknowledgements: acknowledge dgilbert - - Acknowledge David Alan Gilbert for reporting VIRTIO-120. - -See \ref{chap:Acknowledgements}. -} \\ -\hline -- cgit v1.2.3 From c9873341c915886263023cd7e30320c5c9736c6f Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Sun, 15 Mar 2015 11:10:30 +0000 Subject: makediff: update for cs03 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@483 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- makediff.sh | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/makediff.sh b/makediff.sh index 16eba2d..b7e6831 100755 --- a/makediff.sh +++ b/makediff.sh @@ -9,31 +9,17 @@ export DATESTR=${DATESTR:-`cat REVISION-DATE`} MAIN=$1 PATH=.:${PATH} cur="$PWD" -oldrev=`git rev-list -1 origin/tags/v1.0-cs01` +oldrev=`git rev-list -1 origin/tags/v1.0-cs02` newrev=`git rev-list -1 HEAD` rm -fr old new git clone $PWD old cd "${cur}/old" git checkout $oldrev -##suppress diff of title -#git cherry-pick 0adee486ab987c3e98c5f31b51cc963d8bb6fff4 -##suppress diff of changelog -#git cherry-pick a41f3813a748e7d279cb6eb82f3c0afde4a3243a -#git cherry-pick fbfb402e69cdd9279c44b7684612e6f81df99e6d -#git cherry-pick 9f240fe0e718bf9b1e502e02916db9d8fede304b -#git cherry-pick a02605f9945f450ecaadf86736741de2e2c2e788 -#git cherry-pick 175e797beede8aea840102bee9b70bb08190153d while read -r rev; do echo "Applying $rev" git cherry-pick `git rev-list -1 -F --grep "$rev" $newrev` || exit 1 done << 'EOF' -formatting: escape \ldots in lstlisting -formatting: mark change manually as changed in cs02 -cl: remove changelog for cs01 -cl-os: prepare changelog for v1.0 cs02 -title: update previous version to cs01 -changelog: list acknowledgement change -changelog: typo fixup: formatting: formatting +Revert: formatting: mark change manually as changed in cs02 EOF #mv specvars.tex specvars-orig.tex -- cgit v1.2.3 From f612f689e7e97df615294f090b14d06a31fdabab Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Sun, 15 Mar 2015 11:10:49 +0000 Subject: makediff: work around for lstlisting latexdiff seems to go wild trying to diff lstlisting. But marking lstlisting as picture - so old text is commented out - then removing the comment sign - seems to work, with the only disadvantage being that listing is diffed as a whole. Seems to be the best I can come up with ATM. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@484 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- fixupdiff.pl | 14 ++++++++++++++ makediff.sh | 8 +++++--- 2 files changed, 19 insertions(+), 3 deletions(-) create mode 100644 fixupdiff.pl diff --git a/fixupdiff.pl b/fixupdiff.pl new file mode 100644 index 0000000..70d4e30 --- /dev/null +++ b/fixupdiff.pl @@ -0,0 +1,14 @@ +my $lstlisting=0; +while (<>) { + my $line = $_; + if (m/%DIFDELCMD\s+<\s+\\begin{lstlisting}/) { + $lstlisting=1; + } + if ($lstlisting) { + $line =~ s/%DIFDELCMD\s+<\s+//; + } + print $line; + if (m/%DIFDELCMD\s+<\s+\\end{lstlisting}/) { + $lstlisting=0; + } +} diff --git a/makediff.sh b/makediff.sh index b7e6831..dc2efff 100755 --- a/makediff.sh +++ b/makediff.sh @@ -50,6 +50,8 @@ sed 's/\\footnote{/\\footnote {/' new/flat.tex > new/flat-fixed.tex #wget http://mirror.math.ku.edu/tex-archive/support/latexdiff/latexdiff-fast #chmod +x latexdiff-fast latexdiff-fast --config \ -"FLOATENV=(?:figure|longtable|table|tabular|plate)[\w\d*@]*" \ - --append-safecmd=field --append-textcmd=mmioreg --ignore-warnings -p diffpreamble.tex old/flat-fixed.tex new/flat-fixed.tex > virtio-diff.tex -#perl -pi fixupdiff.pl virtio-diff.tex +"FLOATENV=(?:figure|longtable|table|tabular|plate|lstlisting)[\w\d*@]*,PICTUREENV=(?:picture|DIFnomarkup|lstlisting)[\w\d*@]*" \ + --append-safecmd=field --append-textcmd=mmioreg \ +--ignore-warnings -p diffpreamble.tex old/flat-fixed.tex \ +new/flat-fixed.tex > virtio-diff-tofix.tex +perl fixupdiff.pl virtio-diff-tofix.tex > virtio-diff.tex -- cgit v1.2.3 From c407b04f9ddd80af2787b3b7f4fa3430c4100d22 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:06:05 +0000 Subject: virtio-ring: comment fixup virtio_ring.h included with spec has this text: /* Support for avail_idx and used_idx fields */ it should really refer to avail_event and used_event. VIRTIO-135. Reported-by: Jason Wang Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@485 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- virtio-ring.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/virtio-ring.h b/virtio-ring.h index aa01d92..5a1e87d 100644 --- a/virtio-ring.h +++ b/virtio-ring.h @@ -53,7 +53,7 @@ /* Support for indirect descriptors */ #define VIRTIO_F_INDIRECT_DESC 28 -/* Support for avail_idx and used_idx fields */ +/* Support for avail_event and used_event fields */ #define VIRTIO_F_EVENT_IDX 29 /* Arbitrary descriptor layouts. */ -- cgit v1.2.3 From d5d4b0c8bb2edb6f7aa771a7a060bf7c9a5f864a Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:06:22 +0000 Subject: document idx field in virtqueue used ring Section 2.4.8 The Virtqueue Used Ring lists the idx field, but never documents it. VIRTIO-136. Reported-by: Jason Wang Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@486 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content.tex b/content.tex index d34685d..c9440a4 100644 --- a/content.tex +++ b/content.tex @@ -595,6 +595,9 @@ for drivers using untrusted buffers: if you do not know exactly how much has been written by the device, you usually have to zero the buffer to ensure no data leakage occurs. +\field{idx} field indicates where the driver would put the next descriptor +entry in the ring (modulo the queue size). This starts at 0, and increases. + \begin{note} The legacy \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]} referred to these structures as vring_used and vring_used_elem, and -- cgit v1.2.3 From 525835c50ef60324c9cb14bf3b8a8bc7839f77d6 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:06:40 +0000 Subject: ISR status: Fix incorrect diagram ISR status capability diagram has the "Device Configuration Interrupt " as bit 0, and the "Queue Interrupt" as bit 1. This is the wrong way around: it disagrees with the legacy implementations, as well as the spec elsewhere. All current guests correctly follow the text, fix up the diagram to match. VIRTIO-130 Signed-off-by: Rusty Russell Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@487 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content.tex b/content.tex index c9440a4..1b682d8 100644 --- a/content.tex +++ b/content.tex @@ -1415,7 +1415,7 @@ change interrupts and normal virtqueue interrupts: \hline Bits & 0 & 1 & 2 to 31 \\ \hline -Purpose & Device Configuration Interrupt & Queue Interrupt & Reserved \\ +Purpose & Queue Interrupt & Device Configuration Interrupt & Reserved \\ \hline \end{tabular} -- cgit v1.2.3 From 0bc9dbd2b501b8e37410344fb9dc645537142ff2 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:07:04 +0000 Subject: Change 4.1.5.1.2.1 to device requirement 4.1.5.1.2.1 is incorrectly labelled as a driver requirement; it's self-evidently referring to the device. VIRTIO-133 Signed-off-by: Rusty Russell Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@488 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- conformance.tex | 2 +- content.tex | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/conformance.tex b/conformance.tex index 59193e9..350d2d0 100644 --- a/conformance.tex +++ b/conformance.tex @@ -57,7 +57,6 @@ A PCI driver MUST conform to the following normative statements: \item \ref{drivernormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout} \item \ref{drivernormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability} \item \ref{drivernormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability} -\item \ref{drivernormative:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver} \item \ref{drivernormative:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / MSI-X Vector Configuration} \item \ref{drivernormative:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Notification of Device Configuration Changes} \end{itemize} @@ -162,6 +161,7 @@ A PCI device MUST conform to the following normative statements: \item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability} \item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Device-specific configuration} \item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver} \item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / MSI-X Vector Configuration} \item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Virtqueue Interrupts From The Device} \item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Notification of Device Configuration Changes} diff --git a/content.tex b/content.tex index 1b682d8..947e4b0 100644 --- a/content.tex +++ b/content.tex @@ -1631,7 +1631,7 @@ Structure PCI capabilities as detailed in \ref{sec:Virtio Transport Options / Vi \paragraph{Non-transitional Device With Legacy Driver}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver} -\drivernormative{\subparagraph}{Non-transitional Device With Legacy Driver}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver} +\devicenormative{\subparagraph}{Non-transitional Device With Legacy Driver}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver} Non-transitional devices, on a platform where a legacy driver for a legacy device with the same ID might have previously existed, -- cgit v1.2.3 From 27e14c7cea0fc4f1e25d8b44cde3d282bc46a020 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:07:22 +0000 Subject: cl: drop contents temporarily This is helpful for diff generation. Will re-add shortly. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@489 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/cl-os.tex b/cl-os.tex index 9abd1f4..e69de29 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -1,10 +0,0 @@ -478 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-129: legacy: -clean up virtqueue layout definitions - -Generalize "Legacy Interfaces: A Note on Virtqueue Layout" to allow -for different alignment requirements. Have pci and ccw refer to that -section for legacy devices. Remove the double definition of virtqueue -alignment (which referred to legacy, but was not tagged as such) from -the ccw section. - } \\ -\hline -- cgit v1.2.3 From 2f59b7e162a6516b19be69645a1bac686cade395 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:07:39 +0000 Subject: changelog: comment out header Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@490 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- changelog.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog.tex b/changelog.tex index fbe2dd5..c52d6d5 100644 --- a/changelog.tex +++ b/changelog.tex @@ -4,7 +4,7 @@ of this specification: \begin{longtable}{ | c | c | c | p{0.4\textwidth} | } \hline -\textbf{Revision} & \textbf{Date} & \textbf{Editor} & \textbf{Changes Made} \\ +%\textbf{Revision} & \textbf{Date} & \textbf{Editor} & \textbf{Changes Made} \\ \hline \endhead %\lbrack Rev number \rbrack & \lbrack Rev Date \rbrack & \lbrack Modified By \rbrack & \lbrack Summary of Changes \rbrack \\ -- cgit v1.2.3 From dc053552494d9a65f64de4ce11cd54b98cdeb407 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:07:56 +0000 Subject: changelog: uncomment header This reverts commit d9536a52200d9f9f5048fd6534605ec75aadb08f. git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@491 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- changelog.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog.tex b/changelog.tex index c52d6d5..fbe2dd5 100644 --- a/changelog.tex +++ b/changelog.tex @@ -4,7 +4,7 @@ of this specification: \begin{longtable}{ | c | c | c | p{0.4\textwidth} | } \hline -%\textbf{Revision} & \textbf{Date} & \textbf{Editor} & \textbf{Changes Made} \\ +\textbf{Revision} & \textbf{Date} & \textbf{Editor} & \textbf{Changes Made} \\ \hline \endhead %\lbrack Rev number \rbrack & \lbrack Rev Date \rbrack & \lbrack Modified By \rbrack & \lbrack Summary of Changes \rbrack \\ -- cgit v1.2.3 From b03b5688eea99b40ac8a83589f28be30746ab841 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:08:14 +0000 Subject: cl: list virtio-129 This reverts commit de1e7c191a168195f67aa5259603f83264b35e28. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@492 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/cl-os.tex b/cl-os.tex index e69de29..9abd1f4 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -0,0 +1,10 @@ +478 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-129: legacy: +clean up virtqueue layout definitions + +Generalize "Legacy Interfaces: A Note on Virtqueue Layout" to allow +for different alignment requirements. Have pci and ccw refer to that +section for legacy devices. Remove the double definition of virtqueue +alignment (which referred to legacy, but was not tagged as such) from +the ccw section. + } \\ +\hline -- cgit v1.2.3 From 76341d2a6a45b36fa49dc0d1c0ba1a8e0a383522 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:08:32 +0000 Subject: cl: list virtio-116 change Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@493 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/cl-os.tex b/cl-os.tex index 9abd1f4..a4dbbee 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -8,3 +8,13 @@ alignment (which referred to legacy, but was not tagged as such) from the ccw section. } \\ \hline +479 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-116: +ccw: allow WRITE_STATUS to fail + +We want to be able to fail setting a status on the device +(e.g. FEATURES_OK if the device can't work with the features +negotiated). +The easiest way to do that is to allow the device to fail the +WRITE_STATUS command by posting a command reject. + } \\ +\hline -- cgit v1.2.3 From 4c2ad7e26fae8f3e3ddf5f53b4ddafb9012ba4a1 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:08:50 +0000 Subject: cl: list more changes Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@494 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/cl-os.tex b/cl-os.tex index a4dbbee..4648156 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -6,6 +6,8 @@ for different alignment requirements. Have pci and ccw refer to that section for legacy devices. Remove the double definition of virtqueue alignment (which referred to legacy, but was not tagged as such) from the ccw section. +See \ref{ +}. } \\ \hline 479 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-116: @@ -16,5 +18,26 @@ We want to be able to fail setting a status on the device negotiated). The easiest way to do that is to allow the device to fail the WRITE_STATUS command by posting a command reject. +See \ref{ +}. + } \\ +\hline +485 & 15 Mar 2015 & Jason Wang & {VIRTIO-135: +virtio-ring: comment fixup + +virtio_ring.h included with spec has this text: +/* Support for avail_idx and used_idx fields */ +it should really refer to avail_event and used_event. +See \ref{ +}. + } \\ +\hline +486 & 15 Mar 2015 & Jason Wang & {VIRTIO-136: +document idx field in virtqueue used ring + +Section 2.4.8 The Virtqueue Used Ring +lists the idx field, but never documents it. +See \ref{ +}. } \\ \hline -- cgit v1.2.3 From 6e0259102391343e43f051d51a5e9502b06f3e33 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:09:11 +0000 Subject: changelog: disable markup Doesn't work properly with latexdiff anyway. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@495 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- changelog.tex | 2 ++ commands.tex | 1 + 2 files changed, 3 insertions(+) diff --git a/changelog.tex b/changelog.tex index fbe2dd5..4b89e97 100644 --- a/changelog.tex +++ b/changelog.tex @@ -2,6 +2,7 @@ The following changes have been made since the previous version of this specification: +\begin{DIFnomarkup} \begin{longtable}{ | c | c | c | p{0.4\textwidth} | } \hline \textbf{Revision} & \textbf{Date} & \textbf{Editor} & \textbf{Changes Made} \\ @@ -11,3 +12,4 @@ of this specification: %\hline \input{cl-os.tex} \end{longtable} +\end{DIFnomarkup} diff --git a/commands.tex b/commands.tex index 59c3da3..871f416 100644 --- a/commands.tex +++ b/commands.tex @@ -14,3 +14,4 @@ \newcommand{\devicenormative}[3]{#1{Device Requirements: #2}\label{devicenormative:#3}} \providecommand{\DIFaddtextcstwo}[1]{#1} \providecommand{\DIFdeltextcstwo}[1]{} +\newenvironment{DIFnomarkup}{}{} -- cgit v1.2.3 From ab5fb8dd72b80f7587d03a0a9b4aac5738f56998 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:09:28 +0000 Subject: makediff: cherry pick cl changes Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@496 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- makediff.sh | 2 ++ 1 file changed, 2 insertions(+) diff --git a/makediff.sh b/makediff.sh index dc2efff..df51bce 100755 --- a/makediff.sh +++ b/makediff.sh @@ -20,6 +20,8 @@ while read -r rev; do git cherry-pick `git rev-list -1 -F --grep "$rev" $newrev` || exit 1 done << 'EOF' Revert: formatting: mark change manually as changed in cs02 +cl: move out cs02 changelog +cl: drop contents temporarily EOF #mv specvars.tex specvars-orig.tex -- cgit v1.2.3 From 86ef23688f7091a0fb00177ffe4e26ed0138d969 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:09:46 +0000 Subject: cl: add cross-references to changes since cs02 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@497 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/cl-os.tex b/cl-os.tex index 4648156..084e327 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -6,8 +6,14 @@ for different alignment requirements. Have pci and ccw refer to that section for legacy devices. Remove the double definition of virtqueue alignment (which referred to legacy, but was not tagged as such) from the ccw section. -See \ref{ -}. +See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / +Legacy Interfaces: A Note on Virtqueue Layout}, \ref{sec:Virtio +Transport Options / Virtio Over PCI Bus / PCI-specific +Initialization And Device Operation / Device Initialization / +Virtqueue Configuration / Legacy Interface: A Note on Virtqueue +Configuration} and \ref{sec:Virtio Transport Options / Virtio +over channel I/O / Device Initialization / Configuring a +Virtqueue / Legacy Interface: A Note on Configuring a Virtqueue}. } \\ \hline 479 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-116: @@ -18,8 +24,8 @@ We want to be able to fail setting a status on the device negotiated). The easiest way to do that is to allow the device to fail the WRITE_STATUS command by posting a command reject. -See \ref{ -}. +See \ref{sec:Virtio Transport Options / Virtio over channel I/O / +Device Initialization / Communicating Status Information}. } \\ \hline 485 & 15 Mar 2015 & Jason Wang & {VIRTIO-135: @@ -28,16 +34,16 @@ virtio-ring: comment fixup virtio_ring.h included with spec has this text: /* Support for avail_idx and used_idx fields */ it should really refer to avail_event and used_event. -See \ref{ -}. +See \ref{sec:virtio-ring.h}. } \\ \hline 486 & 15 Mar 2015 & Jason Wang & {VIRTIO-136: document idx field in virtqueue used ring -Section 2.4.8 The Virtqueue Used Ring -lists the idx field, but never documents it. -See \ref{ -}. +Section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues +/ The Virtqueue Used Ring} The Virtqueue Used Ring +listed the idx field, but never documented it. +See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / +The Virtqueue Used Ring}. } \\ \hline -- cgit v1.2.3 From 1132bfe6a3b930bcd2e06925e85bb1a473adda67 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:10:06 +0000 Subject: makediff: cherry-pick header removal makes changelog diff slightly prettier. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@498 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- makediff.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/makediff.sh b/makediff.sh index df51bce..bba099a 100755 --- a/makediff.sh +++ b/makediff.sh @@ -22,6 +22,7 @@ done << 'EOF' Revert: formatting: mark change manually as changed in cs02 cl: move out cs02 changelog cl: drop contents temporarily +changelog: comment out header EOF #mv specvars.tex specvars-orig.tex -- cgit v1.2.3 From 6e7b2573da4f83dabb8b0add0f56751ca088bc85 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:10:25 +0000 Subject: cl: tweak changelog slightly Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@499 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cl-os.tex b/cl-os.tex index 084e327..08aea99 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -34,7 +34,7 @@ virtio-ring: comment fixup virtio_ring.h included with spec has this text: /* Support for avail_idx and used_idx fields */ it should really refer to avail_event and used_event. -See \ref{sec:virtio-ring.h}. +See Appendix \ref{sec:virtio-ring.h}. } \\ \hline 486 & 15 Mar 2015 & Jason Wang & {VIRTIO-136: -- cgit v1.2.3 From 8bce9fca4ad831d618b9e5d56ab5ce078bbbc29f Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:10:43 +0000 Subject: cl: add more changelog text Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@500 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/cl-os.tex b/cl-os.tex index 08aea99..05c1f16 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -16,6 +16,15 @@ over channel I/O / Device Initialization / Configuring a Virtqueue / Legacy Interface: A Note on Configuring a Virtqueue}. } \\ \hline +479 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-118: +ccw: clarify basic channel commands + +"Basic channel commands" seems to be not as clear as it +could, so let's spell out which channel commands we refer to. +See \ref{sec:Virtio Transport Options / Virtio over channel I/O / +Basic Concepts}. +} \\ +\hline 479 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-116: ccw: allow WRITE_STATUS to fail -- cgit v1.2.3 From 930364b1f7237263fc4ef47157cd10b65b08daf6 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:11:02 +0000 Subject: cl: list virtio-130 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@501 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/cl-os.tex b/cl-os.tex index 05c1f16..64a83a7 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -56,3 +56,17 @@ See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}. } \\ \hline +486 & 15 Mar 2015 & Rusty Russell & {VIRTIO-130: +ISR status: Fix incorrect diagram + +ISR status capability diagram has the "Device Configuration +Interrupt " as bit 0, and the "Queue Interrupt" as bit 1. This is +the wrong way around: it disagrees with the legacy +implementations, as well as the spec elsewhere. + +All current guests correctly follow the text, fix +up the diagram to match. +See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI +Device Layout / ISR status capability}. + } \\ +\hline -- cgit v1.2.3 From 54f331fd3460295cf5c2c2264a3c0346818adf7d Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:11:19 +0000 Subject: cl: add virtio-133 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@502 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/cl-os.tex b/cl-os.tex index 64a83a7..4f16391 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -70,3 +70,16 @@ See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability}. } \\ \hline +486 & 15 Mar 2015 & Rusty Russell & {VIRTIO-133: +Change 4.1.5.1.2.1 to device requirement + +4.1.5.1.2.1 is incorrectly labelled as a driver requirement; it's +self-evidently referring to the device. +See \ref{sec:Conformance / Driver Conformance / PCI Driver +Conformance}, \ref{sec:Conformance / Device Conformance / PCI +Device Conformance} and \ref{devicenormative:Virtio +Transport Options / Virtio Over PCI Bus / PCI-specific +Initialization And Device Operation / Device Initialization / +Non-transitional Device With Legacy Driver}. + } \\ +\hline -- cgit v1.2.3 From 37648703597b09fa2db9a3db77504e41608ff3c4 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 25 Mar 2015 17:11:36 +0000 Subject: cl: tweak revisions Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@503 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cl-os.tex b/cl-os.tex index 4f16391..05b6dfa 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -56,7 +56,7 @@ See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}. } \\ \hline -486 & 15 Mar 2015 & Rusty Russell & {VIRTIO-130: +487 & 15 Mar 2015 & Rusty Russell & {VIRTIO-130: ISR status: Fix incorrect diagram ISR status capability diagram has the "Device Configuration @@ -70,7 +70,7 @@ See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability}. } \\ \hline -486 & 15 Mar 2015 & Rusty Russell & {VIRTIO-133: +488 & 15 Mar 2015 & Rusty Russell & {VIRTIO-133: Change 4.1.5.1.2.1 to device requirement 4.1.5.1.2.1 is incorrectly labelled as a driver requirement; it's -- cgit v1.2.3 From 24880105eadd411078dc97484a933dc5ab2e2878 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 08:24:59 +0000 Subject: VIRTIO-137: used ring: define the meaning and requirements of the len field. We said what it was for, and noted why. We didn't place any requirements on it, nor clearly spell out the implications of its use. This clarification comes particularly from noticing that QEMU didn't set len correctly, and philosophising over the correct value when an error has occurred. (Wording precision feedback from Michael and Cornelia - Thanks!) Signed-off-by: Rusty Russell Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@504 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 39 +++++++++++++++++++++++++++++++++++---- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/content.tex b/content.tex index 947e4b0..9120730 100644 --- a/content.tex +++ b/content.tex @@ -590,10 +590,19 @@ them: it is only written to by the device, and read by the driver. Each entry in the ring is a pair: \field{id} indicates the head entry of the descriptor chain describing the buffer (this matches an entry placed in the available ring by the guest earlier), and \field{len} the total -of bytes written into the buffer. The latter is extremely useful -for drivers using untrusted buffers: if you do not know exactly -how much has been written by the device, you usually have to zero -the buffer to ensure no data leakage occurs. +of bytes written into the buffer. + +\begin{note} +\field{len} is particularly useful +for drivers using untrusted buffers: if a driver does not know exactly +how much has been written by the device, the driver would have to zero +the buffer in advance to ensure no data leakage occurs. + +For example, a network driver may hand a received buffer directly to +an unprivileged userspace application. If the network device has not +overwritten the bytes which were in that buffer, this could leak the +contents of freed memory from other processes to the application. +\end{note} \field{idx} field indicates where the driver would put the next descriptor entry in the ring (modulo the queue size). This starts at 0, and increases. @@ -605,6 +614,28 @@ the constant as VRING_USED_F_NO_NOTIFY, but the layout and value were identical. \end{note} +\devicenormative{\subsubsection}{The Virtqueue Used Ring}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring} + +The device MUST set \field{len} prior to updating the used \field{idx}. + +The device MUST write at least \field{len} bytes to descriptor, +beginning at the first device-writable buffer, +prior to updating the used \field{idx}. + +The device MAY write more than \field{len} bytes to descriptor. + +\begin{note} +There are potential error cases where a device might not know what +parts of the buffers have been written. This is why \field{len} is +permitted to be an underestimate: that's preferable to the driver believing +that uninitialized memory has been overwritten when it has not. +\end{note} + +\drivernormative{\subsubsection}{The Virtqueue Used Ring}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring} + +The driver MUST NOT make assumptions about data in device-writable buffers +beyond the first \field{len} bytes, and SHOULD ignore this data. + \subsection{Virtqueue Notification Suppression}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression} The device can suppress notifications in a manner analogous to the way -- cgit v1.2.3 From 3199466fd385ccd1a5db26ddfea779c41e1c7b6c Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 08:25:18 +0000 Subject: makediff: mark note as floatenv Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@505 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- makediff.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/makediff.sh b/makediff.sh index bba099a..1135cbb 100755 --- a/makediff.sh +++ b/makediff.sh @@ -53,7 +53,7 @@ sed 's/\\footnote{/\\footnote {/' new/flat.tex > new/flat-fixed.tex #wget http://mirror.math.ku.edu/tex-archive/support/latexdiff/latexdiff-fast #chmod +x latexdiff-fast latexdiff-fast --config \ -"FLOATENV=(?:figure|longtable|table|tabular|plate|lstlisting)[\w\d*@]*,PICTUREENV=(?:picture|DIFnomarkup|lstlisting)[\w\d*@]*" \ +"FLOATENV=(?:figure|longtable|table|tabular|plate|lstlisting|note)[\w\d*@]*,PICTUREENV=(?:picture|DIFdeltextcstwo|DIFnomarkup|lstlisting)[\w\d*@]*" \ --append-safecmd=field --append-textcmd=mmioreg \ --ignore-warnings -p diffpreamble.tex old/flat-fixed.tex \ new/flat-fixed.tex > virtio-diff-tofix.tex -- cgit v1.2.3 From 8028f89c17039a31e558a275c627cab8ae40a65b Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 08:25:35 +0000 Subject: multiple errors: Non-transitional With Legacy virtio 1.0 has two sections titled "Non-transitional Device With Legacy Driver" the first says devices SHOULD fail, the second says devices MUST fail. Clearly a mistake. Other issues: devices don't really fail - they cause drivers to fail. second section seems to be in the wrong place, and also have a section followed by subsection with no explanatory text in between, which is ugly. Finally, this text was originally ritten to handle buggy windows drivers gracefully, but later we changed device IDs so it's not really required there. Might be handy for some other buggy legacy drivers, though no such drivers are known. To fix, drop the duplicate section variant, add some explanatory text, clarify what does "same ID" mean here, and clarify that the work-around is only needed if a buggy driver is known to bind to a transitional device. VIRTIO-138 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@506 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/content.tex b/content.tex index 9120730..5a1a989 100644 --- a/content.tex +++ b/content.tex @@ -1636,10 +1636,25 @@ on PCI Device Layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Non-transitional Device With Legacy Driver: A Note on PCI Device Layout} +All known legacy drivers check either the PCI Revision or the +Device and Vendor IDs, and thus won't attempt to drive a +non-transitional device. + +A buggy legacy driver might mistakenly attempt to drive a +non-transitional device. If support for such drivers is required +(as opposed to fixing the bug), the following would be the +recommended way to detect and handle them. +\begin{note} +Such buggy drivers are not currently known to be used in +production. +\end{note} + +\devicenormative{\paragraph}{Non-transitional Device With Legacy Driver}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver} Non-transitional devices, on a platform where a legacy driver for -a legacy device with the same ID might have previously existed, -SHOULD take the following steps to fail gracefully when a legacy -driver attempts to drive them: +a legacy device with the same ID (including PCI Revision, Device +and Vendor IDs) is known to have previously existed, +SHOULD take the following steps to cause the legacy driver to +fail gracefully when it attempts to drive them: \begin{enumerate} \item Present an I/O BAR in BAR0, and @@ -1660,22 +1675,6 @@ As a prerequisite to device initialization, the driver scans the PCI capability list, detecting virtio configuration layout using Virtio Structure PCI capabilities as detailed in \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / Virtio Structure PCI Capabilities} -\paragraph{Non-transitional Device With Legacy Driver}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver} - -\devicenormative{\subparagraph}{Non-transitional Device With Legacy Driver}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver} - -Non-transitional devices, on a platform where a legacy driver for -a legacy device with the same ID might have previously existed, -MUST take the following steps to fail gracefully when a legacy -driver attempts to drive them: - -\begin{enumerate} -\item Present an I/O BAR in BAR0, and -\item Respond to a single-byte zero write to offset 18 - (corresponding to Device Status register in the legacy layout) - of BAR0 by presenting zeroes on every BAR and ignoring writes. -\end{enumerate} - \subparagraph{Legacy Interface: A Note on Device Layout Detection}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Virtio Device Configuration Layout Detection / Legacy Interface: A Note on Device Layout Detection} Legacy drivers skipped the Device Layout Detection step, assuming legacy -- cgit v1.2.3 From a75a70b428f33cf2b684f09a4b0dcc7985726b02 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 08:25:52 +0000 Subject: mark diff for non-transitional with legacy latexdiff doesn't handle changing labels well, causes latex unresolved reference errors. opencode and mark up diff manually. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@507 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/content.tex b/content.tex index 5a1a989..48d735d 100644 --- a/content.tex +++ b/content.tex @@ -1649,7 +1649,19 @@ Such buggy drivers are not currently known to be used in production. \end{note} -\devicenormative{\paragraph}{Non-transitional Device With Legacy Driver}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver} +\subparagraph{ +\DIFdeltextcstwo{Driver Requirements: Non-transitional Device With Legacy Driver} +\DIFaddtextcstwo{Device Requirements: Non-transitional Device With Legacy Driver} +} +\label{drivernormative:Virtio Transport Options / Virtio Over PCI +Bus / PCI-specific Initialization And Device Operation / +Device Initialization / Non-transitional Device With Legacy +Driver} +\label{devicenormative:Virtio Transport Options / Virtio Over PCI +Bus / PCI-specific Initialization And Device Operation / +Device Initialization / Non-transitional Device With Legacy +Driver} + Non-transitional devices, on a platform where a legacy driver for a legacy device with the same ID (including PCI Revision, Device and Vendor IDs) is known to have previously existed, -- cgit v1.2.3 From fdc047cb06529edebed75a185b2bab7383161470 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 08:26:11 +0000 Subject: pci: missing documentation for dealing with 64 bit config fields pci spec says what width access to use for 32, 16 and 8 bit fields, but does not explicitly say what to do for 32 bit fields. As we have text that says driver must treat 64 bit accesses as non-atomic, this seems to imply driver should always do two 32 bit wide accesses. Let's make this an explicit requirement, and require devices to support this. VIRTIO-139 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@508 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- conformance.tex | 1 + content.tex | 19 ++++++++++++++----- 2 files changed, 15 insertions(+), 5 deletions(-) diff --git a/conformance.tex b/conformance.tex index 350d2d0..0f601d7 100644 --- a/conformance.tex +++ b/conformance.tex @@ -155,6 +155,7 @@ A PCI device MUST conform to the following normative statements: \begin{itemize} \item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus} \item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout} \item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / Virtio Structure PCI Capabilities} \item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout} \item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability} diff --git a/content.tex b/content.tex index 48d735d..95ae23e 100644 --- a/content.tex +++ b/content.tex @@ -1083,14 +1083,23 @@ Structure PCI Capabilities. Fields of different sizes are present in the device configuration regions. -All 32-bit and 16-bit fields are little-endian. +All 64-bit, 32-bit and 16-bit fields are little-endian. +64-bit fields are to be treated as two 32-bit fields, +with low 32 bit part followed by the high 32 bit part. \drivernormative{\subsubsection}{PCI Device Layout}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout} -The driver -MUST access each field using the ``natural'' access method, i.e. -32-bit accesses for 32-bit fields, 16-bit accesses for 16-bit -fields and 8-bit accesses for 8-bit fields. +For device configuration access, 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-bit and 64-bit wide fields. For 64-bit fields, the driver MAY +access each of the high and low 32-bit parts of the field +independently. + +\devicenormative{\subsubsection}{PCI Device Layout}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout} + +For 64-bit device configuration fields, the device MUST allow driver +independent access to high and low 32-bit parts of the field. \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / Virtio Structure PCI Capabilities} -- cgit v1.2.3 From 74fc1eee7b04389562d525e91e47be295eb2714c Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 08:26:27 +0000 Subject: balloon: MUST -> has to MUST shouldn't be used outside normative statements, that's confusing. Replace with "has to". Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@509 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content.tex b/content.tex index 95ae23e..748c78d 100644 --- a/content.tex +++ b/content.tex @@ -4338,7 +4338,7 @@ guest memory statistics to the host. \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Feature bits} \begin{description} -\item[VIRTIO_BALLOON_F_MUST_TELL_HOST (0)] Host MUST be told before +\item[VIRTIO_BALLOON_F_MUST_TELL_HOST (0)] Host has to be told before pages from the balloon are used. \item[VIRTIO_BALLOON_F_STATS_VQ (1)] A virtqueue for reporting guest -- cgit v1.2.3 From e8ea9dd1f96fe548b29a5db5eaec3039b9956e5f Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 09:06:41 +0000 Subject: conformance: add VIRTIO-137 to statements Add links to new conformance statements added to resolve VIRTIO-137 (describing used ring entry len usage). Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@510 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- conformance.tex | 2 ++ 1 file changed, 2 insertions(+) diff --git a/conformance.tex b/conformance.tex index 0f601d7..bac51e5 100644 --- a/conformance.tex +++ b/conformance.tex @@ -38,6 +38,7 @@ A driver MUST conform to the following normative statements: \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression} +\item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression} \item \ref{drivernormative:General Initialization And Device Operation / Device Initialization} \item \ref{drivernormative:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Updating idx} @@ -144,6 +145,7 @@ A device MUST conform to the following normative statements: \item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression} +\item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression} \item \ref{devicenormative:Reserved Feature Bits} \end{itemize} -- cgit v1.2.3 From 8aaa8ec616d023ab9577cd30f16d7460c4ea936d Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 11:25:04 +0000 Subject: makediff: cherry pick disabling markup on cl Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@511 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- makediff.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/makediff.sh b/makediff.sh index 1135cbb..cb6eb76 100755 --- a/makediff.sh +++ b/makediff.sh @@ -23,6 +23,7 @@ Revert: formatting: mark change manually as changed in cs02 cl: move out cs02 changelog cl: drop contents temporarily changelog: comment out header +changelog: disable markup EOF #mv specvars.tex specvars-orig.tex -- cgit v1.2.3 From c8fa7c1b3a541445f475f5a7a2383f8c1e117d0f Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 11:25:21 +0000 Subject: diffpreamble: redefine colors in nomarkup section Changelog appears within DIFaddbegin/DIFaddend, suppress marking it as added text, that's confusing. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@512 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- diffpreamble.tex | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/diffpreamble.tex b/diffpreamble.tex index 8162004..9b5b7e5 100644 --- a/diffpreamble.tex +++ b/diffpreamble.tex @@ -27,6 +27,13 @@ \providecommand{\DIFaddendFL}{} \providecommand{\DIFdelbeginFL}{} \providecommand{\DIFdelendFL}{} +\renewenvironment{DIFnomarkup} +{ +\begingroup\color{black}\hypersetup{linkcolor=blue,urlcolor=blue} +} +{ +\endgroup +} %DIF END FLOATSAFE PREAMBLE %% diffpreable.tex end -- cgit v1.2.3 From e0ce988563106c29a5d88219b92ee63eb79a8cc7 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 11:25:38 +0000 Subject: cl: document VIRTIO-137 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@513 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/cl-os.tex b/cl-os.tex index 05b6dfa..6ae3180 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -83,3 +83,29 @@ Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver}. } \\ \hline +504 & 22 Apr 2015 & Rusty Russell & {VIRTIO-137: +define the meaning and requirements of the len field. + +We said what it was for, and noted why. We didn't place any +requirements on it, nor clearly spell out the implications of its use. + +This clarification comes particularly from noticing that QEMU +didn't set len correctly, and philosophising over the correct value +when an error has occurred. +See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / +The Virtqueue Used Ring}, \ref{devicenormative:Basic Facilities +of a Virtio Device / Virtqueues / The Virtqueue Used Ring} and +\ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The +Virtqueue Used Ring}. + } \\ +\hline +510 & 22 Apr 2015 & Michael Tsirkin & {conformance: +add VIRTIO-137 statement links + +Add links to new conformance statements added to +resolve VIRTIO-137 (describing used ring entry len usage). + +See \ref{sec:Conformance / Device Conformance} +and \ref{sec:Conformance / Driver Conformance}. + } \\ +\hline -- cgit v1.2.3 From 8aae5034956b183536aae59586541a783e78c4e4 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 11:25:58 +0000 Subject: cl: document r508: VIRTIO-139 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@514 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/cl-os.tex b/cl-os.tex index 6ae3180..5278658 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -99,6 +99,26 @@ of a Virtio Device / Virtqueues / The Virtqueue Used Ring} and Virtqueue Used Ring}. } \\ \hline +508 & 22 Apr 2015 & Michael Tsirkin & {VIRTIO-139: +pci: missing documentation for dealing with 64 bit config fields + +pci spec says what width access to use for 32, 16 and 8 +bit fields, but does not explicitly say what to do for +32 bit fields. As we have text that says driver must +treat 64 bit accesses as non-atomic, this seems +to imply driver should always do two 32 bit wide accesses. + +Let's make this an explicit requirement, and require +devices to support this. + +See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI +Device Layout}, \ref{drivernormative:Virtio Transport Options / +Virtio Over PCI Bus / PCI Device Layout}, +\ref{devicenormative:Virtio Transport Options / Virtio Over PCI +Bus / PCI Device Layout} and \ref{sec:Conformance / Driver +Conformance / PCI Driver Conformance}. + } \\ +\hline 510 & 22 Apr 2015 & Michael Tsirkin & {conformance: add VIRTIO-137 statement links -- cgit v1.2.3 From 29b3906c61385501ec846d5163cabf1bcc32b73f Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 11:26:17 +0000 Subject: cl: list r506 and VIRTIO-138 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@515 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/cl-os.tex b/cl-os.tex index 5278658..ffa3601 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -99,6 +99,38 @@ of a Virtio Device / Virtqueues / The Virtqueue Used Ring} and Virtqueue Used Ring}. } \\ \hline +506 & 22 Apr 2015 & Michael Tsirkin & {VIRTIO-138: +multiple errors: Non-transitional With Legacy + +virtio 1.0 has two sections titled "Non-transitional Device With +Legacy Driver" the first says devices SHOULD fail, the second +says devices MUST fail. Clearly a mistake. + +Other issues: devices don't really fail - they cause drivers to +fail. second section seems to be in the wrong place, and also +have a section followed by subsection with no explanatory text in +between, which is ugly. +Finally, this text was originally ritten to handle buggy windows +drivers gracefully, but later we changed device IDs so it's not +really required there. Might be handy for some other buggy legacy +drivers, though no such drivers are known. + +To fix, drop the duplicate section variant, add some explanatory +text, clarify what does "same ID" mean here, and clarify +that the work-around is only needed if a buggy driver +is known to bind to a transitional device. + +See \ref{sec:Virtio Transport Options / Virtio +Over PCI Bus / PCI Device Layout / Non-transitional Device With +Legacy Driver: A Note on PCI Device Layout}, +\ref{devicenormative:Virtio Transport Options / Virtio Over PCI +Bus / PCI-specific Initialization And Device Operation / Device +Initialization / Non-transitional Device With Legacy Driver} and +\ref{sec:Virtio Transport Options / Virtio Over PCI Bus / +PCI-specific Initialization And Device Operation / Device +Initialization}. +} \\ +\hline 508 & 22 Apr 2015 & Michael Tsirkin & {VIRTIO-139: pci: missing documentation for dealing with 64 bit config fields -- cgit v1.2.3 From 4a135df4116c17baf70e222b20eeabfba4b3c53d Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 11:26:37 +0000 Subject: cl: document r509 wording tweak in balloon. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@516 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/cl-os.tex b/cl-os.tex index ffa3601..c744dbb 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -151,6 +151,16 @@ Bus / PCI Device Layout} and \ref{sec:Conformance / Driver Conformance / PCI Driver Conformance}. } \\ \hline +509 & 22 Apr 2015 & Michael Tsirkin & {balloon: +MUST -> has to + +MUST shouldn't be used outside normative statements, +that's confusing. Replace with "has to". + +See \ref{sec:Device Types / Memory Balloon Device / Feature +bits}. + } \\ +\hline 510 & 22 Apr 2015 & Michael Tsirkin & {conformance: add VIRTIO-137 statement links -- cgit v1.2.3 From 464653caedd353652354fed220178af382ce7816 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 11:32:03 +0000 Subject: acknowledgements: contributors+minor fixup acknowledge feedback by Jason Wang, add Richard Sohn who joined the TC, sort acknowledged reviewers alphabetically. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@517 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- acknowledgements.tex | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/acknowledgements.tex b/acknowledgements.tex index 3866a0c..6c86d12 100644 --- a/acknowledgements.tex +++ b/acknowledgements.tex @@ -20,6 +20,7 @@ Luiz Capitulino, Red Hat \newline Michael S. Tsirkin, Red Hat \newline Paolo Bonzini, Red Hat \newline Pawel Moll, ARM \newline +Richard Sohn, Alcatel-Lucent \newline Rusty Russell, IBM \newline Sasha Levin, Oracle \newline Sergey Tverdyshev, Thales e-Security \newline @@ -33,12 +34,13 @@ specification and are gratefully acknowledged: \begin{oasistitlesection}{Reviewers} Andrew Thornton, Google \newline Arun Subbarao, LynuxWorks \newline +Brian Foley, ARM \newline +David Alan Gilbert, Red Hat \newline Fam Zheng, Red Hat \newline Gerd Hoffmann, Red Hat \newline +Jason Wang, Red Hat \newline Laura Novich, Red Hat \newline Patrick Durusau, Technical Advisory Board, OASIS \newline Thomas Huth, IBM \newline Yan Vugenfirer, Red Hat / Daynix \newline -Brian Foley, ARM \newline -David Alan Gilbert, Red Hat \newline \end{oasistitlesection} -- cgit v1.2.3 From 1a776d986d1b9ebe6bb5c5bb757be81bd3bf2e86 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 11:32:25 +0000 Subject: cl: document r517 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@518 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/cl-os.tex b/cl-os.tex index c744dbb..a201f90 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -171,3 +171,12 @@ See \ref{sec:Conformance / Device Conformance} and \ref{sec:Conformance / Driver Conformance}. } \\ \hline +517 & 22 Apr 2015 & Michael Tsirkin & {acknowledgements: +contributors+minor fixup + +acknowledge feedback by Jason Wang, add Richard Sohn who +joined the TC, sort acknowledged reviewers alphabetically. + +See \ref{chap:Acknowledgements}. +} \\ +\hline -- cgit v1.2.3 From 4ce541760523e7e1dba274d4e0c98473d93f61c0 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 22 Apr 2015 11:32:51 +0000 Subject: cl: fix name for MST Should be Michael S. Tsirkin, not Michael Tsirkin. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@519 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/cl-os.tex b/cl-os.tex index a201f90..1a6f799 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -99,7 +99,7 @@ of a Virtio Device / Virtqueues / The Virtqueue Used Ring} and Virtqueue Used Ring}. } \\ \hline -506 & 22 Apr 2015 & Michael Tsirkin & {VIRTIO-138: +506 & 22 Apr 2015 & Michael S. Tsirkin & {VIRTIO-138: multiple errors: Non-transitional With Legacy virtio 1.0 has two sections titled "Non-transitional Device With @@ -131,7 +131,7 @@ PCI-specific Initialization And Device Operation / Device Initialization}. } \\ \hline -508 & 22 Apr 2015 & Michael Tsirkin & {VIRTIO-139: +508 & 22 Apr 2015 & Michael S. Tsirkin & {VIRTIO-139: pci: missing documentation for dealing with 64 bit config fields pci spec says what width access to use for 32, 16 and 8 @@ -151,7 +151,7 @@ Bus / PCI Device Layout} and \ref{sec:Conformance / Driver Conformance / PCI Driver Conformance}. } \\ \hline -509 & 22 Apr 2015 & Michael Tsirkin & {balloon: +509 & 22 Apr 2015 & Michael S. Tsirkin & {balloon: MUST -> has to MUST shouldn't be used outside normative statements, @@ -161,7 +161,7 @@ See \ref{sec:Device Types / Memory Balloon Device / Feature bits}. } \\ \hline -510 & 22 Apr 2015 & Michael Tsirkin & {conformance: +510 & 22 Apr 2015 & Michael S. Tsirkin & {conformance: add VIRTIO-137 statement links Add links to new conformance statements added to @@ -171,7 +171,7 @@ See \ref{sec:Conformance / Device Conformance} and \ref{sec:Conformance / Driver Conformance}. } \\ \hline -517 & 22 Apr 2015 & Michael Tsirkin & {acknowledgements: +517 & 22 Apr 2015 & Michael S. Tsirkin & {acknowledgements: contributors+minor fixup acknowledge feedback by Jason Wang, add Richard Sohn who -- cgit v1.2.3 From 12e4378536ea473f578edf05b83c78b9f846d516 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 29 Apr 2015 11:08:43 +0000 Subject: give explicit guidance on the use of 64 bit fields Just saying 64 bit fields may not be atomic is true, but less helpful than it might be. Add explicit guidance about what the consequences of non-atomicity are. VIRTIO-140 Signed-off-by: James Bottomley Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@520 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- newdevice.tex | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/newdevice.tex b/newdevice.tex index c7e6221..28e1c7b 100644 --- a/newdevice.tex +++ b/newdevice.tex @@ -22,8 +22,9 @@ configuration information (the network device does this for filtering, otherwise the table in the config space could potentially be very large). -Remember that configuration fields over 32 bits wide might not be -atomically writable by the driver. +Remember that configuration fields over 32 bits wide might not be atomically +writable by the driver. Therefore, no writeable field which triggers an +action ought to be wider than 32 bits. \section{What Device Number?}\label{sec:Creating New Device Types / What Device Number?} -- cgit v1.2.3 From 3b676c2fb1c342ab01565ab61354b62105640427 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 29 Apr 2015 11:09:04 +0000 Subject: VIRTIO-134: Spell out details of indirect elements in chains 1) It's implied that a chain terminates with an indirect descriptor (since VIRTIO-15) but we didn't spell out that a device MUST NOT continue it. 2) We allow [direct]->[direct]->[indirect], and qemu and bhyve both accept it. Make it clear that this is valid, thus devices MUST handle it. Signed-off-by: Rusty Russell Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@521 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/content.tex b/content.tex index 748c78d..2d032a7 100644 --- a/content.tex +++ b/content.tex @@ -477,9 +477,21 @@ one table per descriptor). A driver MUST NOT create a descriptor chain longer than the Queue Size of the device. +A driver MUST NOT set both VIRTQ_DESC_F_INDIRECT and VIRTQ_DESC_F_NEXT +in \field{flags}. + \devicenormative{\paragraph}{Indirect Descriptors}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors} The device MUST ignore the write-only flag (\field{flags}\&VIRTQ_DESC_F_WRITE) in the descriptor that refers to an indirect table. +The device MUST handle the case of zero or more normal chained +descriptors followed by a single descriptor with \field{flags}\&VIRTQ_DESC_F_INDIRECT. + +\begin{note} +While unusual (most implementations either create a chain solely using +non-indirect descriptors, or use a single indirect element), such a +layout is valid. +\end{note} + \subsection{The Virtqueue Available Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Available Ring} \begin{lstlisting} -- cgit v1.2.3 From 3470801a246fc18326454d5c3ec91b543e6390e1 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 29 Apr 2015 11:09:21 +0000 Subject: used ring: specify legacy behaviour for len field many hypervisors implemented len field incorrectly. Document existing bugs in the legacy sections. VIRTIO-141 Signed-off-by: Rusty Russell Cc: Paolo Bonzini Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@522 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/content.tex b/content.tex index 2d032a7..7e46b7d 100644 --- a/content.tex +++ b/content.tex @@ -626,6 +626,17 @@ the constant as VRING_USED_F_NO_NOTIFY, but the layout and value were identical. \end{note} +\subsubsection{Legacy Interface: The Virtqueue Used +Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues +/ The Virtqueue Used Ring/ Legacy Interface: The Virtqueue Used +Ring} + +Historically, many drivers ignored the \field{len} value, as a +result, many devices set \field{len} incorrectly. Thus, when +using the legacy interface, it is generally a good idea to ignore +the \field{len} value in used ring entries if possible. Specific +known issues are listed per device type. + \devicenormative{\subsubsection}{The Virtqueue Used Ring}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring} The device MUST set \field{len} prior to updating the used \field{idx}. @@ -3248,6 +3259,15 @@ The legacy driver only presented \field{num_buffers} in the struct virtio_net_hd when VIRTIO_NET_F_MRG_RXBUF was not negotiated; without that feature the structure was 2 bytes shorter. +When using the legacy interface, the driver SHOULD ignore the +\field{len} value in used ring entries for the transmit queues +and the controlq queue. +\begin{note} +Historically, some devices put +the total descriptor length there, even though no data was +actually written. +\end{note} + \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / Device Operation / Packet Transmission} Transmitting a single packet is simple, but varies depending on @@ -3948,6 +3968,14 @@ MUST format the fields in struct virtio_blk_req according to the native endian of the guest rather than (necessarily when not using the legacy interface) little-endian. +When using the legacy interface, transitional drivers +SHOULD ignore the \field{len} value in used ring entries. +\begin{note} +Historically, some devices put the total descriptor length, +or the total length of device-writable buffers there, +even when only the status byte was actually written. +\end{note} + The \field{reserved} field was previously called \field{ioprio}. \field{ioprio} is a hint about the relative priorities of requests to the device: higher numbers indicate more important requests. @@ -4271,6 +4299,14 @@ MUST format the fields in struct virtio_console_control according to the native endian of the guest rather than (necessarily when not using the legacy interface) little-endian. +When using the legacy interface, the driver SHOULD ignore the +\field{len} value in used ring entries for the transmit queues +and the control transmitq. +\begin{note} +Historically, some devices put the total descriptor length there, +even though no data was actually written. +\end{note} + \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Console Device / Legacy Interface: Framing Requirements} @@ -4444,6 +4480,15 @@ before using the pages. The driver MUST update \field{actual} after changing the number of pages in the balloon. +\paragraph{Legacy Interface: Device Operation}\label{sec:Device +Types / Memory Balloon Device / Device Operation / Legacy +Interface: Device Operation} +When using the legacy interface, the driver SHOULD ignore the \field{len} value in used ring entries. +\begin{note} +Historically, some devices put the total descriptor length there, +even though no data was actually written. +\end{note} + \subsubsection{Memory Statistics}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics} The stats virtqueue is atypical because communication is driven @@ -4661,6 +4706,16 @@ RESET.}. Device operation consists of operating request queues, the control queue and the event queue. +\paragraph{Legacy Interface: Device Operation}\label{sec:Device +Types / SCSI Host Device / Device Operation / Legacy +Interface: Device Operation} +When using the legacy interface, the driver SHOULD ignore the \field{len} value in used ring entries. +\begin{note} +Historically, devices put the total descriptor length, +or the total length of device-writable buffers there, +even when only part of the buffers were actually written. +\end{note} + \subsubsection{Device Operation: Request Queues}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues} The driver queues requests to an arbitrary request queue, and -- cgit v1.2.3 From 99aacdaa9d8c60950bde56ddddafede496d7e7c7 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 29 Apr 2015 11:09:39 +0000 Subject: entropy device: typo fix The driver MUST examine the length written by the driver makes no sense. length is written by the device. VIRTIO-142 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@523 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content.tex b/content.tex index 7e46b7d..11015a5 100644 --- a/content.tex +++ b/content.tex @@ -4349,7 +4349,7 @@ by random data by the device. The driver MUST NOT place driver-readable buffers into the queue. -The driver MUST examine the length written by the driver to determine +The driver MUST examine the length written by the device to determine how many random bytes were received. \devicenormative{\subsubsection}{Device Operation}{Device Types / Entropy Device / Device Operation} -- cgit v1.2.3 From dfb4b9c11c7b15e34045c500e89ffa2fa5015712 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 29 Apr 2015 11:09:56 +0000 Subject: conformance: add missing links previous commit "used ring: specify legacy behaviour for len field" to resolve VIRTIO-141 added new sections with normative statements for legacy balloon and scsi devices. Link them from the conformance section. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@524 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- conformance.tex | 2 ++ 1 file changed, 2 insertions(+) diff --git a/conformance.tex b/conformance.tex index bac51e5..80b333f 100644 --- a/conformance.tex +++ b/conformance.tex @@ -293,8 +293,10 @@ Feature Bits / Legacy Interface: A Note on Feature Bits} \item Section \ref{sec:Device Types / Console Device / Device configuration layout / Legacy Interface: Device configuration layout} \item Section \ref{sec:Device Types / Console Device / Device Operation / Legacy Interface: Device Operation} \item Section \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation} +\item Section \ref{sec:Device Types / Memory Balloon Device / Device Operation / Legacy Interface: Device Operation} \item Section \ref{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics / Legacy Interface: Memory Statistics} \item Section \ref{sec:Device Types / SCSI Host Device / Device configuration layout / Legacy Interface: Device configuration layout} +\item Section \ref{sec:Device Types / SCSI Host Device / Device Operation / Legacy Interface: Device Operation} \item Section \ref{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues / Legacy Interface: Device Operation: Request Queues} \item Section \ref{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: controlq / Legacy Interface: Device Operation: controlq} \item Section \ref{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: eventq / Legacy Interface: Device Operation: eventq} -- cgit v1.2.3 From c6f96d66e73a132172d186fd57d468b87a86ec56 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Wed, 29 Apr 2015 11:10:14 +0000 Subject: cl: document VIRTIO-134, VIRTIO-140, VIRTIO-141, VIRTIO-142 document changes made by commits r520 to r523 inclusive Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@525 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/cl-os.tex b/cl-os.tex index 1a6f799..ee65be3 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -180,3 +180,63 @@ joined the TC, sort acknowledged reviewers alphabetically. See \ref{chap:Acknowledgements}. } \\ \hline +520 & 30 Apr 2015 & James Bottomley & {VIRTIO-140: +give explicit guidance on the use of 64 bit fields + +Just saying 64 bit fields may not be atomic is true, but less +helpful than it might be. Add explicit guidance about what the +consequences of non-atomicity are. + +See \ref{sec:Creating New Device Types / What Device +Configuration Space Layout?} +} \\ +\hline +521 & 30 Apr 2015 & Rusty Russell & {VIRTIO-134: +Spell out details of indirect elements in chains + +1) It's implied that a chain terminates with an indirect descriptor (since +VIRTIO-15) but we didn't spell out that a device MUST NOT +continue it. + +2) We allow [direct]->[direct]->[indirect], and qemu and +bhyve both accept it. Make it clear that this is valid, thus devices MUST +handle it. + +See \ref{drivernormative:Basic Facilities of a Virtio Device / +Virtqueues / The Virtqueue Descriptor Table / Indirect +Descriptors} and \ref{devicenormative:Basic Facilities of a +Virtio Device / Virtqueues / The Virtqueue Descriptor Table / +Indirect Descriptors} +} \\ +\hline +522 & 30 Apr 2015 & Michael S. Tsirkin & {VIRTIO-141: +used ring: specify legacy behaviour for len field + +many hypervisors implemented len field incorrectly. +Document existing bugs in the legacy sections. + +See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues +/ The Virtqueue Used Ring/ Legacy Interface: The Virtqueue Used +Ring}, \ref{sec:Device Types / Network Device / Device Operation +/ Legacy Interface: Device Operation}, \ref{sec:Device Types / +Block Device / Device Operation / Legacy Interface: Device +Operation}, \ref{sec:Device Types / Console Device / Device +Operation / Legacy Interface: Device Operation}, \ref{sec:Device +Types / Memory Balloon Device / Device Operation / Legacy +Interface: Device Operation}, \ref{sec:Device +Types / SCSI Host Device / Device Operation / Legacy +Interface: Device Operation} and \ref{sec:Conformance / Legacy +Interface: Transitional Device and Transitional Driver +Conformance}. +} \\ +\hline +523 & 30 Apr 2015 & Michael S. Tsirkin & {VIRTIO-142: +entropy device: typo fix + +Current text: "The driver MUST examine the length written by the +driver" makes no sense. length is written by the device. + +See \ref{drivernormative:Device Types / Entropy Device / Device +Operation}. +} \\ +\hline -- cgit v1.2.3 From 0eb5a23ae51b8b5c99a5176a52f81c097d925895 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Mon, 18 May 2015 20:48:58 +0000 Subject: balloon: transitional device support Virtio 1.0 cs02 doesn't include a modern balloon device. At some point we'll likely define an incompatible interface with a different ID and different semantics. But for now, it's not a big effort to support a transitional balloon device: this has the advantage of supporting existing drivers, transparently, as well as transports that don't allow mixing virtio 0 and virtio 1 devices. And balloon is an easy device to test, so it's also useful for people to test virtio core handling of transitional devices. Three issues with legacy hypervisors have been identified: 1. Actual value is actually used, and is necessary for management to work. Luckily 4 byte config space writes are now atomic. When using old guests, hypervisors can detect access to the last byte. When using old hypervisors, drivers can use atomic 4-byte accesses. 2. Hypervisors actually didn't ignore the stats from the first buffer supplied. This means the values there would be incorrect until hypervisor resends the request. Add a note suggesting hypervisors ignore the 1st buffer. 3. QEMU simply over-writes stats from each buffer it gets. Thus if driver supplies a different subset of stats on each request, stale values will be there. Require drivers to supply the same subset on each request. This also gives us a simple way to figure out which stats are supported. VIRTIO-143 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@526 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- conformance.tex | 26 ++++++++- content.tex | 171 +++++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 168 insertions(+), 29 deletions(-) diff --git a/conformance.tex b/conformance.tex index 80b333f..279b5cb 100644 --- a/conformance.tex +++ b/conformance.tex @@ -15,13 +15,13 @@ Conformance targets: \begin{itemize} \item Clause \ref{sec:Conformance / Driver Conformance}, \item One of clauses \ref{sec:Conformance / Driver Conformance / PCI Driver Conformance}, \ref{sec:Conformance / Driver Conformance / MMIO Driver Conformance} or \ref{sec:Conformance / Driver Conformance / Channel I/O Driver Conformance}. - \item One of clauses \ref{sec:Conformance / Driver Conformance / Network Driver Conformance}, \ref{sec:Conformance / Driver Conformance / Block Driver Conformance}, \ref{sec:Conformance / Driver Conformance / Console Driver Conformance}, \ref{sec:Conformance / Driver Conformance / Entropy Driver Conformance} or \ref{sec:Conformance / Driver Conformance / SCSI Host Driver Conformance}. + \item One of clauses \ref{sec:Conformance / Driver Conformance / Network Driver Conformance}, \ref{sec:Conformance / Driver Conformance / Block Driver Conformance}, \ref{sec:Conformance / Driver Conformance / Console Driver Conformance}, \ref{sec:Conformance / Driver Conformance / Entropy Driver Conformance}, \ref{sec:Conformance / Driver Conformance / Traditional Memory Balloon Driver Conformance} or \ref{sec:Conformance / Driver Conformance / SCSI Host Driver Conformance}. \end{itemize} \item[Device] A device MUST conform to three conformance clauses: \begin{itemize} \item Clause \ref{sec:Conformance / Device Conformance}, \item One of clauses \ref{sec:Conformance / Device Conformance / PCI Device Conformance}, \ref{sec:Conformance / Device Conformance / MMIO Device Conformance} or \ref{sec:Conformance / Device Conformance / Channel I/O Device Conformance}. - \item One of clauses \ref{sec:Conformance / Device Conformance / Network Device Conformance}, \ref{sec:Conformance / Device Conformance / Block Device Conformance}, \ref{sec:Conformance / Device Conformance / Console Device Conformance}, \ref{sec:Conformance / Device Conformance / Entropy Device Conformance} or \ref{sec:Conformance / Device Conformance / SCSI Host Device Conformance}. + \item One of clauses \ref{sec:Conformance / Device Conformance / Network Device Conformance}, \ref{sec:Conformance / Device Conformance / Block Device Conformance}, \ref{sec:Conformance / Device Conformance / Console Device Conformance}, \ref{sec:Conformance / Device Conformance / Entropy Device Conformance}, \ref{sec:Conformance / Device Conformance / Traditional Memory Balloon Device Conformance} or \ref{sec:Conformance / Device Conformance / SCSI Host Device Conformance}. \end{itemize} \end{description} @@ -123,6 +123,16 @@ An entropy driver MUST conform to the following normative statements: \item \ref{drivernormative:Device Types / Entropy Device / Device Operation} \end{itemize} +\subsection{Traditional Memory Balloon Driver Conformance}\label{sec:Conformance / Driver Conformance / Traditional Memory Balloon Driver Conformance} + +A traditional memory balloon driver MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{drivernormative:Device Types / Memory Balloon Device / Feature bits} +\item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation} +\item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation / Memory Statistics} +\end{itemize} + \subsection{SCSI Host Driver Conformance}\label{sec:Conformance / Driver Conformance / SCSI Host Driver Conformance} An SCSI host driver MUST conform to the following normative statements: @@ -230,6 +240,16 @@ An entropy device MUST conform to the following normative statements: \item \ref{devicenormative:Device Types / Entropy Device / Device Operation} \end{itemize} +\subsection{Traditional Memory Balloon Device Conformance}\label{sec:Conformance / Device Conformance / Traditional Memory Balloon Device Conformance} + +A traditional memory balloon device MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{devicenormative:Device Types / Memory Balloon Device / Feature bits} +\item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation} +\item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation / Memory Statistics} +\end{itemize} + \subsection{SCSI Host Device Conformance}\label{sec:Conformance / Device Conformance / SCSI Host Device Conformance} An SCSI host device MUST conform to the following normative statements: @@ -292,7 +312,7 @@ Feature Bits / Legacy Interface: A Note on Feature Bits} \item Section \ref{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation} \item Section \ref{sec:Device Types / Console Device / Device configuration layout / Legacy Interface: Device configuration layout} \item Section \ref{sec:Device Types / Console Device / Device Operation / Legacy Interface: Device Operation} -\item Section \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation} +\item Section \ref{sec:Device Types / Memory Balloon Device / Feature bits / Legacy Interface: Feature bits} \item Section \ref{sec:Device Types / Memory Balloon Device / Device Operation / Legacy Interface: Device Operation} \item Section \ref{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics / Legacy Interface: Memory Statistics} \item Section \ref{sec:Device Types / SCSI Host Device / Device configuration layout / Legacy Interface: Device configuration layout} diff --git a/content.tex b/content.tex index 11015a5..b1cd7bf 100644 --- a/content.tex +++ b/content.tex @@ -1046,7 +1046,7 @@ Transitional PCI Device ID & Virtio Device \\ \hline 0x1001 & block device \\ \hline -0x1002 & memory ballooning (legacy) \\ +0x1002 & memory ballooning (traditional) \\ \hline 0x1003 & console \\ \hline @@ -2966,7 +2966,7 @@ Device ID & Virtio Device \\ \hline 4 & entropy source \\ \hline -5 & memory ballooning (legacy) \\ +5 & memory ballooning (traditional) \\ \hline 6 & ioMemory \\ \hline @@ -4357,14 +4357,13 @@ how many random bytes were received. The device MUST place one or more random bytes into the buffer, but it MAY use less than the entire buffer length. -\section{Legacy Interface: Memory Balloon Device}\label{sec:Device Types / Memory Balloon Device} +\section{Traditional Memory Balloon Device}\label{sec:Device Types / Memory Balloon Device} -This device is deprecated, and thus only exists as a legacy device -illustrated here for reference. The device number 13 is reserved for -a new memory balloon interface which is expected in a future version -of the standard. +This is the traditional balloon device. The device number 13 is +reserved for a new memory balloon interface, with different +semantics, which is expected in a future version of the standard. -The virtio memory balloon device is a primitive device for +The traditional virtio memory balloon device is a primitive device for managing guest memory: the device asks for a certain amount of memory, and the driver supplies it (or withdraws it, if the device has more than it asks for). This allows the guest to adapt to @@ -4393,6 +4392,25 @@ guest memory statistics to the host. memory statistics is present. \end{description} +\drivernormative{\subsubsection}{Feature bits}{Device Types / Memory Balloon Device / Feature bits} +The driver SHOULD accept the VIRTIO_BALLOON_F_MUST_TELL_HOST +feature if offered by the device. + +\devicenormative{\subsubsection}{Feature bits}{Device Types / Memory Balloon Device / Feature bits} +If the device offers the VIRTIO_BALLOON_F_MUST_TELL_HOST feature +bit, and if the driver did not accept this feature bit, the +device MAY signal failure by failing to set FEATURES_OK +\field{device status} bit when the driver writes it. +\subparagraph{Legacy Interface: Feature bits}\label{sec:Device +Types / Memory Balloon Device / Feature bits / Legacy Interface: +Feature bits} +As the legacy interface does not have a way to gracefully report feature +negotiation failure, when using the legacy interface, +transitional devices MUST support guests which do not negotiate +VIRTIO_BALLOON_F_MUST_TELL_HOST feature, and SHOULD +allow guest to use memory before notifying host if +VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated. + \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout} Both fields of this configuration are always available. @@ -4404,25 +4422,31 @@ struct virtio_balloon_config { }; \end{lstlisting} -Note that these fields are always little endian, despite convention -that legacy device fields are guest endian. +\subparagraph{Legacy Interface: Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device +configuration layout / Legacy Interface: Device configuration layout} +When using the legacy interface, transitional devices and drivers +MUST format the fields in struct virtio_balloon_config +according to the little-endian format. +\begin{note} +This is unlike the usual convention that legacy device fields are guest endian. +\end{note} \subsection{Device Initialization}\label{sec:Device Types / Memory Balloon Device / Device Initialization} +The device initialization process is outlined below: + \begin{enumerate} \item The inflate and deflate virtqueues are identified. \item If the VIRTIO_BALLOON_F_STATS_VQ feature bit is negotiated: \begin{enumerate} \item Identify the stats virtqueue. - - \item Add one empty buffer to the stats virtqueue and notify the - device. + \item Add one empty buffer to the stats virtqueue. + \item DRIVER_OK is set: device operation begins. + \item Notify the device about the stats virtqueue buffer. \end{enumerate} \end{enumerate} -Device operation begins immediately. - \subsection{Device Operation}\label{sec:Device Types / Memory Balloon Device / Device Operation} The device is driven by the receipt of a @@ -4451,16 +4475,16 @@ configuration change interrupt. \item If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the guest informs the device of pages before it uses them. - \item Otherwise, the guest MAY begin to re-use pages previously + \item Otherwise, the guest is allowed to re-use pages previously given to the balloon before the device has acknowledged their withdrawal\footnote{In this case, deflation advice is merely a courtesy. }. \end{enumerate} -\item In either case, once the device has completed the inflation or - deflation, the driver updates \field{actual} to reflect the new number of pages in the balloon\footnote{As updates to device-specific configuration space are not atomic, this field -isn't particularly reliable, but can be used to diagnose buggy guests. -}. +\item In either case, the device acknowledges inflate and deflate +requests by using the descriptor. +\item Once the device has acknowledged the inflation or + deflation, the driver updates \field{actual} to reflect the new number of pages in the balloon. \end{enumerate} \drivernormative{\subsubsection}{Device Operation}{Device Types / Memory Balloon Device / Device Operation} @@ -4474,12 +4498,38 @@ The driver MUST use the deflateq to inform the device of pages that it wants to use from the balloon. If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the -driver MUST wait until the device has used the deflateq descriptor -before using the pages. +driver MUST NOT use pages from the balloon until +the device has acknowledged the deflate request. + +Otherwise, if the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is not +negotiated, the driver MAY begin to re-use pages previously +given to the balloon before the device has acknowledged the +deflate request. + +In any case, the driver MUST NOT use pages from the balloon +after adding the pages to the balloon, but before the device has +acknowledged the inflate request. + +The driver MUST NOT request deflation of pages in +the balloon before the device has acknowledged the inflate +request. The driver MUST update \field{actual} after changing the number of pages in the balloon. +\devicenormative{\subsubsection}{Device Operation}{Device Types / Memory Balloon Device / Device Operation} + +The device MAY modify the contents of a page in the balloon +after detecting its physical number in an inflate request +and before acknowledging the inflate request by using the inflateq +descriptor. + +If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the +device MAY modify the contents of a page in the balloon +after detecting its physical number in an inflate request +and before detecting its physical number in a deflate request +and acknowledging the deflate request. + \paragraph{Legacy Interface: Device Operation}\label{sec:Device Types / Memory Balloon Device / Device Operation / Legacy Interface: Device Operation} @@ -4488,7 +4538,25 @@ When using the legacy interface, the driver SHOULD ignore the \field{len} value Historically, some devices put the total descriptor length there, even though no data was actually written. \end{note} - +When using the legacy interface, the driver MUST write out all +4 bytes each time it updates the \field{actual} value in the +configuration space, using a single atomic operation. + +When using the legacy interface, the device SHOULD NOT use the +\field{actual} value written by the driver in the configuration +space, until the last, most-significant byte of the value has been +written. +\begin{note} +Historically, devices used the \field{actual} value, even though +when using Virtio Over PCI Bus the device-specific configuration +space was not guaranteed to be atomic. Using intermediate +values during update by driver is best avoided, except for +debugging. + +Historically, drivers using Virtio Over PCI Bus wrote the +\field{actual} value by using multiple single-byte writes in +order, from the least-significant to the most-significant value. +\end{note} \subsubsection{Memory Statistics}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics} The stats virtqueue is atypical because communication is driven @@ -4513,10 +4581,11 @@ as follows: subsequent request) and consumes the statistics. \end{enumerate} + Within the buffer, statistics are an array of 6-byte entries. Each statistic consists of a 16 bit tag and a 64 bit value. All statistics are optional and the driver chooses which ones to supply. To guarantee backwards - compatibility, the driver SHOULD omit unsupported statistics. + compatibility, devices omit unsupported statistics. \begin{lstlisting} struct virtio_balloon_stat { @@ -4526,17 +4595,67 @@ struct virtio_balloon_stat { #define VIRTIO_BALLOON_S_MINFLT 3 #define VIRTIO_BALLOON_S_MEMFREE 4 #define VIRTIO_BALLOON_S_MEMTOT 5 - u16 tag; - u64 val; + le16 tag; + le64 val; } __attribute__((packed)); \end{lstlisting} +\drivernormative{\paragraph}{Memory Statistics}{Device Types / Memory Balloon Device / Device Operation / Memory Statistics} +Normative statements in this section apply if and only if the +VIRTIO_BALLOON_F_STATS_VQ feature has been negotiated. + +The driver MUST make at most one buffer available to the device +in the statsq, at all times. + +After initializing the device, the driver MUST make an output +buffer available in the statsq. + +Upon detecting that device has used a buffer in the statsq, the +driver MUST make an output buffer available in the statsq. + +Before making an output buffer available in the statsq, the +driver MUST initialize it, including one struct +virtio_balloon_stat entry for each statistic that it supports. + +Driver MUST use an output buffer size which is a multiple of 6 +bytes for all buffers submitted to the statsq. + +Driver MAY supply struct virtio_balloon_stat entries in the +output buffer submitted to the statsq in any order, without +regard to \field{tag} values. + +Driver MAY supply a subset of all statistics in the output buffer +submitted to the statsq. + +Driver MUST supply the same subset of statistics in all buffers +submitted to the statsq. + +\devicenormative{\paragraph}{Memory Statistics}{Device Types / Memory Balloon Device / Device Operation / Memory Statistics} +Normative statements in this section apply if and only if the +VIRTIO_BALLOON_F_STATS_VQ feature has been negotiated. + +Within an output buffer submitted to the statsq, +the device MUST ignore entries with \field{tag} values that it does not recognize. + +Within an output buffer submitted to the statsq, +the device MUST accept struct virtio_balloon_stat entries in any +order without regard to \field{tag} values. + \paragraph{Legacy Interface: Memory Statistics}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics / Legacy Interface: Memory Statistics} + When using the legacy interface, transitional devices and drivers MUST format the fields in struct virtio_balloon_stat according to the native endian of the guest rather than (necessarily when not using the legacy interface) little-endian. +When using the legacy interface, +the device SHOULD ignore all values in the first buffer in the +statsq supplied by the driver after device initialization. +\begin{note} +Historically, drivers supplied an uninitialized buffer in the +first buffer. +\end{note} + \subsubsection{Memory Statistics Tags}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics Tags} \begin{description} -- cgit v1.2.3 From 36780da73e29e6fd2e0ac9560f4d1cc447cc82af Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Mon, 18 May 2015 20:49:25 +0000 Subject: balloon: document deflate on oom Document the new option, and also clarify behaviour without it. In particular, I noticed that actual field is not the actual number of pages in the balloon as driver might do inflate followed by deflate. Also, device isn't always driven by interrupts, driver can inflate/deflate in response to e.g. memory compaction. VIRTIO-126 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@527 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/content.tex b/content.tex index b1cd7bf..9f65748 100644 --- a/content.tex +++ b/content.tex @@ -4390,6 +4390,9 @@ guest memory statistics to the host. \item[VIRTIO_BALLOON_F_STATS_VQ (1)] A virtqueue for reporting guest memory statistics is present. +\item[VIRTIO_BALLOON_F_DEFLATE_ON_OOM (2) ] Deflate balloon on + guest out of memory condition. + \end{description} \drivernormative{\subsubsection}{Feature bits}{Device Types / Memory Balloon Device / Feature bits} @@ -4449,8 +4452,10 @@ The device initialization process is outlined below: \subsection{Device Operation}\label{sec:Device Types / Memory Balloon Device / Device Operation} -The device is driven by the receipt of a -configuration change interrupt. +The device is driven either by the receipt of a configuration +change interrupt, or by changing guest memory needs, such as +performing memory compaction or responding to out of memory +conditions. \begin{enumerate} \item \field{num_pages} configuration field is examined. If this is @@ -4489,10 +4494,25 @@ requests by using the descriptor. \drivernormative{\subsubsection}{Device Operation}{Device Types / Memory Balloon Device / Device Operation} The driver SHOULD supply pages to the balloon when \field{num_pages} is -greater than \field{actual}. +greater than the actual number of pages in the balloon. The driver MAY use pages from the balloon when \field{num_pages} is -less than \field{actual}. +less than the actual number of pages in the balloon. + +The driver MAY supply pages to the balloon when \field{num_pages} is +greater than or equal to the actual number of pages in the balloon. + +If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has not been negotiated, the +driver MUST NOT use pages from the balloon when \field{num_pages} +is less than or equal to the actual number of pages in the +balloon. + +If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has been negotiated, the +driver MAY use pages from the balloon when \field{num_pages} +is less than or equal to the actual number of pages in the +balloon if this is required for system stability +(e.g. if memory is required by applications running within + the guest). The driver MUST use the deflateq to inform the device of pages that it wants to use from the balloon. @@ -4517,6 +4537,9 @@ request. The driver MUST update \field{actual} after changing the number of pages in the balloon. +The driver MAY update \field{actual} once after multiple +inflate and deflate operations. + \devicenormative{\subsubsection}{Device Operation}{Device Types / Memory Balloon Device / Device Operation} The device MAY modify the contents of a page in the balloon -- cgit v1.2.3 From aa8bdde30c52f29e603cfbd13ce29af349b8a044 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Mon, 18 May 2015 20:49:51 +0000 Subject: network device: xmit/receive cleanup Fix up multiple issues in xmit/receive sections: - drop MAY/MUST/SHOULD outside normative statements - spell out conformance requirements for both drivers and devices, for xmit and receive paths - document the missing VIRTIO_NET_HDR_F_DATA_VALID - document handling of unrecognized flag bits so we can extend flags in the future, similar to VIRTIO_NET_HDR_F_DATA_VALID VIRTIO-123 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@528 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- conformance.tex | 4 +- content.tex | 197 ++++++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 181 insertions(+), 20 deletions(-) diff --git a/conformance.tex b/conformance.tex index 279b5cb..0ba2240 100644 --- a/conformance.tex +++ b/conformance.tex @@ -92,6 +92,7 @@ A network driver MUST conform to the following normative statements: \item \ref{drivernormative:Device Types / Network Device / Device configuration layout} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Packet Transmission} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Setting Up Receive Buffers} +\item \ref{drivernormative:Device Types / Network Device / Device Operation / Processing of Incoming Packets} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Setting MAC Address Filtering} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Gratuitous Packet Sending} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Automatic receive steering in multiqueue mode} @@ -208,8 +209,9 @@ A network device MUST conform to the following normative statements: \begin{itemize} \item \ref{devicenormative:Device Types / Network Device / Device configuration layout} +\item \ref{devicenormative:Device Types / Network Device / Device Operation / Packet Transmission} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Setting Up Receive Buffers} -\item \ref{devicenormative:Device Types / Network Device / Device Operation / Processing of Packets} +\item \ref{devicenormative:Device Types / Network Device / Device Operation / Processing of Incoming Packets} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Setting MAC Address Filtering} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Gratuitous Packet Sending} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Automatic receive steering in multiqueue mode} diff --git a/content.tex b/content.tex index 9f65748..98ebed4 100644 --- a/content.tex +++ b/content.tex @@ -3215,7 +3215,12 @@ if both guests are amenable.} the VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6, VIRTIO_NET_F_GUEST_UFO and VIRTIO_NET_F_GUEST_ECN are the input equivalents of the features described above. - See \ref{sec:Device Types / Network Device / Device Operation / Setting Up Receive Buffers}~\nameref{sec:Device Types / Network Device / Device Operation / Setting Up Receive Buffers} and \ref{sec:Device Types / Network Device / Device Operation / Processing of Packets}~\nameref{sec:Device Types / Network Device / Device Operation / Processing of Packets} below. + See \ref{sec:Device Types / Network Device / Device Operation / +Setting Up Receive Buffers}~\nameref{sec:Device Types / Network +Device / Device Operation / Setting Up Receive Buffers} and +\ref{sec:Device Types / Network Device / Device Operation / +Processing of Incoming Packets}~\nameref{sec:Device Types / +Network Device / Device Operation / Processing of Incoming Packets} below. \end{enumerate} A truly minimal driver would only accept VIRTIO_NET_F_MAC and ignore @@ -3274,10 +3279,10 @@ Transmitting a single packet is simple, but varies depending on the different features the driver negotiated. \begin{enumerate} -\item The driver MAY send a completely checksummed packet. In this case, +\item The driver can send a completely checksummed packet. In this case, \field{flags} will be zero, and \field{gso_type} will be VIRTIO_NET_HDR_GSO_NONE. -\item If the driver negotiated VIRTIO_NET_F_CSUM, it MAY skip +\item If the driver negotiated VIRTIO_NET_F_CSUM, it can skip checksumming the packet: \begin{itemize} \item \field{flags} has the VIRTIO_NET_HDR_F_NEEDS_CSUM set, @@ -3336,15 +3341,83 @@ specifically in the protocol.}. \drivernormative{\paragraph}{Packet Transmission}{Device Types / Network Device / Device Operation / Packet Transmission} -If a driver has not negotiated VIRTIO_NET_F_CSUM, \field{flags} MUST be zero and -the packet MUST be fully checksummed. - The driver MUST set \field{num_buffers} to zero. -A driver SHOULD NOT send TCP packets requiring segmentation offload which have the Explicit Congestion Notification bit set, unless the VIRTIO_NET_F_HOST_ECN feature is -negotiated\footnote{This is a common restriction in real, older network cards.}, in -which case it MUST set the VIRTIO_NET_HDR_GSO_ECN bit in \field{gso_type}. +If VIRTIO_NET_F_CSUM is not negotiated, the driver MUST set +\field{flags} to zero and SHOULD supply a fully checksummed +packet to the device. + +If VIRTIO_NET_F_HOST_TSO4 is negotiated, the driver MAY set +\field{gso_type} to VIRTIO_NET_HDR_GSO_TCPV4 to request TCPv4 +segmentation, otherwise the driver MUST NOT set +\field{gso_type} to VIRTIO_NET_HDR_GSO_TCPV4. + +If VIRTIO_NET_F_HOST_TSO6 is negotiated, the driver MAY set +\field{gso_type} to VIRTIO_NET_HDR_GSO_TCPV6 to request TCPv6 +segmentation, otherwise the driver MUST NOT set +\field{gso_type} to VIRTIO_NET_HDR_GSO_TCPV6. + +If VIRTIO_NET_F_HOST_UFO is negotiated, the driver MAY set +\field{gso_type} to VIRTIO_NET_HDR_GSO_UDP to request UDP +segmentation, otherwise the driver MUST NOT set +\field{gso_type} to VIRTIO_NET_HDR_GSO_UDP. + +The driver SHOULD NOT send to the device TCP packets requiring segmentation offload +which have the Explicit Congestion Notification bit set, unless the +VIRTIO_NET_F_HOST_ECN feature is negotiated, in which case the +driver MUST set the VIRTIO_NET_HDR_GSO_ECN bit in +\field{gso_type}. + +If the VIRTIO_NET_F_CSUM feature has been negotiated, the +driver MAY set the VIRTIO_NET_HDR_F_NEEDS_CSUM bit in +\field{flags}, if so: +\begin{enumerate} +\item the driver MUST validate the packet checksum at + offset \field{csum_offset} from \field{csum_start} as well as all + preceding offsets; +\item the driver MUST set the packet checksum stored in the + buffer to the TCP/UDP pseudo header; +\item the driver MUST set \field{csum_start} and + \field{csum_offset} such that calculating a ones' + complement checksum from \field{csum_start} up until the end of + the packet and storing the result at offset \field{csum_offset} + from \field{csum_start} will result in a fully checksummed + packet; +\end{enumerate} + +If none of the VIRTIO_NET_F_HOST_TSO4, TSO6 or UFO options have +been negotiated, the driver MUST set \field{gso_type} to +VIRTIO_NET_HDR_GSO_NONE. + +If \field{gso_type} differs from VIRTIO_NET_HDR_GSO_NONE, then +the driver MUST also set the VIRTIO_NET_HDR_F_NEEDS_CSUM bit in +\field{flags} and MUST set \field{gso_size} to indicate the +desired MSS. + +If one of the VIRTIO_NET_F_HOST_TSO4, TSO6 or UFO options have +been negotiated, the driver SHOULD set \field{hdr_len} to a value +not less than the length of the headers, including the transport +header. + +The driver MUST NOT set the VIRTIO_NET_HDR_F_DATA_VALID bit in +\field{flags}. + +\devicenormative{\paragraph}{Packet Transmission}{Device Types / Network Device / Device Operation / Packet Transmission} +The device MUST ignore \field{flag} bits that it does not recognize. + +If VIRTIO_NET_HDR_F_NEEDS_CSUM bit in \field{flags} is not set, the +device MUST NOT use the \field{csum_start} and \field{csum_offset}. + +If one of the VIRTIO_NET_F_HOST_TSO4, TSO6 or UFO options have +been negotiated, the device MAY use \field{hdr_len} only as a hint about the +transport header size. +The device MUST NOT rely on \field{hdr_len} to be correct. +\begin{note} +This is due to various bugs in implementations. +\end{note} +If VIRTIO_NET_HDR_F_NEEDS_CSUM is not set, the device MUST NOT +rely on the packet checksum being correct. \paragraph{Packet Transmission Interrupt}\label{sec:Device Types / Network Device / Device Operation / Packet Transmission / Packet Transmission Interrupt} Often a driver will suppress transmission interrupts using the @@ -3401,14 +3474,15 @@ The device MUST use only a single descriptor if VIRTIO_NET_F_MRG_RXBUF was not negotiated. \note{This means that \field{num_buffers} will always be 1 if VIRTIO_NET_F_MRG_RXBUF is not negotiated.} -\subsubsection{Processing of Packets}\label{sec:Device Types / Network Device / Device Operation / Processing of Packets} +\subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network Device / Device Operation / Processing of Incoming Packets} +\label{sec:Device Types / Network Device / Device Operation / Processing of Packets}%old label for latexdiff When a packet is copied into a buffer in the receiveq, the optimal path is to disable further interrupts for the receiveq (see \ref{sec:General Initialization And Device Operation / Device Operation / Receiving Used Buffers From The Device}~\nameref{sec:General Initialization And Device Operation / Device Operation / Receiving Used Buffers From The Device}) and process packets until no more are found, then re-enable them. -Processing packet involves: +Processing incoming packets involves: \begin{enumerate} \item \field{num_buffers} indicates how many descriptors @@ -3424,10 +3498,25 @@ Processing packet involves: \field{num_buffers} is one, then the entire packet will be contained within this buffer, immediately following the struct virtio_net_hdr. +\item If the VIRTIO_NET_F_GUEST_CSUM feature was negotiated, the + VIRTIO_NET_HDR_F_DATA_VALID bit in \field{flags} can be + set: if so, device has validated the packet checksum. + In case of multiple encapsulated protocols, one level of checksums + has been validated. +\end{enumerate} +Additionally, VIRTIO_NET_F_GUEST_CSUM, TSO4, TSO6, UDP and ECN +features enable receive checksum, large receive offload and ECN +support which are the input equivalents of the transmit checksum, +transmit segmentation offloading and ECN features, as described +in \ref{sec:Device Types / Network Device / Device Operation / +Packet Transmission}: +\begin{enumerate} \item If the VIRTIO_NET_F_GUEST_CSUM feature was negotiated, the - VIRTIO_NET_HDR_F_NEEDS_CSUM bit in \field{flags} MAY be - set: if so, the checksum on the packet is incomplete and + VIRTIO_NET_HDR_F_NEEDS_CSUM bit in \field{flags} can be + set: if so, the packet checksum at offset \field{csum_offset} + from \field{csum_start} and any preceding checksums + have been validated. The checksum on the packet is incomplete and \field{csum_start} and \field{csum_offset} indicate how to calculate it (see Packet Transmission point 1). @@ -3437,10 +3526,23 @@ Processing packet involves: desired MSS (see Packet Transmission point 2). \end{enumerate} -\devicenormative{\paragraph}{Processing of Packets}{Device Types / Network Device / Device Operation / Processing of Packets} +\devicenormative{\paragraph}{Processing of Incoming Packets}{Device Types / Network Device / Device Operation / Processing of Incoming Packets} +\label{devicenormative:Device Types / Network Device / Device Operation / Processing of Packets}%old label for latexdiff + +If VIRTIO_NET_F_MRG_RXBUF has not been negotiated, the device MUST set +\field{num_buffers} to 1. -If VIRTIO_NET_F_CSUM is not negotiated, the device MUST set -\field{flags} to zero and the packet MUST be fully checksummed. +If VIRTIO_NET_F_MRG_RXBUF has been negotiated, the device MUST set +\field{num_buffers} to indicate the number of descriptors +the packet (including the header) is spread over. + +The device MUST use all descriptors used by a single receive +packet together, by atomically incrementing \field{idx} in the +used ring by the \field{num_buffers} value. + +If VIRTIO_NET_F_GUEST_CSUM is not negotiated, the device MUST set +\field{flags} to zero and SHOULD supply a fully checksummed +packet to the driver. If VIRTIO_NET_F_GUEST_TSO4 is not negotiated, the device MUST NOT set \field{gso_type} to VIRTIO_NET_HDR_GSO_TCPV4. @@ -3451,11 +3553,68 @@ If VIRTIO_NET_F_GUEST_UDP is not negotiated, the device MUST NOT set If VIRTIO_NET_F_GUEST_TSO6 is not negotiated, the device MUST NOT set \field{gso_type} to VIRTIO_NET_HDR_GSO_TCPV6. -A device SHOULD NOT send TCP packets requiring segmentation offload +The device SHOULD NOT send to the driver TCP packets requiring segmentation offload which have the Explicit Congestion Notification bit set, unless the -VIRTIO_NET_F_GUEST_ECN feature is negotiated, in which case it MUST set -the VIRTIO_NET_HDR_GSO_ECN bit in \field{gso_type}. +VIRTIO_NET_F_GUEST_ECN feature is negotiated, in which case the +device MUST set the VIRTIO_NET_HDR_GSO_ECN bit in +\field{gso_type}. + +If the VIRTIO_NET_F_GUEST_CSUM feature has been negotiated, the +device MAY set the VIRTIO_NET_HDR_F_NEEDS_CSUM bit in +\field{flags}, if so: +\begin{enumerate} +\item the device MUST validate the packet checksum at + offset \field{csum_offset} from \field{csum_start} as well as all + preceding offsets; +\item the device MUST set the packet checksum stored in the + receive buffer to the TCP/UDP pseudo header; +\item the device MUST set \field{csum_start} and + \field{csum_offset} such that calculating a ones' + complement checksum from \field{csum_start} up until the + end of the packet and storing the result at offset + \field{csum_offset} from \field{csum_start} will result in a + fully checksummed packet; +\end{enumerate} + +If none of the VIRTIO_NET_F_GUEST_TSO4, TSO6 or UFO options have +been negotiated, the device MUST set \field{gso_type} to +VIRTIO_NET_HDR_GSO_NONE. + +If \field{gso_type} differs from VIRTIO_NET_HDR_GSO_NONE, then +the device MUST also set the VIRTIO_NET_HDR_F_NEEDS_CSUM bit in +\field{flags} MUST set \field{gso_size} to indicate the desired MSS. + +If one of the VIRTIO_NET_F_GUEST_TSO4, TSO6 or UFO options have +been negotiated, the device SHOULD set \field{hdr_len} to a value +not less than the length of the headers, including the transport +header. + +If the VIRTIO_NET_F_GUEST_CSUM feature has been negotiated, the +device MAY set the VIRTIO_NET_HDR_F_DATA_VALID bit in +\field{flags}, if so, the device MUST validate the packet +checksum (in case of multiple encapsulated protocols, one level +of checksums is validated). + +\drivernormative{\paragraph}{Processing of Incoming +Packets}{Device Types / Network Device / Device Operation / +Processing of Incoming Packets} + +The driver MUST ignore \field{flag} bits that it does not recognize. + +If VIRTIO_NET_HDR_F_NEEDS_CSUM bit in \field{flags} is not set, the +driver MUST NOT use the \field{csum_start} and \field{csum_offset}. + +If one of the VIRTIO_NET_F_GUEST_TSO4, TSO6 or UFO options have +been negotiated, the driver MAY use \field{hdr_len} only as a hint about the +transport header size. +The driver MUST NOT rely on \field{hdr_len} to be correct. +\begin{note} +This is due to various bugs in implementations. +\end{note} +If neither VIRTIO_NET_HDR_F_NEEDS_CSUM nor +VIRTIO_NET_HDR_F_DATA_VALID is set, the driver MUST NOT +rely on the packet checksum being correct. \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue} The driver uses the control virtqueue (if VIRTIO_NET_F_CTRL_VQ is -- cgit v1.2.3 From dbd41a9f9570a29f66c95d03bcb2287d8bb25c16 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Mon, 18 May 2015 20:50:15 +0000 Subject: network device: document VIRTIO_NET_F_CTRL_RX_EXTRA VIRTIO-124 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@529 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 77 insertions(+), 9 deletions(-) diff --git a/content.tex b/content.tex index 98ebed4..3d7cf46 100644 --- a/content.tex +++ b/content.tex @@ -3643,32 +3643,93 @@ do except issue a diagnostic if \field{ack} is not VIRTIO_NET_OK. \paragraph{Packet Receive Filtering}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering} +\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting Promiscuous Mode}%old label for latexdiff -If the VIRTIO_NET_F_CTRL_RX feature is negotiated, the driver can -send control commands for promiscuous mode, multicast receiving, -and filtering of MAC addresses. +If the VIRTIO_NET_F_CTRL_RX and VIRTIO_NET_F_CTRL_RX_EXTRA +features are negotiated, the driver can send control commands for +promiscuous mode, multicast, unicast and broadcast receiving. \begin{note} In general, these commands are best-effort: unwanted packets could still arrive. \end{note} -\paragraph{Setting Promiscuous Mode}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting Promiscuous Mode} - \begin{lstlisting} #define VIRTIO_NET_CTRL_RX 0 #define VIRTIO_NET_CTRL_RX_PROMISC 0 #define VIRTIO_NET_CTRL_RX_ALLMULTI 1 + #define VIRTIO_NET_CTRL_RX_ALLUNI 2 + #define VIRTIO_NET_CTRL_RX_NOMULTI 3 + #define VIRTIO_NET_CTRL_RX_NOUNI 4 + #define VIRTIO_NET_CTRL_RX_NOBCAST 5 \end{lstlisting} -The class VIRTIO_NET_CTRL_RX has two commands: -VIRTIO_NET_CTRL_RX_PROMISC turns promiscuous mode on and off, and -VIRTIO_NET_CTRL_RX_ALLMULTI turns all-multicast receive on and + +\devicenormative{\subparagraph}{Packet Receive Filtering}{Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering} + +If the VIRTIO_NET_F_CTRL_RX feature has been negotiated, +the device MUST support the following VIRTIO_NET_CTRL_RX class +commands: +\begin{itemize} +\item VIRTIO_NET_CTRL_RX_PROMISC turns promiscuous mode on and +off. The command-specific-data is one byte containing 0 (off) or +1 (on). If promiscous mode is on, the device SHOULD receive all +incoming packets. +This SHOULD take effect even if one of the other modes set by +a VIRTIO_NET_CTRL_RX class command is on. +\item VIRTIO_NET_CTRL_RX_ALLMULTI turns all-multicast receive on and +off. The command-specific-data is one byte containing 0 (off) or +1 (on). When all-multicast receive is on the device SHOULD allow +all incoming multicast packets. +\end{itemize} + +If the VIRTIO_NET_F_CTRL_RX_EXTRA feature has been negotiated, +the device MUST support the following VIRTIO_NET_CTRL_RX class +commands: +\begin{itemize} +\item VIRTIO_NET_CTRL_RX_ALLUNI turns all-unicast receive on and off. The command-specific-data is one byte containing 0 (off) or -1 (on). +1 (on). When all-unicast receive is on the device SHOULD allow +all incoming unicast packets. +\item VIRTIO_NET_CTRL_RX_NOMULTI suppresses multicast receive. +The command-specific-data is one byte containing 0 (multicast +receive allowed) or 1 (multicast receive suppressed). +When multicast receive is suppressed, the device SHOULD NOT +send multicast packets to the driver. +This SHOULD take effect even if VIRTIO_NET_CTRL_RX_ALLMULTI is on. +This filter SHOULD NOT apply to broadcast packets. +\item VIRTIO_NET_CTRL_RX_NOUNI suppresses unicast receive. +The command-specific-data is one byte containing 0 (unicast +receive allowed) or 1 (unicast receive suppressed). +When unicast receive is suppressed, the device SHOULD NOT +send unicast packets to the driver. +This SHOULD take effect even if VIRTIO_NET_CTRL_RX_ALLUNI is on. +\item VIRTIO_NET_CTRL_RX_NOBCAST suppresses broadcast receive. +The command-specific-data is one byte containing 0 (broadcast +receive allowed) or 1 (broadcast receive suppressed). +When broadcast receive is suppressed, the device SHOULD NOT +send broadcast packets to the driver. +This SHOULD take effect even if VIRTIO_NET_CTRL_RX_ALLMULTI is on. +\end{itemize} + +\drivernormative{\subparagraph}{Packet Receive Filtering}{Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering} + +If the VIRTIO_NET_F_CTRL_RX feature has not been negotiated, +the driver MUST NOT issue commands VIRTIO_NET_CTRL_RX_PROMISC or +VIRTIO_NET_CTRL_RX_ALLMULTI. + +If the VIRTIO_NET_F_CTRL_RX_EXTRA feature has not been negotiated, +the driver MUST NOT issue commands + VIRTIO_NET_CTRL_RX_ALLUNI, + VIRTIO_NET_CTRL_RX_NOMULTI, + VIRTIO_NET_CTRL_RX_NOUNI or + VIRTIO_NET_CTRL_RX_NOBCAST. \paragraph{Setting MAC Address Filtering}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting MAC Address Filtering} +If the VIRTIO_NET_F_CTRL_RX feature is negotiated, the driver can +send control commands for MAC address filtering. + \begin{lstlisting} struct virtio_net_ctrl_mac { le32 entries; @@ -3715,6 +3776,13 @@ nor the MAC filtering table. \drivernormative{\subparagraph}{Setting MAC Address Filtering}{Device Types / Network Device / Device Operation / Control Virtqueue / Setting MAC Address Filtering} +If VIRTIO_NET_F_CTRL_RX has not been negotiated, +the driver MUST NOT issue VIRTIO_NET_CTRL_MAC class commands. + +If VIRTIO_NET_F_CTRL_RX has been negotiated, +the driver SHOULD issue VIRTIO_NET_CTRL_MAC_ADDR_SET +to set the default mac if it is different from \field{mac}. + The driver MUST follow the VIRTIO_NET_CTRL_MAC_TABLE_SET command by a le32 number, followed by that number of non-multicast MAC addresses, followed by another le32 number, followed by -- cgit v1.2.3 From 2cf3b8656574f93c0b154486df5b675fb6b99d19 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Thu, 21 May 2015 10:12:02 +0000 Subject: conformance: link in new conformance statements Link new conformance statements added by commit network device: document VIRTIO_NET_F_CTRL_RX_EXTRA Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@530 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- conformance.tex | 2 ++ 1 file changed, 2 insertions(+) diff --git a/conformance.tex b/conformance.tex index 0ba2240..7b7df32 100644 --- a/conformance.tex +++ b/conformance.tex @@ -93,6 +93,7 @@ A network driver MUST conform to the following normative statements: \item \ref{drivernormative:Device Types / Network Device / Device Operation / Packet Transmission} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Setting Up Receive Buffers} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Processing of Incoming Packets} +\item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Setting MAC Address Filtering} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Gratuitous Packet Sending} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Automatic receive steering in multiqueue mode} @@ -212,6 +213,7 @@ A network device MUST conform to the following normative statements: \item \ref{devicenormative:Device Types / Network Device / Device Operation / Packet Transmission} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Setting Up Receive Buffers} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Processing of Incoming Packets} +\item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Setting MAC Address Filtering} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Gratuitous Packet Sending} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Automatic receive steering in multiqueue mode} -- cgit v1.2.3 From 12527ecbbe4f6b4b5fabfe35d45bc2ce71650d62 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Thu, 21 May 2015 10:12:25 +0000 Subject: cl-os: VIRTIO-123, VIRTIO-124, VIRTIO-126, VIRTIO-143 Document resolutions to VIRTIO-123, VIRTIO-124, VIRTIO-126 and VIRTIO-143. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@531 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-os.tex | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) diff --git a/cl-os.tex b/cl-os.tex index ee65be3..ab26d64 100644 --- a/cl-os.tex +++ b/cl-os.tex @@ -240,3 +240,89 @@ See \ref{drivernormative:Device Types / Entropy Device / Device Operation}. } \\ \hline +526 & 18 May 2015 & Michael S. Tsirkin & {VIRTIO-143: +balloon: transitional device support + +Support a transitional balloon device: this has the advantage of supporting +existing drivers, transparently, as well as transports that don't allow mixing +virtio 0 and virtio 1 devices. And balloon is an easy device to test, so it's +also useful for people to test virtio core handling of transitional devices. + +Three issues with legacy hypervisors have been identified: +\begin{enumerate} +\item +Actual value is actually used, and is necessary for management +to work. Luckily 4 byte config space writes are now atomic. +When using old guests, hypervisors can detect access to the last byte. +When using old hypervisors, drivers can use atomic 4-byte accesses. +\item Hypervisors actually didn't ignore the stats from the first +buffer supplied. This means the values there would be +incorrect until hypervisor resends the request. +Add a note suggesting hypervisors ignore the 1st buffer. +\item QEMU simply over-writes stats from each buffer it gets. +Thus if driver supplies a different subset of stats +on each request, stale values will be there. +Require drivers to supply the same subset on each +request. This also gives us a simple way to figure out +which stats are supported. +\end{enumerate} + +See +\ref{sec:Device Types / Memory Balloon Device}, +\ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery}, +\ref{sec:Conformance / Driver Conformance / Traditional Memory Balloon Driver Conformance}, +\ref{sec:Conformance / Device Conformance / Traditional Memory Balloon Device Conformance}, +\ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}, +\ref{sec:Conformance / Device Conformance} and \ref{sec:Conformance / Driver Conformance}. +} \\ +\hline +527 & 18 May 2015 & Michael S. Tsirkin & {VIRTIO-126: +document deflate on oom + +Document the new option, and also clarify behaviour +without it. + +In particular, actual field is not the +actual number of pages in the balloon as +driver might do inflate followed by deflate. + +Also, device isn't always driven by interrupts, +driver can inflate/deflate in response to e.g. +memory compaction. + +See \ref{sec:Device Types / Memory Balloon Device / Feature bits}, +\ref{sec:Device Types / Memory Balloon Device / Device Operation} and +\ref{drivernormative:Device Types / Memory Balloon Device / Device Operation}. +} \\ +\hline +528 & 18 May 2015 & Michael S. Tsirkin & {VIRTIO-123: +network device: xmit/receive cleanup + +Fix up multiple issues in xmit/receive sections: +\begin{itemize} + \item drop MAY/MUST/SHOULD outside normative statements + \item spell out conformance requirements for both drivers and + devices, for xmit and receive paths + \item document the missing VIRTIO_NET_HDR_F_DATA_VALID + \item document handling of unrecognized flag bits so we can extend + flags in the future, similar to VIRTIO_NET_HDR_F_DATA_VALID +\end{itemize} + +\ref{sec:Device Types / Network Device / Device Initialization}, +\ref{drivernormative:Device Types / Network Device / Device Operation / Packet Transmission}, +\ref{devicenormative:Device Types / Network Device / Device Operation / Packet Transmission}, +\ref{sec:Device Types / Network Device / Device Operation / Processing of Incoming Packets}, +\ref{sec:Conformance / Driver Conformance / Network Driver Conformance} and +\ref{sec:Conformance / Device Conformance / Network Device Conformance}. +} \\ +\hline +529 & 18 May 2015 & Michael S. Tsirkin & {VIRTIO-124: +network device: document VIRTIO_NET_F_CTRL_RX_EXTRA + +See +\ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering}, +\ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting MAC Address Filtering}, +\ref{sec:Conformance / Driver Conformance / Network Driver Conformance} and +\ref{sec:Conformance / Device Conformance / Network Device Conformance}. +} \\ +\hline -- cgit v1.2.3 From 2e49873218f722345804f50b6a4d310203428700 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Thu, 21 May 2015 10:12:45 +0000 Subject: content: replace \\note with note environment \\note just before start of subsection seems to confuse latex, resulting in incorrect text alignment. Replace with \begin{note} \end{note}. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@532 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/content.tex b/content.tex index 3d7cf46..d989d98 100644 --- a/content.tex +++ b/content.tex @@ -3471,8 +3471,11 @@ The device MUST set \field{num_buffers} to the number of descriptors used to hold the incoming packet. The device MUST use only a single descriptor if VIRTIO_NET_F_MRG_RXBUF -was not negotiated. \note{This means that \field{num_buffers} will always be 1 +was not negotiated. +\begin{note} +{This means that \field{num_buffers} will always be 1 if VIRTIO_NET_F_MRG_RXBUF is not negotiated.} +\end{note} \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network Device / Device Operation / Processing of Incoming Packets} \label{sec:Device Types / Network Device / Device Operation / Processing of Packets}%old label for latexdiff -- cgit v1.2.3 From 077b7f28068b171123060d4542e685fd901f00b1 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Thu, 21 May 2015 10:13:04 +0000 Subject: makediff: mark enumerate/itemize as floats Helps detect begin/end crossing these environments and fix up automatically. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@533 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- makediff.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/makediff.sh b/makediff.sh index cb6eb76..7d64c93 100755 --- a/makediff.sh +++ b/makediff.sh @@ -54,7 +54,7 @@ sed 's/\\footnote{/\\footnote {/' new/flat.tex > new/flat-fixed.tex #wget http://mirror.math.ku.edu/tex-archive/support/latexdiff/latexdiff-fast #chmod +x latexdiff-fast latexdiff-fast --config \ -"FLOATENV=(?:figure|longtable|table|tabular|plate|lstlisting|note)[\w\d*@]*,PICTUREENV=(?:picture|DIFdeltextcstwo|DIFnomarkup|lstlisting)[\w\d*@]*" \ +"FLOATENV=(?:figure|longtable|table|tabular|plate|lstlisting|note|enumerate|itemize)[\w\d*@]*,PICTUREENV=(?:picture|DIFdeltextcstwo|DIFnomarkup|lstlisting)[\w\d*@]*" \ --append-safecmd=field --append-textcmd=mmioreg \ --ignore-warnings -p diffpreamble.tex old/flat-fixed.tex \ new/flat-fixed.tex > virtio-diff-tofix.tex -- cgit v1.2.3 From e06b2ff405259b3d4a8f49ec83e4ae69f84f75f6 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Thu, 21 May 2015 10:13:22 +0000 Subject: fixupdiff.pl: more work-arounds for latexdiff work around more latexdiff issues: - force FL style within headers - fix beginFL ending with end and vice versa across begin/end of enum or itemize Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@534 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- fixupdiff.pl | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/fixupdiff.pl b/fixupdiff.pl index 70d4e30..94c5112 100644 --- a/fixupdiff.pl +++ b/fixupdiff.pl @@ -1,3 +1,6 @@ +my $bufferdiff=""; +my $diff=""; +my $buffer=""; my $lstlisting=0; while (<>) { my $line = $_; @@ -6,6 +9,61 @@ while (<>) { } if ($lstlisting) { $line =~ s/%DIFDELCMD\s+<\s+//; + #print "%FIXED BY RULE 1\n"; + } + #In section headings, replace begin/end with begin/endFL, + #but be careful in case some tag spills over to the next + #line + if (m/\\(section|subsection|subsubsection|paragraph)/ and m/DIF/) { + my @list = split(/(\\DIF(?:add|del)(?:begin|end)(?:FL)?)/, $line, -1); + #if there's only one tag, don't touch it: + #matching one is on the other line + if ($#list >= 5) { + #if first tag is end, don't touch it - matching + #begin is on the previous line + if ($list[1] =~ m/begin$/) { + $list[1] .= "FL"; + } + #if last tag is begin, don't touch it - matching + #end is on the next line + if ($list[$#list - 1] =~ m/end$/) { + $list[$#list - 1] .= "FL"; + } + } + for (my $i = 3; $i <= $#list - 3; $i += 2) { + if (not $list[$i] =~ m/FL$/) { + $list[$i] .= "FL"; + } + } + $line = join("", @list); + #print "%FIXED BY RULE 2\n"; + } + #detect where we have DIFbegin/end cross + #enumerate/itemize environments and fix up + if (m/\\DIF(?:add|del)(?:begin|end)/) { + my @list = split(/(\\DIF(?:add|del)(?:begin|end)(?:FL)?)/, $line, -1); + $diff = $list[$#list - 1]; + if ($diff =~ m/begin/) { + $diff =~ s/begin/end/; + } else { + $diff = ""; + } + } + if ($diff ne "" and m/\\(?:begin|end){(?:enumerate|itemize)}$/ and not m/\\DIF/) { + $buffer = $line; + $bufferdiff = $diff; + $line = ""; + #print "%BUFFERED BY RULE 3: $bufferdiff\n"; + } + if ($buffer ne "" and $line ne "") { + if (m/^(\\DIF(?:add|del)end(?:FL)?)/ and $bufferdiff ne $1) { + $line =~ s/^(\\DIF(?:add|del)end(?:FL)?)//; + $buffer =~ s/(\\(?:begin|end){(?:enumerate|itemize)})$/$bufferdiff$1/; + #print "%FIXED BY RULE 3: $bufferdiff\n"; + } + print $buffer; + $buffer = ""; + $bufferdiff = ""; } print $line; if (m/%DIFDELCMD\s+<\s+\\end{lstlisting}/) { -- cgit v1.2.3 From 601882e8907263e0d16cafd934ade9fe6e20f80f Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Thu, 21 May 2015 10:13:40 +0000 Subject: fixupdiff: better diff for lstlisting Actually strike out deleted text. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@535 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- fixupdiff.pl | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/fixupdiff.pl b/fixupdiff.pl index 94c5112..e557e2b 100644 --- a/fixupdiff.pl +++ b/fixupdiff.pl @@ -1,14 +1,18 @@ my $bufferdiff=""; my $diff=""; my $buffer=""; -my $lstlisting=0; while (<>) { my $line = $_; if (m/%DIFDELCMD\s+<\s+\\begin{lstlisting}/) { $lstlisting=1; + $line =~s/%DIFDELCMD\s+) { } print $line; if (m/%DIFDELCMD\s+<\s+\\end{lstlisting}/) { + print "}\n"; $lstlisting=0; } } -- cgit v1.2.3 From 2c9cd1ce5ead57d1c2e8e5b39adb3863c27ea95e Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Thu, 21 May 2015 11:39:27 +0000 Subject: title: update previous version link Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@536 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- title.tex | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/title.tex b/title.tex index 89f94b3..00eea75 100644 --- a/title.tex +++ b/title.tex @@ -20,10 +20,10 @@ \end{oasistitlesection} \begin{oasistitlesection}{Previous version} -\url{http://docs.oasis-open.org/virtio/virtio/v1.0/cs01/tex/} +\url{http://docs.oasis-open.org/virtio/virtio/v1.0/cs02/tex/} {}(Authoritative)\newline -\url{http://docs.oasis-open.org/virtio/virtio/v1.0/cs01/virtio-v1.0-cs01.pdf}\newline -\url{http://docs.oasis-open.org/virtio/virtio/v1.0/cs01/virtio-v1.0-cs01.html} +\url{http://docs.oasis-open.org/virtio/virtio/v1.0/cs02/virtio-v1.0-cs02.pdf}\newline +\url{http://docs.oasis-open.org/virtio/virtio/v1.0/cs02/virtio-v1.0-cs02.html} \end{oasistitlesection} \begin{oasistitlesection}{Latest version} -- cgit v1.2.3 From 6233eaefd1a6207d6298b924da0aa96350b468ab Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Sun, 2 Aug 2015 11:31:12 +0000 Subject: admin: set date and revision for cs03 Approved Aug 2: https://www.oasis-open.org/apps/org/workgroup/virtio/ballot.php?id=2843 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@537 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- REVISION | 2 +- REVISION-DATE | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/REVISION b/REVISION index 9ae2867..376c82e 100644 --- a/REVISION +++ b/REVISION @@ -1 +1 @@ -virtio-v1.0-cs02 +virtio-v1.0-cs03 diff --git a/REVISION-DATE b/REVISION-DATE index 83b910b..86ffb4e 100644 --- a/REVISION-DATE +++ b/REVISION-DATE @@ -1 +1 @@ -18 January 2015 +02 August 2015 -- cgit v1.2.3