.. _virtio-input:

Virtio-Input
############

The virtio input device can be used to create virtual human interface
devices such as keyboards, mice, and tablets. It sends Linux
input layer events over virtio.

The ACRN virtio-input architecture is shown below.

.. figure:: images/virtio-hld-image53.png
   :align: center

   Virtio-input Architecture on ACRN

Virtio-input is implemented as a virtio modern device in the ACRN Device
Model. It is registered as a PCI virtio device to the guest OS. No changes
are required in frontend Linux virtio-input except that the guest kernel
must be built with ``CONFIG_VIRTIO_INPUT=y``.

Two virtqueues are used to transfer input_event between FE and BE. One
is for the input_events from BE to FE, as generated by input hardware
devices in the Service VM. The other is for status changes from FE to BE, as
finally sent to input hardware devices in the Service VM.

At the probe stage of the FE virtio-input driver, a buffer (used to
accommodate 64 input events) is allocated together with the driver data.
Sixty-four descriptors are added to the event virtqueue. One descriptor
points to one entry in the buffer. Then a kick on the event virtqueue is
performed.

The virtio-input BE driver in the Device Model uses mevent to poll the
availability of the input events from an input device through the evdev char
device. When an input event is available, the BE driver reads it out from the
char device and caches it into an internal buffer until an EV_SYN input
event with SYN_REPORT is received. The BE driver then copies all the cached
input events to the event virtqueue, one by one. These events are added by
the FE driver following a notification to the FE driver, implemented
as an interrupt injection to the User VM.

For input events regarding status change, the FE driver allocates a
buffer for an input event and adds it to the status virtqueue followed
by a kick. The BE driver reads the input event from the status virtqueue and
writes it to the evdev char device.

The data transferred between FE and BE is organized as struct
input_event:

.. code-block:: c

   struct input_event {
      struct timeval time;
      __u16 type;
      __u16 code;
      __s32 value;
   };

A structure virtio_input_config is defined and used as the
device-specific configuration registers. To query a specific piece of
configuration information, the FE driver sets "select" and "subsel"
accordingly. Information size is returned in "size" and information data
is returned in union "u":

.. code-block:: c

   struct virtio_input_config {
      uint8_t select;
      uint8_t subsel;
      uint8_t size;
      uint8_t reserved[5];
      union {
         char string[128];
         uint8_t bitmap[128];
         struct virtio_input_absinfo abs;
         struct virtio_input_devids ids;
       } u;
   };

Read/Write to these registers results in a vmexit, and cfgread/cfgwrite
callbacks in struct virtio_ops are called finally in the Device Model. The
virtio-input BE in the Device Model issues ioctl to the evdev char device
according to the "select" and "subselect" registers to get the corresponding
device capabilities information from the kernel. The virtio-input BE returns the
information to the guest OS.

The FE driver obtains all the device-specific configurations at the
probe stage. Based on this information, the virtio-input FE driver registers
an input device to the input subsystem.

The general command syntax is::

   -s n,virtio-input,/dev/input/eventX[,serial]

-  /dev/input/eventX is used to specify the evdev char device node in
   the Service VM.

-  "serial" is an optional string. When it is specified, it will be used
   as the Uniq of the guest virtio input device.
