qemu-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Qemu-devel] [virtio-dev] [PATCH] Add virtio input device specificat


From: Stefan Hajnoczi
Subject: Re: [Qemu-devel] [virtio-dev] [PATCH] Add virtio input device specification.
Date: Mon, 9 May 2016 15:02:21 +0100
User-agent: Mutt/1.6.0 (2016-04-01)

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 <address@hidden>
> ---
>  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.

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]