[virtio-comment] [PATCH] virtio-gpio: add the device specification

[Viresh Kumar <viresh.kumar@linaro.org>]

virtio-gpio is a virtual GPIO controller. It provides a way to flexibly
communicate with the host GPIO controllers from the guest.

This patch adds the specification for it.

Based on the initial work done by:
"Enrico Weigelt, metux IT consult" <lkml@metux.net>.

Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org>
---
 conformance.tex |  26 ++++-
 content.tex     |   1 +
 virtio-gpio.tex | 256 ++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 279 insertions(+), 4 deletions(-)
 create mode 100644 virtio-gpio.tex

diff --git a/conformance.tex b/conformance.tex
index a164cbb69093..5341abe096c2 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -29,8 +29,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \ref{sec:Conformance / Driver Conformance / IOMMU Driver Conformance},
 \ref{sec:Conformance / Driver Conformance / Sound Driver Conformance},
 \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance},
-\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance} or
-\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}.
+\ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance},
+\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance} or
+\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance}.
 
     \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.
   \end{itemize}
@@ -52,8 +53,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \ref{sec:Conformance / Device Conformance / IOMMU Device Conformance},
 \ref{sec:Conformance / Device Conformance / Sound Device Conformance},
 \ref{sec:Conformance / Device Conformance / Memory Device Conformance},
-\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance} or
-\ref{sec:Conformance / Device Conformance / SCMI Device Conformance}.
+\ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance},
+\ref{sec:Conformance / Device Conformance / SCMI Device Conformance} or
+\ref{sec:Conformance / Device Conformance / GPIO Device Conformance}.
 
     \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.
   \end{itemize}
@@ -288,6 +290,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{drivernormative:Device Types / SCMI Device / Device Operation / Setting Up eventq Buffers}
 \end{itemize}
 
+\conformance{\subsection}{GPIO Driver Conformance}\label{sec:Conformance / Driver Conformance / GPIO Driver Conformance}
+
+An GPIO driver MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{drivernormative:Device Types / GPIO Device / Device Operation}
+\end{itemize}
+
 \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance}
 
 A device MUST conform to the following normative statements:
@@ -527,6 +537,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{devicenormative:Device Types / SCMI Device / Device Operation / Shared Memory Operation}
 \end{itemize}
 
+\conformance{\subsection}{GPIO Device Conformance}\label{sec:Conformance / Device Conformance / GPIO Device Conformance}
+
+An GPIO device MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{devicenormative:Device Types / GPIO Device / Device Operation}
+\end{itemize}
+
 \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}
 A conformant implementation MUST be either transitional or
 non-transitional, see \ref{intro:Legacy
diff --git a/content.tex b/content.tex
index d9913d056317..e572ac3bb6c0 100644
--- a/content.tex
+++ b/content.tex
@@ -6583,6 +6583,7 @@ \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
 \input{virtio-mem.tex}
 \input{virtio-i2c.tex}
 \input{virtio-scmi.tex}
+\input{virtio-gpio.tex}
 
 \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
 
diff --git a/virtio-gpio.tex b/virtio-gpio.tex
new file mode 100644
index 000000000000..683950029c6d
--- /dev/null
+++ b/virtio-gpio.tex
@@ -0,0 +1,256 @@
+\section{GPIO Device}\label{sec:Device Types / GPIO Device}
+
+virtio-gpio is a virtual general purpose IO controller device. It provides a way
+to access the host GPIO devices from the guest. This device provides a hardware
+independent interface between the host and the guests. It allows the host to
+club together GPIO lines from otherwise independent GPIO controllers and present
+them as a single GPIO controller at the guest.
+
+\subsection{Device ID}\label{sec:Device Types / GPIO Device / Device ID}
+41
+
+\subsection{Virtqueues}\label{sec:Device Types / GPIO Device / Virtqueues}
+
+\begin{description}
+\item[0] command
+\item[1] interrupt
+\end{description}
+
+\subsection{Feature bits}\label{sec:Device Types / GPIO Device / Feature bits}
+
+None currently defined.
+
+\subsection{Device configuration layout}\label{sec:Device Types / GPIO Device / Device configuration layout}
+
+All fields of this configuration are always available and are read-only for the driver.
+
+\begin{lstlisting}
+struct virtio_gpio_config {
+    char name[32];
+    u16 ngpio;
+    u16 gpio_names_size;
+    char gpio_names[0];
+}
+\end{lstlisting}
+
+\begin{description}
+\item[\field{name}] is a null-terminated string that represents the name of the
+    GPIO controller.
+\item[\field{ngpio}] is the total number of GPIO lines provided by the
+    controller.
+\item[\field{gpio_names_size}] is the size of the \field{gpio_names} string.
+    This field must be set to 0, if the \field(gpio_names) is not used.
+\item[\field{gpio_names}] is a stream of \field{ngpio} null-terminated strings,
+    where each string corresponds to a GPIO line.
+\end{description}
+
+
+\subsection{Device Initialization}\label{sec:Device Types / GPIO Device / Device Initialization}
+
+\begin{enumerate}
+\item The virtqueue is initialized.
+\end{enumerate}
+
+\subsection{Device Operation}\label{sec:Device Types / GPIO Device / Device Operation}
+
+The operations of a virtio GPIO device are almost always driven by the guest.
+The guest initiates one of the requests from \field{VIRTIO_GPIO_REQ_*} on the
+\field{command} virtqueue and the host responds synchronously on the same
+virtqueue with a response message. The host initiates an operation
+(\field{VIRTIO_GPIO_IRQ_EVENT}) only for reporting the detection of an interrupt
+on a GPIO line and uses the \field{interrupt} virtqueue for the same.
+
+\begin{lstlisting}
+/* GPIO request types */
+#define VIRTIO_GPIO_REQ_ACTIVATE                0x01
+#define VIRTIO_GPIO_REQ_DEACTIVATE              0x02
+#define VIRTIO_GPIO_REQ_GET_DIRECTION           0x03
+#define VIRTIO_GPIO_REQ_DIRECTION_IN            0x04
+#define VIRTIO_GPIO_REQ_DIRECTION_OUT           0x05
+#define VIRTIO_GPIO_REQ_GET_VALUE               0x06
+#define VIRTIO_GPIO_REQ_SET_VALUE               0x07
+#define VIRTIO_GPIO_REQ_IRQ_TYPE                0x08
+#define VIRTIO_GPIO_REQ_IRQ_MASK                0x09
+#define VIRTIO_GPIO_REQ_IRQ_UNMASK              0x0a
+#define VIRTIO_GPIO_IRQ_EVENT                   0x0b
+\end{lstlisting}
+
+\subsubsection{Device Operation: Request Queue}\label{sec:Device Types / GPIO Device / Device Operation: Request Queue}
+
+The communication between the host and the guest take place using a pair of
+request and response messages. The virtio GPIO specification defines two request
+and two response layouts. The particular request/response pair used for each
+GPIO request type is specific later in the request specific sections.
+
+Supported request and response types:
+
+\begin{lstlisting}
+/* GPIO Request */
+struct virtio_gpio_request_nodata {
+        u8 gpio;
+};
+
+struct virtio_gpio_request {
+        u8 gpio;
+        u8 data;
+};
+
+/* GPIO Response */
+struct virtio_gpio_response_nodata {
+        u8 status;
+};
+
+struct virtio_gpio_response {
+        u8 status;
+        u8 data;
+};
+\end{lstlisting}
+
+\begin{description}
+\item[\field{gpio}] GPIO line number.
+\item[\field{data}] Request/Response specific data.
+\item[\field{status}] Status of the request, success or failure.
+\end{description}
+
+Here is the list of different values these fields can contain based on the
+specific request type.
+
+\begin{lstlisting}
+/* GPIO line direction */
+#define VIRTIO_GPIO_DIRECTION_OUT               0x0
+#define VIRTIO_GPIO_DIRECTION_IN                0x1
+
+/* GPIO line interrupt type */
+#define VIRTIO_GPIO_IRQ_TYPE_NONE               0x00
+#define VIRTIO_GPIO_IRQ_TYPE_EDGE_RISING        0x01
+#define VIRTIO_GPIO_IRQ_TYPE_EDGE_FALLING       0x02
+#define VIRTIO_GPIO_IRQ_TYPE_EDGE_BOTH          0x03
+#define VIRTIO_GPIO_IRQ_TYPE_LEVEL_HIGH         0x04
+#define VIRTIO_GPIO_IRQ_TYPE_LEVEL_LOW          0x08
+
+/* Possible values of the status field */
+#define VIRTIO_GPIO_STATUS_OK                   0x0
+#define VIRTIO_GPIO_STATUS_ERR                  0x1
+\end{lstlisting}
+
+\subsubsection{Device Operation: Activate}\label{sec:Device Types / GPIO Device / Device Operation / Activate }
+
+The \field{VIRTIO_GPIO_REQ_ACTIVATE} request is initiated by the guest to
+request the host to activate one of the GPIO lines for use. The guest sends the
+\field{struct virtio_gpio_request_nodata} to the host, and the host responds
+with \field{struct virtio_gpio_response_nodata}.
+
+\subsubsection{Device Operation: Deactivate}\label{sec:Device Types / GPIO Device / Device Operation / Deactivate }
+
+The \field{VIRTIO_GPIO_REQ_DEACTIVATE} request is initiated by the guest to
+request the host to deactivate one of the GPIO lines guest was previously using.
+The guest sends the \field{struct virtio_gpio_request_nodata} to the host, and
+the host responds with \field{struct virtio_gpio_response_nodata}.
+
+\subsubsection{Device Operation: Get Direction}\label{sec:Device Types / GPIO Device / Device Operation / Get Direction }
+
+The \field{VIRTIO_GPIO_REQ_GET_DIRECTION} request is initiated by the guest to
+request the host to return a GPIO line's configured direction. The guest sends
+the \field{struct virtio_gpio_request_nodata} to the host, and the host responds
+with \field{struct virtio_gpio_response}. The host shall set the \field{data}
+field in the response to \field{VIRTIO_GPIO_DIRECTION_OUT} or
+\field{VIRTIO_GPIO_DIRECTION_IN}.
+
+\subsubsection{Device Operation: Direction In}\label{sec:Device Types / GPIO Device / Device Operation / Direction In }
+
+The \field{VIRTIO_GPIO_REQ_DIRECTION_IN} request is initiated by the guest to
+request the host to configure a GPIO line for input direction. The guest sends the
+\field{struct virtio_gpio_request_nodata} to the host, and the host responds
+with \field{struct virtio_gpio_response_nodata}.
+
+\subsubsection{Device Operation: Direction Out}\label{sec:Device Types / GPIO Device / Device Operation / Direction Out }
+
+The \field{VIRTIO_GPIO_REQ_DIRECTION_OUT} request is initiated by the guest to
+request the host to configure a GPIO line for output direction with an initial
+output value (0 for low, 1 for high). The guest sends the \field{struct
+virtio_gpio_request} to the host with initial output value set in the
+\field{data} field, and the host responds with \field{struct
+virtio_gpio_response_nodata}.
+
+\subsubsection{Device Operation: Get Value}\label{sec:Device Types / GPIO Device / Device Operation / Get Value }
+
+The \field{VIRTIO_GPIO_REQ_GET_VALUE} request is initiated by the guest to
+request the host to return the current value sensed on a GPIO line (0 for low, 1
+for high) configured for input. The guest sends the \field{struct
+virtio_gpio_request_nodata} to the host, and the host responds responds with
+\field{struct virtio_gpio_response} with its \field{data} field set to GPIO's
+value.
+
+\subsubsection{Device Operation: Set Value}\label{sec:Device Types / GPIO Device / Device Operation / Set Value }
+
+The \field{VIRTIO_GPIO_REQ_SET_VALUE} request is initiated by the guest to
+request the host to set the value (0 for low, 1 for high) for a GPIO line
+configured for output. The guest sends the \field{struct virtio_gpio_request}
+to the host, with the output value set in the \field{data} field, and the host
+responds with \field{struct virtio_gpio_response_nodata}.
+
+\subsubsection{Device Operation: IRQ Type}\label{sec:Device Types / GPIO Device / Device Operation / IRQ Type }
+
+The \field{VIRTIO_GPIO_REQ_IRQ_TYPE} request is initiated by the guest to
+request the host to set the IRQ trigger type (one of
+\field{VIRTIO_GPIO_IRQ_TYPE_*}) for a GPIO line configured for input. The guest
+sends the \field{struct virtio_gpio_request} to the host, with the IRQ trigger
+type set in the \field{data} field, and the host responds with \field{struct
+virtio_gpio_response_nodata}.
+
+\subsubsection{Device Operation: IRQ Mask}\label{sec:Device Types / GPIO Device / Device Operation / IRQ Mask }
+
+The \field{VIRTIO_GPIO_REQ_IRQ_MASK} request is initiated by the guest to
+request the host to mask the specified GPIO line for interrupts. The guest sends
+the \field{struct virtio_gpio_request_nodata} to the host, and the host responds
+with \field{struct virtio_gpio_response_nodata}.
+
+\subsubsection{Device Operation: IRQ Unmask}\label{sec:Device Types / GPIO Device / Device Operation / IRQ Unmask }
+
+The \field{VIRTIO_GPIO_REQ_IRQ_UNMASK} request is initiated by the guest to
+request the host to unmask the specified GPIO line for interrupts. The guest
+sends the \field{struct virtio_gpio_request_nodata} to the host, and the host
+responds with \field{struct virtio_gpio_response_nodata}.
+
+\subsubsection{Device Operation: IRQ Event}\label{sec:Device Types / GPIO Device / Device Operation / IRQ Event }
+
+The \field{VIRTIO_GPIO_IRQ_EVENT} request is the only request initiated by the
+host to inform the guest that an interrupt is detected on one of the GPIO lines
+configured for input. The host sends the \field{struct
+virtio_gpio_request_nodata} to the guest, and the guest responds with
+\field{struct virtio_gpio_response_nodata}. This is the only request that uses
+the \field{interrupt} virtqueue, while all other requests use the
+\field{command} virtqueue.
+
+
+\drivernormative{\subsubsection}{Device Operation}{Device Types / GPIO Device / Device Operation}
+
+A driver MUST set all the fields of the \field{struct
+virtio_gpio_request_nodata} and \field{struct virtio_gpio_request} before
+sending the request.
+
+A driver MUST NOT use \field{data} field if the final \field{status} returned
+from the device is \field{VIRTIO_GPIO_STATUS_ERR}.
+
+A driver MUST NOT try to set value of a GPIO line configured for input.
+
+A driver MUST NOT try to get value of a GPIO line configured for output.
+
+A driver MUST NOT send IRQ related requests for a GPIO line configured for
+output.
+
+A driver MUST queue only one request at a time and wait for its response before
+queuing the next request.
+
+\devicenormative{\subsubsection}{Device Operation}{Device Types / GPIO Device / Device Operation}
+
+A device MUST set the \field{status} field to \field{VIRTIO_GPIO_STATUS_OK} for
+all successful requests.
+
+A device MUST NOT change the value of any of the fields of the \field{struct
+virtio_gpio_request_nodata} and \field{struct virtio_gpio_request}.
+
+A driver MUST set all the fields of the \field{struct
+virtio_gpio_response_nodata} and \field{struct virtio_gpio_response} before
+sending the response, unless an error has occurred and it has set the
+\field{status} field to \field{VIRTIO_GPIO_STATUS_ERR}.
-- 
2.31.1.272.g89b43f80a514


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/