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 19 The Android input subsystem nominally consists of an event pipeline 20 that traverses multiple layers of the system. 21 22 ## Input Pipeline ## 23 24 At the lowest layer, the physical input device produces signals that 25 describe state changes such as key presses and touch contact points. 26 The device firmware encodes and transmits these signals in some way 27 such as by sending USB HID reports to the system or by producing 28 interrupts on an I2C bus. 29 30 The signals are then decoded by a device driver in the Linux kernel. 31 The Linux kernel provides drivers for many standard peripherals, 32 particularly those that adhere to the HID protocol. However, an OEM 33 must often provide custom drivers for embedded devices that are 34 tightly integrated into the system at a low-level, such as touch screens. 35 36 The input device drivers are responsible for translating device-specific 37 signals into a standard input event format, by way of the Linux 38 input protocol. The Linux input protocol defines a standard set of 39 event types and codes in the `linux/input.h` kernel header file. 40 In this way, components outside the kernel do not need to care about 41 the details such as physical scan codes, HID usages, I2C messages, 42 GPIO pins, and the like. 43 44 Next, the Android `EventHub` component reads input events from the kernel 45 by opening the `evdev` driver associated with each input device. 46 The Android InputReader component then decodes the input events 47 according to the device class and produces a stream of Android input 48 events. As part of this process, the Linux input protocol event codes 49 are translated into Android event codes according to the 50 input device configuration, keyboard layout files, and various 51 mapping tables. 52 53 Finally, the `InputReader` sends input events to the InputDispatcher 54 which forwards them to the appropriate window. 55 56 ## Control Points ## 57 58 There are several stages in the input pipeline which effect control 59 over the behavior of the input device. 60 61 ### Driver and Firmware Configuration ### 62 63 Input device drivers frequently configure the behavior of the input 64 device by setting parameters in registers or even uploading the 65 firmware itself. This is particularly the case for embedded 66 devices such as touch screens where a large part of the calibration 67 process involves tuning these parameters or fixing the firmware 68 to provide the desired accuracy and responsiveness and to suppress 69 noise. 70 71 Driver configuration options are often specified as module parameters 72 in the kernel board support package (BSP) so that the same driver 73 can support multiple different hardware implementations. 74 75 This documentation does attempt to describe driver or firmware 76 configuration, but it does offer guidance as to device calibration 77 in general. 78 79 ### Board Configuration Properties ### 80 81 The kernel board support package (BSP) may export board configuration 82 properties via SysFS that are used by the Android InputReader component, 83 such as the placement of virtual keys on a touch screen. 84 85 Refer to the device class sections for details about how different 86 devices use board configuration properties. 87 88 ### Resource Overlays ### 89 90 A few input behaviors are configured by way of resource overlays 91 in `config.xml` such as the operation of lid switch. 92 93 Here 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 107 Refer to the documentation within `frameworks/base/core/res/res/values/config.xml` 108 for details about each configuration option. 109 110 ### Key Maps ### 111 112 Key maps are used by the Android `EventHub` and `InputReader` components 113 to configure the mapping from Linux event codes to Android event codes 114 for keys, joystick buttons and joystick axes. The mapping may 115 be device or language dependent. 116 117 Refer to the device class sections for details about how different 118 devices use key maps. 119 120 ### Input Device Configuration Files ### 121 122 Input device configuration files are used by the Android `EventHub` and 123 `InputReader` components to configure special device characteristics 124 such as how touch size information is reported. 125 126 Refer to the device class sections for details about how different 127 devices use input device configuration maps. 128 129 ## Understanding HID Usages and Event Codes ## 130 131 There are often several different identifiers used to refer to any 132 given key on a keyboard, button on a game controller, joystick axis 133 or other control. The relationships between these identifiers 134 are not always the same: they are dependent on a set of mapping tables, 135 some of which are fixed, and some which vary based on characteristics 136 of the device, the device driver, the current locale, the system 137 configuration, user preferences and other factors. 138 139 Physical 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 151 HID 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 162 Linux 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 176 Linux 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 188 Linux 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 199 Android 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 216 Android 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 226 Android 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 240 Android 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 254 1. [Linux input event codes](http://www.kernel.org/doc/Documentation/input/event-codes.txt) 255 2. [Linux multi-touch protocol](http://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt) 256 3. [Linux input drivers](http://www.kernel.org/doc/Documentation/input/input.txt) 257 4. [Linux force feedback](http://www.kernel.org/doc/Documentation/input/ff.txt) 258 5. [HID information, including HID usage tables](http://www.usb.org/developers/hidpage) 259 260
