From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:35112) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1azllW-0004Ov-W0 for qemu-devel@nongnu.org; Mon, 09 May 2016 10:02:32 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1azllR-0003E3-NL for qemu-devel@nongnu.org; Mon, 09 May 2016 10:02:29 -0400 Received: from mx1.redhat.com ([209.132.183.28]:39880) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1azllR-0003DT-FA for qemu-devel@nongnu.org; Mon, 09 May 2016 10:02:25 -0400 Date: Mon, 9 May 2016 15:02:21 +0100 From: Stefan Hajnoczi Message-ID: <20160509140221.GH3372@stefanha-x1.localdomain> References: <1462365524-21163-1-git-send-email-kraxel@redhat.com> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="smOfPzt+Qjm5bNGJ" Content-Disposition: inline In-Reply-To: <1462365524-21163-1-git-send-email-kraxel@redhat.com> Subject: Re: [Qemu-devel] [virtio-dev] [PATCH] Add virtio input device specification. List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Gerd Hoffmann Cc: virtio-dev@lists.oasis-open.org, qemu-devel@nongnu.org --smOfPzt+Qjm5bNGJ Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Wed, May 04, 2016 at 02:38:44PM +0200, Gerd Hoffmann wrote: > Resuming the effort to get the input device specs actually merged. >=20 > Support has been added to the linux kernel version 4.1 > and to qemu version 2.4. >=20 > git branch: > https://www.kraxel.org/cgit/virtio-spec/log/?h=3Dvirtio-input >=20 > 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-280= 0007 >=20 > Signed-off-by: Gerd Hoffmann > --- > content.tex | 2 + > virtio-input.tex | 124 +++++++++++++++++++++++++++++++++++++++++++++++++= ++++++ > 2 files changed, 126 insertions(+) > create mode 100644 virtio-input.tex >=20 > 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{residu= al}, > \field{status_qualifier}, \field{status}, \field{response} and > \field{sense} fields. > =20 > +\input{virtio-input.tex} > + > \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} > =20 > 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.gi= t/tree/include/uapi/linux/input.h}{include/uapi/linux/input.h} > +and \href{https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.gi= t/tree/include/uapi/linux/input-event-codes.h}{include/uapi/linux/input-eve= nt-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 / Virtqueu= es} > + > +\begin{description} > +\item[0] eventq > +\item[1] statusq > +\end{description} > + > +\subsection{Feature bits}\label{sec:Device Types / Input Device / Featur= e 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 =3D 0x00, > + VIRTIO_INPUT_CFG_ID_NAME =3D 0x01, > + VIRTIO_INPUT_CFG_ID_SERIAL =3D 0x02, > + VIRTIO_INPUT_CFG_PROP_BITS =3D 0x10, > + VIRTIO_INPUT_CFG_EV_BITS =3D 0x11, > + VIRTIO_INPUT_CFG_ABS_INFO =3D 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.bitma= p}. > + > +\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 / De= vice 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. --smOfPzt+Qjm5bNGJ Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 iQEcBAEBAgAGBQJXMJhtAAoJEJykq7OBq3PIwzsH/i6wFhG1cwzfdxmWuQ4LfRwL YFueDowOBfiaYQ8qhUZ2fEuG53eyecUwy/+pyqAN2jVN2i2v+Giss5yu6WRSe09t DhzjzCjEgiAZxE4R8g3oub+RfQ5y1+eaDXYn3ttM0kweBWsapDt6u7uGLYGI+P31 YX2ahNMOhD9flDUalsK/dO2s782WbOL91jPIzJFIPRkub4MJ2vyJaAHdIQZbEDKo yHYG0h+2JNJzhi9yHZeFuNITEXk03KzOGM7FE9gJ3G3Qx0NeDU4SyA67fCWNrgBn 3EgqVVhKc55b++lT52sEU/vx+cFWSiGuuFsBFU20CJ/L0gURD5CwgjgeY4OYnhg= =Azhx -----END PGP SIGNATURE----- --smOfPzt+Qjm5bNGJ--