Chapter XII - The Android Input Architecture

Experiment: Looking at low-level input events

You can examine input events yourself through the shell. First, look at the files in /dev/input. On the emulator, you should see something like this:

root@generic:/ # ls -l /dev/input
crw-rw---- root     input     13,  64 2013-11-15 18:24 event0
crw-rw---- root     input     13,  63 2013-11-15 18:24 mice
crw-rw---- root     input     13,  32 2013-11-15 18:24 mouse0

Output on a real device will likely be different, as these have many more input channels, mapped to its various sensors; The Samsung S3, for example, has event0 through event13, and no "mouse0". The major and minor numbers, however, should be the same, and the major (13) is associated with the kernel input driver subsystems (as can be verified with grep input /proc/devices).

The system keeps track of all devices quite conveniently in /proc/bus/input/devices:

shell@htc_m8wl:/ $ cat /proc/bus/input/devices 
I: Bus=0000 Vendor=0000 Product=0000 Version=0000
N: Name="h2w headset"
P: Phys=
S: Sysfs=/devices/virtual/input/input6
U: Uniq=
H: Handlers=kbd event6 keychord 
B: PROP=0
B: EV=3
B: KEY=84 10000 138 0 e0800 0 0 0
..

To see the properties and capabilities of a given device, say /dev/input/event0, examine its sysfs entry:

## File sizes are reported as 4k (pagesize) arbitrarily - all virtual anyway
shell@generic:/sys/class/input/event0$ ls -l
-r--r--r-- root  root 4096  2013-11-15 18:24 dev
lrwxrwxrwx root  root       2013-11-15 18:24 device -> ../../input0
drwxr-xr-x root  root       2013-11-15 18:24 power
lrwxrwxrwx root  root       2013-11-15 18:24 subsystem -> ../../../../../class/input
-rw-r--r-- root  root 4096  2013-11-15 18:24 uevent
root@generic:/sys/class/input/event0 # cat uevent
MAJOR=13
MINOR=64
DEVNAME=input/event0

By accessing the device nodes, you can treat the input sources as files, and by using a command such as "cat" on them, dump raw events directly to standard output, though those would be appear to be nothing more than synchronized garbage. A better way would be to use the getevent command, which is part of toolbox. The source for this tool is at system/core/toolbox/getevent.c.

When used as getevent, toolbox invokes getevent_main(), which uses Linux's inotify to enumerate the files in /dev/input/event. It then opens each detected device, and uses the ioctls from the previous table to obtain the device information. Finally, it adds the device to an array of file descriptors which it polls continuously. As each device (event source) signals input, getevent reads the event records and dumps it to stdout.

getevent has several particularly useful switches:

• -i: Show HID codes and other information
• -l: Show numbers in human readable constant form (e.g. "0001" as KEY_ESC)
• -p: Show device capabilities (as per sysfs capabilities file) and exit
• -t: Show timestamps
• -h: Show help on all switches (-n, -t, -s, -S, -v, -d, -p, -i, -l, -q, -c and -r) then exit

Experiment: Looking at low-level input events (cont.)

Armed with this information, you can conduct this simple experiment: Make sure your display isn't sleeping, then run getevent -l via adb on your device (or emulator), and then touch the screen. On the emulator, you should see output similar to the following:

shell@generic:/$ getevent -l
could not get driver version for /dev/input/mouse0, Not a typewriter
add device 1: /dev/input/event0
  name:     "qwerty2"
could not get driver version for /dev/input/mice, Not a typewriter
/dev/input/event0: EV_ABS  ABS_X                00000083 # X position of touch
/dev/input/event0: EV_ABS  ABS_Y                00000129 # Y position of touch
/dev/input/event0: EV_KEY  BTN_TOUCH            DOWN     # Touch start       
/dev/input/event0: EV_SYN  SYN_REPORT           00000000 # Event "terminator"
/dev/input/event0: EV_KEY  BTN_TOUCH            UP       # Touch end
/dev/input/event0: EV_SYN  SYN_REPORT           00000000 # Event "terminator" 

On a real device (for example, the Samsung S3) you'll see much more output, owing to the myriad input sources it has. The msm8960 sensors, for example, are what enables headphone vendors to control music playing and call answering through the headphone jack.

shell@s3:/$ getevent -l
## getevent will display all enumerated devices:
add device 1: /dev/input/event6   name:     "sec_touchscreen"
add device 2: /dev/input/event8   name:     "barometer_sensor"
add device 3: /dev/input/event4   name:     "sec_jack"
add device 4: /dev/input/event3   name:     "light_sensor"
add device 5: /dev/input/event2   name:     "proximity_sensor"
add device 6: /dev/input/event0   name:     "sii9234_rcp"
add device 7: /dev/input/event12  name:     "msm8960-snd-card Headset Jack"
add device 8: /dev/input/event11  name:     "msm8960-snd-card Button Jack"
add device 9: /dev/input/event10  name:     "msm8960-snd-card Volumeup Jack"
add device 10: /dev/input/event9  name:     "msm8960-snd-card Volumedown Jack"
add device 11: /dev/input/event13 name:     "sec_touchkey"
add device 12: /dev/input/event1  name:     "fsa9485"       
add device 13: /dev/input/event5  name:     "sec_keys"         # physical keys
add device 14: /dev/input/event7  name:     "sec_powerkey"     # power button - KEY_POWER
# These are sent regularly from the light sensor, as it's highly sensitive
/dev/input/event3: EV_REL  REL_X                00000020            
/dev/input/event3: EV_REL  REL_Y                00000021            
/dev/input/event3: EV_REL  REL_Z                00000015            
/dev/input/event3: EV_REL  REL_MISC             00000024            
/dev/input/event3: EV_SYN  SYN_REPORT           00000000            
## Touch event: Notice ABS_MT is used here, rather than BTN_TOUCH
/dev/input/event6: EV_ABS  ABS_MT_TRACKING_ID   00000043 # unique ID for this touch           
/dev/input/event6: EV_ABS  ABS_MT_WIDTH_MAJOR   0000000a # major axis of approaching ellipse           
/dev/input/event6: EV_ABS  ABS_MT_POSITION_X    0000011f # center x touch position          
/dev/input/event6: EV_ABS  ABS_MT_POSITION_Y    0000022d # center y touch position
/dev/input/event6: EV_ABS  ABS_MT_TOUCH_MAJOR   00000010 # major axis of touch ellipse
/dev/input/event6: EV_ABS  ABS_MT_TOUCH_MINOR   0000000c # minor axis of touch ellipse
/dev/input/event6: EV_ABS  ABS_MT_TOOL_X        ffffffc4 # center y tool position
## Physical buttons: HOME and VOLUMEDOWN together (notice /dev/input/event5)
/dev/input/event5: EV_KEY  KEY_VOLUMEDOWN       DOWN         
/dev/input/event5: EV_SYN  SYN_REPORT           00000000       
/dev/input/event5: EV_KEY  KEY_HOMEPAGE         DOWN                
/dev/input/event5: EV_SYN  SYN_REPORT           00000000       
/dev/input/event5: EV_KEY  KEY_VOLUMEDOWN       UP         
/dev/input/event5: EV_SYN  SYN_REPORT           00000000       
/dev/input/event5: EV_KEY  KEY_HOMEPAGE         UP
/dev/input/event5: EV_SYN  SYN_REPORT           00000000