From patchwork Tue Aug 9 07:37:28 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Christian Pinto X-Patchwork-Id: 9270567 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id BBB6F60839 for ; Tue, 9 Aug 2016 07:40:46 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id ABC55280F4 for ; Tue, 9 Aug 2016 07:40:46 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 9C42828415; Tue, 9 Aug 2016 07:40:46 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.8 required=2.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_HI,T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 4D387280F4 for ; Tue, 9 Aug 2016 07:40:44 +0000 (UTC) Received: from localhost ([::1]:34007 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bX1eV-000633-2y for patchwork-qemu-devel@patchwork.kernel.org; Tue, 09 Aug 2016 03:40:43 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:49667) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bX1dw-0005ol-Qh for qemu-devel@nongnu.org; Tue, 09 Aug 2016 03:40:10 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bX1ds-0004pm-Qo for qemu-devel@nongnu.org; Tue, 09 Aug 2016 03:40:08 -0400 Received: from mail-wm0-x242.google.com ([2a00:1450:400c:c09::242]:36802) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bX1ds-0004pY-Dx for qemu-devel@nongnu.org; Tue, 09 Aug 2016 03:40:04 -0400 Received: by mail-wm0-x242.google.com with SMTP id i138so1407789wmf.3 for ; Tue, 09 Aug 2016 00:40:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=virtualopensystems-com.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id; bh=AMYZZrKHK0HaEPrT2QW/Am+M++of6CkwGNU10tsGC5E=; b=OWPj53JSSeWUWrlcVQQNb8E3j4xyYKgcN8zTgXYa2VhEFzVckhbSUYSLTzKUbW+nSg RhhifKw0Pu2pbCCWF6namgZLDcCCq4Hex7rJyztmYIj/dwNOrT5bPxRiRi1JVYHhrM5Y LY3bDNehrF3Qdp1EmszLtywIbGi/4Faxx0Ur7JxPvc40tHLRZeu3OxTST7whakFt2PSt gGBJUWsTygPGyBViWG5hEX4WwnNZLgEfwHO2u5hv8b4cjEfJldRpIt6jTQhc7qIRLkEa MVd185zGroQF2rlBQlKhYVwzK0n+i0T4wqR+bpwypTELeZ9DK0+2XK2sm5QR7fe9055G vZSg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=AMYZZrKHK0HaEPrT2QW/Am+M++of6CkwGNU10tsGC5E=; b=TBEND/RSoaiUmIYLo9gmIiu+weUVP/M/8JTMHZp1xjP+RF/NlK83HKv0pTZeofeVJF kFyIDBD6J05sjLFSDxpW57ooKUHfY73HD8A+bfGCa7q/0Eem0MUOuKIcNSMxcYtGlNqs 1h5nEa97iLad0I8fLNFYdBzxiOUmr5tXt90ZDmxCGgTOggTM62vXbCMIcOg4Ap0eaR/w 2Rtu6Qypjym/3Y3J/F/hwPqrklVTDeKNvf05hXQsEkhkAmRKnl2R+KltBZ6sc+/IWBCv gH7y7530YEWZQkDKpJXyViNhDdx279GurI8MZsHklPqTQrGLwDXrNzO2r9HHO7X5FJH2 Camg== X-Gm-Message-State: AEkoouvyjuWFtNHnRC+nrsrSovBEktCvfEOrI31HywLhXy2bHlwPSkcJK/htcz7ly812Ew== X-Received: by 10.194.235.229 with SMTP id up5mr96427200wjc.69.1470728403559; Tue, 09 Aug 2016 00:40:03 -0700 (PDT) Received: from localhost.localdomain ([151.67.15.251]) by smtp.googlemail.com with ESMTPSA id m81sm1905824wmf.1.2016.08.09.00.40.01 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 09 Aug 2016 00:40:02 -0700 (PDT) From: Christian Pinto To: virtio-dev@lists.oasis-open.org Date: Tue, 9 Aug 2016 09:37:28 +0200 Message-Id: <1470728248-8424-1-git-send-email-c.pinto@virtualopensystems.com> X-Mailer: git-send-email 1.9.1 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2a00:1450:400c:c09::242 Subject: [Qemu-devel] [virtio-dev][RFC v3] virtio-sdm: new device specification X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Baptiste Reynal , Claudio.Fontana@huawei.com, qemu-devel@nongnu.org, Christian Pinto , stefanha@redhat.com, cornelia.huck@de.ibm.com, Jani.Kokkonen@huawei.com, tech@virtualopensystems.com Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP This patch adds the specification of the Signal Dristribution Module virtio device to the current virtio specification document. Signed-off-by: Christian Pinto Signed-off-by: Baptiste Reynal --- v2 -> v3: - Removed master field from configuration and replaced with device_id - Added new RESET signal - Added signals definition into device specs - Added feature bits associated to signals 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 | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 168 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..ee43e23 --- /dev/null +++ b/virtio-sdm.tex @@ -0,0 +1,166 @@ +\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. + +There are three signal types supported by the device, namely the +\textit{IRQ} signal, \textit{BOOT} signal and \textit{RESET} signal. Such set of +signals covers most of the needs of an AMP system, where a master processor can +trigger the boot or reset of slave processors, and processors send IRQs between +each other. + +\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} + +\begin{description} +\item[VIRTIO_SDM_F_IRQ_SIG (0)] Device supports the IRQ signal. + +\item[VIRTIO_SDM_F_BOOT_SIG (1)] Device supports the BOOT signal. + +\item[VIRTIO_SDM_F_RESET_SIG (2)] Device supports the RESET signal. +\end{description} + +This set of bits is used by each virtio SDM device to declare which of the +signals it supports. By specification each device can support all or a subset of +the defined signals. + +\subsection{Device configuration layout}\label{sec:Device Types / SDM Device / +Device configuration layout} + +The device configuration is composed by three fields: +\texttt{max_slaves}, \texttt{current_slaves} and the \texttt{device_id}. + +\begin{lstlisting} +struct virtio_sdm_config { + u16 max_slaves; + u16 current_slaves; + u32 device_id; +}; +\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 configuration change notification 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. Finally the +\texttt{device_id} field is used by each driver to know the ID of the device it +is attached to, the field contains 0 in case of a master instance. A driver +figures out whether it is attached to a master or a slave instance thanks to this +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. + +The last phase of the initialization is the negotiation of the feature bits. +Each device implementation declares the signals supported by offering all or a +subset of the three feature bits (VIRTIO_SDM_F_IRQ_SIG, VIRTIO_SDM_F_BOOT_SIG, +VIRTIO_SDM_F_RESET_SIG). The SDM driver will be aware of the set of signals to +handle thanks to this negotiation phase. + +\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, + SDM_RESET, +}; + +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 three 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{SDM_RESET} is also meant to be used in AMP like scenarios, to +trigger the reset of the target slave processor. As an assumption a driver +cannot trigger the reset of the device it is attached to, so each driver +implementation should ignore reset signals where the source slave corresponds to +the device ID the driver is attached to. +This is done by comparing, when a message is recevied, the value of +the \texttt{slave} field of the \texttt{SDMSignalData} data structure with the +\texttt{device_id} field of the configuration space. +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. When instead a message is recevied, this field contains the ID of +the slave source of the signal. +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. Finally the payload field is ignored also in case of +\texttt{SDM_RESET} signal, since no extra information is needed to trigger the +reset of the target processor. + + +The \texttt{SDMSignalData} structure is first filled by the source SDM kernel +virtio driver and sent over the gh_vq.