diff mbox

Add virtio input device specification.

Message ID 1462365524-21163-1-git-send-email-kraxel@redhat.com (mailing list archive)
State New, archived
Headers show

Commit Message

Gerd Hoffmann May 4, 2016, 12:38 p.m. UTC 
Resuming the effort to get the input device specs actually merged.

Support has been added to the linux kernel version 4.1
and to qemu version 2.4.

git branch:
  https://www.kraxel.org/cgit/virtio-spec/log/?h=virtio-input

Rendered versions are available here:
  https://www.kraxel.org/virtio/virtio-v1.0-cs03-virtio-input.pdf
  https://www.kraxel.org/virtio/virtio-v1.0-cs03-virtio-input.html#x1-2800007

Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
---
 content.tex      |   2 +
 virtio-input.tex | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 126 insertions(+)
 create mode 100644 virtio-input.tex

Comments

Stefan Hajnoczi May 9, 2016, 2:02 p.m. UTC | #1 
On Wed, May 04, 2016 at 02:38:44PM +0200, Gerd Hoffmann wrote:
> Resuming the effort to get the input device specs actually merged.
> 
> Support has been added to the linux kernel version 4.1
> and to qemu version 2.4.
> 
> git branch:
>   https://www.kraxel.org/cgit/virtio-spec/log/?h=virtio-input
> 
> Rendered versions are available here:
>   https://www.kraxel.org/virtio/virtio-v1.0-cs03-virtio-input.pdf
>   https://www.kraxel.org/virtio/virtio-v1.0-cs03-virtio-input.html#x1-2800007
> 
> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> ---
>  content.tex      |   2 +
>  virtio-input.tex | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 126 insertions(+)
>  create mode 100644 virtio-input.tex
> 
> diff --git a/content.tex b/content.tex
> index d989d98..4c0c4c9 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -5641,6 +5641,8 @@ descriptor for the \field{sense_len}, \field{residual},
>  \field{status_qualifier}, \field{status}, \field{response} and
>  \field{sense} fields.
>  
> +\input{virtio-input.tex}
> +
>  \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
>  
>  Currently there are three device-independent feature bits defined:
> diff --git a/virtio-input.tex b/virtio-input.tex
> new file mode 100644
> index 0000000..cdc16ac
> --- /dev/null
> +++ b/virtio-input.tex
> @@ -0,0 +1,124 @@
> +\section{Input Device}\label{sec:Device Types / Input Device}
> +
> +The virtio input device can be used to create virtual human interface
> +devices such as keyboards, mice and tablets.  It basically sends linux
> +input layer events over virtio.
> +See \href{https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/input.h}{include/uapi/linux/input.h}
> +and \href{https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/input-event-codes.h}{include/uapi/linux/input-event-codes.h}
> +in the linux source tree.
> +
> +\subsection{Device ID}\label{sec:Device Types / Input Device / Device ID}
> +
> +18
> +
> +\subsection{Virtqueues}\label{sec:Device Types / Input Device / Virtqueues}
> +
> +\begin{description}
> +\item[0] eventq
> +\item[1] statusq
> +\end{description}
> +
> +\subsection{Feature bits}\label{sec:Device Types / Input Device / Feature bits}
> +
> +None.
> +
> +\subsection{Device configuration layout}\label{sec:Device Types / Input Device / Device configuration layout}
> +
> +Device configuration holds all information the guest needs to handle
> +the device, most importantly the events which are supported.
> +
> +\begin{lstlisting}
> +enum virtio_input_config_select {
> +	VIRTIO_INPUT_CFG_UNSET      = 0x00,
> +	VIRTIO_INPUT_CFG_ID_NAME    = 0x01,
> +	VIRTIO_INPUT_CFG_ID_SERIAL  = 0x02,
> +	VIRTIO_INPUT_CFG_PROP_BITS  = 0x10,
> +	VIRTIO_INPUT_CFG_EV_BITS    = 0x11,
> +	VIRTIO_INPUT_CFG_ABS_INFO   = 0x12,
> +};
> +
> +struct virtio_input_absinfo {
> +	le32  min;
> +	le32  max;
> +	le32  fuzz;
> +	le32  flat;
> +};
> +
> +struct virtio_input_config {
> +	u8    select;
> +	u8    subsel;
> +	u8    size;
> +	u8    reserved[5];
> +	union {
> +		char string[128];
> +		u8   bitmap[128];
> +		struct virtio_input_absinfo abs;
> +	} u;
> +};
> +\end{lstlisting}
> +
> +To query a specific piece of information the driver MUST set
> +\field{select} and \field{subsel} accordingly, then check \field{size}
> +to see and how much information is available.  \field{size} can be
> +zero if no information is available.

Is there a particular write order that matters (subsel then select vs
select then subsel)?

MUST/MAY/etc statements go into \devicenormative or \drivernormative
sections.  These must be referenced from conformance.tex too.

> +
> +\begin{description}
> +
> +\item[VIRTIO_INPUT_CFG_ID_NAME]
> +\field{subsel} is not used and MUST be zero.
> +Returns the name of the device, in \field{u.string}.

Is it a NUL-terminated string and does size include the NUL byte?

> +
> +Same as EVIOCGNAME ioctl for linux evdev devices.
> +
> +\item[VIRTIO_INPUT_CFG_ID_SERIAL]
> +\field{subsel} is not used and MUST be zero.
> +Returns the serial number of the device, in \field{u.string}.
> +
> +\item[VIRTIO_INPUT_CFG_PROP_BITS]
> +\field{subsel} is not used and MUST be zero.
> +Returns input properties (INPUT_PROP_*) of the device, in \field{u.bitmap}.
> +
> +\item[VIRTIO_INPUT_CFG_EV_BITS]
> +\field{subsel} specifies the event type (EV_*).  If \field{size} is
> +non-zero the event type is supported and a bitmap the of supported
> +event codes is returned in \field{u.bitmap}.
> +
> +Same as EVIOCGBIT ioctl.
> +
> +\item[VIRTIO_INPUT_CFG_ABS_INFO]
> +\field{subsel} specifies the absolute axes (ABS_*).
> +Informations about the axis will be returned in \field{u.abs}.
> +
> +Same as EVIOCGABS ioctl.
> +
> +\end{description}
> +
> +\subsection{Device Initialization}\label{sec:Device Types / Input Device / Device Initialization}
> +
> +\begin{enumerate}
> +\item The device is queried for supported event types and codes.
> +\item The eventq is populated with receive buffers.
> +\end{enumerate}
> +
> +\subsection{Device Operation}\label{sec:Device Types / Input Device / Device Operation}
> +
> +\begin{enumerate}
> +\item Input events such as press and release events for keys and
> +  buttons and motion events are send from the device to the driver

s/send/sent/

> +  using the eventq.
> +\item Status feedback such as keyboard led updates are sent from the
> +  driver to the device using the statusq.
> +\item Both queues use the same virtio_input_event struct.
> +  \field{type}, \field{code} and \field{value} are filled according to
> +  the linux input layer (evdev) interface, except that the fields are
> +  in little endian byte order whereas the evdev ioctl interface uses
> +  native endian.
> +\end{enumerate}
> +
> +\begin{lstlisting}
> +struct virtio_input_event {
> +	le16 type;
> +	le16 code;
> +	le32 value;
> +};
> +\end{lstlisting}

Is there any provision for running out of descriptors in the eventq?  I
guess the device can buffer events until the eventq has more
descriptors.  Given that this is HID hopefully the event rate is low
enough that even slow guests can refill eventq in time for the next
event.
Gerd Hoffmann May 10, 2016, 9:21 a.m. UTC | #2 
Hi,

> > +To query a specific piece of information the driver MUST set
> > +\field{select} and \field{subsel} accordingly, then check \field{size}
> > +to see and how much information is available.  \field{size} can be
> > +zero if no information is available.
> 
> Is there a particular write order that matters (subsel then select vs
> select then subsel)?

No.

> MUST/MAY/etc statements go into \devicenormative or \drivernormative
> sections.  These must be referenced from conformance.tex too.

Hmm, seems they are linked to section.  I'd rate that particular section
(device config layout) normative for both device and driver ...

> > +\item[VIRTIO_INPUT_CFG_ID_NAME]
> > +\field{subsel} is not used and MUST be zero.
> > +Returns the name of the device, in \field{u.string}.
> 
> Is it a NUL-terminated string and does size include the NUL byte?

Not NUL-terminated (in practice chances are high it actually is
NUL-terminated, but that is more a side effect of the actual
implementation).  Length without NUL-byte obviously.

Text updated.

> > +\begin{enumerate}
> > +\item Input events such as press and release events for keys and
> > +  buttons and motion events are send from the device to the driver
> 
> s/send/sent/

Fixed.

> > +\begin{lstlisting}
> > +struct virtio_input_event {
> > +	le16 type;
> > +	le16 code;
> > +	le32 value;
> > +};
> > +\end{lstlisting}
> 
> Is there any provision for running out of descriptors in the eventq?  I
> guess the device can buffer events until the eventq has more
> descriptors.  Given that this is HID hopefully the event rate is low
> enough that even slow guests can refill eventq in time for the next
> event.

An input event can have multiple eventq entries, and the input layer
uses a special sync event to group them.  So, a mouse move usually has
three entries:  One for the X axis, one for the Y axis, and the sync.

The qemu implementation queues up events until it sees a sync, then goes
place the whole group into the event queue.  Or drops them all in case
there isn't enough space.  So the guest will never see a incomplete
group.

But that's it.  No additional buffering.  The event queue has 64
entries, that should be plenty given that HID is low-rate indeed.  If
the queue is full you likely have bigger problems than dropped input
events ...

cheers,
  Gerd
diff mbox

Patch

diff --git a/content.tex b/content.tex
index d989d98..4c0c4c9 100644
--- a/content.tex
+++ b/content.tex
@@ -5641,6 +5641,8 @@  descriptor for the \field{sense_len}, \field{residual},
 \field{status_qualifier}, \field{status}, \field{response} and
 \field{sense} fields.
 
+\input{virtio-input.tex}
+
 \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
 
 Currently there are three device-independent feature bits defined:
diff --git a/virtio-input.tex b/virtio-input.tex
new file mode 100644
index 0000000..cdc16ac
--- /dev/null
+++ b/virtio-input.tex
@@ -0,0 +1,124 @@ 
+\section{Input Device}\label{sec:Device Types / Input Device}
+
+The virtio input device can be used to create virtual human interface
+devices such as keyboards, mice and tablets.  It basically sends linux
+input layer events over virtio.
+See \href{https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/input.h}{include/uapi/linux/input.h}
+and \href{https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/input-event-codes.h}{include/uapi/linux/input-event-codes.h}
+in the linux source tree.
+
+\subsection{Device ID}\label{sec:Device Types / Input Device / Device ID}
+
+18
+
+\subsection{Virtqueues}\label{sec:Device Types / Input Device / Virtqueues}
+
+\begin{description}
+\item[0] eventq
+\item[1] statusq
+\end{description}
+
+\subsection{Feature bits}\label{sec:Device Types / Input Device / Feature bits}
+
+None.
+
+\subsection{Device configuration layout}\label{sec:Device Types / Input Device / Device configuration layout}
+
+Device configuration holds all information the guest needs to handle
+the device, most importantly the events which are supported.
+
+\begin{lstlisting}
+enum virtio_input_config_select {
+	VIRTIO_INPUT_CFG_UNSET      = 0x00,
+	VIRTIO_INPUT_CFG_ID_NAME    = 0x01,
+	VIRTIO_INPUT_CFG_ID_SERIAL  = 0x02,
+	VIRTIO_INPUT_CFG_PROP_BITS  = 0x10,
+	VIRTIO_INPUT_CFG_EV_BITS    = 0x11,
+	VIRTIO_INPUT_CFG_ABS_INFO   = 0x12,
+};
+
+struct virtio_input_absinfo {
+	le32  min;
+	le32  max;
+	le32  fuzz;
+	le32  flat;
+};
+
+struct virtio_input_config {
+	u8    select;
+	u8    subsel;
+	u8    size;
+	u8    reserved[5];
+	union {
+		char string[128];
+		u8   bitmap[128];
+		struct virtio_input_absinfo abs;
+	} u;
+};
+\end{lstlisting}
+
+To query a specific piece of information the driver MUST set
+\field{select} and \field{subsel} accordingly, then check \field{size}
+to see and how much information is available.  \field{size} can be
+zero if no information is available.
+
+\begin{description}
+
+\item[VIRTIO_INPUT_CFG_ID_NAME]
+\field{subsel} is not used and MUST be zero.
+Returns the name of the device, in \field{u.string}.
+
+Same as EVIOCGNAME ioctl for linux evdev devices.
+
+\item[VIRTIO_INPUT_CFG_ID_SERIAL]
+\field{subsel} is not used and MUST be zero.
+Returns the serial number of the device, in \field{u.string}.
+
+\item[VIRTIO_INPUT_CFG_PROP_BITS]
+\field{subsel} is not used and MUST be zero.
+Returns input properties (INPUT_PROP_*) of the device, in \field{u.bitmap}.
+
+\item[VIRTIO_INPUT_CFG_EV_BITS]
+\field{subsel} specifies the event type (EV_*).  If \field{size} is
+non-zero the event type is supported and a bitmap the of supported
+event codes is returned in \field{u.bitmap}.
+
+Same as EVIOCGBIT ioctl.
+
+\item[VIRTIO_INPUT_CFG_ABS_INFO]
+\field{subsel} specifies the absolute axes (ABS_*).
+Informations about the axis will be returned in \field{u.abs}.
+
+Same as EVIOCGABS ioctl.
+
+\end{description}
+
+\subsection{Device Initialization}\label{sec:Device Types / Input Device / Device Initialization}
+
+\begin{enumerate}
+\item The device is queried for supported event types and codes.
+\item The eventq is populated with receive buffers.
+\end{enumerate}
+
+\subsection{Device Operation}\label{sec:Device Types / Input Device / Device Operation}
+
+\begin{enumerate}
+\item Input events such as press and release events for keys and
+  buttons and motion events are send from the device to the driver
+  using the eventq.
+\item Status feedback such as keyboard led updates are sent from the
+  driver to the device using the statusq.
+\item Both queues use the same virtio_input_event struct.
+  \field{type}, \field{code} and \field{value} are filled according to
+  the linux input layer (evdev) interface, except that the fields are
+  in little endian byte order whereas the evdev ioctl interface uses
+  native endian.
+\end{enumerate}
+
+\begin{lstlisting}
+struct virtio_input_event {
+	le16 type;
+	le16 code;
+	le32 value;
+};
+\end{lstlisting}