Re: [Qemu-devel] [virtio-dev][RFC v2 2/2] virtio-sdm: new device specification

[Stefan Hajnoczi <stefanha@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 7672 bytes --]

On Tue, Jun 28, 2016 at 01:03:44PM +0200, Christian Pinto wrote:
> This patch adds the specification of the Signal Dristribution Module virtio
> device to the current virtio specification document.
> 
> Signed-off-by: Christian Pinto <c.pinto@virtualopensystems.com>
> Signed-off-by: Baptiste Reynal <b.reynal@virtualopensystems.com>
> 
> ---
> v1 -> v2:
> - Fixed some typos
> - Removed dependencies from QEMU
> - Added explanation on how SDM can be used in AMP systems
> - Explained semantics of payload field in SDMSignalData struct
> ---
>  content.tex    |   2 +
>  virtio-sdm.tex | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 130 insertions(+)
>  create mode 100644 virtio-sdm.tex
> 
> diff --git a/content.tex b/content.tex
> index 3317916..7fcf779 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -5643,6 +5643,8 @@ descriptor for the \field{sense_len}, \field{residual},
>  \field{status_qualifier}, \field{status}, \field{response} and
>  \field{sense} fields.
>  
> +\input{virtio-sdm.tex}
> +
>  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
>  
>  Currently there are three device-independent feature bits defined:
> diff --git a/virtio-sdm.tex b/virtio-sdm.tex
> new file mode 100644
> index 0000000..76b0a7b
> --- /dev/null
> +++ b/virtio-sdm.tex
> @@ -0,0 +1,128 @@
> +\section{Signal Distribution Module}\label{sec:Device Types / SDM Device}
> +
> +The virtio Signal Distribution Module is meant to enable Inter Processor signal
> +exchange.
> +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.
> +In AMP systems signals are used for various purposes, an example are remoteproc
> +or RPMSG. In the former signals are used by a master processor to trigger
> +the boot of a slave processor. While the latter, RPMSG, uses virtio queues as a
> +message exchange medium between processors. In this case the SDM can be used to
> +generate the interrupt associated to the kick of a virtio queue.
> +
> +\subsection{Device ID}\label{sec:Device Types / SDM Device / Device ID}
> +
> +21
> +
> +\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 device-to-driver communication (i.e., notification of a
> +signal), while queue 1 for driver-to-device 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;

The next field has 16-bit alignment so there is a hole in this struct.
Three options:

1. Add an explicit u8 padding field.
2. Change master's type from u8 to u16.
3. Move master to the end of the struct.

> +	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
> +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. A notification change is sent to the driver each time the value
> +of \texttt{max_slaves} is changed from the device side.
> +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 driver 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. It has to be noted that the behavior of the device is
> +independent from the communication channel used, that is a detail of each
> +specific implementation of the SDM device.

How are SDM devices identified?  For example, if two SDM devices are
available, how does the driver know which one serves a particular
function?

> +
> +\subsection{Device Operation}\label{sec:Device Types / SDM Device / Device
> +peration}
> +
> +The SDM device handles signals coming from the two following sources:
> +
> +\begin{enumerate}
> +\item The local processor to which the device 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 a second SDM device instance.
> +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 themselves 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 semantics of the payload field depends on the signal itself. In case of
> +\texttt{SDM_IRQ} signal, the payload field is ignored since interrupts do not
> +need any extra information to be handled. In the case of \texttt{SDM_BOOT}
> +signal the payload contains the boot address of the slave processor, to be used
> +at the destination to initialize the program counter register before the actual
> +boot process is started.
> +
> +
> +The \texttt{SDMSignalData} structure is first filled by the source SDM kernel
> +virtio driver and sent over the gh_vq.
> -- 
> 1.9.1
> 
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 473 bytes --]