1<!-- 2 Copyright 2011 The Android Open Source Project 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15--> 16 17# Overview # 18 19The Android input subsystem nominally consists of an event pipeline 20that traverses multiple layers of the system. 21 22## Input Pipeline ## 23 24At the lowest layer, the physical input device produces signals that 25describe state changes such as key presses and touch contact points. 26The device firmware encodes and transmits these signals in some way 27such as by sending USB HID reports to the system or by producing 28interrupts on an I2C bus. 29 30The signals are then decoded by a device driver in the Linux kernel. 31The Linux kernel provides drivers for many standard peripherals, 32particularly those that adhere to the HID protocol. However, an OEM 33must often provide custom drivers for embedded devices that are 34tightly integrated into the system at a low-level, such as touch screens. 35 36The input device drivers are responsible for translating device-specific 37signals into a standard input event format, by way of the Linux 38input protocol. The Linux input protocol defines a standard set of 39event types and codes in the `linux/input.h` kernel header file. 40In this way, components outside the kernel do not need to care about 41the details such as physical scan codes, HID usages, I2C messages, 42GPIO pins, and the like. 43 44Next, the Android `EventHub` component reads input events from the kernel 45by opening the `evdev` driver associated with each input device. 46The Android InputReader component then decodes the input events 47according to the device class and produces a stream of Android input 48events. As part of this process, the Linux input protocol event codes 49are translated into Android event codes according to the 50input device configuration, keyboard layout files, and various 51mapping tables. 52 53Finally, the `InputReader` sends input events to the InputDispatcher 54which forwards them to the appropriate window. 55 56## Control Points ## 57 58There are several stages in the input pipeline which effect control 59over the behavior of the input device. 60 61### Driver and Firmware Configuration ### 62 63Input device drivers frequently configure the behavior of the input 64device by setting parameters in registers or even uploading the 65firmware itself. This is particularly the case for embedded 66devices such as touch screens where a large part of the calibration 67process involves tuning these parameters or fixing the firmware 68to provide the desired accuracy and responsiveness and to suppress 69noise. 70 71Driver configuration options are often specified as module parameters 72in the kernel board support package (BSP) so that the same driver 73can support multiple different hardware implementations. 74 75This documentation does attempt to describe driver or firmware 76configuration, but it does offer guidance as to device calibration 77in general. 78 79### Board Configuration Properties ### 80 81The kernel board support package (BSP) may export board configuration 82properties via SysFS that are used by the Android InputReader component, 83such as the placement of virtual keys on a touch screen. 84 85Refer to the device class sections for details about how different 86devices use board configuration properties. 87 88### Resource Overlays ### 89 90A few input behaviors are configured by way of resource overlays 91in `config.xml` such as the operation of lid switch. 92 93Here are a few examples: 94 95* `config_lidKeyboardAccessibility`: Specifies the effect of the 96 lid switch on whether the hardware keyboard is accessible or hidden. 97 98* `config_lidNavigationAccessibility`: Specifies the effect of the 99 lid switch on whether the trackpad is accessible or hidden. 100 101* `config_longPressOnPowerBehavior`: Specifies what should happen when 102 the user holds down the power button. 103 104* `config_lidOpenRotation`: Specifies the effect of the lid switch 105 on screen orientation. 106 107Refer to the documentation within `frameworks/base/core/res/res/values/config.xml` 108for details about each configuration option. 109 110### Key Maps ### 111 112Key maps are used by the Android `EventHub` and `InputReader` components 113to configure the mapping from Linux event codes to Android event codes 114for keys, joystick buttons and joystick axes. The mapping may 115be device or language dependent. 116 117Refer to the device class sections for details about how different 118devices use key maps. 119 120### Input Device Configuration Files ### 121 122Input device configuration files are used by the Android `EventHub` and 123`InputReader` components to configure special device characteristics 124such as how touch size information is reported. 125 126Refer to the device class sections for details about how different 127devices use input device configuration maps. 128 129## Understanding HID Usages and Event Codes ## 130 131There are often several different identifiers used to refer to any 132given key on a keyboard, button on a game controller, joystick axis 133or other control. The relationships between these identifiers 134are not always the same: they are dependent on a set of mapping tables, 135some of which are fixed, and some which vary based on characteristics 136of the device, the device driver, the current locale, the system 137configuration, user preferences and other factors. 138 139Physical Scan Code 140: A physical scan code is a device-specific identifier that is associated 141 with each key, button or other control. Because physical scan codes 142 often vary from one device to another, the firmware or device driver 143 is responsible for mapping them to standard identifiers such as 144 HID Usages or Linux key codes. 145 146 Scan codes are mainly of interest for keyboards. Other devices 147 typically communicate at a low-level using GPIO pins, I2C messages 148 or other means. Consequently, the upper layers of the software 149 stack rely on the device drivers to make sense of what is going on. 150 151HID Usage 152: A HID usage is a standard identifier that is used to report the 153 state of a control such as a keyboard key, joystick axis, 154 mouse button, or touch contact point. Most USB and Bluetooth 155 input devices conform to the HID specification, which enables 156 the system to interface with them in a uniform manner. 157 158 The Android Framework relies on the Linux kernel HID drivers to 159 translate HID usage codes into Linux key codes and other identifiers. 160 Therefore HID usages are mainly of interest to peripheral manufacturers. 161 162Linux Key Code 163: A Linux key code is a standard identifier for a key or button. 164 Linux key codes are defined in the `linux/input.h` header file using 165 constants that begin with the prefix `KEY_` or `BTN_`. The Linux 166 kernel input drivers are responsible for translating physical 167 scan codes, HID usages and other device-specific signals into Linux 168 key codes and delivering information about them as part of 169 `EV_KEY` events. 170 171 The Android API sometimes refers to the Linux key code associated 172 with a key as its "scan code". This is technically incorrect in 173 but it helps to distinguish Linux key codes from Android key codes 174 in the API. 175 176Linux Relative or Absolute Axis Code 177: A Linux relative or absolute axis code is a standard identifier 178 for reporting relative movements or absolute positions along an 179 axis, such as the relative movements of a mouse along its X axis 180 or the absolute position of a joystick along its X axis. 181 Linux axis code are defined in the `linux/input.h` header file using 182 constants that begin with the prefix `REL_` or `ABS_`. The Linux 183 kernel input drivers are responsible for translating HID usages 184 and other device-specific signals into Linux axis codes and 185 delivering information about them as part of `EV_REL` and 186 `EV_ABS` events. 187 188Linux Switch Code 189: A Linux switch code is a standard identifier for reporting the 190 state of a switch on a device, such as a lid switch. Linux 191 switch codes are defined in the `linux/input.h` header file 192 using constants that begin with the prefix `SW_`. The Linux 193 kernel input drivers report switch state changes as `EV_SW` events. 194 195 Android applications generally do not receive events from switches, 196 but the system may use them interally to control various 197 device-specific functions. 198 199Android Key Code 200: An Android key code is a standard identifier defined in the Android 201 API for indicating a particular key such as 'HOME'. Android key codes 202 are defined by the `android.view.KeyEvent` class as constants that 203 begin with the prefix `KEYCODE_`. 204 205 The key layout specifies how Linux key codes are mapped to Android 206 key codes. Different key layouts may be used depending on the keyboard 207 model, language, country, layout, or special functions. 208 209 Combinations of Android key codes are transformed into character codes 210 using a device and locale specific key character map. For example, 211 when the keys identified as `KEYCODE_SHIFT` and `KEYCODE_A` are both 212 pressed together, the system looks up the combination in the key 213 character map and finds the capital letter 'A', which is then inserted 214 into the currently focused text widget. 215 216Android Axis Code 217: An Android axis code is a standard identifier defined in the Android 218 API for indicating a particular device axis. Android axis codes are 219 defined by the `android.view.MotionEvent` class as constants that 220 begin with the prefix `AXIS_`. 221 222 The key layout specifies how Linux Axis Codes are mapped to Android 223 axis codes. Different key layouts may be used depending on the device 224 model, language, country, layout, or special functions. 225 226Android Meta State 227: An Android meta state is a standard identifier defined in the Android 228 API for indicating which modifier keys are pressed. Android meta states 229 are defined by the `android.view.KeyEvent` class as constants that 230 begin with the prefix `META_`. 231 232 The current meta state is determined by the Android InputReader 233 component which monitors when modifier keys such as `KEYCODE_SHIFT_LEFT` 234 are pressed / released and sets / resets the appropriate meta state flag. 235 236 The relationship between modifier keys and meta states is hardcoded 237 but the key layout can alter how the modifier keys themselves are 238 mapped which in turns affects the meta states. 239 240Android Button State 241: An Android button state is a standard identifier defined in the Android 242 API for indicating which buttons (on a mouse or stylus) are pressed. 243 Android button states are defined by the `android.view.MotionEvent` 244 class as constants that begin with the prefix `BUTTON_`. 245 246 The current button state is determined by the Android InputReader 247 component which monitors when buttons (on a mouse or stylus) are 248 pressed / released and sets / resets appropriate button state flag. 249 250 The relationship between buttons and button states is hardcoded. 251 252## Further Reading ## 253 2541. [Linux input event codes](http://www.kernel.org/doc/Documentation/input/event-codes.txt) 2552. [Linux multi-touch protocol](http://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt) 2563. [Linux input drivers](http://www.kernel.org/doc/Documentation/input/input.txt) 2574. [Linux force feedback](http://www.kernel.org/doc/Documentation/input/ff.txt) 2585. [HID information, including HID usage tables](http://www.usb.org/developers/hidpage) 259 260