Important

This is the latest documentation for the unstable development branch of Project ACRN (master).
Use the drop-down menu on the left to select documentation for a stable release such as v3.2 or v3.0.

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.

../../_images/virtio-hld-image53.png

Figure 202 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:

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”:

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.