This patch adds the specification of the Signal Dristribution Module virtio device to the current virtio specification document.
Signed-off-by: Christian Pinto <c.pi...@virtualopensystems.com> --- virtio-sdm.tex | 126 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 virtio-sdm.tex diff --git a/virtio-sdm.tex b/virtio-sdm.tex new file mode 100644 index 0000000..abbdb80 --- /dev/null +++ b/virtio-sdm.tex @@ -0,0 +1,126 @@ +\section{Signal Distribution Module}\label{sec:Device Types / SDM Device} + +The virtio Signal Distribution Module is meant to enable Inter Processor +interrupts in QEMU/KVM environment. The SDM enables different processors in the +same or different QEMU instances to send mutual signals. An example are Inter +Processor Interrupts used in AMP systems, for the processors involved to notify +the presence of new data in the communication queues. + +\subsection{Device ID}\label{sec:Device Types / SDM Device / Device ID} + +19 + +\subsection{Virtqueues}\label{sec:Device Types / SDM Device / Virtqueues} + +\begin{description} +\item[0] hg_vq +\item[1] gh_vq +\end{description} + +Queue 0 is used for host-guest communication (i.e., notification of a signal), +while queue 1 for guest-host communication. + +\subsection{Feature bits}\label{sec:Device Types / SDM Device / Feature bits} + +None. + +\subsection{Device configuration layout}\label{sec:Device Types / SDM Device / +Device configuration layout} + +The device configuration is composed by three fields: \texttt{master}, +\texttt{max_slaves} and \texttt{current_slaves}. + +\begin{lstlisting} +struct virtio_sdm_config { + u8 master; + u16 max_slaves; + u16 current_slaves; +}; +\end{lstlisting} + +The SDM device can be instantiated either as a master or as a slave. The master +slave behavior is meant on purpose to reflect the AMP like type of communication +where a master processor controls one or more slave processors. +A master SDM instance can send a signal to any of the slaves instances, +while slaves can only signal the master. + +The \texttt{master} field of the configuration space is meant to be read by the +Linux driver to figure out whether a specific instance is a master or a slave. +The \texttt{max_slaves} field contains the maximum number of slaves supported by +the SDM device. +The value of \texttt{max_slaves} is initially set from the command line of QEMU, +but can be changed during operations through the configuration space. +Finally the \texttt{current_slaves} field contains the actual number of slaves +registered to the master SDM. This field is a read only field. + +\subsection{Device Initialization}\label{sec:Device Types / SDM Device / +evice Initialization} + +During initialization the \texttt{hg_vq} and \texttt{gh_vq} are identified and +the device is immediately operational. A master instance can access the number +of slaves registered at any time by reading the configuration space of the +device. + +During the initialization phase the device connects also to the communication +channel that is specificied as a parameter when configuring the device. At the +current state there are two types of communication channels: local and +socket(TCP or UNIX). +The local channel is meant for SDM devices attached to the same QEMU instance, +while the network channel makes it possible to exchange signals between +SDMs in different instances of QEMU. +The type of communication channel is chosen at QEMU boot time and cannot be +changed during operations. It has to be noted that the behavior of the device is +independent from the communication channel used. + +\subsection{Device Operation}\label{sec:Device Types / SDM Device / Device +peration} + +The SDM device handles signal coming from the two following sources: + +\begin{enumerate} +\item The local processor to which the devics is attached to. +\item The communication channel connecting to other slaves/master. +\end{enumerate} + +The first case is verified when the processor attached to the SDM device wants +to send a signal to SDM device instance (being it the same QEMU instance or a +separate one). +The second case is instead when an SDM device instance receives a signal from +another SDM device, to be forwarded to the local processor. +It is important to note that due to the master/slave behavior, slaves cannot +signal among themsleves but only with the master SDM instance. + +In both cases, before sending over the communication channel, the signal is +packed in the \texttt{SDMSignalData} data structure. + +\begin{lstlisting} +enum sdm_signal_type { + SDM_IRQ, + SDM_BOOT, +}; + +struct SDMSignalData { + uint32_t type; + uint32_t slave; + uint32_t payload[2]; +}; +\end{lstlisting} + +The \texttt{type} field indicates the type of signal to be sent to the +destination SDM. The current implementation supports two signal types. +The \texttt{SDM_IRQ} signal is used to send an inter processor interrupt, while +the \texttt{SDM_BOOT} signal is sent to trigger the boot of the destination +processor. The boot signal is meant to be used in an AMP like scenario where a +master processor boots one or more slave processors (e.g., via remoteproc). +The \texttt{slave} field contains the id of the SDM instance destination of the +signal. Id 0 is reserved for the master, from 1 onwards for the slaves. +This means that the \texttt{slave} field will always contain 0 when the source +of the signal is a slave SDM instance, while the actual id of the slave in case +of a master. +The \texttt{payload} is used to pass extra accompanying information with the +signal. The use case for the payload field is a hardware mailbox, where data is +pushed into the mailbox and an interrupt is triggered towards all the devices +registered with the mailbox. + +The \texttt{SDMSignalData} structure is first filled by the source SDM kernel +virtio driver and sent over the gh_vq. -- 1.9.1