1.. _virtio-input:
2
3Virtio-Input
4############
5
6The virtio input device can be used to create virtual human interface
7devices such as keyboards, mice, and tablets. It sends Linux
8input layer events over virtio.
9
10The ACRN virtio-input architecture is shown below.
11
12.. figure:: images/virtio-hld-image53.png
13   :align: center
14
15   Virtio-input Architecture on ACRN
16
17Virtio-input is implemented as a virtio modern device in the ACRN Device
18Model. It is registered as a PCI virtio device to the guest OS. No changes
19are required in frontend Linux virtio-input except that the guest kernel
20must be built with ``CONFIG_VIRTIO_INPUT=y``.
21
22Two virtqueues are used to transfer input_event between FE and BE. One
23is for the input_events from BE to FE, as generated by input hardware
24devices in the Service VM. The other is for status changes from FE to BE, as
25finally sent to input hardware devices in the Service VM.
26
27At the probe stage of the FE virtio-input driver, a buffer (used to
28accommodate 64 input events) is allocated together with the driver data.
29Sixty-four descriptors are added to the event virtqueue. One descriptor
30points to one entry in the buffer. Then a kick on the event virtqueue is
31performed.
32
33The virtio-input BE driver in the Device Model uses mevent to poll the
34availability of the input events from an input device through the evdev char
35device. When an input event is available, the BE driver reads it out from the
36char device and caches it into an internal buffer until an EV_SYN input
37event with SYN_REPORT is received. The BE driver then copies all the cached
38input events to the event virtqueue, one by one. These events are added by
39the FE driver following a notification to the FE driver, implemented
40as an interrupt injection to the User VM.
41
42For input events regarding status change, the FE driver allocates a
43buffer for an input event and adds it to the status virtqueue followed
44by a kick. The BE driver reads the input event from the status virtqueue and
45writes it to the evdev char device.
46
47The data transferred between FE and BE is organized as struct
48input_event:
49
50.. code-block:: c
51
52   struct input_event {
53      struct timeval time;
54      __u16 type;
55      __u16 code;
56      __s32 value;
57   };
58
59A structure virtio_input_config is defined and used as the
60device-specific configuration registers. To query a specific piece of
61configuration information, the FE driver sets "select" and "subsel"
62accordingly. Information size is returned in "size" and information data
63is returned in union "u":
64
65.. code-block:: c
66
67   struct virtio_input_config {
68      uint8_t select;
69      uint8_t subsel;
70      uint8_t size;
71      uint8_t reserved[5];
72      union {
73         char string[128];
74         uint8_t bitmap[128];
75         struct virtio_input_absinfo abs;
76         struct virtio_input_devids ids;
77       } u;
78   };
79
80Read/Write to these registers results in a vmexit, and cfgread/cfgwrite
81callbacks in struct virtio_ops are called finally in the Device Model. The
82virtio-input BE in the Device Model issues ioctl to the evdev char device
83according to the "select" and "subselect" registers to get the corresponding
84device capabilities information from the kernel. The virtio-input BE returns the
85information to the guest OS.
86
87The FE driver obtains all the device-specific configurations at the
88probe stage. Based on this information, the virtio-input FE driver registers
89an input device to the input subsystem.
90
91The general command syntax is::
92
93   -s n,virtio-input,/dev/input/eventX[,serial]
94
95-  /dev/input/eventX is used to specify the evdev char device node in
96   the Service VM.
97
98-  "serial" is an optional string. When it is specified, it will be used
99   as the Uniq of the guest virtio input device.
100