1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
\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. An instance of the virtio
device represents one such input device. Device behavior mirrors that
of the evdev layer in Linux, making pass-through implementations on top
of evdev easy.
This specification defines how evdev events are transported
over virtio and how the set of supported events is discovered by a driver.
It does not, however, define the semantics of input events as this is
dependent on the particular evdev implementation. For the list of events
used by Linux input devices, see
\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_ID_DEVIDS = 0x03,
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;
le32 res;
};
struct virtio_input_devids {
le16 bustype;
le16 vendor;
le16 product;
le16 version;
};
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;
struct virtio_input_devids ids;
} u;
};
\end{lstlisting}
To query a specific piece of information the driver sets
\field{select} and \field{subsel} accordingly, then checks \field{size}
to see how much information is available. \field{size} can be
zero if no information is available. Strings do not include a
NUL terminator. Related evdev ioctl names are provided for reference.
\begin{description}
\item[VIRTIO_INPUT_CFG_ID_NAME]
\field{subsel} is zero.
Returns the name of the device, in \field{u.string}.
Similar to EVIOCGNAME ioctl for Linux evdev devices.
\item[VIRTIO_INPUT_CFG_ID_SERIAL]
\field{subsel} is zero.
Returns the serial number of the device, in \field{u.string}.
\item[VIRTIO_INPUT_CFG_ID_DEVIDS]
\field{subsel} is zero.
Returns ID information of the device, in \field{u.ids}.
Similar to EVIOCGID ioctl for Linux evdev devices.
\item[VIRTIO_INPUT_CFG_PROP_BITS]
\field{subsel} is zero.
Returns input properties of the device, in \field{u.bitmap}.
Individual bits in the bitmap correspond to INPUT_PROP_*
constants used by the underlying evdev implementation.
Similar to EVIOCGPROP ioctl for Linux evdev devices.
\item[VIRTIO_INPUT_CFG_EV_BITS]
\field{subsel} specifies the event type using EV_*
constants in the underlying evdev implementation. If
\field{size} is non-zero the event type is supported and
a bitmap of supported event codes is returned in \field{u.bitmap}.
Individual bits in the bitmap correspond to
implementation-defined input event codes, for example keys
or pointing device axes.
Similar to EVIOCGBIT ioctl for Linux evdev devices.
\item[VIRTIO_INPUT_CFG_ABS_INFO]
\field{subsel} specifies the absolute axis using ABS_*
constants in the underlying evdev implementation.
Information about the axis will be returned in \field{u.abs}.
Similar to EVIOCGABS ioctl for Linux evdev devices.
\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}
\drivernormative{\subsubsection}{Device Initialization}{Device Types / Input Device / Device Initialization}
A driver MUST set both \field{select} and \field{subsel} when querying
device configuration, in any order.
A driver MUST NOT write to configuration fields other than \field{select}
and \field{subsel}.
A driver SHOULD check the \field{size} field before accessing the
configuration information.
\devicenormative{\subsubsection}{Device Initialization}{Device Types / Input Device / Device Initialization}
A device MUST set the \field{size} field to zero if it doesn't support a
given \field{select} and \field{subsel} combination.
\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 for pointing devices are sent 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-ness.
\end{enumerate}
\begin{lstlisting}
struct virtio_input_event {
le16 type;
le16 code;
le32 value;
};
\end{lstlisting}
\drivernormative{\subsubsection}{Device Operation}{Device Types / Input Device / Device Operation}
A driver SHOULD keep the eventq populated with buffers. These buffers
MUST be device-writable and MUST be at least the size of
struct virtio_input_event.
Buffers placed into the statusq by a driver MUST be at least the size
of struct virtio_input_event.
A driver SHOULD ignore eventq input events it does not recognize. Note
that evdev devices generally maintain backward compatibility by sending
redundant events and relying on the consuming side using only the events
it understands and ignoring the rest.
\devicenormative{\subsubsection}{Device Operation}{Device Types / Input Device / Device Operation}
A device MAY drop input events if the eventq does not have enough
available buffers. It SHOULD NOT drop individual input events if
they are part of a sequence forming one input device update. For
example, a pointing device update typically consists of several
input events, one for each axis, and a terminating EV_SYN event.
A device SHOULD either buffer or drop the entire sequence.
|
