1# Input 2 3crosvm supports 4[virtio-input](https://docs.oasis-open.org/virtio/virtio/v1.2/csd01/virtio-v1.2-csd01.html#x1-3850008) 5devices that provide human input devices like multi-touch devices, trackpads, keyboards, and mice. 6 7Events may be sent to the input device via a socket carrying `virtio_input_event` structures. On 8Unix-like platforms, this socket must be a UNIX domain socket in stream mode (`AF_UNIX`/`AF_LOCAL`, 9`SOCK_STREAM`). Typically this will be created by a separate program that listens and accepts a 10connection on this socket and sends the desired events. 11 12On Linux, it is also possible to grab an `evdev` device and forward its events to the guest. 13 14The general syntax of the input option is as follows: 15 16``` 17--input DEVICE-TYPE[KEY=VALUE,KEY=VALUE,...] 18``` 19 20For example, to create a 1920x1080 multi-touch device reading data from `/tmp/multi-touch-socket`: 21 22```sh 23crosvm run \ 24 ... 25 --input multi-touch[path=/tmp/multi-touch-socket,width=1920,height=1080] 26 ... 27``` 28 29The available device types and their specific options are listed below. 30 31## Input device types 32 33### Evdev 34 35Linux only. 36 37Passes an [event device](https://docs.kernel.org/input/input.html#evdev) node into the VM. The 38device will be grabbed (unusable from the host) and made available to the guest with the same 39configuration it shows on the host. 40 41Options: 42 43- `path` (required): path to `evdev` device, e.g. `/dev/input/event0` 44 45Example: 46 47```sh 48crosvm run \ 49 --input evdev[path=/dev/input/event0] \ 50 ... 51``` 52 53### Keyboard 54 55Add a keyboard virtio-input device. 56 57Options: 58 59- `path` (required): path to event source socket 60 61Example: 62 63```sh 64crosvm run \ 65 --input keyboard[path=/tmp/keyboard-socket] \ 66 ... 67``` 68 69### Mouse 70 71Add a mouse virtio-input device. 72 73Options: 74 75- `path` (required): path to event source socket 76 77Example: 78 79```sh 80crosvm run \ 81 --input mouse[path=/tmp/mouse-socket] \ 82 ... 83``` 84 85### Multi-Touch 86 87Add a multi-touch touchscreen virtio-input device. 88 89Options: 90 91- `path` (required): path to event source socket 92- `width` (optional): width of the touchscreen in pixels (default: 1280) 93- `height` (optional): height of the touchscreen in pixels (default: 1024) 94- `name` (optional): device name string 95 96If `width` and `height` are not specified, the first multi-touch input device is sized to match the 97GPU display size, if specified. 98 99Example: 100 101```sh 102crosvm run \ 103 ... 104 --input multi-touch[path=/tmp/multi-touch-socket,width=1920,height=1080,name=mytouch2] 105 ... 106``` 107 108### Rotary 109 110Add a rotating side button/wheel virtio-input device. 111 112Options: 113 114- `path` (required): path to event source socket 115 116Example: 117 118```sh 119crosvm run \ 120 --input rotary[path=/tmp/rotary-socket] \ 121 ... 122``` 123 124### Single-Touch 125 126Add a single-touch touchscreen virtio-input device. 127 128Options: 129 130- `path` (required): path to event source socket 131- `width` (optional): width of the touchscreen in pixels (default: 1280) 132- `height` (optional): height of the touchscreen in pixels (default: 1024) 133- `name` (optional): device name string 134 135If `width` and `height` are not specified, the first single-touch input device is sized to match the 136GPU display size, if specified. 137 138Example: 139 140```sh 141crosvm run \ 142 ... 143 --input single-touch[path=/tmp/single-touch-socket,width=1920,height=1080,name=mytouch1] 144 ... 145``` 146 147### Switches 148 149Add a switches virtio-input device. Switches are often used for accessibility, such as with the 150Android [Switch Access](https://support.google.com/accessibility/android/topic/6151780) feature. 151 152Options: 153 154- `path` (required): path to event source socket 155 156Example: 157 158```sh 159crosvm run \ 160 --input switches[path=/tmp/switches-socket] \ 161 ... 162``` 163 164### Trackpad 165 166Add a trackpad virtio-input device. 167 168Options: 169 170- `path` (required): path to event source socket 171- `width` (optional): width of the touchscreen in pixels (default: 1280) 172- `height` (optional): height of the touchscreen in pixels (default: 1024) 173- `name` (optional): device name string 174 175Example: 176 177```sh 178crosvm run \ 179 ... 180 --input trackpad[path=/tmp/trackpad-socket,width=1920,height=1080,name=mytouch1] 181 ... 182``` 183 184### Custom 185 186Add a custom virtio-input device. 187 188- `path` (required): path to event source socket 189- `config_path` (required): path to file configuring device 190 191```sh 192crosvm run \ 193 --input custom[path=/tmp/keyboard-socket,config-path=/tmp/custom-keyboard-config.json] \ 194 ... 195``` 196 197This config_path requires a JSON-formatted configuration file. "events" configures the supported 198events. "name" defines the customized device name, "serial" defines customized serial name. The 199properties and axis info are yet to be supported. 200 201Here is an example of event config file: 202 203``` 204{ 205 "name": "Virtio Custom", 206 "serial_name": "virtio-custom", 207 "events": [ 208 { 209 "event_type": "EV_KEY", 210 "event_type_code": 1, 211 "supported_events": { 212 "KEY_ESC": 1, 213 "KEY_1": 2, 214 "KEY_2": 3, 215 "KEY_A": 30, 216 "KEY_B": 48, 217 "KEY_SPACE": 57 218 } 219 }, 220 { 221 "event_type": "EV_REP", 222 "event_type_code": 20, 223 "supported_events": { 224 "REP_DELAY": 0, 225 "REP_PERIOD": 1 226 } 227 }, 228 { 229 "event_type": "EV_LED", 230 "event_type_code": 17, 231 "supported_events": { 232 "LED_NUML": 0, 233 "LED_CAPSL": 1, 234 "LED_SCROLLL": 2 235 } 236 } 237 ] 238} 239``` 240