@@ -937,44 +937,12 @@ \subsubsection{Virtqueue Configuration}
937937VIRTIO\_ F\_ RING\_ RESET is negotiated). Each queue is typically configured by
938938reading its maximum size, provisioning descriptor/available/used buffers, and
939939then calling \msgref {SET_VQUEUE } with the chosen size, physical addresses, and
940- queue-state operation in \field {flags}.
941-
942- \drivernormative {\paragraph }{Virtqueue Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Driver}
943- \begin {itemize }
944- \item A driver MUST use \msgref {GET_VQUEUE } to determine the maximum queue
945- size and current queue state before programming it.
946- \item A driver MUST set \msgref {SET_VQUEUE } \field {flags} according to the
947- desired queue-state operation and field-update behavior.
948- \item If a driver updates queue size via \msgref {SET_VQUEUE }, it MUST ensure
949- the requested size does not exceed the maximum reported by the device.
950- \item If a driver updates queue addresses via \msgref {SET_VQUEUE }, it MUST
951- supply valid descriptor/driver/device physical addresses for each
952- updated field.
953- \item A driver MUST reconfigure queue parameters only while the queue is
954- disabled.
955- \item If a queue is enabled and requires reconfiguration, a driver MUST issue
956- \msgref {RESET_VQUEUE } before reprogramming it when
957- VIRTIO\_ F\_ RING\_ RESET is negotiated.
958- \item If a queue is enabled and VIRTIO\_ F\_ RING\_ RESET has not been
959- negotiated, a driver MUST NOT attempt to reconfigure the queue via
960- \msgref {SET_VQUEUE }.
961- \end {itemize }
962-
963- \devicenormative {\paragraph }{Virtqueue Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Device}
964- \begin {itemize }
965- \item A device MUST report accurate maximum queue sizes in \msgref {GET_VQUEUE }
966- and MUST report accurate current queue size and enabled state.
967- \item A device MUST persist the parameters supplied via \msgref {SET_VQUEUE }
968- for fields not marked ignored by \field {flags} while the queue is
969- disabled.
970- \item A device MUST update queue state according to the
971- \msgref {SET_VQUEUE } \field {flags} state-operation bits.
972- \item A device MUST NOT use \msgref {SET_VQUEUE } to perform an
973- enabled-to-disabled or reset transition for a queue.
974- \item When \msgref {RESET_VQUEUE } is issued (and VIRTIO\_ F\_ RING\_ RESET is
975- negotiated), the device MUST quiesce the queue, release any resources
976- associated with it, and allow the driver to reconfigure it.
977- \end {itemize }
940+ queue-state operation in \field {flags}. A \msgref {GET_VQUEUE } response with
941+ \field {max_size}=0 indicates that the requested queue is not available for
942+ configuration. The message definitions for \msgref {GET_VQUEUE },
943+ \msgref {SET_VQUEUE }, and \msgref {RESET_VQUEUE } define the normative
944+ queue-availability, reconfiguration, and reset rules; this subsection
945+ describes the usual sequencing.
978946
979947\subsubsection {Status Information }
980948\label {sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information }
@@ -1104,32 +1072,9 @@ \subsubsection{Virtqueue Changes During Operation}
11041072Drivers may provision unused virtqueues later in the device lifetime by issuing
11051073\msgref {SET_VQUEUE }. Queue reconfiguration remains constrained to disabled
11061074queues. If a queue is enabled, the driver first resets that queue via
1107- \msgref {RESET_VQUEUE } when VIRTIO\_ F\_ RING\_ RESET is negotiated.
1108-
1109- \drivernormative {\paragraph }{Runtime Virtqueue Changes}{Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation / Driver}
1110- \begin {itemize }
1111- \item A driver MAY configure additional virtqueues and update selected
1112- virtqueue fields after initialization using \msgref {SET_VQUEUE },
1113- provided it follows the same validation steps and updates only disabled
1114- queues.
1115- \item If an enabled queue requires reconfiguration and
1116- VIRTIO\_ F\_ RING\_ RESET is negotiated, a driver MUST issue
1117- \msgref {RESET_VQUEUE } before issuing \msgref {SET_VQUEUE } updates for
1118- that queue.
1119- \end {itemize }
1120-
1121- \devicenormative {\paragraph }{Runtime Virtqueue Changes}{Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation / Device}
1122- \begin {itemize }
1123- \item A device MUST honor \msgref {SET_VQUEUE } requests issued after
1124- initialization and update queue parameters according to \field {flags}
1125- only while the queue is disabled.
1126- \item For a queue that is enabled, a device MUST accept only
1127- \msgref {SET_VQUEUE } requests that do not modify queue parameters and do
1128- not request a disable/reset transition.
1129- \item When \msgref {RESET_VQUEUE } is received (and VIRTIO\_ F\_ RING\_ RESET is
1130- negotiated), the device MUST quiesce the queue and allow the driver to
1131- reconfigure it without processing stale data.
1132- \end {itemize }
1075+ \msgref {RESET_VQUEUE } when VIRTIO\_ F\_ RING\_ RESET is negotiated. The same
1076+ \msgref {GET_VQUEUE }, \msgref {SET_VQUEUE }, and \msgref {RESET_VQUEUE } rules
1077+ continue to apply after initialization.
11331078
11341079\subsubsection {Device Reset and Shutdown }
11351080\label {sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Reset }
@@ -1352,6 +1297,11 @@ \subsubsection{Overview}
13521297 \item A driver SHOULD treat the response as the authoritative source for
13531298 feature-block count, configuration size, and virtqueue limits before
13541299 proceeding with initialization.
1300+ \item A driver MUST interpret \field {admin_vq_count}=0 as indicating that the
1301+ device exposes no administration virtqueues.
1302+ \item If \field {admin_vq_count} is greater than 0, a driver MUST treat the
1303+ range starting at \field {admin_vq_start} and spanning
1304+ \field {admin_vq_count} entries as part of \field {max_virtqueues}.
13551305 \item A driver MUST interpret a nil UUID in \field {device_uuid} as indicating
13561306 that no UUID is provided.
13571307\end {itemize }
@@ -1603,7 +1553,9 @@ \subsubsection{Overview}
16031553
16041554\msgref {GET_VQUEUE } returns information about a specific virtqueue, including
16051555its maximum size, current size, enabled state, and, if already configured, the
1606- descriptor, driver, and device area physical addresses.
1556+ descriptor, driver, and device area physical addresses. For unavailable,
1557+ unimplemented, or out-of-range queue indexes, the response uses a
1558+ deterministic zero sentinel while still echoing the requested \field {index}.
16071559
16081560\ begin{lstlisting}
16091561struct virtio_msg_get_vqueue_req {
@@ -1612,12 +1564,12 @@ \subsubsection{Overview}
16121564
16131565struct virtio_msg_get_vqueue_resp {
16141566 le32 index; /* echoed virtqueue index */
1615- le32 max_size; /* maximum queue size */
1616- le32 cur_size; /* current size (0 if unconfigured) */
1617- le32 flags; /* bit0: enabled state, bits[31:1] reserved */
1618- le64 desc_addr; /* descriptor area physical address */
1619- le64 driver_addr; /* driver area physical address */
1620- le64 device_addr; /* device area physical address */
1567+ le32 max_size; /* maximum queue size (0 if unavailable) */
1568+ le32 cur_size; /* current size (0 if unconfigured/unavailable ) */
1569+ le32 flags; /* bit0: enabled state, 0 if unavailable */
1570+ le64 desc_addr; /* descriptor area physical address (0 if unavailable) */
1571+ le64 driver_addr; /* driver area physical address (0 if unavailable) */
1572+ le64 device_addr; /* device area physical address (0 if unavailable) */
16211573};
16221574\end {lstlisting }
16231575
@@ -1633,9 +1585,15 @@ \subsubsection{Overview}
16331585
16341586\devicenormative {\paragraph }{GET\_ VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_VQUEUE / Device}
16351587\begin {itemize }
1636- \item A device MUST report accurate maxima and current queue sizes for each
1637- virtqueue and MUST return zero as the current size if the queue has not
1638- yet been configured.
1588+ \item For an available and implemented virtqueue index, a device MUST report
1589+ accurate maxima and current queue sizes and MUST return zero as the
1590+ current size if the queue has not yet been configured.
1591+ \item For an unavailable, unimplemented, or out-of-range virtqueue index
1592+ (\field {index} >= \field {max_virtqueues} from \msgref {GET_DEVICE_INFO }),
1593+ a device MUST return the deterministic unavailable-queue sentinel:
1594+ \field {max_size}=0, \field {cur_size}=0, \field {flags}=0,
1595+ \field {desc_addr}=0, \field {driver_addr}=0, and \field {device_addr}=0,
1596+ while echoing the requested \field {index}.
16391597 \item A device MUST report queue enabled state in \field {flags} bit 0 and
16401598 MUST set \field {flags} bits 31:1 to zero.
16411599\end {itemize }
@@ -1692,6 +1650,8 @@ \subsubsection{Overview}
16921650 bits [31:6] to zero.
16931651 \item A driver MUST NOT use state operation value 3 in \field {flags} bits
16941652 [1:0].
1653+ \item A driver SHOULD use \msgref {GET_VQUEUE } to determine whether a queue is
1654+ available before relying on \msgref {SET_VQUEUE } to modify it.
16951655 \item A driver MUST NOT use state operation value 0 as a request to disable an
16961656 already enabled queue.
16971657 \item If \field {size\_ ignore} is 0, a driver MUST set \field {size} to a value
@@ -1710,11 +1670,18 @@ \subsubsection{Overview}
17101670
17111671\devicenormative {\paragraph }{SET\_ VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Device}
17121672\begin {itemize }
1713- \item A device MUST reject \msgref {SET_VQUEUE } if \field {reserved} is nonzero,
1714- if \field {flags} bits [31:6] are nonzero, or if \field {flags} bits [1:0]
1715- use state operation value 3.
1716- \item A device MUST reject \msgref {SET_VQUEUE } if \field {flags} requests state
1717- operation value 0 for a queue that is currently enabled.
1673+ \item For an unavailable, unimplemented, or out-of-range virtqueue index
1674+ (\field {index} >= \field {max_virtqueues} from \msgref {GET_DEVICE_INFO }),
1675+ a device MUST treat \msgref {SET_VQUEUE } as a no-op and MUST NOT modify
1676+ any queue state or parameters.
1677+ \item If \field {reserved} is nonzero, if \field {flags} bits [31:6] are
1678+ nonzero, or if \field {flags} bits [1:0] use state operation value 3, a
1679+ device MUST do nothing (no queue state or parameter change) and MUST
1680+ return the normal empty \msgref {SET_VQUEUE } response.
1681+ \item If \field {flags} requests state operation value 0 for a queue that is
1682+ currently enabled, a device MUST do nothing (no queue state or
1683+ parameter change) and MUST return the normal empty
1684+ \msgref {SET_VQUEUE } response.
17181685 \item A device MUST process \msgref {SET_VQUEUE } updates atomically: it MUST
17191686 either apply all requested field updates and queue-state changes, or
17201687 do nothing (no queue state or parameter change) and return the normal
@@ -1754,6 +1721,8 @@ \subsubsection{Overview}
17541721 \item A driver MUST issue \msgref {RESET_VQUEUE } only if
17551722 VIRTIO\_ F\_ RING\_ RESET has been negotiated and it needs to reconfigure
17561723 or recover a specific queue.
1724+ \item A driver SHOULD use \msgref {GET_VQUEUE } to determine whether a queue is
1725+ available before relying on \msgref {RESET_VQUEUE } to affect it.
17571726 \item If an enabled queue requires reconfiguration and
17581727 VIRTIO\_ F\_ RING\_ RESET is negotiated, a driver MUST wait for
17591728 \msgref {RESET_VQUEUE } completion before issuing \msgref {SET_VQUEUE }
@@ -1762,8 +1731,13 @@ \subsubsection{Overview}
17621731
17631732\devicenormative {\paragraph }{RESET\_ VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Device}
17641733\begin {itemize }
1765- \item If VIRTIO\_ F\_ RING\_ RESET has not been negotiated, a device MUST reject
1766- \msgref {RESET_VQUEUE } without changing queue state.
1734+ \item For an unavailable, unimplemented, or out-of-range virtqueue index
1735+ (\field {index} >= \field {max_virtqueues} from \msgref {GET_DEVICE_INFO }),
1736+ a device MUST treat \msgref {RESET_VQUEUE } as a no-op and MUST NOT
1737+ modify any queue state.
1738+ \item If VIRTIO\_ F\_ RING\_ RESET has not been negotiated, a device MUST do
1739+ nothing (no queue state change) and MUST return the normal empty
1740+ \msgref {RESET_VQUEUE } response.
17671741 \item Upon receiving \msgref {RESET_VQUEUE }, a device MUST stop processing the
17681742 indicated queue, reset its internal state for that queue, and allow the
17691743 driver to reconfigure it via \msgref {SET_VQUEUE } while the queue is
@@ -1892,6 +1866,7 @@ \subsubsection{Overview}
18921866};
18931867\end {lstlisting }
18941868
1869+
18951870\subsection {Bus Messages }\label {sec:Virtio Transport Options / Virtio Over Messages / Bus Messages }
18961871
18971872Bus messages cover device discovery, hotplug notifications, and bus-level
0 commit comments