diff options
| -rw-r--r-- | content.tex | 65 |
1 files changed, 46 insertions, 19 deletions
diff --git a/content.tex b/content.tex index c072832..9de50bc 100644 --- a/content.tex +++ b/content.tex @@ -2188,9 +2188,6 @@ Bytes & Description & Contents \\ \hline \end{tabular} -A driver for virtio-ccw devices MUST check for a control unit -type of 0x3832 and MUST ignore the device type and model. - In addition to the basic channel commands, virtio-ccw defines a set of channel commands related to configuration and operation of virtio: @@ -2210,6 +2207,8 @@ virtio: #define CCW_CMD_SET_VIRTIO_REV 0x83 \end{lstlisting} +\devicenormative{Virtio Transport Options / Virtio over channel I/O / Basic Concepts} + The virtio-ccw device acts like a normal channel device, as specified in \hyperref[intro:S390 PoP]{[S390 PoP]} and \hyperref[intro:S390 Common I/O]{[S390 Common I/O]}. In particular: @@ -2225,10 +2224,16 @@ in \hyperref[intro:S390 PoP]{[S390 PoP]} and \hyperref[intro:S390 Common I/O]{[S device MUST present a check condition if the transmitted data does not contain enough data to process the command. If the driver submitted a buffer that was too long, the device SHOULD accept the command. - The driver SHOULD attempt to provide the correct length even if it - suppresses length checks. \end{itemize} +\drivernormative{Virtio Transport Options / Virtio over channel I/O / Basic Concepts} + +A driver for virtio-ccw devices MUST check for a control unit +type of 0x3832 and MUST ignore the device type and model. + +A driver SHOULD attempt to provide the correct length in a channel +command even if it suppresses length checks for that command. + \subsection{Device Initialization}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization} virtio-ccw uses several channel commands to set up a device. @@ -2267,30 +2272,36 @@ The following values are supported: Note that a change in the virtio standard does not necessarily correspond to a change in the virtio-ccw revision. +\devicenormative{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting the Virtio Revision} + A device MUST post a unit check with command reject for any \field{revision} it does not support. For any invalid combination of \field{revision}, \field{length} and \field{data}, it MUST post a unit check with command reject as well. A non-transitional device MUST reject revision id 0. -A driver SHOULD start with trying to set the highest revision it -supports and continue with lower revisions if it gets a command reject. - -A driver MUST NOT issue any other virtio-ccw specific channel commands -prior to setting the revision. - A device MUST answer with command reject to any virtio-ccw specific channel command that is not contained in the revision selected by the driver. -After a revision has been successfully selected by the driver, it -MUST NOT attempt to select a different revision. A device MUST answer -to any such attempt with a command reject. +A device MUST answer with command reject to any attempt to select a different revision +after a revision has been successfully selected by the driver. A device MUST treat the revision as unset from the time the associated subchannel has been enabled until a revision has been successfully set by the driver. This implies that revisions are not persistent across disabling and enabling of the associated subchannel. +\drivernormative{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting the Virtio Revision} + +A driver SHOULD start with trying to set the highest revision it +supports and continue with lower revisions if it gets a command reject. + +A driver MUST NOT issue any other virtio-ccw specific channel commands +prior to setting the revision. + +After a revision has been successfully selected by the driver, it +MUST NOT attempt to select a different revision. + \paragraph{Legacy Interfaces: A Note on Setting the Virtio Revision}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting the Virtio Revision / Legacy Interfaces: A Note on Setting the Virtio Revision} A legacy device will not support the CCW_CMD_SET_VIRTIO_REV and answer @@ -2339,6 +2350,9 @@ struct vq_info_block { \field{desc}, \field{avail} and \field{used} contain the guest addresses for the descriptor table, available ring and used ring for queue \field{index}, respectively. The actual virtqueue size (number of allocated buffers) is transmitted in \field{num}. + +\devicenormative{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue} + \field{res0} is reserved and MUST be ignored by the device. \paragraph{Legacy Interface: A Note on Configuring a Virtqueue}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue / Legacy Interface: A Note on Configuring a Virtqueue} @@ -2506,6 +2520,7 @@ No padding is added at the end of the structure, it is exactly 25 bytes in length. +\devicenormative{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting Up Indicators / Setting Up Two-Stage Queue Indicators} If the driver has already set up classic queue indicators via the CCW_CMD_SET_IND command, the device MUST post a unit check with command reject to any subsequent CCW_CMD_SET_IND_ADAPTER command. @@ -2553,8 +2568,14 @@ For notifying the driver of virtqueue buffers, the device sets the bit in the guest-provided indicator area at the corresponding offset. The guest-provided summary indicator is set to 0x01. An adapter I/O interrupt for the corresponding interruption subclass is generated. + +\devicenormative{Virtio Transport Options / Virtio over channel I/O / Device Operation / Host->Guest Notification / Notification via Adapter I/O Interrupts} + The device SHOULD only generate an adapter I/O interrupt if the -summary indicator had not been set prior to notification. The driver +summary indicator had not been set prior to notification. + +\drivernormative{Virtio Transport Options / Virtio over channel I/O / Device Operation / Host->Guest Notification / Notification via Adapter I/O Interrupts} +The driver MUST clear the summary indicator after receiving an adapter I/O interrupt before it processes the queue indicators. @@ -2585,20 +2606,26 @@ GPR & Input Value & Output Value \\ \hline \end{tabular} +\devicenormative{Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification} The device MUST ignore bits 0-31 (counting from the left) of GPR2. This aligns passing the subchannel ID with the way it is passed for the existing I/O instructions. -Host cookie is an optional per-virtqueue 64 bit value that MAY be -used by the hypervisor to speed up the notification execution. -For each notification, the output value is returned in GPR2 and -SHOULD be passed in GPR4 for the next notification: +The device MAY return a 64-bit host cookie in GPR2 to speed up the +notification execution. +\drivernormative{Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification} + +For each notification, the driver SHOULD use GPR4 to pass the host cookie received in GPR2 from the previous notication. + +\begin{note} +For example: \begin{lstlisting} info->cookie = do_notify(schid, virtqueue_get_queue_index(vq), info->cookie); \end{lstlisting} +\end{note} \subsubsection{Resetting Devices}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Operation / Resetting Devices} |