Merge remote-tracking branch 'goog/ics-aah'
diff --git a/scripts/build.py b/scripts/build.py
index 8188f51..12bcb98 100755
--- a/scripts/build.py
+++ b/scripts/build.py
@@ -1,5 +1,19 @@
#!/usr/bin/env python
+# Copyright (C) 2011 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
import os
import glob
import shutil
@@ -9,7 +23,7 @@
# call markdown as a subprocess, and capture the output
def markdown(raw_file):
- extensions = '-x tables' + ' ' + '-x "toc(title=In This Document)"'
+ extensions = '-x tables -x "toc(title=In This Document)" -x def_list'
command = 'markdown' + ' ' + extensions + ' ' + raw_file
p = subprocess.Popen(command, stdout = subprocess.PIPE, shell = True)
return p.communicate()[0]
@@ -20,7 +34,7 @@
for line in open(raw_file, 'r'):
if '#' in line:
return line.strip(' #\n')
- return ""
+ return ''
# directory to compile the site to (will be clobbered during build!)
@@ -31,36 +45,45 @@
TEMPLATE_DIR = 'templates'
# filenames of templates to load, in order
-TEMPLATE_LIST = ['includes', 'header', 'sidebar', 'main', 'footer']
+TEMPLATE_LIST = ['includes', 'header', 'sidebar', 'main', 'footer']
-t = ""
+# Step 1, concatenate the template pieces into a single template string
+t = ''
for f in TEMPLATE_LIST:
t += open(os.path.join(TEMPLATE_DIR, f), 'r').read()
template = string.Template(t)
+# Step 2, rm -rf HTML_DIR if it exists, and then re-create it
if os.path.exists(HTML_DIR):
shutil.rmtree(HTML_DIR)
os.mkdir(HTML_DIR)
+# Step 3, recursively mirror SRC_DIR to HTML_DIR, directory by directory, translating *.md
category = 'home'
parents = {}
for curdir, subdirs, files in os.walk(SRC_DIR):
print 'Processing %s...' % (curdir,),
- outdir = [x for x in curdir.split(os.path.sep) if x]
+ # Step A: split path, and update cached category name if needed
+ curdir = os.path.normpath(curdir)
+ outdir = curdir.split(os.path.sep)
outdir[0] = HTML_DIR
if len(outdir) == 2:
category = outdir[-1]
outdir = os.path.join(*outdir)
+ # Step B: mirror the hierarchy of immediate subdirectories
for subdir in subdirs:
os.mkdir(os.path.join(outdir, subdir))
+ # Step C: cache the translated sidebars, keyed by parent dir, so we can do sidebar inheritance
+ # FIXME: make this depth-agnostic, perhaps by caching all sidebars and moving the resolution
+ # FIXME: complexity out of the datastructure and into the resolution algorithm.
parentdir = os.path.dirname(curdir)
if parentdir in parents:
parent = parents[parentdir]
else:
- parent = ('', '')
+ parent = ('', '', '')
if 'sidebar.md' in files:
sidebar = markdown(os.path.join(curdir, 'sidebar.md'))
@@ -74,19 +97,30 @@
else:
sidebar2 = parent[1]
- parents[curdir] = (sidebar, sidebar2)
+ if 'sidebar3.md' in files:
+ sidebar3 = markdown(os.path.join(curdir, 'sidebar3.md'))
+ del files[files.index('sidebar3.md')]
+ else:
+ sidebar3 = parent[2]
+ parents[curdir] = (sidebar, sidebar2, sidebar3)
+
+ # Step D: mirror all non-*.md files, and translate (file).md files into (file).html
for f in files:
print ' .',
+ # Note that this "absolute" filename has a root at SRC_DIR, not "/"
+ absfilename = os.path.join(curdir, f)
+
if f.endswith('.md'):
- main = markdown(os.path.join(curdir, f))
+ main = markdown(absfilename)
final = template.safe_substitute(main=main, sidebar=sidebar, sidebar2=sidebar2, \
- category=category, title=get_title(os.path.join(curdir, f)))
-
+ sidebar3=sidebar3, category=category, title=get_title(absfilename))
+
html = file(os.path.join(outdir, f.replace('.md', '.html')), 'w')
html.write(final)
else:
- shutil.copy(os.path.join(curdir, f), os.path.join(outdir, f))
+ shutil.copy(absfilename, os.path.join(outdir, f))
print
print 'Done.'
+
diff --git a/scripts/micro-httpd.py b/scripts/micro-httpd.py
index 13e35a7..1cffa08 100755
--- a/scripts/micro-httpd.py
+++ b/scripts/micro-httpd.py
@@ -1,4 +1,4 @@
-#!/usr/bin/env python2.4
+#!/usr/bin/env python
# Copyright (C) 2010 The Android Open Source Project
#
@@ -14,9 +14,16 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-import SimpleHTTPServer, SocketServer, os
+import SimpleHTTPServer
+import SocketServer
+import os
+
+
+outdir = os.path.join(os.path.dirname(__file__), '..', 'out')
+os.chdir(outdir)
PORT = int(os.environ.get('HTTP_PORT', 8080))
Handler = SimpleHTTPServer.SimpleHTTPRequestHandler
-httpd = SocketServer.TCPServer(("0.0.0.0", PORT), Handler)
-print "Serving on port %d" % PORT
+httpd = SocketServer.TCPServer(('0.0.0.0', PORT), Handler)
+httpd.allow_reuse_address = True
+print 'Serving on port %d' % PORT
httpd.serve_forever()
diff --git a/src/assets/main.css b/src/assets/main.css
index 59f2dd1..18662a1 100644
--- a/src/assets/main.css
+++ b/src/assets/main.css
@@ -241,6 +241,15 @@
padding: 1em;
}
+dt {
+ color: #1f2a33;
+ font-size: 110%;
+}
+
+dd {
+ margin: 1em 1em 1em 1em;
+}
+
/* TABLE OF CONTENTS */
.toc {
diff --git a/src/compatibility/4.0/android-4.0-cdd.pdf b/src/compatibility/4.0/android-4.0-cdd.pdf
new file mode 100755
index 0000000..f6c06a5
--- /dev/null
+++ b/src/compatibility/4.0/android-4.0-cdd.pdf
Binary files differ
diff --git a/src/compatibility/4.0/versions.md b/src/compatibility/4.0/versions.md
new file mode 100644
index 0000000..1b70297
--- /dev/null
+++ b/src/compatibility/4.0/versions.md
@@ -0,0 +1,36 @@
+<!--
+ Copyright 2010 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Permitted Version Strings for Android 4.0 #
+
+As described in Section 3.2.2 of the [Android 4.0 Compatibility Definition](/cdds/android-4.0-cdd.pdf),
+only certain strings are allowable for the system property
+`android.os.Build.VERSION.RELEASE`. The reason for this is that
+applications and web sites may rely on predictable values for this string, and
+so that end users can easily and reliably identify the version of Android
+running on their devices.
+
+Because subsequent releases of the Android software may revise this string,
+but not change any API behavior, such releases may not be accompanied by a new
+Compatibility Definition Document. This page lists the versions that are
+allowable by an Android 4.0-based system. The only permitted values for
+`android.os.Build.VERSION.RELEASE` for Android 4.0 are:
+
+- 4.0
+
+- 4.0.1
+
+- 4.0.3
diff --git a/src/compatibility/android-4.0-cdd.pdf b/src/compatibility/android-4.0-cdd.pdf
new file mode 100644
index 0000000..f6c06a5
--- /dev/null
+++ b/src/compatibility/android-4.0-cdd.pdf
Binary files differ
diff --git a/src/compatibility/android-cts-manual-r4.pdf b/src/compatibility/android-cts-manual-r4.pdf
index f16b6f9..a5861ac 100644
--- a/src/compatibility/android-cts-manual-r4.pdf
+++ b/src/compatibility/android-cts-manual-r4.pdf
Binary files differ
diff --git a/src/compatibility/contact-us.md b/src/compatibility/contact-us.md
index 486677d..b7fa837 100644
--- a/src/compatibility/contact-us.md
+++ b/src/compatibility/contact-us.md
@@ -35,7 +35,7 @@
cases that require disclosure of confidential information only, so general
questions will be directed back to the public android-compatibility
list. Note also that this list is for specific technical questions; general
-inquiries will also be directed back to the android-compatibility list.
+inquiries will also be directed back to the [android-compatibility list.](http://groups.google.com/group/android-compatibility)
## For Business Inquiries ##
diff --git a/src/compatibility/cts-development.md b/src/compatibility/cts-development.md
index fda1dca..04adb00 100644
--- a/src/compatibility/cts-development.md
+++ b/src/compatibility/cts-development.md
@@ -19,7 +19,7 @@
## Initializing Your Repo Client ##
Follow the [instructions](/source/downloading.html)
-to get and build the Android source code but specify `-b gingerbread`
+to get and build the Android source code but specify `-b android-4.0.3_r1`
when issuing the `repo init` command. This assures that your CTS
changes will be included in the next CTS release and beyond.
diff --git a/src/compatibility/cts-intro.md b/src/compatibility/cts-intro.md
index c9550df..0f62b84 100644
--- a/src/compatibility/cts-intro.md
+++ b/src/compatibility/cts-intro.md
@@ -32,7 +32,7 @@
## Workflow ##
-1. [Download](downloads.html) the CTS.
+1. [Download](downloads.html) the CTS and CTS media files.
1. Attach at least one device (or emulator) to your machine.
@@ -48,6 +48,12 @@
2. On the device, enable all the android.deviceadmin.cts.* device administrators under Settings > Location & security > Select device administrators
+1. For CTS 2.3 R12 and beyond, the CTS media files must be copied to the device's external storage. Check section 4.2 of the latest CTS manual for further details on copying these files:
+
+ 2. Unzip the CTS Media zip file.
+
+ 2. Run copy_media.sh [720x480|1280x720|1920x1080|all] [-s serial]. If no resolution is specified, the default maximum resolution of 480x360 is assumed.
+
1. Launch the CTS. The CTS test harness loads the test plan onto the attached devices. For each test in the test harness:
- The test harness pushes a .apk file to each device, executes the test through instrumentation, and records test results.
diff --git a/src/compatibility/downloads.md b/src/compatibility/downloads.md
index 3c0225b..045dbcd 100644
--- a/src/compatibility/downloads.md
+++ b/src/compatibility/downloads.md
@@ -19,14 +19,24 @@
Thanks for your interest in Android Compatibility! The links below allow
you to access the key documents and information.
+## Android 4.0.3 ##
+
+Android 4.0.3 is the release of the development milestone code-named
+Ice Cream Sandwich. Android 4.0.3 is the current version of Android. Source code for
+Android 4.0.3 is found in the 'android-4.0.3_r1' branch in the open-source tree.
+
+- [Android 4.0 Compatibility Definition Document (CDD)](4.0/android-4.0-cdd.pdf)
+- [Android 4.0.3 R2 Compatibility Test Suite (CTS)](http://dl.google.com/dl/android/cts/android-cts-4.0.3_r2-linux_x86-arm.zip)
+- [Android 4.0.3 R1 CTS Verifier](http://dl.google.com/dl/android/cts/android-cts-verifier-4.0.3_r1-linux_x86-arm.zip)
+
## Android 2.3 ##
Android 2.3 is the release of the development milestone code-named
-Gingerbread. Android 2.3 is the current version of Android. Source code for
-Android 2.3 is found in the 'gingerbread' branch in the open-source tree.
+Gingerbread. Source code for Android 2.3 is found in the 'gingerbread' branch in
+the open-source tree.
- [Android 2.3 Compatibility Definition Document (CDD)](2.3/android-2.3.3-cdd.pdf)
-- [Android 2.3 R9 Compatibility Test Suite (CTS)](http://dl.google.com/dl/android/cts/android-cts-2.3_r9-linux_x86-armv5.zip)
+- [Android 2.3 R12 Compatibility Test Suite (CTS)](http://dl.google.com/dl/android/cts/android-cts-2.3_r12-linux_x86-arm.zip)
- [Android 2.3 R2 CTS Verifier](http://dl.google.com/dl/android/cts/android-cts-verifier-2.3_r2-linux_x86-armv5.zip)
## Android 2.2 ##
@@ -36,7 +46,7 @@
open-source tree.
- [Android 2.2 Compatibility Definition Document (CDD)](2.2/android-2.2-cdd.pdf)
-- [Android 2.2 R7 Compatibility Test Suite (CTS)](http://dl.google.com/dl/android/cts/android-cts-2.2_r7-x86.zip)
+- [Android 2.2 R8 Compatibility Test Suite (CTS)](http://dl.google.com/dl/android/cts/android-cts-2.2_r8-linux_x86-arm.zip)
## Android 2.1 ##
@@ -64,6 +74,11 @@
- [Compatibility Test Suite (CTS) User Manual](android-cts-manual-r4.pdf)
+## CTS Media Files ##
+These media files are required for the CTS media stress tests.
+
+- [CTS Media 1.0](http://dl.google.com/dl/android/cts/android-cts-media-1.0.zip)
+
## Older Android Versions ##
There is no Compatibility Program for older versions of Android, such as Android
diff --git a/src/compatibility/index.md b/src/compatibility/index.md
index 67ba133..da38918 100644
--- a/src/compatibility/index.md
+++ b/src/compatibility/index.md
@@ -28,9 +28,7 @@
them.
These pages describe the Android Compatibility Program and how to get
-access to compatibility information and tools. The latest version of the
-Android source code and compatibility program is 2.3, which
-corresponded to the Gingerbread branch.
+access to compatibility information and tools.
## Why build compatible Android devices? ##
diff --git a/src/compatibility/overview.md b/src/compatibility/overview.md
index 7d4eb27..19e4a94 100644
--- a/src/compatibility/overview.md
+++ b/src/compatibility/overview.md
@@ -102,7 +102,7 @@
If you want to build a device compatible with a given Android version,
start by checking out the source code for that version, and then read the
corresponding CDD and stay within its guidelines. For additional details,
-simply examine [the latest CDD](2.3/android-2.3.3-cdd.pdf).
+simply examine [the latest CDD](4.0/android-4.0-cdd.pdf).
# Compatibility Test Suite (CTS) #
diff --git a/src/compatibility/sidebar.md b/src/compatibility/sidebar.md
index abefb40..3b96786 100644
--- a/src/compatibility/sidebar.md
+++ b/src/compatibility/sidebar.md
@@ -1,6 +1,6 @@
# Getting Started #
- [Compatibility Overview](/compatibility/overview.html)
-- [Current CDD](/compatibility/2.3/android-2.3.3-cdd.pdf)
+- [Current CDD](/compatibility/4.0/android-4.0-cdd.pdf)
- [CTS Introduction](/compatibility/cts-intro.html)
- [CTS Development](/compatibility/cts-development.html)
diff --git a/src/index.md b/src/index.md
index 5963be7..54319bf 100644
--- a/src/index.md
+++ b/src/index.md
@@ -20,6 +20,14 @@
## News ##
+### Source Code Available for Android 4.0 ###
+
+The source code for the Android 4.0 platform and software stack has been
+released! This release allows OEMs to begin preparing Android 4.0 for
+installation on new and existing devices, and allows hobbyists, enthusiasts,
+and researchers to develop custom builds. For information on how to obtain the
+software, visit our [Getting the Source](source/downloading.html) page.
+
### Compatibility Definition for Android 2.3 ###
The Compatibility Definition Document for Android 2.3.3 has been published.
@@ -29,14 +37,6 @@
Communications support to the Android APIs. For more information, visit the
[Compatibility](compatibility/index.html) page.
-### Source Code Available for Android 2.3 ###
-
-The source code for the Android 2.3 platform and software stack has been
-released! This release allows OEMs to begin preparing Android 2.3 for
-installation on new and existing devices, and allows hobbyists, enthusiasts,
-and researchers to develop custom builds. For information on how to obtain the
-software, visit our [Getting the Source](source/downloading.html) page.
-
</div>
<img style="float: right; padding-right: 1.5em;" src="images/home-bugdroid.png" alt="Android Mascot"/>
diff --git a/src/source/build-numbers.md b/src/source/build-numbers.md
index 8d1dd3b..1e782b7 100644
--- a/src/source/build-numbers.md
+++ b/src/source/build-numbers.md
@@ -25,21 +25,23 @@
The code names match the following version numbers, along with
API levels and NDK releases provided for convenience:
-Code name | Version | API level
----------------|--------------|------------
-(no code name) | 1.0 | API level 1
-(no code name) | 1.1 | API level 2
-Cupcake | 1.5 | API level 3, NDK 1
-Donut | 1.6 | API level 4, NDK 2
-Eclair | 2.0 | API level 5
-Eclair | 2.0.1 | API level 6
-Eclair | 2.1 (incl. 2.1-update 1) | API level 7, NDK 3
-Froyo | 2.2.x | API level 8, NDK 4
-Gingerbread | 2.3 - 2.3.2 | API level 9, NDK 5
-Gingerbread | 2.3.3 - 2.3.7 | API level 10
-Honeycomb | 3.0 | API level 11
-Honeycomb | 3.1 | API level 12
-Honeycomb | 3.2 - 3.2.2 | API level 13
+Code name | Version | API level
+-----------------|---------------|--------------------
+(no code name) | 1.0 | API level 1
+(no code name) | 1.1 | API level 2
+Cupcake | 1.5 | API level 3, NDK 1
+Donut | 1.6 | API level 4, NDK 2
+Eclair | 2.0 | API level 5
+Eclair | 2.0.1 | API level 6
+Eclair | 2.1 | API level 7, NDK 3
+Froyo | 2.2.x | API level 8, NDK 4
+Gingerbread | 2.3 - 2.3.2 | API level 9, NDK 5
+Gingerbread | 2.3.3 - 2.3.7 | API level 10
+Honeycomb | 3.0 | API level 11
+Honeycomb | 3.1 | API level 12, NDK 6
+Honeycomb | 3.2.x | API level 13
+IceCreamSandwich | 4.0.1 - 4.0.2 | API level 14, NDK 7
+IceCreamSandwich | 4.0.3 - 4.0.4 | API level 15
Starting with Cupcake, individual builds are identified with a short
build code, e.g. FRF85B.
@@ -88,7 +90,9 @@
FRG22D | android-2.2_r1.3
FRG83 | android-2.2.1_r1 | Nexus One
FRG83D | android-2.2.1_r2 | Nexus One
-FRG83G | android-2.2.2_r1 | latest Froyo version, Nexus One
+FRG83G | android-2.2.2_r1 | Nexus One
+FRK76 | android-2.2.3_r1
+FRK76C | android-2.2.3_r2 | latest Froyo version
GRH55 | android-2.3_r1 | earliest Gingerbread version, Nexus S
GRH78 | android-2.3.1_r1 | Nexus S
GRH78C | android-2.3.2_r1 | Nexus S
@@ -100,8 +104,16 @@
GRK39C | android-2.3.6_r0.9 | Nexus S
GRK39F | android-2.3.6_r1 | Nexus One, Nexus S
GWK74 | android-2.3.7_r1 | latest Gingerbread version, Nexus S 4G
+ITL41D | android-4.0.1_r1 | earliest IceCreamSandwich version, Galaxy Nexus
+ITL41D | android-4.0.1_r1.1 | Galaxy Nexus
+ITL41F | android-4.0.1_r1.2 | Galaxy Nexus
+ICL53F | android-4.0.2_r1 | Galaxy Nexus
+IML74K | android-4.0.3_r1 | Nexus S
+IML77 | android-4.0.3_r1.1 |
+IMM76 | android-4.0.4_r1 |
+IMM76D | android-4.0.4_r1.1 | Nexus S, latest IceCreamSandwich version
-The branches donut, eclair, froyo, gingerbread represent development
+The branches froyo, gingerbread, ics-mr0, ics-mr1, represent development
branches that do not exactly match configurations that were tested
by Google. They might contain a variety of changes in addition to
the official tagged releases, and those haven't been as thoroughly
@@ -124,7 +136,8 @@
HTK55D | android-3.2.1_r1
HTK75D | android-3.2.1_r2
HLK75C | android-3.2.2_r1
-HLK75D | android-3.2.2_r2 | latest Honeycomb version
+HLK75D | android-3.2.2_r2
+HLK75F | android-3.2.4_r1 | latest Honeycomb version
There is no manifest that contains exactly those. However, there
are manifests that allow building those components. The following
diff --git a/src/source/building-devices.md b/src/source/building-devices.md
index 62023d2..5183b63 100644
--- a/src/source/building-devices.md
+++ b/src/source/building-devices.md
@@ -16,15 +16,34 @@
# Building for devices #
-This page complements the main page about [Building](building.html) with information
-that is specific to individual devices.
+This page complements the main page about [Building](building.html) with
+information that is specific to individual devices.
-The only supported devices are Nexus S, a.k.a. "crespo", and Nexus S 4G, a.k.a.
-"crespo4g".
-Nexus S is the recommended device to use with the Android Open-Source Project.
-Nexus One a.k.a. "passion" is experimental and unsupported. Android Developer
-Phones (ADP1 and ADP2, a.k.a. "dream" and "sapphire") are obsolete, were
-experimental and unsupported in froyo, and can't be used with gingerbread.
+The supported devices with the current release are the Galaxy Nexus, Motorola
+Xoom, and Nexus S.
+
+Galaxy Nexus is supported only in GSM/HSPA+ configuration "maguro" and only
+if it was originally sold with a "yakju" operating system.
+
+The Motorola Xoom is supported in the Wi-fi configuration "wingray"
+sold in the USA.
+
+Nexus S is supported in the GSM configuration "crespo".
+
+In addition, [PandaBoard](http://pandaboard.org) a.k.a. "panda" is supported
+in the master branch only, but is currently considered experimental.
+The specific details to use a PandaBoard with the Android Open-Source Project
+are in the file `device/ti/panda/README` in the source tree.
+
+Nexus One a.k.a. "passion" is obsolete, was experimental in gingerbread and
+unsupported, and can't be used with newer versions of the Android Open-Source
+Project.
+
+Android Developer Phones (ADP1 and ADP2, a.k.a. "dream" and "sapphire") are
+obsolete, were experimental and unsupported in froyo, and can't be used with
+newer versions of the Android Open-Source Project.
+
+No CDMA devices are supported in the Android Open-Source Project.
## Building fastboot and adb ##
@@ -41,8 +60,10 @@
Device | Keys
---------|------
+maguro | Press and hold both *Volume Up* and *Volume Down*, then press and hold *Power*
+panda | Press and hold *Input*, then press *Power*
+wingray | Press and hold *Volume Down*, then press and hold *Power*
crespo | Press and hold *Volume Up*, then press and hold *Power*
-crespo4g | Press and hold *Volume Up*, then press and hold *Power*
passion | Press and hold the trackball, then press *Power*
sapphire | Press and hold *Back*, then press *Power*
dream | Press and hold *Back*, then press *Power*
@@ -57,27 +78,38 @@
This is the default setup on ADP1 and ADP2.
-On Nexus One, Nexus S, and Nexus S 4G, the bootloader is locked by default.
-With the device in fastboot mode, the bootloader is unlocked with
+On Nexus One, Nexus S, Xoom, and Galaxy Nexus,
+the bootloader is locked by default. With the device in fastboot mode, the
+bootloader is unlocked with
$ fastboot oem unlock
The procedure must be confirmed on-screen, and deletes the user data for
privacy reasons. It only needs to be run once.
+Note that on the Nexus S, Motorola Xoom and on Galaxy Nexus,
+all data on the phone is erased, i.e. both the applications' private data
+and the shared data that is accessible over USB, including photos and
+movies. Be sure to make a backup of any precious files you have before
+unlocking the bootloader.
+
On Nexus One, the operation voids the warranty and is irreversible.
-On Nexus S and Nexus S 4G, the bootloader can be locked back with
+On Nexus S, Xoom, and Galaxy Nexus,
+the bootloader can be locked back with
$ fastboot oem lock
+Note that this erases user data on Xoom (including the shared USB data).
+
## Obtaining proprietary binaries ##
-While it's possible to build and run a system using exclusively source code
-from Android Open-Source Project, such a system can only use the devices'
-hardware capabilities for which Open-Source support exists.
+Starting with IceCreamSandwich, the Android Open-Source Project can't be used
+from pure source code only, and requires additional hardware-related proprietary
+libraries to run, specifically for hardware graphics acceleration.
-Official binaries for Nexus S and Nexus S 4G can be downloaded from
+Official binaries for Nexus S, Galaxy Nexus, and PandaBoard can be
+downloaded from
[Google's Nexus driver page](http://code.google.com/android/nexus/drivers.html),
which add access to additional hardware capabilities with non-Open-Source code.
@@ -85,20 +117,12 @@
### Extracting the proprietary binaries ###
-Each driver comes as a self-extracting script in a compressed archive.
+Each set of binaries comes as a self-extracting script in a compressed archive.
After uncompressing each archive, run the included self-extracting script
from the root of the source tree, confirm that you agree to the terms of the
enclosed license agreement, and the binaries and their matching makefiles
will get installed in the `vendor/` hierarchy of the source tree.
-There's an additional step on Nexus S 4G. Build the signapk tool with
-
- $ make signapk
-
-Then reassemble the proprietary applicatons with
-
- $ vendor/samsung/crespo4g/reassemble-apks.sh
-
### Cleaning up when adding proprietary binaries ###
In order to make sure that the newly installed binaries are properly
@@ -113,15 +137,17 @@
are described in the page about [Building](building.html).
The recommended builds for the various devices are available through
-the lunch menu, accesed when running the `lunch` command with no arguments:
+the lunch menu, accessed when running the `lunch` command with no arguments:
-Device | Branch | Build configuration
----------|------------------|------------------------
-crespo | android-2.3.5_r1 | full_crespo-userdebug
-crespo4g | android-2.3.5_r1 | full_crespo4g-userdebug
-passion | android-2.3.5_r1 | full_passion-userdebug
-sapphire | android-2.2.2_r1 | full_sapphire-userdebug
-dream | android-2.2.2_r1 | full_dream-userdebug
+Device | Branch | Build configuration
+---------|--------------------|------------------------
+maguro | android-4.0.4_r1.1 | full_maguro-userdebug
+panda | master | full_panda-userdebug
+wingray | android-4.0.4_r1.1 | full_wingray-userdebug
+crespo | android-4.0.4_r1.1 | full_crespo-userdebug
+passion | android-2.3.7_r1 | full_passion-userdebug
+sapphire | android-2.2.3_r1 | full_sapphire-userdebug
+dream | android-2.2.3_r1 | full_dream-userdebug
## Flashing a device ##
@@ -140,16 +166,24 @@
$ fastboot flashall
-On crespo, crespo4g, sapphire and dream (but not on passion), the commands above can
-be replaced with a single command
+On all devices except passion,
+the commands above can be replaced with a single command
$ fastboot -w flashall
-### Nexus S and Nexus S 4G Bootloader and Cell Radio compatibility ###
+Note that filesystems created via fastboot on Motorola Xoom aren't working
+optimally, and it is strongly recommended to re-create them through recovery
-On Nexus S and Nexus S 4G, each version of Android has only been thoroughly
-tested with on specific version of the underlying bootloader and cell radio
-software.
+ $ adb reboot recovery
+
+Once in recovery, open the menu (press Power + Volume Up), wipe the cache
+partition, then wipe data.
+
+### Nexus S and Galaxy Nexus Bootloader and Cell Radio compatibility ###
+
+On Nexus S, and Galaxy Nexus, each version of Android has only
+been thoroughly tested with on specific version of the underlying bootloader
+and cell radio software.
However, no compatibility issues are expected when running newer systems
with older bootloaders and radio images according to the following tables.
@@ -164,6 +198,8 @@
2.3.4 (GRJ22) | I9020XXKA3 | I9020XXKD1 | All previous versions
2.3.5 (GRJ90) | I9020XXKA3 | I9020XXKF1 | All previous versions
2.3.6 (GRK39F) | I9020XXKA3 | I9020XXKF1 | All previous versions
+4.0.3 (IML74K) | I9020XXKL1 | I9020XXKI1 | All previous versions
+4.0.4 (IMM76D) | I9020XXKL1 | I9020XXKI1
Nexus S (850MHz version "UC"):
@@ -174,6 +210,8 @@
2.3.5 (GRJ90) | I9020XXKA3 | I9020UCKF1 | All previous versions
2.3.6 (GRK39C) | I9020XXKA3 | I9020UCKF1 | All previous versions
2.3.6 (GRK39F) | I9020XXKA3 | I9020UCKF1 | All previous versions
+4.0.3 (IML74K) | I9020XXKL1 | I9020UCKF1 | All previous versions
+4.0.4 (IMM76D) | I9020XXKL1 | I9020UCKJ1 | All previous versions
Nexus S (Korea version "KR"):
@@ -183,23 +221,31 @@
2.3.4 (GRJ22) | I9020XXKA3 | M200KRKC1 | All previous versions
2.3.5 (GRJ90) | I9020XXKA3 | M200KRKC1 | All previous versions
2.3.6 (GRK39F) | I9020XXKA3 | M200KRKC1 | All previous versions
+4.0.3 (IML74K) | I9020XXKL1 | M200KRKC1 | All previous versions
+4.0.4 (IMM76D) | I9020XXKL1 | M200KRKC1 | All previous versions
-Nexus S 4G:
+Galaxy Nexus (GSM/HSPA+):
Android Version | Preferred Bootloader | Preferred Radio | Also possible
----------------|----------------------|-----------------|--------------
-2.3.4 (GRJ06D) | D720SPRKC5 | D720SPRKC9
-2.3.4 (GRJ22) | D720SPRKC5 | D720SPRKD8 | All previous versions
-2.3.5 (GRJ90) | D720SPRKC5 | D720SPRKE5 | All previous versions
-2.3.7 (GWK74) | D720SPRKE1 | D720SPRKH1 (*) | All previous versions
+4.0.1 (ITL41D) | PRIMEKJ10 | I9250XXKK1
+4.0.2 (ICL53F) | PRIMEKK15 | I9250XXKK6 | All previous versions
+4.0.3 (IML74K) | PRIMEKL01 | I9250XXKK6 | All previous versions
+4.0.4 (IMM76D) | PRIMEKL03 | I9250XXLA02 | Versions from 4.0.2
-If you're building a new version of Android, if your Nexus S or Nexus S 4G has
+If you're building a new version of Android, if your Nexus S or
+Galaxy Nexus has
an older bootloader and radio image that is marked as being also possible in
the table above but is not recognized by fastboot, you can locally
delete the `version-bootloader` and `version-baseband` lines in
-`device/samsung/crespo/board-info.txt` or `device/samsung/crespo4g/board-info.txt`.
+`device/samsung/crespo/board-info.txt` or
+`device/samsung/maguro/board-info.txt`
-(*) As a note, radio version D720SPRKH1 for Nexus S 4G sometimes erroneously
-reports version D720SPRKE1. If this is the case for your Nexus S 4G, you can
-locally modify the version-baseband line in
-`device/samsung/crespo4g/board-info.txt` accordingly.
+## Restoring a device to its original factory state ##
+
+Factory images for Galaxy Nexus (GSM/HSPA+) are available from
+[Google's factory image page](http://code.google.com/android/nexus/images.html).
+
+Factory images for the Motorola Xoom are distributed directly by Motorola.
+
+No factory images are available for Nexus S and Nexus One.
diff --git a/src/source/building-kernels.md b/src/source/building-kernels.md
new file mode 100644
index 0000000..8eb9639
--- /dev/null
+++ b/src/source/building-kernels.md
@@ -0,0 +1,80 @@
+<!--
+ Copyright 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Building Kernels #
+
+If you are only interested in the kernel, you may use this guide
+to download and build the appropriate kernel.
+
+The following instructions assume that you have not downloaded all
+of AOSP. If you have downloaded all of AOSP, you may skip the git
+clone steps other than the step to download the actual kernel sources.
+
+We will use the Pandaboard kernel in all the following examples.
+
+
+## Figuring out which kernel to build ##
+
+You will want to look at the git log for the kernel in the device project that
+you are interested in.
+Device projects are of the form device/<vendor>/<name>.
+
+ $ git clone https://android.googlesource.com/device/ti/panda
+ $ cd panda
+ $ git log kernel
+
+The log should contain notes of the commit SHA1 for the appropriate
+kernel project. Keep this value at hand so that you can use it in
+a later step.
+
+## Downloading sources ##
+
+Depending on which kernel you want,
+
+ $ git clone https://android.googlesource.com/kernel/common.git
+ $ git clone https://android.googlesource.com/kernel/goldfish.git
+ $ git clone https://android.googlesource.com/kernel/msm.git
+ $ git clone https://android.googlesource.com/kernel/omap.git
+ $ git clone https://android.googlesource.com/kernel/samsung.git
+ $ git clone https://android.googlesource.com/kernel/tegra.git
+
+
+## Downloading a prebuilt gcc ##
+
+Ensure that the prebuilt toolchain is in your path.
+
+ $ git clone https://android.googlesource.com/platform/prebuilt
+ $ export PATH=$(pwd)/prebuilt/linux-x86/toolchain/arm-eabi-4.4.3/bin:$PATH
+
+
+## Building ##
+
+As an example, we would build the panda kernel using the following commands:
+
+ $ export ARCH=arm
+ $ export SUBARCH=arm
+ $ export CROSS_COMPILE=arm-eabi-
+ $ cd omap
+ $ git checkout <commit_from_first_step>
+ $ make panda_defconfig
+ $ make
+
+To build the tuna kernel, you may run the previous commands replacing all
+instances of "panda" with "tuna".
+
+The image is output as arch/arm/boot/zImage. You may copy it as
+device/<vendor>/<name>/kernel or device/ti/panda/kernel in the case of this
+example.
diff --git a/src/source/building.md b/src/source/building.md
index 5bfdee7..77e67fd 100644
--- a/src/source/building.md
+++ b/src/source/building.md
@@ -46,9 +46,9 @@
Build name | Device | Notes
------------|----------|---------------------------
-generic | emulator | lowest-common denominator
full | emulator | fully configured with all languages, apps, input methods
-full_crespo | crespo | `full` build running on Nexus S ("crespo")
+full_maguro | maguro | `full` build running on Galaxy Nexus GSM/HSPA+ ("maguro")
+full_panda | panda | `full` build running on PandaBoard ("panda")
and the BUILDTYPE is one of the following:
diff --git a/src/source/cla-corporate.pdf b/src/source/cla-corporate.pdf
new file mode 100644
index 0000000..09dc022
--- /dev/null
+++ b/src/source/cla-corporate.pdf
Binary files differ
diff --git a/src/source/cla-individual.md b/src/source/cla-individual.md
index d51ad83..34a1c28 100644
--- a/src/source/cla-individual.md
+++ b/src/source/cla-individual.md
@@ -16,7 +16,7 @@
# Contributor License Agreement for Individuals #
-*Please visit the [code review tool](https://review.source.android.com/#settings,new-agreement)
+*Please visit the [code review tool](https://android-review.googlesource.com/#/settings/new-agreement)
to execute the grant online.This page provides the text of the Individual Contributor License Grant for your quick review.*
In order to clarify the intellectual property license granted with Contributions from any person or entity, the Android Open Source Project (the "Project") must have a Contributor License Grant ("Grant") on file that has been signed by each Contributor, indicating agreement to the license terms below. This license is for your protection as a Contributor as well as the protection of the Project and the Android Open Source Project Leads (the "Project Leads"); it does not change your rights to use your own Contributions for any other purpose. If you have not already done so, please complete and send an original signed Grant to
@@ -30,7 +30,9 @@
U.S.A.
</blockquote>
-Scanned agreements may also be emailed in PDF form to cla-submissions@google.com, sent by facsimile to (650) 887-1625, or [signed electronically](https://review.source.android.com/#settings,new-agreement).
+Scanned agreements may also be emailed in PDF form to
+cla-submissions@google.com, sent by facsimile to (650) 887-1625, or
+[signed electronically](https://android-review.googlesource.com/#/settings/new-agreement).
Please read this document carefully before signing and keep a copy for your records.
diff --git a/src/source/code-lines.md b/src/source/code-lines.md
index 1d6d421..8b268f2 100644
--- a/src/source/code-lines.md
+++ b/src/source/code-lines.md
@@ -28,7 +28,7 @@
will become a new branch in git, and sometimes not, based on the needs of the
moment.
-<img src="/images/code-lines.png"/>
+<img src="/images/code-lines.png" alt="code-line diagram"/>
## Notes and Explanations ##
diff --git a/src/source/downloading.md b/src/source/downloading.md
index 42008e5..9f81cae 100644
--- a/src/source/downloading.md
+++ b/src/source/downloading.md
@@ -32,13 +32,15 @@
$ curl https://dl-ssl.google.com/dl/googlesource/git-repo/repo > ~/bin/repo
$ chmod a+x ~/bin/repo
- - The SHA-1 checksum for repo is e1fd3bef059d152edf4d0522590725d317bc637f
+ - The SHA-1 checksum for repo is 29ba4221d4fccdfa8d87931cd73466fdc24040b5
+
## Initializing a Repo client ##
After installing Repo, set up your client to access the android source repository:
- Create an empty directory to hold your working files.
+ If you're using MacOS, this has to be on a case-sensitive filesystem.
Give it any name you like:
@@ -51,14 +53,13 @@
To check out a branch other than "master", specify it with -b:
- $ repo init -u https://android.googlesource.com/platform/manifest -b android-2.3.7_r1
+ $ repo init -u https://android.googlesource.com/platform/manifest -b android-4.0.1_r1
- When prompted, please configure Repo with your real name and email address. To use the Gerrit code-review tool, you will need an email address that is connected with a [registered Google account](http://www.google.com/accounts). Make sure this is a live address at which you can receive messages. The name that you provide here will show up in attributions for your code submissions.
A successful initialization will end with a message stating that Repo is initialized in your working directory. Your client directory should now contain a `.repo` directory where files such as the manifest will be kept.
-
## Getting the files ##
To pull down files to your working directory from the repositories as specified in the default manifest, run
@@ -71,6 +72,87 @@
Repo commands, see [Version Control](version-control.html).
+## Using authentication ##
+
+By default, access to the Android source code is anonymous. To protect the
+servers against excessive usage, each IP address is associated with a quota.
+
+When sharing an IP address with other users (e.g. when accessing the source
+repositories from beyond a NAT firewall), the quotas can trigger even for
+regular usage patterns (e.g. if many users sync new clients from the same IP
+address within a short period).
+
+In that case, it is possible to use authenticated access, which then uses
+a separate quota for each user, regardless of the IP address.
+
+The first step is to create a password from
+[the password generator](https://android.googlesource.com/new-password) and
+to save it in `~/.netrc` according to the instructions on that page.
+
+The second step is to force authenticated access, by using the following
+manifest URI: `https://android.googlesource.com/a/platform/manifest`. Notice
+how the `/a/` directory prefix triggers mandatory authentication. You can
+convert an existing client to use mandatory authentication with the following
+command:
+
+ $ repo init -u https://android.googlesource.com/a/platform/manifest
+
+## Troubleshooting network issues ##
+
+When downloading from behind a proxy (which is common in some
+corporate environments), it might be necessary to explicitly
+specify the proxy that is then used by repo:
+
+ $ export HTTP_PROXY=http://<proxy_user_id>:<proxy_password>@<proxy_server>:<proxy_port>
+ $ export HTTPS_PROXY=http://<proxy_user_id>:<proxy_password>@<proxy_server>:<proxy_port>
+
+More rarely, Linux clients experience connectivity issues, getting
+stuck in the middle of downloads (typically during "Receiving objects").
+It has been reported that tweaking the settings of the TCP/IP stack and
+using non-parallel commands can improve the situation. You need root
+access to modify the TCP setting:
+
+ $ sudo sysctl -w net.ipv4.tcp_window_scaling=0
+ $ repo sync -j1
+
+
+## Using a local mirror ##
+
+When using many clients, especially in situations where bandwidth is scarce,
+it is better to create a local mirror of the entire server content, and to
+sync clients from that mirror (which requires no network access).
+
+These instructions assume that the mirror is created in `/usr/local/aosp/mirror`.
+The first step is to create and sync the mirror itself, which uses close to
+10GB of network bandwidth and a similar amount of disk space. Notice the
+`--mirror` flag, which can only be specified when creating a new client:
+
+ $ mkdir -p /usr/local/aosp/mirror
+ $ cd /usr/local/aosp/mirror
+ $ repo init -u https://android.googlesource.com/mirror/manifest --mirror
+ $ repo sync
+
+Once the mirror is synced, new clients can be created from it. Note that it's
+important to specify an absolute path:
+
+ $ mkdir -p /usr/local/aosp/master
+ $ cd /usr/local/aosp/master
+ $ repo init -u /usr/local/aosp/mirror/platform/manifest.git
+ $ repo sync
+
+Finally, to sync a client against the server, the mirror needs to be synced
+against the server, then the client against the mirror:
+
+ $ cd /usr/local/aosp/mirror
+ $ repo sync
+ $ cd /usr/local/aosp/master
+ $ repo sync
+
+It's possible to store the mirror on a LAN server and to access it over
+NFS, SSH or Git. It's also possible to store it on a removable drive and
+to pass that drive around between users or between machines.
+
+
## Verifying Git Tags ##
Load the following public key into your GnuPG key database. The key is used to sign annotated tags that represent releases.
@@ -114,6 +196,8 @@
$ git tag -v TAG_NAME
+If you haven't [set up ccache](initializing.html#ccache) yet,
+now would be a good time to do it.
# Next: Build the code #
diff --git a/src/source/initializing.md b/src/source/initializing.md
index e15df10..8e8bf8b 100644
--- a/src/source/initializing.md
+++ b/src/source/initializing.md
@@ -18,29 +18,35 @@
The "Getting Started" section describes how to set up your local work environment, how to use Repo to get the Android files, and how to build the files on your machine. To build the Android source files, you will need to use Linux or Mac OS. Building under Windows is not currently supported.
-*Note: The source is approximately 2.6GB in size. You will need 10GB free to complete the build.*
+*Note: The source download is approximately 6GB in size.
+You will need 25GB free to complete a single build, and
+up to 90GB (or more) for a full set of builds.*
For an overview of the entire code-review and code-update process, see [Life of a Patch](life-of-a-patch.html).
-To see snapshots and histories of the files available in the public Android repositories, visit the [GitWeb](http://android.git.kernel.org) web interface.
-
# Setting up a Linux build environment #
-The Android build is routinely tested in house on recent versions of Ubuntu (10.04 and later), but most distributions should have the required build tools available. Reports of successes or failures on other distributions are welcome.
+The Android build is routinely tested in house on recent versions of
+Ubuntu LTS (10.04), but most distributions should have the required
+build tools available. Reports of successes or failures on other
+distributions are welcome.
-*Note: It is also possible to build Android in a virtual machine. If you are running Linux in a virtual machine, you will need at least 8GB of RAM/swap and 12GB or more of disk space in order to build the Android tree.*
+*Note: It is also possible to build Android in a virtual machine.
+If you are running Linux in a virtual machine, you will need at
+least 16GB of RAM/swap and 30GB or more of disk space in order to
+build the Android tree.*
In general you will need:
- - Python 2.4 -- 2.7, which you can download from [python.org](http://www.python.org/download/).
+ - Python 2.5 -- 2.7, which you can download from [python.org](http://www.python.org/download/).
+
+ - GNU Make 3.81 -- 3.82, which you can download from [gnu.org](http://ftp.gnu.org/gnu/make/),
- JDK 6 if you wish to build Gingerbread or newer; JDK 5 for Froyo or older. You can download both from [java.sun.com](http://java.sun.com/javase/downloads/).
- - Git 1.5.4 or newer. You can find it at [git-scm.com](http://git-scm.com/download).
-
- - (optional) Valgrind, a tool that will help you find memory leaks, stack corruption, array bounds overflows, etc. Download from [valgrind.org](http://valgrind.org/downloads/current.html).
+ - Git 1.7 or newer. You can find it at [git-scm.com](http://git-scm.com/download).
Detailed instructions for Ubuntu 10.04+ follow.
@@ -51,7 +57,6 @@
Java 6: for Gingerbread and newer
$ sudo add-apt-repository "deb http://archive.canonical.com/ lucid partner"
- $ sudo add-apt-repository "deb-src http://archive.canonical.com/ubuntu lucid partner"
$ sudo apt-get update
$ sudo apt-get install sun-java6-jdk
@@ -62,15 +67,47 @@
$ sudo apt-get update
$ sudo apt-get install sun-java5-jdk
-## Installing required packages ##
+*Note: The `lunch` command in the build step will ensure that the Sun JDK is
+used instead of any previously installed JDK.*
-To set up your development environment, install the following required packages:
+## Installing required packages (Ubuntu 10.04 -- 11.10) ##
+
+You will need a 64-bit version of Ubuntu. Ubuntu 10.04 is recommended.
+Building using a newer version of Ubuntu is currently only experimentally
+supported and is not guaranteed to work on branches other than master.
$ sudo apt-get install git-core gnupg flex bison gperf build-essential \
zip curl zlib1g-dev libc6-dev lib32ncurses5-dev ia32-libs \
x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev \
libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown \
- libxml2-utils
+ libxml2-utils xsltproc
+
+On Ubuntu 10.10:
+
+ $ sudo ln -s /usr/lib32/mesa/libGL.so.1 /usr/lib32/mesa/libGL.so
+
+On Ubuntu 11.10:
+
+ $ sudo apt-get install libx11-dev:i386
+
+## Installing required packages (Ubuntu 12.04) ##
+
+Building on Ubuntu 12.04 is currently only experimentally supported and is not
+guaranteed to work on branches other than master.
+
+ $ sudo apt-get install git-core gnupg flex bison gperf build-essential \
+ zip curl libc6-dev libncurses5-dev:i386 x11proto-core-dev \
+ libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-dev:i386 \
+ g++-multilib mingw32 openjdk-6-jdk tofrodos python-markdown \
+ libxml2-utils xsltproc zlib1g-dev:i386
+
+You may also need to fix a compilation issue in a kernel header:
+
+ $ sudo vim /usr/include/linux/usb/ch9.h # line 592
+
+ # return le16_to_cpu(epd->wMaxPacketSize);
+ return __le16_to_cpu(epd->wMaxPacketSize);
+
## Configuring USB Access ##
@@ -92,6 +129,20 @@
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e22", MODE="0600", OWNER="<username>"
# fastboot protocol on crespo/crespo4g (Nexus S)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e20", MODE="0600", OWNER="<username>"
+ # adb protocol on stingray/wingray (Xoom)
+ SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", ATTR{idProduct}=="70a9", MODE="0600", OWNER="<username>"
+ # fastboot protocol on stingray/wingray (Xoom)
+ SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="708c", MODE="0600", OWNER="<username>"
+ # adb protocol on maguro/toro (Galaxy Nexus)
+ SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", ATTR{idProduct}=="6860", MODE="0600", OWNER="<username>"
+ # fastboot protocol on maguro/toro (Galaxy Nexus)
+ SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e30", MODE="0600", OWNER="<username>"
+ # adb protocol on panda (PandaBoard)
+ SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d101", MODE="0600", OWNER="<username>"
+ # fastboot protocol on panda (PandaBoard)
+ SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d022", MODE="0600", OWNER="<username>"
+ # usbboot protocol on panda (PandaBoard)
+ SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d010", MODE="0600", OWNER="<username>"
Those new rules take effect the next time a device is plugged in.
It might therefore be necessary to unplug the device and plug it
@@ -101,10 +152,37 @@
Lucid Lynx (10.04.x LTS). Other versions of Ubuntu or other
variants of GNU/linux might require different configurations.
+<a name="ccache"></a>
+## Setting up ccache ##
+
+You can optionally tell the build to use the ccache compilation tool.
+Ccache acts as a compiler cache that can be used to speed-up rebuilds.
+This works very well if you do "make clean" often, or if you frequently
+switch between different build products.
+
+Put the following in your .bashrc or equivalent.
+
+ export USE_CCACHE=1
+
+By default the cache will be stored in ~/.ccache.
+If your home directory is on NFS or some other non-local filesystem,
+you will want to specify the directory in your .bashrc as well.
+
+ export CCACHE_DIR=<path-to-your-cache-directory>
+
+The suggested cache size is 50-100GB.
+You will need to run the following command once you have downloaded
+the source code.
+
+ prebuilt/linux-x86/ccache/ccache -M 50G
+
+This setting is stored in the CCACHE_DIR and is persistent.
+
# Setting up a Mac OS X build environment #
-To build the Android files in a Mac OS environment, you need an Intel/x86 machine running MacOS 10.4 (Tiger), 10.5 (Leopard), or 10.6 (Snow Leopard). The Android build system and tools do not support the obsolete PowerPC architecture.
+To build the Android files in a Mac OS environment, you need an
+Intel/x86 machine running MacOS 10.6 (Snow Leopard).
Android must be built on a case-sensitive file system because the sources contain files that differ only in case. We recommend that you build Android on a partition that has been formatted with the journaled file system HFS+. HFS+ is required to successfully build Mac OS applications such as the Android Emulator for OS X.
@@ -112,7 +190,7 @@
If you want to avoid partitioning/formatting your hard drive, you can use
a case-sensitive disk image instead. To create the image, launch Disk
-Utility and select "New Image". A size of 12GB is the minimum to
+Utility and select "New Image". A size of 25GB is the minimum to
complete the build, larger numbers are more future-proof. Using sparse images
saves space while allowing to grow later as the need arises. Be sure to select
"case sensitive, journaled" as the volume format.
@@ -121,7 +199,7 @@
# hdiutil create -type SPARSE -fs 'Case-sensitive Journaled HFS+' -size 40g ~/android.dmg
-This will create a .dmg file which, once mounted, acts as a drive with the required formatting for Android development. For a disk image named "android.dmg" stored in your home directory, you can add the following to your `~/.bash_profile` to mount the image when you execute "mountAndroid":
+This will create a .dmg (or possibly a .dmg.sparsefile) file which, once mounted, acts as a drive with the required formatting for Android development. For a disk image named "android.dmg" stored in your home directory, you can add the following to your `~/.bash_profile` to mount the image when you execute "mountAndroid":
# mount the android file image
function mountAndroid { hdiutil attach ~/android.dmg -mountpoint /Volumes/android; }
@@ -130,7 +208,11 @@
## Installing required packages ##
-- Install XCode from [the Apple developer site](http://developer.apple.com/). We recommend version 3.0 or newer. If you are not already registered as an Apple developer, you will have to create an Apple ID in order to download.
+- Install XCode from [the Apple developer site](http://developer.apple.com/).
+We recommend version 3.1.4 or newer, i.e. gcc 4.2.
+Version 4.x could cause difficulties.
+If you are not already registered as an Apple developer, you will have to
+create an Apple ID in order to download.
- Install MacPorts from [macports.org](http://www.macports.org/install.php).
diff --git a/src/source/known-issues.md b/src/source/known-issues.md
new file mode 100644
index 0000000..a7dd9fa
--- /dev/null
+++ b/src/source/known-issues.md
@@ -0,0 +1,47 @@
+<!--
+ Copyright 2010 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Known Issues #
+
+Even with our best care, small problems sometimes slip in. This page keeps
+track of the known issues around using the Android source code.
+
+## Missing CTS Native XML Generator ##
+
+**Symptom**: On some builds of IceCreamSandwich and later, the following
+warning is printed early during the build:
+`/bin/bash: line 0: cd: cts/tools/cts-native-xml-generator/src/res: No
+such file or directory`
+
+**Cause**: Some makefile references that path, which doesn't exist.
+
+**Fix**: None. This is a harmless warning.
+
+## Black Gingerbread Emulator ##
+
+**Symptom**: The emulator built directly from the gingerbread branch
+doesn't start and stays stuck on a black screen.
+
+**Cause**: The gingerbread branch uses version R7 of the emulator,
+which doesn't have all the features necessary to run recent versions
+of gingerbread.
+
+**Fix**: Use version R12 of the emulator, and a newer kernel that matches
+those tools. No need to do a clean build.
+
+ $ repo forall external/qemu -c git checkout aosp/tools_r12
+ $ make
+ $ emulator -kernel prebuilt/android-arm/kernel/kernel-qemu-armv7
diff --git a/src/source/licenses.md b/src/source/licenses.md
index 74979f9..0405e84 100644
--- a/src/source/licenses.md
+++ b/src/source/licenses.md
@@ -35,7 +35,7 @@
only on their own behalf) of ideas, code, or documentation to the Android Open
Source Project will be required to complete, sign, and submit an [Individual
Contributor License Grant](cla-individual.html). The grant can be executed online through the
-[code review tool](https://review.source.android.com/#settings,agreements).
+[code review tool](https://android-review.googlesource.com/#/settings/agreements).
The grant clearly defines the terms under which intellectual
property has been contributed to the Android Open Source Project. This license
is for your protection as a contributor as well as the protection of the
@@ -44,7 +44,7 @@
For a *corporation* (or other entity) that has assigned employees to
work on the Android Open Source Project, a [Corporate
-Contributor License Grant](cla-corporate.html) is available.
+Contributor License Grant](cla-corporate.pdf) is available.
This version of the grant allows a
corporation to authorize contributions submitted by its designated employees
and to grant copyright and patent licenses. Note that a Corporate Contributor
diff --git a/src/source/life-of-a-patch.md b/src/source/life-of-a-patch.md
index 7799424..f0fbc40 100644
--- a/src/source/life-of-a-patch.md
+++ b/src/source/life-of-a-patch.md
@@ -24,4 +24,4 @@
For full instructions on how to get set up to use gerrit and git, please
see the [Submitting Patches](submit-patches.html) page.
-<img src="/images/workflow-0.png"/>
+<img src="/images/workflow-0.png" alt="workflow diagram"/>
diff --git a/src/source/overview.md b/src/source/overview.md
index b42c436..34ef955 100644
--- a/src/source/overview.md
+++ b/src/source/overview.md
@@ -23,9 +23,14 @@
The links below will navigate you away from this site.
+## [Android 4.0](http://developer.android.com/sdk/android-4.0-highlights.html) ##
+
+Android 4.0 corresponded to the "IceCreamSandwich" milestone branch, and has an API level of 14.
+
## [Android 2.3](http://developer.android.com/sdk/android-2.3-highlights.html) ##
Android 2.3 corresponded to the "Gingerbread" milestone branch, and has an API level of 9.
+In versions 2.3.3 and higher, the API level is 10.
## [Android 2.2](http://developer.android.com/sdk/android-2.2-highlights.html) ##
diff --git a/src/source/report-bugs.md b/src/source/report-bugs.md
index c660b34..5433126 100644
--- a/src/source/report-bugs.md
+++ b/src/source/report-bugs.md
@@ -22,10 +22,10 @@
First, though: if you think you've found a security vulnerability,
*please don't use the forms below*. Using the public forms below may
allow anyone to see your report, which may put users at risk until the bug is
-fixed. Instead, please report security bugs to our security team by emailing
-<a href="mailto:security@android.com">security@android.com</a>. We believe in
-responsible disclosure of security vulnerabilities, and will give you proper
-attribution for any issues you report.
+fixed. Please visit
+<a href="https://developer.android.com/resources/faq/security.html#issue">our
+security faq</a> for more information on reporting security vulnerabilities
+to the Android security team.
Here's how to report non-security bugs:
diff --git a/src/source/sidebar.md b/src/source/sidebar.md
index 31d782b..45189a2 100644
--- a/src/source/sidebar.md
+++ b/src/source/sidebar.md
@@ -4,6 +4,8 @@
- [Downloading the Source](downloading.html)
- [Building and Running](building.html)
- [Building for Devices](building-devices.html)
+- [Building Kernels](building-kernels.html)
+- [Known Issues](known-issues.html)
# Navigating the Source #
diff --git a/src/source/submit-patches.md b/src/source/submit-patches.md
index 037aca4..07bcbe6 100644
--- a/src/source/submit-patches.md
+++ b/src/source/submit-patches.md
@@ -41,7 +41,7 @@
For each change you intend to make, start a new branch within the relevant git repository:
- $ repo start NAME
+ $ repo start NAME .
You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and will not be included on gerrit or the final source tree.
@@ -75,7 +75,10 @@
If you have started multiple branches in the same repository, you will be prompted to select which one(s) to upload.
-After a successful upload, repo will provide you the URL of a new page on [r.android.com](http://review.source.android.com). Visit this link to view your patch on the review server, add comments, or request specific reviewers for your patch.
+After a successful upload, repo will provide you the URL of a new page on
+[Gerrit](https://android-review.googlesource.com/). Visit this link to view
+your patch on the review server, add comments, or request specific reviewers
+for your patch.
## Uploading a replacement patch ##
@@ -108,7 +111,7 @@
## After a submission is approved ##
-After a submission makes it through the review and verification process, Gerrit automatically merges the change into the public repository. The change will now be visible in gitweb, and others users will be able to run `repo sync` to pull the update into their local client.
+After a submission makes it through the review and verification process, Gerrit automatically merges the change into the public repository. Other users will be able to run `repo sync` to pull the update into their local client.
# For reviewers and verifiers #
@@ -147,7 +150,7 @@
$ repo download TARGET CHANGE
where TARGET is the local directory into which the change should be downloaded and CHANGE is the
-change number as listed in [Gerrit](https://review.source.android.com/). For more information,
+change number as listed in [Gerrit](https://android-review.googlesource.com/). For more information,
see the [Repo reference](/source/using-repo.html).
## How do I become a Verifier or Approver? ##
@@ -168,16 +171,31 @@
To publish your comments so that others using Gerrit will be able to see them, click the Publish Comments button. Your comments will be emailed to all relevant parties for this change, including the change owner, the patch set uploader (if different from the owner), and all current reviewers.
-## Using GitWeb to track patch histories ##
-
-To view snapshots of the files that are in the public Android repositories and view file histories, use the [Android instance of GitWeb](http://android.git.kernel.org/).
-
<a name="upstream-projects"></a>
# Upstream Projects #
Android makes use of a number of other open-source projects, such as the Linux kernel and WebKit, as described in
-[Branches and Releases](/source/code-lines.html). For the upstream projects detailed below, changes should be made directly upstream. Such changes will be incorporated into the Android tree as part of the usual process of pulling these projects.
+[Branches and Releases](/source/code-lines.html). For most projects under `external/`, changes should be made upstream and then the Android maintainers informed of the new upstream release containing these changes. It may also be useful to upload patches that move us to track a new upstream release, though these can be difficult changes to make if the project is widely used within Android like most of the larger ones mentioned below, where we tend to upgrade with every release.
+
+One interesting special case is bionic. Much of the code there is from BSD, so unless the change is to code that's new to bionic, we'd much rather see an upstream fix and then pull a whole new file from the appropriate BSD. (Sadly we have quite a mix of different BSDs at the moment, but we hope to address that in future, and get into a position where we track upstream much more closely.)
+
+## ICU4C ##
+
+All changes to the ICU4C project at `external/icu4c` should be made upstream at
+[icu-project.org/](http://site.icu-project.org/).
+See [Submitting ICU Bugs and Feature Requests](http://site.icu-project.org/bugs) for more.
+
+## OpenSSL ##
+
+All changes to the OpenSSL project at `external/openssl` should be made upstream at
+[openssl.org](http://www.openssl.org).
+
+## V8 ##
+
+All changes to the V8 project at `external/v8` should be submitted upstream at
+[code.google.com/p/v8](http://code.google.com/p/v8). See [Contributing to V8](http://code.google.com/p/v8/wiki/Contributing)
+for details.
## WebKit ##
@@ -188,9 +206,7 @@
attention once a proposed fix is added and tests are included. See
[Contributing Code to WebKit](http://webkit.org/coding/contributing.html) for details.
-## V8 ##
+## zlib ##
-All changes to the V8 project at `external/v8` should be submitted upstream at
-[code.google.com/p/v8](http://code.google.com/p/v8). See [Contributing to V8](http://code.google.com/p/v8/wiki/Contributing)
-for details.
-
+All changes to the zlib project at `external/zlib` should be made upstream at
+[zlib.net](http://zlib.net).
diff --git a/src/source/using-eclipse.md b/src/source/using-eclipse.md
index 5af32a8..94e24cf 100644
--- a/src/source/using-eclipse.md
+++ b/src/source/using-eclipse.md
@@ -42,7 +42,7 @@
### Increase Eclipse's Memory Settings ###
-The Android project is large enough that Eclipse's Java VM sometimes runs out of memory while compiling it. Avoid this problem by editing the the `eclipse.ini` file. On Apple OSX the eclipse.ini file is located at
+The Android project is large enough that Eclipse's Java VM sometimes runs out of memory while compiling it. Avoid this problem by editing the `eclipse.ini` file. On Apple OSX the eclipse.ini file is located at
/Applications/eclipse/Eclipse.app/Contents/MacOS/eclipse.ini
diff --git a/src/source/using-repo.md b/src/source/using-repo.md
index f343639..b3bf9bb 100644
--- a/src/source/using-repo.md
+++ b/src/source/using-repo.md
@@ -84,9 +84,16 @@
For the specified projects, Repo compares the local branches to the remote branches updated during the last repo sync. Repo will prompt you to select one or more of the branches that have not yet been uploaded for review.
-After you select one or more branches, all commits on the selected branches are transmitted to Gerrit over an SSH connection.You will need to configure an SSH key to enable upload authorization. Visit [SSH Keys](http://review.source.android.com/Gerrit#settings,ssh-keys) within the user settings panel to register your public keys with Gerrit. To enable password-less uploads, consider using ssh-agent on your client system.
+After you select one or more branches, all commits on the selected branches
+are transmitted to Gerrit over an HTTPS connection. You will need to
+configure an HTTPS password to enable upload authorization. Visit the
+[Password Generator](https://android-review.googlesource.com/new-password)
+to generate a new username/password pair to use over HTTPS.
-When Gerrit receives the object data over its SSH server, it will turn each commit into a change so that reviewers can comment on each commit individually. To combine several "checkpoint" commits together into a single commit, use git rebase -i before you run repo upload.
+When Gerrit receives the object data over its server, it will turn each
+commit into a change so that reviewers can comment on each commit
+individually. To combine several "checkpoint" commits together into a
+single commit, use git rebase -i before you run repo upload.
If you run repo upload without any arguments, it will search all the projects for changes to upload.
@@ -121,13 +128,16 @@
Downloads the specified change from the review system and makes it available in your project's local working directory.
-For example, to download [change 1241](http://review.source.android.com/1241) into your platform/frameworks/base directory:
+For example, to download [change 23823](https://android-review.googlesource.com/23823) into your platform/frameworks/base directory:
- $ repo download platform/frameworks/base 1241
+ $ repo download platform/build 23823
A `repo sync` should effectively remove any commits retrieved via `repo download`. Or, you can check out the remote branch; e.g., `git checkout m/master`.
-*Note: There is a slight mirroring lag between when a change is visible on the web in [Gerrit](http://review.source.android.com) and when `repo download` will be able to find it, because changes are actually downloaded off the git://android.git.kernel.org/ mirror farm. Hence there will always be a lag of approximately 5 minutes before Gerrit pushes newly uploaded changes out to the mirror farm.*
+*Note: There is a slight mirroring lag between when a change is visible on
+the web in [Gerrit](https://android-review.googlesource.com/) and when
+`repo download` will be able to find it for all users, because of replication
+delays to all servers worldwide.
## forall ##
diff --git a/src/source/version-control.md b/src/source/version-control.md
index 623e30f..302fb68 100644
--- a/src/source/version-control.md
+++ b/src/source/version-control.md
@@ -20,14 +20,23 @@
**Git** is an open-source version-control system designed to handle very large projects that are distributed over multiple repositories. In the context of Android, we use Git for local operations such as local branching, commits, diffs, and edits. One of the challenges in setting up the Android project was figuring out how to best support the outside community--from the hobbiest community to large OEMs building mass-market consumer devices. We wanted components to be replaceable, and we wanted interesting components to be able to grow a life of their own outside of Android. We first chose a distributed revision control system, then further narrowed it down to Git.
-**Repo** is a repository management tool that we built on top of Git. Repo unifies the many Git repositories when necessary, does the uploads to our [revision control system](http://review.source.android.com/), and automates parts of the Android development workflow. Repo is not meant to replace Git, only to make it easier to work with Git in the context of Android. The repo command is an executable Python script that you can put anywhere in your path. In working with the Android source files, you will use Repo for across-network operations. For example, with a single Repo command you can download files from multiple repositories into your local working directory.
+**Repo** is a repository management tool that we built on top of Git. Repo
+unifies the many Git repositories when necessary, does the uploads to our
+[revision control system](https://android-review.googlesource.com/), and
+automates parts of the Android development workflow. Repo is not meant to
+replace Git, only to make it easier to work with Git in the context of
+Android. The repo command is an executable Python script that you can put
+anywhere in your path. In working with the Android source files, you will
+use Repo for across-network operations. For example, with a single Repo
+command you can download files from multiple repositories into your local
+working directory.
**Gerrit** is a web-based code review system for projects that use git. Gerrit encourages more centralized use of Git by allowing all authorized users to submit changes, which are automatically merged if they pass code review. In addition, Gerrit makes reviewing easier by displaying changes side by side in-browser and enabling inline comments.
## Basic Workflow ##
<div style="float:right">
- <img src="/images/submit-patches-0.png">
+ <img src="/images/submit-patches-0.png" alt="basic workflow diagram">
</div>
The basic pattern of interacting with the repositories is as follows:
@@ -60,7 +69,7 @@
## Creating topic branches ##
Start a topic branch in your local work environment whenever you begin a change, for example when you begin work on a bug or new feature. A topic branch is not a copy of the original files; it is a pointer to a particular commit. This makes creating local branches and switching among them a light-weight operation. By using branches, you can isolate one aspect of your work from the others. For an interesting article about using topic branches, see [Separating topic branches](http://www.kernel.org/pub/software/scm/git/docs/howto/separating-topic-branches.txt).
-<img src="/images/external-link.png">
+<img src="/images/external-link.png" alt="">
To start a topic branch using Repo:
@@ -173,6 +182,6 @@
# Git and Repo cheatsheet #
-<img src="/images/git-repo-1.png">
+<img src="/images/git-repo-1.png" alt="list of basic git and repo commands">
diff --git a/src/tech/dalvik/dalvik-bytecode.html b/src/tech/dalvik/dalvik-bytecode.html
index 35fa64b..66c9c48 100644
--- a/src/tech/dalvik/dalvik-bytecode.html
+++ b/src/tech/dalvik/dalvik-bytecode.html
@@ -24,8 +24,13 @@
such as (but not limited to) the program counter and a reference to the
<code>.dex</code> file that contains the method.
</li>
- <li>Registers are 32 bits wide. Adjacent register pairs are used for 64-bit
- values.
+ <li>When used for bit values (such as integers and floating point
+ numbers), registers are considered 32 bits wide. Adjacent register
+ pairs are used for 64-bit values. There is no alignment requirement
+ for register pairs.
+ </li>
+ <li>When used for object references, registers are considered wide enough
+ to hold exactly one such reference.
</li>
<li>In terms of bitwise representation, <code>(Object) null == (int)
0</code>.
@@ -52,19 +57,24 @@
reasonably common, many instructions are limited to only addressing
the first 16
registers. When reasonably possible, instructions allow references to
- up to the first 256 registers. In cases where an instruction variant isn't
+ up to the first 256 registers. In addition, some instructions have variants
+ that allow for much larger register counts, including a pair of catch-all
+ <code>move</code> instructions that can address registers in the range
+ <code>v0</code> – <code>v65535</code>.
+ In cases where an instruction variant isn't
available to address a desired register, it is expected that the register
contents get moved from the original register to a low register (before the
operation) and/or moved from a low result register to a high register
(after the operation).
</li>
<li>There are several "pseudo-instructions" that are used to hold
- variable-length data referred to by regular instructions (for example,
+ variable-length data payloads, which are referred to by regular
+ instructions (for example,
<code>fill-array-data</code>). Such instructions must never be
encountered during the normal flow of execution. In addition, the
instructions must be located on even-numbered bytecode offsets (that is,
4-byte aligned). In order to meet this requirement, dex generation tools
- should emit an extra <code>nop</code> instruction as a spacer if such an
+ must emit an extra <code>nop</code> instruction as a spacer if such an
instruction would otherwise be unaligned. Finally, though not required,
it is expected that most tools will choose to emit these instructions at
the ends of methods, since otherwise it would likely be the case that
@@ -81,16 +91,18 @@
<li>Human-syntax and mnemonics:
<ul>
<li>Dest-then-source ordering for arguments.</li>
- <li>Some opcodes have a disambiguating suffix with respect to the type(s)
- they operate on: Type-general 64-bit opcodes
- are suffixed with <code>-wide</code>.
- Type-specific opcodes are suffixed with their type (or a
+ <li>Some opcodes have a disambiguating name suffix to indicate the type(s)
+ they operate on:
+ <ul>
+ <li>Type-general 32-bit opcodes are unmarked.</li>
+ <li>Type-general 64-bit opcodes are suffixed with <code>-wide</code>.</li>
+ <li>Type-specific opcodes are suffixed with their type (or a
straightforward abbreviation), one of: <code>-boolean</code>
<code>-byte</code> <code>-char</code> <code>-short</code>
<code>-int</code> <code>-long</code> <code>-float</code>
<code>-double</code> <code>-object</code> <code>-string</code>
- <code>-class</code> <code>-void</code>. Type-general 32-bit opcodes
- are unmarked.
+ <code>-class</code> <code>-void</code>.</li>
+ </ul>
</li>
<li>Some opcodes have a disambiguating suffix to distinguish
otherwise-identical operations that have different instruction layouts
@@ -99,6 +111,27 @@
mapping with static constants in the code that generates and interprets
executables (that is, to reduce ambiguity for humans).
</li>
+ <li>In the descriptions here, the width of a value (indicating, e.g., the
+ range of a constant or the number of registers possibly addressed) is
+ emphasized by the use of a character per four bits of width.
+ </li>
+ <li>For example, in the instruction
+ "<code>move-wide/from16 vAA, vBBBB</code>":
+ <ul>
+ <li>"<code>move</code>" is the base opcode, indicating the base operation
+ (move a register's value).</li>
+ <li>"<code>wide</code>" is the name suffix, indicating that it operates
+ on wide (64 bit) data.</li>
+ <li>"<code>from16</code>" is the opcode suffix, indicating a variant
+ that has a 16-bit register reference as a source.</li>
+ <li>"<code>vAA</code>" is the destination register (implied by the
+ operation; again, the rule is that destination arguments always come
+ first), which must be in the range <code>v0</code> –
+ <code>v255</code>.</li>
+ <li>"<code>vBBBB</code>" is the source register, which must be in the
+ range <code>v0</code> – <code>v65535</code>.</li>
+ </ul>
+ </li>
</ul>
</li>
<li>See the <a href="instruction-formats.html">instruction formats
@@ -106,6 +139,10 @@
(listed under "Op & Format") as well as details about the opcode
syntax.
</li>
+<li>See the <a href="dex-format.html"><code>.dex</code> file format
+ document</a> for more details about where the bytecode fits into
+ the bigger picture.
+</li>
</ul>
<h2>Summary of Instruction Set</h2>
@@ -124,7 +161,14 @@
<td>00 10x</td>
<td>nop</td>
<td> </td>
- <td>Waste cycles.</td>
+ <td>Waste cycles.
+ <p><b>Note:</b>
+ Data-bearing pseudo-instructions are tagged with this opcode, in which
+ case the high-order byte of the opcode unit indicates the nature of
+ the data. See "<code>packed-switch-payload</code> Format",
+ "<code>sparse-switch-payload</code> Format", and
+ "<code>fill-array-data-payload</code> Format" below.</p>
+ </td>
</tr>
<tr>
<td>01 12x</td>
@@ -237,7 +281,7 @@
<td>0d 11x</td>
<td>move-exception vAA</td>
<td><code>A:</code> destination register (8 bits)</td>
- <td>Save a just-caught exception into the given register. This should
+ <td>Save a just-caught exception into the given register. This must
be the first instruction of any exception handler whose caught
exception is not to be ignored, and this instruction must <i>only</i>
ever occur as the first instruction of an exception handler; anywhere
@@ -438,10 +482,12 @@
</tr>
<tr>
<td>24 35c</td>
- <td>filled-new-array {vD, vE, vF, vG, vA}, type@CCCC</td>
- <td><code>B:</code> array size and argument word count (4 bits)<br/>
- <code>C:</code> type index (16 bits)<br/>
- <code>D..G, A:</code> argument registers (4 bits each)</td>
+ <td>filled-new-array {vC, vD, vE, vF, vG}, type@BBBB</td>
+ <td>
+ <code>A:</code> array size and argument word count (4 bits)<br/>
+ <code>B:</code> type index (16 bits)<br/>
+ <code>C..G:</code> argument registers (4 bits each)
+ </td>
<td>Construct an array of the given type and size, filling it with the
supplied contents. The type must be an array type. The array's
contents must be single-word (that is,
@@ -466,7 +512,7 @@
<tr>
<td>26 31t</td>
<td>fill-array-data vAA, +BBBBBBBB <i>(with supplemental data as specified
- below in "<code>fill-array-data</code> Format")</i></td>
+ below in "<code>fill-array-data-payload</code> Format")</i></td>
<td><code>A:</code> array reference (8 bits)<br/>
<code>B:</code> signed "branch" offset to table data pseudo-instruction
(32 bits)
@@ -515,7 +561,7 @@
<tr>
<td>2b 31t</td>
<td>packed-switch vAA, +BBBBBBBB <i>(with supplemental data as
- specified below in "<code>packed-switch</code> Format")</i></td>
+ specified below in "<code>packed-switch-payload</code> Format")</i></td>
<td><code>A:</code> register to test<br/>
<code>B:</code> signed "branch" offset to table data pseudo-instruction
(32 bits)
@@ -529,7 +575,7 @@
<tr>
<td>2c 31t</td>
<td>sparse-switch vAA, +BBBBBBBB <i>(with supplemental data as
- specified below in "<code>sparse-switch</code> Format")</i></td>
+ specified below in "<code>sparse-switch-payload</code> Format")</i></td>
<td><code>A:</code> register to test<br/>
<code>B:</code> signed "branch" offset to table data pseudo-instruction
(32 bits)
@@ -698,16 +744,18 @@
</tr>
<tr>
<td>6e..72 35c</td>
- <td>invoke-<i>kind</i> {vD, vE, vF, vG, vA}, meth@CCCC<br/>
+ <td>invoke-<i>kind</i> {vC, vD, vE, vF, vG}, meth@BBBB<br/>
6e: invoke-virtual<br/>
6f: invoke-super<br/>
70: invoke-direct<br/>
71: invoke-static<br/>
72: invoke-interface
</td>
- <td><code>B:</code> argument word count (4 bits)<br/>
- <code>C:</code> method index (16 bits)<br/>
- <code>D..G, A:</code> argument registers (4 bits each)</td>
+ <td>
+ <code>A:</code> argument word count (4 bits)<br/>
+ <code>B:</code> method reference index (16 bits)<br/>
+ <code>C..G:</code> argument registers (4 bits each)
+ </td>
<td>Call the indicated method. The result (if any) may be stored
with an appropriate <code>move-result*</code> variant as the immediately
subsequent instruction.
@@ -749,7 +797,7 @@
78: invoke-interface/range
</td>
<td><code>A:</code> argument word count (8 bits)<br/>
- <code>B:</code> method index (16 bits)<br/>
+ <code>B:</code> method reference index (16 bits)<br/>
<code>C:</code> first argument register (16 bits)<br/>
<code>N = A + C - 1</code></td>
<td>Call the indicated method. See first <code>invoke-<i>kind</i></code>
@@ -935,7 +983,7 @@
</tbody>
</table>
-<h2><code>packed-switch</code> Format</h2>
+<h2><code>packed-switch-payload</code> Format</h2>
<table class="supplement">
<thead>
@@ -974,7 +1022,7 @@
<p><b>Note:</b> The total number of code units for an instance of this
table is <code>(size * 2) + 4</code>.</p>
-<h2><code>sparse-switch</code> Format</h2>
+<h2><code>sparse-switch-payload</code> Format</h2>
<table class="supplement">
<thead>
@@ -1014,7 +1062,7 @@
<p><b>Note:</b> The total number of code units for an instance of this
table is <code>(size * 4) + 2</code>.</p>
-<h2><code>fill-array-data</code> Format</h2>
+<h2><code>fill-array-data-payload</code> Format</h2>
<table class="supplement">
<thead>
diff --git a/src/tech/dalvik/dex-format.html b/src/tech/dalvik/dex-format.html
index cab9d4c..81c0b36 100644
--- a/src/tech/dalvik/dex-format.html
+++ b/src/tech/dalvik/dex-format.html
@@ -176,7 +176,7 @@
used by this file, either for internal naming (e.g., type descriptors)
or as constant objects referred to by code. This list must be sorted
by string contents, using UTF-16 code point values (not in a
- locale-sensitive manner).
+ locale-sensitive manner), and it must not contain any duplicate entries.
</td>
</tr>
<tr>
@@ -185,7 +185,7 @@
<td>type identifiers list. These are identifiers for all types (classes,
arrays, or primitive types) referred to by this file, whether defined
in the file or not. This list must be sorted by <code>string_id</code>
- index.
+ index, and it must not contain any duplicate entries.
</td>
</tr>
<tr>
@@ -194,7 +194,8 @@
<td>method prototype identifiers list. These are identifiers for all
prototypes referred to by this file. This list must be sorted in
return-type (by <code>type_id</code> index) major order, and then
- by arguments (also by <code>type_id</code> index).
+ by arguments (also by <code>type_id</code> index). The list must not
+ contain any duplicate entries.
</td>
</tr>
<tr>
@@ -205,7 +206,7 @@
list must be sorted, where the defining type (by <code>type_id</code>
index) is the major order, field name (by <code>string_id</code> index)
is the intermediate order, and type (by <code>type_id</code> index)
- is the minor order.
+ is the minor order. The list must not contain any duplicate entries.
</td>
</tr>
<tr>
@@ -215,8 +216,9 @@
referred to by this file, whether defined in the file or not. This
list must be sorted, where the defining type (by <code>type_id</code>
index) is the major order, method name (by <code>string_id</code>
- index) is the intermediate order, and method
- prototype (by <code>proto_id</code> index) is the minor order.
+ index) is the intermediate order, and method prototype (by
+ <code>proto_id</code> index) is the minor order. The list must not
+ contain any duplicate entries.
</td>
</tr>
<tr>
@@ -224,7 +226,9 @@
<td>class_def_item[]</td>
<td>class definitions list. The classes must be ordered such that a given
class's superclass and implemented interfaces appear in the
- list earlier than the referring class.
+ list earlier than the referring class. Furthermore, it is invalid for
+ a definition for the same-named class to appear more than once in
+ the list.
</td>
</tr>
<tr>
@@ -240,8 +244,8 @@
<td>link_data</td>
<td>ubyte[]</td>
<td>data used in statically linked files. The format of the data in
- this section is left unspecified by this document;
- this section is empty in unlinked files, and runtime implementations
+ this section is left unspecified by this document.
+ This section is empty in unlinked files, and runtime implementations
may use it as they see fit.
</td>
</tr>
@@ -270,10 +274,10 @@
<p><b>Note:</b> At least a couple earlier versions of the format have
been used in widely-available public software releases. For example,
version <code>009</code> was used for the M3 releases of the
-Android platform (November-December 2007),
+Android platform (November–December 2007),
and version <code>013</code> was used for the M5 releases of the Android
-platform (February-March 2008). In several respects, these earlier versions
-of the format differ significantly from the version described in this
+platform (February–March 2008). In several respects, these earlier
+versions of the format differ significantly from the version described in this
document.</p>
<h2><code>ENDIAN_CONSTANT</code> and <code>REVERSE_ENDIAN_CONSTANT</code></h2>
@@ -311,7 +315,7 @@
<h2><code>access_flags</code> Definitions</h2>
<h4>embedded in <code>class_def_item</code>,
-<code>field_item</code>, <code>method_item</code>, and
+<code>encoded_field</code>, <code>encoded_method</code>, and
<code>InnerClass</code></h4>
<p>Bitfields of these flags are used to indicate the accessibility and
@@ -827,7 +831,7 @@
<p>A <i>SimpleName</i> is the basis for the syntax of the names of other
things. The <code>.dex</code> format allows a fair amount of latitude
here (much more than most common source languages). In brief, a simple
-name may consist of any low-ASCII alphabetic character or digit, a few
+name consists of any low-ASCII alphabetic character or digit, a few
specific low-ASCII symbols, and most non-ASCII code points that are not
control, space, or special characters. Note that surrogate code points
(in the range <code>U+d800</code> … <code>U+dfff</code>) are not
@@ -1320,7 +1324,7 @@
<p>This is a list of the entire contents of a file, in order. It
contains some redundancy with respect to the <code>header_item</code>
but is intended to be an easy form to use to iterate over an entire
-file. A given type may appear at most once in a map, but there is no
+file. A given type must appear at most once in a map, but there is no
restriction on what order types may appear in, other than the
restrictions implied by the rest of the format (e.g., a
<code>header</code> section must appear first, followed by a
@@ -2013,7 +2017,7 @@
</table>
<h2><code>code_item</code></h2>
-<h4>referenced from <code>method_item</code></h4>
+<h4>referenced from <code>encoded_method</code></h4>
<h4>appears in the <code>data</code> section</h4>
<h4>alignment: 4 bytes</h4>
@@ -2091,7 +2095,7 @@
<tr>
<td>tries</td>
<td>try_item[tries_size] <i>(optional)</i></td>
- <td>array indicating where in the code exceptions may be caught and
+ <td>array indicating where in the code exceptions are caught and
how to handle them. Elements of the array must be non-overlapping in
range and in order from low to high address. This element is only
present if <code>tries_size</code> is non-zero.
@@ -2138,8 +2142,10 @@
<tr>
<td>handler_off</td>
<td>ushort</td>
- <td>offset in bytes from the start of the associated encoded handler data
- to the <code>catch_handler_item</code> for this entry
+ <td>offset in bytes from the start of the associated
+ <code>encoded_catch_hander_list</code> to the
+ <code>encoded_catch_handler</code> for this entry. This must be an
+ offset to the start of an <code>encoded_catch_handler</code>.
</td>
</tr>
</tbody>
@@ -2253,7 +2259,7 @@
<code>address</code> register represents the instruction offset in the
associated <code>insns_item</code> in 16-bit code units. The
<code>address</code> register starts at <code>0</code> at the beginning of each
-<code>debug_info</code> sequence and may only monotonically increase.
+<code>debug_info</code> sequence and must only monotonically increase.
The <code>line</code> register represents what source line number
should be associated with the next positions table entry emitted by
the state machine. It is initialized in the sequence header, and may
@@ -2865,7 +2871,7 @@
which is either defined as a member of another class, per se, or is
anonymous but not defined within a method body (e.g., a synthetic
inner class). Every class that has this annotation must also have an
-<code>InnerClass</code> annotation. Additionally, a class may not have
+<code>InnerClass</code> annotation. Additionally, a class must not have
both an <code>EnclosingClass</code> and an
<code>EnclosingMethod</code> annotation.</p>
@@ -2892,7 +2898,7 @@
<p>An <code>EnclosingMethod</code> annotation is attached to each class
which is defined inside a method body. Every class that has this
annotation must also have an <code>InnerClass</code> annotation.
-Additionally, a class may not have both an <code>EnclosingClass</code>
+Additionally, a class must not have both an <code>EnclosingClass</code>
and an <code>EnclosingMethod</code> annotation.</p>
<table class="format">
diff --git a/src/tech/dalvik/instruction-formats.html b/src/tech/dalvik/instruction-formats.html
index d7bf690..f81b595 100644
--- a/src/tech/dalvik/instruction-formats.html
+++ b/src/tech/dalvik/instruction-formats.html
@@ -27,10 +27,17 @@
("<code>|</code>") interspersed to aid in reading. Uppercase letters
in sequence from "<code>A</code>" are used to indicate fields within
the format (which then get defined further by the syntax column). The term
-"<code>op</code>" is used to indicate the position of the eight-bit
-opcode within the format. A slashed zero ("<code>Ø</code>") is
-used to indicate that all bits should be zero in the indicated
-position.</p>
+"<code>op</code>" is used to indicate the position of an eight-bit
+opcode within the format. A slashed zero
+("<code>Ø</code>") is used to indicate that all bits must be
+zero in the indicated position.</p>
+
+<p>For the most part, lettering proceeds from earlier code units to
+later code units, and low-order to high-order within a code unit.
+However, there are a few exceptions to this general rule, which are
+done in order to make the naming of similar-meaning parts be the same
+across different instruction formats. These cases are noted explicitly
+in the format descriptions.</p>
<p>For example, the format "<code>B|A|<i>op</i> CCCC</code>" indicates
that the format consists of two 16-bit code units. The first word
@@ -44,7 +51,7 @@
for the format, which is used in other documents and in code to identify
the format.</p>
-<p>Format IDs consist of three characters, two digits followed by a
+<p>Most format IDs consist of three characters, two digits followed by a
letter. The first digit indicates the number of 16-bit code units in the
format. The second digit indicates the maximum number of registers that the
format contains (maximum, since some formats can accomodate a variable
@@ -54,8 +61,14 @@
format "<code>21t</code>" is of length two, contains one register reference,
and additionally contains a branch target.</p>
-<p>Suggested static linking formats have an additional "<code>s</code>" suffix,
-making them four characters total.</p>
+<p>Suggested static linking formats have an additional
+"<code>s</code>" suffix, making them four characters total. Similarly,
+suggested "inline" linking formats have an additional "<code>i</code>"
+suffix. (In this context, inline linking is like static linking,
+except with more direct ties into a virtual machine's implementation.)
+Finally, a couple oddball suggested formats (e.g.,
+"<code>20bc</code>") include two pieces of data which are both
+represented in its format ID.</p>
<p>The full list of typecode letters are as follows. Note that some
forms have different sizes, depending on the format:</p>
@@ -171,13 +184,13 @@
<p>Similar to the representation of constant pool indices, there are
also suggested (optional) forms that indicate prelinked offsets or
-indices. These prelinked values include "<code>vtaboff</code>"
-(vtable offset), "<code>fieldoff</code>" (field offset), and
-"<code>iface</code>" (interface pool index).</p>
+indices. There are two types of suggested prelinked value: vtable offsets
+(indicated as "<code>vtaboff</code>") and field offsets (indicated as
+"<code>fieldoff</code>").</p>
<p>In the cases where a format value isn't explictly part of the syntax
but instead picks a variant, each variant is listed with the prefix
-"<code>[<i>X</i>=<i>N</i>]</code>" (e.g., "<code>[B=2]</code>") to indicate
+"<code>[<i>X</i>=<i>N</i>]</code>" (e.g., "<code>[A=2]</code>") to indicate
the correspondence.</p>
<h2>The Formats</h2>
@@ -193,6 +206,13 @@
</thead>
<tbody>
<tr>
+ <td><i>N/A</i></td>
+ <td>00x</td>
+ <td><i><code>N/A</code></i></td>
+ <td><i>pseudo-format used for unused opcodes; suggested for use as the
+ nominal format for a breakpoint opcode</i></td>
+</tr>
+<tr>
<td>ØØ|<i>op</i></td>
<td>10x</td>
<td><i><code>op</code></i></td>
@@ -227,6 +247,14 @@
<td>goto/16</td>
</tr>
<tr>
+ <td>AA|<i>op</i> BBBB</td></td>
+ <td>20bc</td>
+ <td><i><code>op</code></i> AA, kind@BBBB</td>
+ <td><i>suggested format for statically determined verification errors;
+ A is the type of error and B is an index into a type-appropriate
+ table (e.g. method references for a no-such-method error)</i></td>
+</tr>
+<tr>
<td rowspan="5">AA|<i>op</i> BBBB</td>
<td>22x</td>
<td><i><code>op</code></i> vAA, vBBBB</td>
@@ -292,8 +320,8 @@
<tr>
<td>22cs</td>
<td><i><code>op</code></i> vA, vB, fieldoff@CCCC</td>
- <td><i>(suggested format for statically linked field access instructions of
- format 22c)</i>
+ <td><i>suggested format for statically linked field access instructions of
+ format 22c</i>
</td>
</tr>
<tr>
@@ -325,96 +353,99 @@
<td>const-string/jumbo</td>
</tr>
<tr>
- <td>B|A|<i>op</i> CCCC G|F|E|D</td>
+ <td rowspan="3">A|G|<i>op</i> BBBB F|E|D|C</td>
<td>35c</td>
- <td><i>[<code>B=5</code>] <code>op</code></i> {vD, vE, vF, vG, vA},
- meth@CCCC<br/>
- <i>[<code>B=5</code>] <code>op</code></i> {vD, vE, vF, vG, vA},
- type@CCCC<br/>
- <i>[<code>B=4</code>] <code>op</code></i> {vD, vE, vF, vG},
- <i><code>kind</code></i>@CCCC<br/>
- <i>[<code>B=3</code>] <code>op</code></i> {vD, vE, vF},
- <i><code>kind</code></i>@CCCC<br/>
- <i>[<code>B=2</code>] <code>op</code></i> {vD, vE},
- <i><code>kind</code></i>@CCCC<br/>
- <i>[<code>B=1</code>] <code>op</code></i> {vD},
- <i><code>kind</code></i>@CCCC<br/>
- <i>[<code>B=0</code>] <code>op</code></i> {},
- <i><code>kind</code></i>@CCCC
+ <td><i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG},
+ meth@BBBB<br/>
+ <i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG},
+ type@BBBB<br/>
+ <i>[<code>A=4</code>] <code>op</code></i> {vC, vD, vE, vF},
+ <i><code>kind</code></i>@BBBB<br/>
+ <i>[<code>A=3</code>] <code>op</code></i> {vC, vD, vE},
+ <i><code>kind</code></i>@BBBB<br/>
+ <i>[<code>A=2</code>] <code>op</code></i> {vC, vD},
+ <i><code>kind</code></i>@BBBB<br/>
+ <i>[<code>A=1</code>] <code>op</code></i> {vC},
+ <i><code>kind</code></i>@BBBB<br/>
+ <i>[<code>A=0</code>] <code>op</code></i> {},
+ <i><code>kind</code></i>@BBBB<br/>
+ <p><i>The unusual choice in lettering here reflects a desire to make
+ the count and the reference index have the same label as in format
+ 3rc.</i></p>
</td>
<td> </td>
</tr>
<tr>
- <td>B|A|<i>op</i> CCCC G|F|E|D</td>
<td>35ms</td>
-
- <td><i>[<code>B=5</code>] <code>op</code></i> {vD, vE, vF, vG, vA},
- vtaboff@CCCC<br/>
- <i>[<code>B=4</code>] <code>op</code></i> {vD, vE, vF, vG},
- vtaboff@CCCC<br/>
- <i>[<code>B=3</code>] <code>op</code></i> {vD, vE, vF},
- vtaboff@CCCC<br/>
- <i>[<code>B=2</code>] <code>op</code></i> {vD, vE},
- vtaboff@CCCC<br/>
- <i>[<code>B=1</code>] <code>op</code></i> {vD},
- vtaboff@CCCC<br/>
+ <td><i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG},
+ vtaboff@BBBB<br/>
+ <i>[<code>A=4</code>] <code>op</code></i> {vC, vD, vE, vF},
+ vtaboff@BBBB<br/>
+ <i>[<code>A=3</code>] <code>op</code></i> {vC, vD, vE},
+ vtaboff@BBBB<br/>
+ <i>[<code>A=2</code>] <code>op</code></i> {vC, vD},
+ vtaboff@BBBB<br/>
+ <i>[<code>A=1</code>] <code>op</code></i> {vC},
+ vtaboff@BBBB<br/>
+ <p><i>The unusual choice in lettering here reflects a desire to make
+ the count and the reference index have the same label as in format
+ 3rms.</i></p>
</td>
- <td><i>(suggested format for statically linked <code>invoke-virtual</code>
- and <code>invoke-super</code> instructions of format 35c)</i>
+ <td><i>suggested format for statically linked <code>invoke-virtual</code>
+ and <code>invoke-super</code> instructions of format 35c</i>
</td>
</tr>
<tr>
- <td>B|A|<i>op</i> DDCC H|G|F|E</td>
- <td>35fs</td>
- <td><i>[<code>B=5</code>] <code>op</code></i> {vE, vF, vG, vH, vA},
- vtaboff@CC, iface@DD<br/>
- <i>[<code>B=4</code>] <code>op</code></i> {vE, vF, vG, vH},
- vtaboff@CC, iface@DD<br/>
- <i>[<code>B=3</code>] <code>op</code></i> {vE, vF, vG},
- vtaboff@CC, iface@DD<br/>
- <i>[<code>B=2</code>] <code>op</code></i> {vE, vF},
- vtaboff@CC, iface@DD<br/>
- <i>[<code>B=1</code>] <code>op</code></i> {vE},
- vtaboff@CC, iface@DD<br/>
+ <td>35mi</td>
+ <td><i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG},
+ inline@BBBB<br/>
+ <i>[<code>A=4</code>] <code>op</code></i> {vC, vD, vE, vF},
+ inline@BBBB<br/>
+ <i>[<code>A=3</code>] <code>op</code></i> {vC, vD, vE},
+ inline@BBBB<br/>
+ <i>[<code>A=2</code>] <code>op</code></i> {vC, vD},
+ inline@BBBB<br/>
+ <i>[<code>A=1</code>] <code>op</code></i> {vC},
+ inline@BBBB<br/>
+ <p><i>The unusual choice in lettering here reflects a desire to make
+ the count and the reference index have the same label as in format
+ 3rmi.</i></p>
</td>
- <td><i>(suggested format for statically linked <code>invoke-interface</code>
- instructions of format 35c)</i>
+ <td><i>suggested format for inline linked <code>invoke-static</code>
+ and <code>invoke-virtual</code> instructions of format 35c</i>
</td>
</tr>
<tr>
- <td>AA|<i>op</i> BBBB CCCC</td>
+ <td rowspan="3">AA|<i>op</i> BBBB CCCC</td>
<td>3rc</td>
<td><i><code>op</code></i> {vCCCC .. vNNNN}, meth@BBBB<br/>
<i><code>op</code></i> {vCCCC .. vNNNN}, type@BBBB<br/>
- <p><i>(where <code>NNNN = CCCC+AA-1</code>, that is <code>A</code>
+ <p><i>where <code>NNNN = CCCC+AA-1</code>, that is <code>A</code>
determines the count <code>0..255</code>, and <code>C</code>
- determines the first register)</i></p>
+ determines the first register</i></p>
</td>
<td> </td>
</tr>
<tr>
- <td>AA|<i>op</i> BBBB CCCC</td>
<td>3rms</td>
<td><i><code>op</code></i> {vCCCC .. vNNNN}, vtaboff@BBBB<br/>
- <p><i>(where <code>NNNN = CCCC+AA-1</code>, that is <code>A</code>
+ <p><i>where <code>NNNN = CCCC+AA-1</code>, that is <code>A</code>
determines the count <code>0..255</code>, and <code>C</code>
- determines the first register)</i></p>
+ determines the first register</i></p>
</td>
- <td><i>(suggested format for statically linked <code>invoke-virtual</code>
- and <code>invoke-super</code> instructions of format <code>3rc</code>)</i>
+ <td><i>suggested format for statically linked <code>invoke-virtual</code>
+ and <code>invoke-super</code> instructions of format <code>3rc</code></i>
</td>
</tr>
<tr>
- <td>AA|<i>op</i> CCBB DDDD</td>
- <td>3rfs</td>
- <td><i><code>op</code></i> {vDDDD .. vNNNN}, vtaboff@BB,
- iface@CC<br/>
- <p><i>(where <code>NNNN = DDDD+AA-1</code>, that is <code>A</code>
- determines the count <code>0..255</code>, and <code>D</code>
- determines the first register)</i></p>
+ <td>3rmi</td>
+ <td><i><code>op</code></i> {vCCCC .. vNNNN}, inline@BBBB<br/>
+ <p><i>where <code>NNNN = CCCC+AA-1</code>, that is <code>A</code>
+ determines the count <code>0..255</code>, and <code>C</code>
+ determines the first register</i></p>
</td>
- <td><i>(suggested format for statically linked <code>invoke-interface</code>
- instructions of format <code>3rc</code>)</i>
+ <td><i>suggested format for inline linked <code>invoke-static</code>
+ and <code>invoke-virtual</code> instructions of format 3rc</i>
</td>
</tr>
<tr>
diff --git a/src/tech/datausage/excluding-network-types.md b/src/tech/datausage/excluding-network-types.md
new file mode 100644
index 0000000..dcaf64f
--- /dev/null
+++ b/src/tech/datausage/excluding-network-types.md
@@ -0,0 +1,29 @@
+<!--
+ Copyright 2012 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+A mobile operator may wish to exclude specific network types from the
+total data usage calculated by a device. For example, network traffic
+over an MMS APN may be “zero-rated” by a mobile operator. To support
+this, the set of network types used to calculate total data usage can
+be configured through the `config_data_usage_network_types` resource
+at build time.
+
+Some mobile radio implementations may have unique Linux network
+interfaces for each active APN, while other radios may force multiple
+APNs to coexist on a single interface. Android can collect network
+statistics from both designs, but `config_data_usage_network_types` is
+not be effective at excluding APNs forced to coexist on a single
+interface.
diff --git a/src/tech/datausage/iface-overview.md b/src/tech/datausage/iface-overview.md
new file mode 100644
index 0000000..fd1e3cc
--- /dev/null
+++ b/src/tech/datausage/iface-overview.md
@@ -0,0 +1,49 @@
+<!--
+ Copyright 2012 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+
+In Android 4.0, statistics reported by Linux network interfaces are
+recorded over time, and are used to enforce network quota limits,
+render user-visible charts, and more.
+
+Each network device driver (Wi-Fi included) must follow the standard
+kernel device lifecycle, and return correct statistics through
+`dev_get_stats()`. In particular, statistics returned must remain
+strictly monotonic while the interface is active. Drivers may reset
+statistics only after successfully completing an `unregister_netdev()`
+or the equivalent that generates a `NETDEV_UNREGISTER` event for
+callbacks registered with `register_netdevice_notifier()` /
+`register_inetaddr_notifier()` / `register_inet6addr_notifier()`.
+
+Mobile operators typically measure data usage at the Internet layer
+(IP). To match this approach in Android 4.0, we rely on the fact that
+for the kernel devices we care about the `rx_bytes` and `tx_bytes`
+values returned by `dev_get_stats()` return exactly the Internet layer
+(`IP`) bytes transferred. But we understand that for other devices it
+might not be the case. For now, the feature relies on this
+peculiarity. New drivers should have that property also, and the
+`dev_get_stats()` values must not include any encapsulation overhead
+of lower network layers (such as Ethernet headers), and should
+preferably not include other traffic (such as ARP) unless it is
+negligible.
+
+The Android framework only collects statistics from network interfaces
+associated with a `NetworkStateTracker` in `ConnectivityService`. This
+enables the framework to concretely identify each network interface,
+including its type (such as `TYPE_MOBILE` or `TYPE_WIFI`) and
+subscriber identity (such as IMSI). All network interfaces used to
+route data should be represented by a `NetworkStateTracker` so that
+statistics can be accounted correctly.
diff --git a/src/tech/datausage/index.md b/src/tech/datausage/index.md
new file mode 100644
index 0000000..279f851
--- /dev/null
+++ b/src/tech/datausage/index.md
@@ -0,0 +1,37 @@
+<!--
+ Copyright 2012 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Data Usage Technical Information #
+
+Android 4.0 (Ice Cream Sandwich) introduces new features that help
+users understand and control how their device uses network data. It
+monitors overall data usage, and supports warning or limit thresholds
+which will trigger notifications or disable mobile data when usage
+exceeds a specific quota.
+
+Data usage is also tracked on a per-application basis, enabling users
+to visually explore historical usage in the Settings app. Users can
+also restrict how specific applications are allowed to use data when
+running in the background.
+
+The documentation in this section is intended for systems integrators
+and mobile operators, to help explain technical details they should be
+aware of when porting Android to specific devices. These details are
+summarized below, and the
+[android-porting](mailto:android-porting+subscribe@googlegroups.com)
+mailing list is a good place for further discussion.
+
+
diff --git a/src/tech/datausage/kernel-changes.md b/src/tech/datausage/kernel-changes.md
new file mode 100644
index 0000000..f89847f
--- /dev/null
+++ b/src/tech/datausage/kernel-changes.md
@@ -0,0 +1,29 @@
+<!--
+ Copyright 2012 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+This is a summary of the main changes in the kernel that diverge from mainline.
+
+* added net/netfilter/xt_qtaguid*
+* imported then modified net/netfilter/xt_quota2.c from xtables-addons project
+* fixes in net/netfilter/ip6_tables.c
+* modified ip*t_REJECT.c
+* modified net/netfilter/xt_socket.c
+
+A few comments on the kernel configuration:
+
+* xt_qtaguid masquerades as xt_owner and relies on xt_socket and itself relies on the connection tracker.
+* The connection tracker can't handle large SIP packets, it must be disabled.
+* The modified xt_quota2 uses the NFLOG support to notify userspace.
diff --git a/src/tech/datausage/kernel-overview.md b/src/tech/datausage/kernel-overview.md
new file mode 100644
index 0000000..d21e0a3
--- /dev/null
+++ b/src/tech/datausage/kernel-overview.md
@@ -0,0 +1,55 @@
+<!--
+ Copyright 2012 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Overview #
+
+The per-application/delegated data usage monitoring and tracking
+functionality relies on the xt_qtaguid module in the android-3.0 Linux
+kernel (`kernel/net/netfilter/xt_qtaguid`). The socket tagging
+functionality in the framework (`system/core/libcutils/qtaguid.c`)
+relies mainly on the existence of `/proc/net/xt_qtaguid/ctrl`
+interface exported by the `xt_qtaguid` kernel module.
+
+The `quota2` netfilter module (originally part of `xtables-addons`)
+allows the functionality to set named quota limits and was extended to
+support notifying userspace when certain limits are reached. Once the
+quota limit is reached, the `quota2` module discards all subsequent
+network traffic. The framework can also specify additional rules to
+restrict background data traffic for an application (refer to
+`com.android.server.NetworkManagementSocketTagger.setKernelCounterSet`
+and
+`android.net.NetworkPolicyManager.POLICY_REJECT_METERED_BACKGROUND`).
+
+# How does it work? #
+
+The `qtaguid` netfilter module tracks the network traffic on a
+per-socket basis for every application using the unique UID of the
+owning application. There are two tag components associated with any
+socket in the system. The first is the UID which uniquely identifies
+the application which is responsible for the data transfer (Linux
+allows the ability to ascribe the ownership of each network socket to
+the UID of the calling application). The second tag component is used
+to support additional characterization of the traffic into application
+developer specified categories. Using these application level tags, an
+application can profile the traffic into several sub-categories.
+
+In the case of applications that provide network data transfer as a
+service, such as the download manager, media streaming service, etc,
+it is possible to attribute the ownership of the network data transfer
+to the UID of the requesting application using the
+`TrafficStats.setThreadStatsUid()` function call. The caller must hold
+the “`android.permission.MODIFY_NETWORK_ACCOUNTING`” permission to
+re-assign the ownership of the network traffic.
diff --git a/src/tech/datausage/sidebar2.md b/src/tech/datausage/sidebar2.md
new file mode 100644
index 0000000..348c684
--- /dev/null
+++ b/src/tech/datausage/sidebar2.md
@@ -0,0 +1,11 @@
+# Network interface statistics #
+- [Overview](/tech/datausage/iface-overview.html)
+- [Excluding network types from data usage](/tech/datausage/excluding-network-types.html)
+- [Tethering data](/tech/datausage/tethering-data.html)
+- [Usage cycle reset dates](/tech/datausage/usage-cycle-resets-dates.html)
+
+# The xt_qtaguid netfilter kernel module #
+- [Overview](/tech/datausage/kernel-overview.html)
+- [Data usage tags explained](/tech/datausage/tags-explained.html)
+- [Kernel changes](/tech/datausage/kernel-changes.html)
+
diff --git a/src/tech/datausage/tags-explained.md b/src/tech/datausage/tags-explained.md
new file mode 100644
index 0000000..90b6a29
--- /dev/null
+++ b/src/tech/datausage/tags-explained.md
@@ -0,0 +1,48 @@
+<!--
+ Copyright 2012 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+Tags represent one of the metrics the data usage counters will be
+tracked against. By default, and implicitly, a tag is just based on
+the UID. The UID is used as the base for policing, and cannot be
+ignored. So a tag will always at least represent a UID (uid_tag). A
+tag can be explicitly augmented with an "accounting tag" which is
+associated with a UID. User space can use
+`TrafficStats.setThreadStatsTag()` to set the acct_tag portion of the
+tag which is then used with sockets: all data belonging to that
+socket will be counted against the tag. The policing is then based on
+the tag's uid_tag portion, and stats are collected for the acct_tag
+portion separately.
+
+Without explicit tagging, the qtaguid module will assume the
+`default_tag: {acct_tag=0, uid_tag=10003}`
+
+ a: {acct_tag=1, uid_tag=10003}
+ b: {acct_tag=2, uid_tag=10003}
+ c: {acct_tag=3, uid_tag=10003}
+
+`a, b, c…` represent explicit tags associated with specific sockets.
+
+`default_tag (acct_tag=0)` is the default accounting tag that contains
+the total traffic for that uid, including all untagged
+traffic, and is typically used to enforce policing/quota rules.
+
+These tags can be used to profile the network traffic of an
+application into separate logical categories (at a network socket
+level). Such tags can be removed, reapplied, or modified during
+runtime.
+
+The qtaguid module has been implemented on [kernel/common branch of
+android-3.0](https://android-review.googlesource.com/#/q/project:kernel/common+branch:android-3.0,n,z)
diff --git a/src/tech/datausage/tethering-data.md b/src/tech/datausage/tethering-data.md
new file mode 100644
index 0000000..0bc8f89
--- /dev/null
+++ b/src/tech/datausage/tethering-data.md
@@ -0,0 +1,20 @@
+<!--
+ Copyright 2012 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+Tethering involves forwarding of traffic from one network interface to
+another using `iptables` forwarding rules. The framework periodically
+records tethering statistics between any interface pairs returned by
+`ConnectivityService.getTetheredIfacePairs()`.
diff --git a/src/tech/datausage/usage-cycle-resets-dates.md b/src/tech/datausage/usage-cycle-resets-dates.md
new file mode 100644
index 0000000..9bddad6
--- /dev/null
+++ b/src/tech/datausage/usage-cycle-resets-dates.md
@@ -0,0 +1,22 @@
+<!--
+ Copyright 2012 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+Users can specify a day of month upon which their data usage
+resets. Internally, cycle boundaries are defined to end at midnight
+`(00:00) UTC` on the requested day. When a month is shorter than the
+requested day, the cycle resets on the first day of the subsequent
+month. For example, a cycle reset day of the 30th would cause a reset
+on January 30 at `00:00 UTC` and March 1 at `00:00 UTC`.
diff --git a/src/tech/index.md b/src/tech/index.md
index f7aa958..d871a9a 100644
--- a/src/tech/index.md
+++ b/src/tech/index.md
@@ -52,3 +52,19 @@
core Android platform.
[» Android Security Overview](/tech/security/index.html)
+
+## Input Technical Information ##
+Android's input subsystem is responsible for supporting touch screens,
+keyboard, joysticks, mice and other devices.
+
+[» Input Information](/tech/input/index.html)
+
+## Data Usage Technical Information ##
+Android's data usage features allow users to understand and control how their
+device uses network data. This document is designed for systems integrators
+and mobile operators, to help explain technical details they should be aware
+of when porting Android to specific devices.
+
+[» Data Usage Information](/tech/datausage/index.html)
+
+
diff --git a/src/tech/input/dumpsys.md b/src/tech/input/dumpsys.md
new file mode 100644
index 0000000..883e8c4
--- /dev/null
+++ b/src/tech/input/dumpsys.md
@@ -0,0 +1,347 @@
+<!--
+ Copyright 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Dumpsys #
+
+The `dumpsys` tool runs on the device and dumps interesting information
+about the status of system services.
+
+## Usage ##
+
+The input system is part of the window manager. To dump its state,
+run the following command.
+
+ $ adb shell su -- dumpsys window
+
+ WINDOW MANAGER INPUT (dumpsys window input)
+ Event Hub State:
+ BuiltInKeyboardId: -1
+ Devices:
+ ...
+
+The set of information that is reported varies depending on the version of Android.
+
+### Event Hub State ###
+
+The `EventHub` component is responsible for communicating with the kernel device
+drivers and identifying device capabilities. Accordingly, its state shows
+information about how devices are configured.
+
+ Event Hub State:
+ BuiltInKeyboardId: -1
+ Devices:
+ 3: tuna-gpio-keypad
+ Classes: 0x00000001
+ Path: /dev/input/event2
+ Location:
+ UniqueId:
+ Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
+ KeyLayoutFile: /system/usr/keylayout/tuna-gpio-keypad.kl
+ KeyCharacterMapFile: /system/usr/keychars/tuna-gpio-keypad.kcm
+ ConfigurationFile:
+ 5: Tuna Headset Jack
+ Classes: 0x00000080
+ Path: /dev/input/event5
+ Location: ALSA
+ UniqueId:
+ Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
+ KeyLayoutFile:
+ KeyCharacterMapFile:
+ ConfigurationFile:
+ 6: Melfas MMSxxx Touchscreen
+ Classes: 0x00000014
+ Path: /dev/input/event1
+ Location: 3-0048/input0
+ UniqueId:
+ Identifier: bus=0x0018, vendor=0x0000, product=0x0000, version=0x0000
+ KeyLayoutFile:
+ KeyCharacterMapFile:
+ ConfigurationFile: /system/usr/idc/Melfas_MMSxxx_Touchscreen.idc
+ 7: Motorola Bluetooth Wireless Keyboard
+ Classes: 0x8000000b
+ Path: /dev/input/event6
+ Location: 0C:DF:A4:B3:2D:BA
+ UniqueId: 00:0F:F6:80:02:CD
+ Identifier: bus=0x0005, vendor=0x22b8, product=0x093d, version=0x0288
+ KeyLayoutFile: /system/usr/keylayout/Vendor_22b8_Product_093d.kl
+ KeyCharacterMapFile: /system/usr/keychars/Generic.kcm
+ ConfigurationFile:
+
+#### Things To Look For ####
+
+1. All of the expected input devices are present.
+
+2. Each input device has an appropriate key layout file, key character map file
+ and input device configuration file. If the files are missing or contain
+ syntax errors, then they will not be loaded.
+
+3. Each input device is being classified correctly. The bits in the `Classes`
+ field correspond to flags in `EventHub.h` such as `INPUT_DEVICE_CLASS_TOUCH_MT`.
+
+4. The `BuiltInKeyboardId` is correct. If the device does not have a built-in keyboard,
+ then the id must be `-1`, otherwise it should be the id of the built-in keyboard.
+
+ If you observe that the `BuiltInKeyboardId` is not `-1` but it should be, then
+ you are missing a key character map file for a special function keypad somewhere.
+ Special function keypad devices should have key character map files that contain
+ just the line `type SPECIAL_FUNCTION` (that's what in the `tuna-gpio-keykad.kcm`
+ file we see mentioned above).
+
+### Input Reader State ###
+
+The `InputReader` is responsible for decoding input events from the kernel.
+Its state dump shows information about how each input device is configured
+and recent state changes that occurred, such as key presses or touches on
+the touch screen.
+
+This is what a special function keypad looks like:
+
+ Input Reader State:
+ Device 3: tuna-gpio-keypad
+ IsExternal: false
+ Sources: 0x00000101
+ KeyboardType: 1
+ Keyboard Input Mapper:
+ Parameters:
+ AssociatedDisplayId: -1
+ OrientationAware: false
+ KeyboardType: 1
+ Orientation: 0
+ KeyDowns: 0 keys currently down
+ MetaState: 0x0
+ DownTime: 75816923828000
+
+Here is a touch screen. Notice all of the information about the resolution of
+the device and the calibration parameters that were used.
+
+ Device 6: Melfas MMSxxx Touchscreen
+ IsExternal: false
+ Sources: 0x00001002
+ KeyboardType: 0
+ Motion Ranges:
+ X: source=0x00001002, min=0.000, max=719.001, flat=0.000, fuzz=0.999
+ Y: source=0x00001002, min=0.000, max=1279.001, flat=0.000, fuzz=0.999
+ PRESSURE: source=0x00001002, min=0.000, max=1.000, flat=0.000, fuzz=0.000
+ SIZE: source=0x00001002, min=0.000, max=1.000, flat=0.000, fuzz=0.000
+ TOUCH_MAJOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000
+ TOUCH_MINOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000
+ TOOL_MAJOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000
+ TOOL_MINOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000
+ Touch Input Mapper:
+ Parameters:
+ GestureMode: spots
+ DeviceType: touchScreen
+ AssociatedDisplay: id=0, isExternal=false
+ OrientationAware: true
+ Raw Touch Axes:
+ X: min=0, max=720, flat=0, fuzz=0, resolution=0
+ Y: min=0, max=1280, flat=0, fuzz=0, resolution=0
+ Pressure: min=0, max=255, flat=0, fuzz=0, resolution=0
+ TouchMajor: min=0, max=30, flat=0, fuzz=0, resolution=0
+ TouchMinor: unknown range
+ ToolMajor: unknown range
+ ToolMinor: unknown range
+ Orientation: unknown range
+ Distance: unknown range
+ TiltX: unknown range
+ TiltY: unknown range
+ TrackingId: min=0, max=65535, flat=0, fuzz=0, resolution=0
+ Slot: min=0, max=9, flat=0, fuzz=0, resolution=0
+ Calibration:
+ touch.size.calibration: diameter
+ touch.size.scale: 10.000
+ touch.size.bias: 0.000
+ touch.size.isSummed: false
+ touch.pressure.calibration: amplitude
+ touch.pressure.scale: 0.005
+ touch.orientation.calibration: none
+ touch.distance.calibration: none
+ SurfaceWidth: 720px
+ SurfaceHeight: 1280px
+ SurfaceOrientation: 0
+ Translation and Scaling Factors:
+ XScale: 0.999
+ YScale: 0.999
+ XPrecision: 1.001
+ YPrecision: 1.001
+ GeometricScale: 0.999
+ PressureScale: 0.005
+ SizeScale: 0.033
+ OrientationCenter: 0.000
+ OrientationScale: 0.000
+ DistanceScale: 0.000
+ HaveTilt: false
+ TiltXCenter: 0.000
+ TiltXScale: 0.000
+ TiltYCenter: 0.000
+ TiltYScale: 0.000
+ Last Button State: 0x00000000
+ Last Raw Touch: pointerCount=0
+ Last Cooked Touch: pointerCount=0
+
+Here is an external keyboard / mouse combo HID device. (This device doesn't actually
+have a mouse but its HID descriptor says it does.)
+
+ Device 7: Motorola Bluetooth Wireless Keyboard
+ IsExternal: true
+ Sources: 0x00002103
+ KeyboardType: 2
+ Motion Ranges:
+ X: source=0x00002002, min=0.000, max=719.000, flat=0.000, fuzz=0.000
+ Y: source=0x00002002, min=0.000, max=1279.000, flat=0.000, fuzz=0.000
+ PRESSURE: source=0x00002002, min=0.000, max=1.000, flat=0.000, fuzz=0.000
+ VSCROLL: source=0x00002002, min=-1.000, max=1.000, flat=0.000, fuzz=0.000
+ Keyboard Input Mapper:
+ Parameters:
+ AssociatedDisplayId: -1
+ OrientationAware: false
+ KeyboardType: 2
+ Orientation: 0
+ KeyDowns: 0 keys currently down
+ MetaState: 0x0
+ DownTime: 75868832946000
+ Cursor Input Mapper:
+ Parameters:
+ AssociatedDisplayId: 0
+ Mode: pointer
+ OrientationAware: false
+ XScale: 1.000
+ YScale: 1.000
+ XPrecision: 1.000
+ YPrecision: 1.000
+ HaveVWheel: true
+ HaveHWheel: false
+ VWheelScale: 1.000
+ HWheelScale: 1.000
+ Orientation: 0
+ ButtonState: 0x00000000
+ Down: false
+ DownTime: 0
+
+Here is a joystick. Notice how all of the axes have been scaled to a normalized
+range. The axis mapping can be configured using key layout files.
+
+ Device 18: Logitech Logitech Cordless RumblePad 2
+ IsExternal: true
+ Sources: 0x01000511
+ KeyboardType: 1
+ Motion Ranges:
+ X: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000
+ Y: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000
+ Z: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000
+ RZ: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000
+ HAT_X: source=0x01000010, min=-1.000, max=1.000, flat=0.000, fuzz=0.000
+ HAT_Y: source=0x01000010, min=-1.000, max=1.000, flat=0.000, fuzz=0.000
+ Keyboard Input Mapper:
+ Parameters:
+ AssociatedDisplayId: -1
+ OrientationAware: false
+ KeyboardType: 1
+ Orientation: 0
+ KeyDowns: 0 keys currently down
+ MetaState: 0x0
+ DownTime: 675270841000
+ Joystick Input Mapper:
+ Axes:
+ X: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000
+ scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000
+ rawAxis=0, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0
+ Y: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000
+ scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000
+ rawAxis=1, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0
+ Z: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000
+ scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000
+ rawAxis=2, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0
+ RZ: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000
+ scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000
+ rawAxis=5, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0
+ HAT_X: min=-1.00000, max=1.00000, flat=0.00000, fuzz=0.00000
+ scale=1.00000, offset=0.00000, highScale=1.00000, highOffset=0.00000
+ rawAxis=16, rawMin=-1, rawMax=1, rawFlat=0, rawFuzz=0, rawResolution=0
+ HAT_Y: min=-1.00000, max=1.00000, flat=0.00000, fuzz=0.00000
+ scale=1.00000, offset=0.00000, highScale=1.00000, highOffset=0.00000
+ rawAxis=17, rawMin=-1, rawMax=1, rawFlat=0, rawFuzz=0, rawResolution=0
+
+At the end of the input reader dump there is some information about global configuration
+parameters such as the mouse pointer speed.
+
+ Configuration:
+ ExcludedDeviceNames: []
+ VirtualKeyQuietTime: 0.0ms
+ PointerVelocityControlParameters: scale=1.000, lowThreshold=500.000, highThreshold=3000.000, acceleration=3.000
+ WheelVelocityControlParameters: scale=1.000, lowThreshold=15.000, highThreshold=50.000, acceleration=4.000
+ PointerGesture:
+ Enabled: true
+ QuietInterval: 100.0ms
+ DragMinSwitchSpeed: 50.0px/s
+ TapInterval: 150.0ms
+ TapDragInterval: 300.0ms
+ TapSlop: 20.0px
+ MultitouchSettleInterval: 100.0ms
+ MultitouchMinDistance: 15.0px
+ SwipeTransitionAngleCosine: 0.3
+ SwipeMaxWidthRatio: 0.2
+ MovementSpeedRatio: 0.8
+ ZoomSpeedRatio: 0.3
+
+#### Things To Look For ####
+
+1. All of the expected input devices are present.
+
+2. Each input device has been configured appropriately. Especially check the
+ touch screen and joystick axes.
+
+### Input Dispatcher State ###
+
+The `InputDispatcher` is responsible for sending input events to applications.
+Its state dump shows information about which window is being touched, the
+state of the input queue, whether an ANR is in progress, and so on.
+
+ Input Dispatcher State:
+ DispatchEnabled: 1
+ DispatchFrozen: 0
+ FocusedApplication: name='AppWindowToken{41b03a10 token=Token{41bdcf78 ActivityRecord{418ab728 com.android.settings/.Settings}}}', dispatchingTimeout=5000.000ms
+ FocusedWindow: name='Window{41908458 Keyguard paused=false}'
+ TouchDown: false
+ TouchSplit: false
+ TouchDeviceId: -1
+ TouchSource: 0x00000000
+ TouchedWindows: <none>
+ Windows:
+ 0: name='Window{41bd5b18 NavigationBar paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x05800068, type=0x000007e3, layer=181000, frame=[0,1184][720,1280], scale=1.000000, touchableRegion=[0,1184][720,1280], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms
+ 1: name='Window{41a19770 RecentsPanel paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01820100, type=0x000007de, layer=151000, frame=[0,0][720,1184], scale=1.000000, touchableRegion=[0,0][720,1184], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms
+ 2: name='Window{41a78768 StatusBar paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x00800048, type=0x000007d0, layer=141000, frame=[0,0][720,50], scale=1.000000, touchableRegion=[0,0][720,50], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms
+ 3: name='Window{41877570 StatusBarExpanded paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x01811328, type=0x000007e1, layer=131005, frame=[0,-1184][720,-114], scale=1.000000, touchableRegion=[0,-1184][720,-114], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms
+ 4: name='Window{41bedf20 TrackingView paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01020300, type=0x000007e1, layer=131000, frame=[0,-1032][720,102], scale=1.000000, touchableRegion=[0,-1032][720,102], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms
+ 5: name='Window{41908458 Keyguard paused=false}', paused=false, hasFocus=true, hasWallpaper=false, visible=true, canReceiveKeys=true, flags=0x15120800, type=0x000007d4, layer=111000, frame=[0,50][720,1184], scale=1.000000, touchableRegion=[0,50][720,1184], inputFeatures=0x00000000, ownerPid=205, ownerUid=1000, dispatchingTimeout=5000.000ms
+ 6: name='Window{4192cc30 com.android.phasebeam.PhaseBeamWallpaper paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x00000308, type=0x000007dd, layer=21010, frame=[0,0][720,1184], scale=1.000000, touchableRegion=[0,0][720,1184], inputFeatures=0x00000000, ownerPid=429, ownerUid=10046, dispatchingTimeout=5000.000ms
+ 7: name='Window{41866c00 com.android.settings/com.android.settings.Settings paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01810100, type=0x00000001, layer=21005, frame=[0,0][720,1184], scale=1.000000, touchableRegion=[0,0][720,1184], inputFeatures=0x00000000, ownerPid=19000, ownerUid=1000, dispatchingTimeout=5000.000ms
+ 8: name='Window{4197c858 com.android.launcher/com.android.launcher2.Launcher paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01910100, type=0x00000001, layer=21000, frame=[0,0][720,1184], scale=1.000000, touchableRegion=[0,0][720,1184], inputFeatures=0x00000000, ownerPid=515, ownerUid=10032, dispatchingTimeout=5000.000ms
+ MonitoringChannels: <none>
+ InboundQueue: length=0
+ ActiveConnections: <none>
+ AppSwitch: not pending
+ Configuration:
+ MaxEventsPerSecond: 90
+ KeyRepeatDelay: 50.0ms
+ KeyRepeatTimeout: 500.0ms
+
+#### Things To Look For ####
+
+1. In general, all input events are being processed as expected.
+
+2. If you touch the touch screen and run dumpsys at the same time, then the `TouchedWindows`
+ line should show the window that you are touching.
diff --git a/src/tech/input/getevent.md b/src/tech/input/getevent.md
new file mode 100644
index 0000000..5807753
--- /dev/null
+++ b/src/tech/input/getevent.md
@@ -0,0 +1,112 @@
+<!--
+ Copyright 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Getevent #
+
+The `getevent` tool runs on the device and provides information about input
+devices and a live dump of kernel input events.
+
+It is very useful tool for ensuring that device drivers are reporing the
+expected set of capabilities for each input device and are generating the
+desired stream of input events.
+
+## Usage ##
+
+### Showing Device Capabilities ###
+
+It is often quite useful to see all of the keys and axes that a device reports.
+Use the `-p` option to do that.
+
+Here is a list of all of the Linux key codes and other events that a
+particular keyboard says it supports.
+
+ $ adb shell su -- getevent -p
+
+ name: "Motorola Bluetooth Wireless Keyboard"
+ events:
+ KEY (0001): 0001 0002 0003 0004 0005 0006 0007 0008
+ 0009 000a 000b 000c 000d 000e 000f 0010
+ 0011 0012 0013 0014 0015 0016 0017 0018
+ 0019 001a 001b 001c 001d 001e 001f 0020
+ 0021 0022 0023 0024 0025 0026 0027 0028
+ 0029 002a 002b 002c 002d 002e 002f 0030
+ 0031 0032 0033 0034 0035 0036 0037 0038
+ 0039 003a 003b 003c 003d 003e 003f 0040
+ 0041 0042 0043 0044 0045 0046 0047 0048
+ 0049 004a 004b 004c 004d 004e 004f 0050
+ 0051 0052 0053 0055 0056 0057 0058 0059
+ 005a 005b 005c 005d 005e 005f 0060 0061
+ 0062 0063 0064 0066 0067 0068 0069 006a
+ 006b 006c 006d 006e 006f 0071 0072 0073
+ 0074 0075 0077 0079 007a 007b 007c 007d
+ 007e 007f 0080 0081 0082 0083 0084 0085
+ 0086 0087 0088 0089 008a 008c 008e 0090
+ 0096 0098 009b 009c 009e 009f 00a1 00a3
+ 00a4 00a5 00a6 00ab 00ac 00ad 00b0 00b1
+ 00b2 00b3 00b4 00b7 00b8 00b9 00ba 00bb
+ 00bc 00bd 00be 00bf 00c0 00c1 00c2 00d9
+ 00f0 0110 0111 0112 01ba
+ REL (0002): 0000 0001 0008
+ ABS (0003): 0028 : value 223, min 0, max 255, fuzz 0, flat 0, resolution 0
+ 0029 : value 0, min 0, max 255, fuzz 0, flat 0, resolution 0
+ 002a : value 0, min 0, max 255, fuzz 0, flat 0, resolution 0
+ 002b : value 0, min 0, max 255, fuzz 0, flat 0, resolution 0
+ MSC (0004): 0004
+ LED (0011): 0000 0001 0002 0003 0004
+ input props:
+ <none>
+
+The `-i` option shows even more information than `-p`, including HID mapping tables
+and debugging information.
+
+The `-l` option uses textual labels for all event codes, which is handy.
+
+ $ adb shell su -- getevent -lp /dev/input/event1
+
+ name: "Melfas MMSxxx Touchscreen"
+ events:
+ ABS (0003): ABS_MT_SLOT : value 0, min 0, max 9, fuzz 0, flat 0, resolution 0
+ ABS_MT_TOUCH_MAJOR : value 0, min 0, max 30, fuzz 0, flat 0, resolution 0
+ ABS_MT_POSITION_X : value 0, min 0, max 720, fuzz 0, flat 0, resolution 0
+ ABS_MT_POSITION_Y : value 0, min 0, max 1280, fuzz 0, flat 0, resolution 0
+ ABS_MT_TRACKING_ID : value 0, min 0, max 65535, fuzz 0, flat 0, resolution 0
+ ABS_MT_PRESSURE : value 0, min 0, max 255, fuzz 0, flat 0, resolution 0
+ input props:
+ INPUT_PROP_DIRECT
+
+### Showing Live Events ###
+
+This is what a two finger multitouch gesture looks like for a touch screen
+that is using the Linux multitouch input protocol "B". We use the `-l` option
+to show textual labels and `-t` to show timestamps.
+
+ $ adb shell su -- getevent -lt /dev/input/event1
+
+ [ 78826.389007] EV_ABS ABS_MT_TRACKING_ID 0000001f
+ [ 78826.389038] EV_ABS ABS_MT_PRESSURE 000000ab
+ [ 78826.389038] EV_ABS ABS_MT_POSITION_X 000000ab
+ [ 78826.389068] EV_ABS ABS_MT_POSITION_Y 0000025b
+ [ 78826.389068] EV_ABS ABS_MT_SLOT 00000001
+ [ 78826.389068] EV_ABS ABS_MT_TRACKING_ID 00000020
+ [ 78826.389068] EV_ABS ABS_MT_PRESSURE 000000b9
+ [ 78826.389099] EV_ABS ABS_MT_POSITION_X 0000019e
+ [ 78826.389099] EV_ABS ABS_MT_POSITION_Y 00000361
+ [ 78826.389099] EV_SYN SYN_REPORT 00000000
+ [ 78826.468688] EV_ABS ABS_MT_SLOT 00000000
+ [ 78826.468688] EV_ABS ABS_MT_TRACKING_ID ffffffff
+ [ 78826.468719] EV_ABS ABS_MT_SLOT 00000001
+ [ 78826.468719] EV_ABS ABS_MT_TRACKING_ID ffffffff
+ [ 78826.468719] EV_SYN SYN_REPORT 00000000
diff --git a/src/tech/input/index.md b/src/tech/input/index.md
new file mode 100644
index 0000000..e01f200
--- /dev/null
+++ b/src/tech/input/index.md
@@ -0,0 +1,24 @@
+<!--
+ Copyright 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Input Technical Information #
+
+The Android input subsystem supports many different device classes,
+including keyboard, joystick, trackball, mouse and touch screen.
+
+The documentation in this section describes how to configure,
+calibrate, test, and write drivers for input devices.
+
diff --git a/src/tech/input/input-device-configuration-files.md b/src/tech/input/input-device-configuration-files.md
new file mode 100644
index 0000000..0a477d0
--- /dev/null
+++ b/src/tech/input/input-device-configuration-files.md
@@ -0,0 +1,152 @@
+<!--
+ Copyright 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Input Device Configuration Files #
+
+Input device configuration files (`.idc` files) contain device-specific
+configuration properties that affect the behavior of input devices.
+
+Input device configuration files are typically not necessary for standard
+peripherals such as HID keyboards and mice since the default system behavior
+usually ensures that they will work out of the box. On the other hand,
+built-in embedded devices, particularly touch screens, almost always
+require input device configuration files to specify their behavior.
+
+## Rationale ##
+
+Android automatically detects and configures most input device capabilities
+based on the event types and properties that are reported by the associated
+Linux kernel input device driver.
+
+For example, if an input device supports the `EV_REL` event type and codes
+`REL_X` and `REL_Y` as well as the `EV_KEY` event type and `BTN_MOUSE`,
+then Android will classify the input device as a mouse. The default behavior
+for a mouse is to present an on-screen cursor which tracks the mouse's movements
+and simulates touches when the mouse is clicked. Although the mouse can
+be configured differently, the default behavior is usually sufficient for
+standard mouse peripherals.
+
+Certain classes of input devices are more ambiguous. For example, multi-touch
+touch screens and touch pads both support the `EV_ABS` event type and codes
+`ABS_MT_POSITION_X` and `ABS_MT_POSITION_Y` at a minimum. However, the intended
+uses of these devices are quite different and cannot always be determined
+automatically. Also, additional information is required to make sense of the
+pressure and size information reported by touch devices. Hence touch devices,
+especially built-in touch screens, usually need IDC files.
+
+## Location ##
+
+Input device configuration files are located by USB vendor, product (and
+optionally version) id or by input device name.
+
+The following paths are consulted in order.
+
+* `/system/usr/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc`
+* `/system/usr/idc/Vendor_XXXX_Product_XXXX.idc`
+* `/system/usr/idc/DEVICE_NAME.idc`
+* `/data/system/devices/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc`
+* `/data/system/devices/idc/Vendor_XXXX_Product_XXXX.idc`
+* `/data/system/devices/idc/DEVICE_NAME.idc`
+
+When constructing a file path that contains the device name, all characters
+in the device name other than '0'-'9', 'a'-'z', 'A'-'Z', '-' or '_' are replaced by '_'.
+
+## Syntax ##
+
+An input device configuration file is a plain text file consisting of property
+assignments and comments.
+
+### Properties ###
+
+Property assignments each consist of a property name, an `=`, a property value,
+and a new line. Like this:
+
+ property = value
+
+Property names are non-empty literal text identifiers. They must not contain
+whitespace. Each components of the input system defines a set of properties
+that are used to configure its function.
+
+Property values are non-empty string literals, integers or floating point numbers.
+They must not contain whitespace or the reserved characters `\` or `"`.
+
+Property names and values are case-sensitive.
+
+### Comments ###
+
+Comment lines begin with '#' and continue to the end of the line. Like this:
+
+ # A comment!
+
+Blank lines are ignored.
+
+### Example ###
+
+ # This is an example of an input device configuration file.
+ # It might be used to describe the characteristics of a built-in touch screen.
+
+ # This is an internal device, not an external peripheral attached to the USB
+ # or Bluetooth bus.
+ device.internal = 1
+
+ # The device should behave as a touch screen, which uses the same orientation
+ # as the built-in display.
+ touch.deviceType = touchScreen
+ touch.orientationAware = 1
+
+ # Additional calibration properties...
+ # etc...
+
+## Common Properties ##
+
+The following properties are common to all input device classes.
+
+Refer to the documentation of each input device class for information about the
+special properties used by each class.
+
+#### `device.internal` ####
+
+*Definition:* `device.internal` = `0` | `1`
+
+Specifies whether the input device is an internal built-in component as opposed to an
+externally attached (most likely removable) peripheral.
+
+* If the value is `0`, the device is external.
+
+* If the value is `1`, the device is internal.
+
+* If the value is not specified, the default value is `0` for all devices on the
+ USB (BUS_USB) or Bluetooth (BUS_BLUETOOTH) bus, `1` otherwise.
+
+This property determines default policy decisions regarding wake events.
+
+Internal input devices generally do not wake the display from sleep unless explicitly
+configured to do so in the key layout file or in a hardcoded policy rule. This
+distinction prevents key presses and touches from spuriously waking up your phone
+when it is in your pocket. Usually there are only a small handful of wake keys defined.
+
+Conversely, external input devices usually wake the device more aggressively because
+they are assumed to be turned off or not plugged in during transport. For example,
+pressing any key on an external keyboard is a good indicator that the user wants the
+device to wake up and respond.
+
+It is important to ensure that the value of the `device.internal` property is set
+correctly for all internal input devices.
+
+## Validation ##
+
+Make sure to validate your input device configuration files using the
+[Validate Keymaps](/tech/input/validate-keymaps.html) tool.
diff --git a/src/tech/input/key-character-map-files.md b/src/tech/input/key-character-map-files.md
new file mode 100644
index 0000000..4a9ec34
--- /dev/null
+++ b/src/tech/input/key-character-map-files.md
@@ -0,0 +1,493 @@
+<!--
+ Copyright 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Key Character Map Files #
+
+Key character map files (`.kcm` files) are responsible for mapping combinations
+of Android key codes with modifiers to Unicode characters.
+
+Device-specific key layout files are *required* for all internal (built-in)
+input devices that have keys, if only to tell the system that the device
+is special purpose only (not a full keyboard).
+
+Device-specific key layout files are *optional* for external keyboards, and
+often aren't needed at all. The system provides a generic key character map
+that is suitable for many external keyboards.
+
+If no device-specific key layout file is available, then the system will
+choose a default instead.
+
+## Location ##
+
+Key character map files are located by USB vendor, product (and optionally version)
+id or by input device name.
+
+The following paths are consulted in order.
+
+* `/system/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm`
+* `/system/usr/keychars/Vendor_XXXX_Product_XXXX.kcm`
+* `/system/usr/keychars/DEVICE_NAME.kcm`
+* `/data/system/devices/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm`
+* `/data/system/devices/keychars/Vendor_XXXX_Product_XXXX.kcm`
+* `/data/system/devices/keychars/DEVICE_NAME.kcm`
+* `/system/usr/keychars/Generic.kcm`
+* `/data/system/devices/keychars/Generic.kcm`
+* `/system/usr/keychars/Virtual.kcm`
+* `/data/system/devices/keychars/Virtual.kcm`
+
+When constructing a file path that contains the device name, all characters
+in the device name other than '0'-'9', 'a'-'z', 'A'-'Z', '-' or '_' are replaced by '_'.
+
+## Generic Key Character Map File ##
+
+The system provides a special built-in key character map file called `Generic.kcm`.
+This key character map is intended to support a variety of standard external
+keyboards.
+
+*Do not modify the generic key character map!*
+
+## Virtual Key Character Map File ##
+
+The system provides a special built-in key character map file called `Virtual.kcm`
+that is used by the virtual keyboard devices.
+
+The virtual keyboard device is a synthetic input device whose id is -1
+(see `KeyCharacterMap.VIRTUAL_KEYBOARD`). It is present on all Android devices
+beginning with Android Honeycomb 3.0. The purpose of the virtual keyboard device
+is to provide a known built-in input device that can be used for injecting
+keystokes into applications by the IME or by test instrumentation, even
+for devices that do not have built-in keyboards.
+
+The virtual keyboard is assumed to have a full QWERTY layout that is the
+same on all devices. This makes it possible for applications to inject
+keystrokes using the virtual keyboard device and always get the same results.
+
+*Do not modify the virtual key character map!*
+
+## Syntax ##
+
+A key character map file is a plain text file consisting of a keyboard type
+declaration and a set of key declarations.
+
+### Keyboard Type Declaration ###
+
+A keyboard type declaration describes the overall behavior of the keyboard.
+A character map file must contain a keyboard type declaration. For clarity,
+it is often placed at the top of the file.
+
+ type FULL
+
+The following keyboard types are recognized:
+
+* `NUMERIC`: A numeric (12-key) keyboard.
+
+ A numeric keyboard supports text entry using a multi-tap approach.
+ It may be necessary to tap a key multiple times to generate the desired letter or symbol.
+
+ This type of keyboard is generally designed for thumb typing.
+
+ Corresponds to `KeyCharacterMap.NUMERIC`.
+
+* `PREDICTIVE`: A keyboard with all the letters, but with more than one letter per key.
+
+ This type of keyboard is generally designed for thumb typing.
+
+ Corresponds to `KeyCharacterMap.PREDICTIVE`.
+
+* `ALPHA`: A keyboard with all the letters, and maybe some numbers.
+
+ An alphabetic keyboard supports text entry directly but may have a condensed
+ layout with a small form factor. In contrast to a `FULL` keyboard, some
+ symbols may only be accessible using special on-screen character pickers.
+ In addition, to improve typing speed and accuracy, the framework provides
+ special affordances for alphabetic keyboards such as auto-capitalization
+ and toggled / locked SHIFT and ALT keys.
+
+ This type of keyboard is generally designed for thumb typing.
+
+* `FULL`: A full PC-style keyboard.
+
+ A full keyboard behaves like a PC keyboard. All symbols are accessed directly
+ by pressing keys on the keyboard without on-screen support or affordances such
+ as auto-capitalization.
+
+ This type of keyboard is generally designed for full two hand typing.
+
+* `SPECIAL_FUNCTION`: A keyboard that is only used to perform system control functions
+ rather than for typing.
+
+ A special function keyboard consists only of non-printing keys such as
+ HOME and POWER that are not actually used for typing.
+
+The `Generic.kcm` and `Virtual.kcm` key character maps are both `FULL` keyboards.
+
+### Key Declarations ###
+
+Key declarations each consist of the keyword `key` followed by an Android key code
+name, an open curly brace, a set of properties and behaviors and a close curly brace.
+
+ key A {
+ label: 'A'
+ base: 'a'
+ shift, capslock: 'A'
+ ctrl, alt, meta: none
+ }
+
+#### Properties ####
+
+Each key property establishes a mapping from a key to a behavior. To make the
+key character map files more compact, several properties can be mapped to the
+same behavior by separating them with a comma.
+
+In the above example, the `label` property is assigned the `'A'` behavior.
+Likewise, the `ctrl`, `alt` and `meta` properties are all simultaneously assigned
+the `none` behavior.
+
+The following properties are recognized:
+
+* `label`: Specifies the label that is physically printed on the key, when it
+ consists of a single character. This is the value that is returned by
+ the `KeyCharacterMap.getDisplayLabel` method.
+
+* `number`: Specifies the behavior (character that should be typed) when a numeric
+ text view has focus, such as when the user is typing a phone number.
+
+ Compact keyboards often combine multiple symbols into a single key, such that
+ the same key might be used to type `'1'` and `'a'` or `'#'` and `'q'`, perhaps.
+ For these keys, the `number` property should be set to indicate which symbol
+ should be typed in a numeric context, if any.
+
+ Some typical "numeric" symbols are digits `'0'` through `'9'`, `'#'`, `'+'`,
+ `'('`, `')'`, `','`, and `'.'`.
+
+* `base`: Specifies the behavior (character that should be typed) when no modifiers
+ are pressed.
+
+* <modifier> or <modifier1>`+`<modifier2>`+`...: Specifies the
+ behavior (character that should be typed) when the key is pressed and all of the
+ specified modifiers are active.
+
+ For example, the modifier property `shift` specifies a behavior that applies when
+ the either the LEFT SHIFT or RIGHT SHIFT modifier is pressed.
+
+ Similarly, the modifier property `rshift+ralt` specifies a behavior that applies
+ when the both RIGHT SHIFT and RIGHT ALT modifiers are pressed together.
+
+The following modifiers are recognized in modifier properties:
+
+* `shift`: Applies when either the LEFT SHIFT or RIGHT SHIFT modifier is pressed.
+* `lshift`: Applies when the LEFT SHIFT modifier is pressed.
+* `rshift`: Applies when the RIGHT SHIFT modifier is pressed.
+* `alt`: Applies when either the LEFT ALT or RIGHT ALT modifier is pressed.
+* `lalt`: Applies when the LEFT ALT modifier is pressed.
+* `ralt`: Applies when the RIGHT ALT modifier is pressed.
+* `ctrl`: Applies when either the LEFT CONTROL or RIGHT CONTROL modifier is pressed.
+* `lctrl`: Applies when the LEFT CONTROL modifier is pressed.
+* `rctrl`: Applies when the RIGHT CONTROL modifier is pressed.
+* `meta`: Applies when either the LEFT META or RIGHT META modifier is pressed.
+* `lmeta`: Applies when the LEFT META modifier is pressed.
+* `rmeta`: Applies when the RIGHT META modifier is pressed.
+* `sym`: Applies when the SYMBOL modifier is pressed.
+* `fn`: Applies when the FUNCTION modifier is pressed.
+* `capslock`: Applies when the CAPS LOCK modifier is locked.
+* `numlock`: Applies when the NUM LOCK modifier is locked.
+* `scrolllock`: Applies when the SCROLL LOCK modifier is locked.
+
+The order in which the properties are listed is significant. When mapping a key to
+a behavior, the system scans all relevant properties in order and returns the last
+applicable behavior that it found.
+
+Consequently, properties that are specified later override properties that are
+specified earlier for a given key.
+
+#### Behaviors ####
+
+Each property maps to a behavior. The most common behavior is typing a character
+but there are others.
+
+The following behaviors are recognized:
+
+* `none`: Don't type a character.
+
+ This behavior is the default when no character is specified. Specifying `none`
+ is optional but it improves clarity.
+
+* `'X'`: Type the specified character literal.
+
+ This behavior causes the specified character to be entered into the focused
+ text view. The character literal may be any ASCII character, or one of the
+ following escape sequences:
+
+ * `'\\'`: Type a backslash character.
+ * `'\n'`: Type a new line character (use this for ENTER / RETURN).
+ * `'\t'`: Type a TAB character.
+ * `'\''`: Type an apostrophe character.
+ * `'\"'`: Type a quote character.
+ * `'\uXXXX'`: Type the Unicode character whose code point is given in hex by XXXX.
+
+* `fallback` <Android key code name>: Perform a default action if the key is not
+ handled by the application.
+
+ This behavior causes the system to simulate a different key press when an application
+ does not handle the specified key natively. It is used to support default behavior
+ for new keys that not all applications know how to handle, such as ESCAPE or
+ numeric keypad keys (when numlock is not pressed).
+
+ When a fallback behavior is performed, the application will receive two key presses:
+ one for the original key and another for the fallback key that was selected.
+ If the application handles the original key during key up, then the fallback key
+ event will be canceled (`KeyEvent.isCanceled` will return `true`).
+
+The system reserves two Unicode characters to perform special functions:
+
+* `'\uef00'`: When this behavior is performed, the text view consumes and removes the
+ four characters preceding the cursor, interprets them as hex digits, and inserts the
+ corresponding Unicode code point.
+
+* `'\uef01'`: When this behavior is performed, the text view displays a
+ character picker dialog that contains miscellaneous symbols.
+
+The system recognizes the following Unicode characters as combining diacritical dead
+key characters:
+
+* `'\u0300'`: Grave accent.
+* `'\u0301'`: Acute accent.
+* `'\u0302'`: Circumflex accent.
+* `'\u0303'`: Tilde accent.
+* `'\u0308'`: Umlaut accent.
+
+When a dead key is typed followed by another character, the dead key and the following
+characters are composed. For example, when the user types a grave accent dead
+key followed by the letter 'a', the result is 'à'.
+
+Refer to `KeyCharacterMap.getDeadChar` for more information about dead key handling.
+
+### Comments ###
+
+Comment lines begin with '#' and continue to the end of the line. Like this:
+
+ # A comment!
+
+Blank lines are ignored.
+
+### How Key Combinations are Mapped to Behaviors ###
+
+When the user presses a key, the system looks up the behavior associated with
+the combination of that key press and the currently pressed modifiers.
+
+#### SHIFT + A ####
+
+Suppose the user pressed A and SHIFT together. The system first locates
+the set of properties and behaviors associated with `KEYCODE_A`.
+
+ key A {
+ label: 'A'
+ base: 'a'
+ shift, capslock: 'A'
+ ctrl, alt, meta: none
+ }
+
+The system scans the properties from first to last and left to right, ignoring
+the `label` and `number` properties, which are special.
+
+The first property encountered is `base`. The `base` property always applies to
+a key, no matter what modifiers are pressed. It essentially specifies the default
+behavior for the key unless it is overridden by following properties.
+Since the `base` property applies to this key press, the system makes note
+of the fact that its behavior is `'a'` (type the character `a`).
+
+The system then continues to scan subsequent properties in case any of them
+are more specific than `base` and override it. It encounters `shift` which
+also applies to the key press SHIFT + A. So the system decides to ignore
+the `base` property's behavior and chooses the behavior associated with
+the `shift` property, which is `'A'` (type the character `A`).
+
+It then continues to scan the table, however no other properties apply to this
+key press (CAPS LOCK is not locked, neither CONTROL key is pressed, neither
+ALT key is pressed and neither META key is pressed).
+
+So the resulting behavior for the key combination SHIFT + A is `'A'`.
+
+#### CONTROL + A ####
+
+Now consider what would happen if the user pressed A and CONTROL together.
+
+As before, the system would scan the table of properties. It would notice
+that the `base` property applied but would also continue scanning until
+it eventually reached the `control` property. As it happens, the `control`
+property appears after `base` so its behavior overrides the `base` behavior.
+
+So the resulting behavior for the key combination CONTROL + A is `none`.
+
+#### ESCAPE ####
+
+Now suppose the user pressed ESCAPE.
+
+ key ESCAPE {
+ base: fallback BACK
+ alt, meta: fallback HOME
+ ctrl: fallback MENU
+ }
+
+This time the system obtains the behavior `fallback BACK`, a fallback behavior.
+Because no character literal appears, no character will be typed.
+
+When processing the key, the system will first deliver `KEYCODE_ESCAPE` to the
+application. If the application does not handle it, then the system will try
+again but this time it will deliver `KEYCODE_BACK` to the application as
+requested by the fallback behavior.
+
+So applications that recognize and support `KEYCODE_ESCAPE` have the
+opportunity to handle it as is, but other applications that do not can instead
+perform the fallback action of treating the key as if it were `KEYCODE_BACK`.
+
+#### NUMPAD_0 with or without NUM LOCK ####
+
+The numeric keypad keys have very different interpretations depending on whether
+the NUM LOCK key is locked.
+
+The following key declaration ensures that `KEYCODE_NUMPAD_0` types `0`
+when NUM LOCK is pressed. When NUM LOCK is not pressed, the key is delivered
+to the application as usual, and if it is not handled, then the fallback
+key `KEYCODE_INSERT` is delivered instead.
+
+ key NUMPAD_0 {
+ label, number: '0'
+ base: fallback INSERT
+ numlock: '0'
+ ctrl, alt, meta: none
+ }
+
+As we can see, fallback key declarations greatly improve compatibility
+with older applications that do not recognize or directly support all of the keys
+that are present on a full PC style keyboard.
+
+### Examples ###
+
+#### Full Keyboard ####
+
+ # This is an example of part of a key character map file for a full keyboard
+ # include a few fallback behaviors for special keys that few applications
+ # handle themselves.
+
+ type FULL
+
+ key C {
+ label: 'C'
+ base: 'c'
+ shift, capslock: 'C'
+ alt: '\u00e7'
+ shift+alt: '\u00c7'
+ ctrl, meta: none
+ }
+
+ key SPACE {
+ label: ' '
+ base: ' '
+ ctrl: none
+ alt, meta: fallback SEARCH
+ }
+
+ key NUMPAD_9 {
+ label, number: '9'
+ base: fallback PAGE_UP
+ numlock: '9'
+ ctrl, alt, meta: none
+ }
+
+#### Alphanumeric Keyboard ####
+
+ # This is an example of part of a key character map file for an alphanumeric
+ # thumb keyboard. Some keys are combined, such as `A` and `2`. Here we
+ # specify `number` labels to tell the system what to do when the user is
+ # typing a number into a dial pad.
+ #
+ # Also note the special character '\uef01' mapped to ALT+SPACE.
+ # Pressing this combination of keys invokes an on-screen character picker.
+
+ type ALPHA
+
+ key A {
+ label: 'A'
+ number: '2'
+ base: 'a'
+ shift, capslock: 'A'
+ alt: '#'
+ shift+alt, capslock+alt: none
+ }
+
+ key SPACE {
+ label: ' '
+ number: ' '
+ base: ' '
+ shift: ' '
+ alt: '\uef01'
+ shift+alt: '\uef01'
+ }
+
+#### Game Pad ####
+
+ # This is an example of part of a key character map file for a game pad.
+ # It defines fallback actions that enable the user to navigate the user interface
+ # by pressing buttons.
+
+ type SPECIAL_FUNCTION
+
+ key BUTTON_A {
+ base: fallback BACK
+ }
+
+ key BUTTON_X {
+ base: fallback DPAD_CENTER
+ }
+
+ key BUTTON_START {
+ base: fallback HOME
+ }
+
+ key BUTTON_SELECT {
+ base: fallback MENU
+ }
+
+## Compatibility Note ##
+
+Prior to Android Honeycomb 3.0, the Android key character map was specified
+using a very different syntax and was compiled into a binary file format
+(`.kcm.bin`) at build time.
+
+Although the new format uses the same extension `.kcm`, the syntax is quite
+different (and much more powerful).
+
+As of Android Honeycomb 3.0, all Android key character map files must use
+the new syntax and plain text file format that is described in this document.
+The old syntax is not supported and the old `.kcm.bin` files are not recognized
+by the system.
+
+## Language Note ##
+
+Android does not currently support multilingual keyboards. Moreover, the
+built-in generic key character map assumes a US English keyboard layout.
+
+OEMs are encouraged to provide custom key character maps for their keyboards
+if they are designed for other languages.
+
+Future versions of Android may provide better support for multilingual keyboards
+or user-selectable keyboard layouts.
+
+## Validation ##
+
+Make sure to validate your key character map files using the
+[Validate Keymaps](/tech/input/validate-keymaps.html) tool.
diff --git a/src/tech/input/key-layout-files.md b/src/tech/input/key-layout-files.md
new file mode 100644
index 0000000..9a2760d
--- /dev/null
+++ b/src/tech/input/key-layout-files.md
@@ -0,0 +1,332 @@
+<!--
+ Copyright 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Key Layout Files #
+
+Key layout files (`.kl` files) are responsible for mapping Linux key codes
+and axis codes to Android key codes and axis codes and specifying associated
+policy flags.
+
+Device-specific key layout files are *required* for all internal (built-in)
+input devices that have keys, including special keys such as volume, power
+and headset media keys.
+
+Device-specific key layout files are *optional* for other input devices but
+they are *recommended* for special-purpose keyboards and joysticks.
+
+If no device-specific key layout file is available, then the system will
+choose a default instead.
+
+## Location ##
+
+Key layout files are located by USB vendor, product (and optionally version)
+id or by input device name.
+
+The following paths are consulted in order.
+
+* `/system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl`
+* `/system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl`
+* `/system/usr/keylayout/DEVICE_NAME.kl`
+* `/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl`
+* `/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl`
+* `/data/system/devices/keylayout/DEVICE_NAME.kl`
+* `/system/usr/keylayout/Generic.kl`
+* `/data/system/devices/keylayout/Generic.kl`
+
+When constructing a file path that contains the device name, all characters
+in the device name other than '0'-'9', 'a'-'z', 'A'-'Z', '-' or '_' are replaced by '_'.
+
+## Generic Key Layout File ##
+
+The system provides a special built-in generic key layout file called `Generic.kl`.
+This key layout is intended to support a variety of standard external
+keyboards and joysticks.
+
+*Do not modify the generic key layout!*
+
+## Syntax ##
+
+A key layout file is a plain text file consisting of key or axis declarations
+and flags.
+
+### Key Declarations ###
+
+Key declarations each consist of the keyword `key` followed by a Linux key code
+number, an Android key code name, and optional set of whitespace delimited policy flags.
+
+ key 1 ESCAPE
+ key 114 VOLUME_DOWN WAKE
+ key 16 Q VIRTUAL WAKE
+
+The following policy flags are recognized:
+
+* `WAKE`: The key should wake the device when it is asleep. For historical reasons,
+ this flag behaves in the same manner as `WAKE_DROPPED` below.
+* `WAKE_DROPPED`: The key should wake the device when it is asleep but the key itself
+ should be dropped when the wake-up occurs. In a sense, the key's action was to
+ wake the device, but the key itself is not processed.
+* `SHIFT`: The key should be interpreted as if the SHIFT key were also pressed.
+* `CAPS_LOCK`: The key should be interpreted as if the CAPS LOCK key were also pressed.
+* `ALT`: The key should be interpreted as if the ALT key were also pressed.
+* `ALT_GR`: The key should be interpreted as if the RIGHT ALT key were also pressed.
+* `FUNCTION`: The key should be interpreted as if the FUNCTION key were also pressed.
+* `VIRTUAL`: The key is a virtual soft key (capacitive button) that is adjacent to
+ the main touch screen. This causes special debouncing logic to be enabled, see below.
+* `MENU`: Deprecated. Do not use.
+* `LAUNCHER`: Deprecated. Do not use.
+
+### Axis Declarations ###
+
+Axis declarations each consist of the keyword `axis` followed by a Linux axis code
+number, and qualifiers that control the behavior of the axis including at least
+one Android axis code name.
+
+#### Basic Axes ####
+
+A basic axis simply maps a Linux axis code to an Android axis code name.
+
+The following declaration maps `ABS_X` (indicated by `0x00`) to `AXIS_X` (indicated by `X`).
+
+ axis 0x00 X
+
+In the above example, if the value of `ABS_X` is `5` then `AXIS_X` will be set to `5`.
+
+#### Split Axes ####
+
+A split axis maps a Linux axis code to two Android axis code names, such that
+values less than or greater than a threshold are split across two different axes when
+mapped. This mapping is useful when a single physical axis reported by the device
+encodes two different mutually exclusive logical axes.
+
+The following declaration maps values of the `ABS_Y` axis (indicated by `0x01`) to
+`AXIS_GAS` when less than `0x7f` or to `AXIS_BRAKE` when greater than `0x7f`.
+
+ axis 0x01 split 0x7f GAS BRAKE
+
+In the above example, if the value of `ABS_Y` is `0x7d` then `AXIS_GAS` is set
+to `2` (`0x7f - 0x7d`) and `AXIS_BRAKE` is set to `0`. Conversely, if the value of
+`ABS_Y` is `0x83` then `AXIS_GAS` is set to `0` and `AXIS_BRAKE` is set to `4`
+(`0x83 - 0x7f`). Finally, if the value of `ABS_Y` equals the split value of `0x7f`
+then both `AXIS_GAS` and `AXIS_BRAKE` are set to `0`.
+
+#### Inverted Axes ####
+
+An inverted axis inverts the sign of the axis value.
+
+The following declaration maps `ABS_RZ` (indicated by `0x05`) to `AXIS_BRAKE`
+(indicated by `BRAKE`), and inverts the output by negating it.
+
+ axis 0x05 invert AXIS_RZ
+
+In the above example, if the value of `ABS_RZ` is `2` then `AXIS_RZ` is set to `-2`.
+
+#### Center Flat Position Option ####
+
+The Linux input protocol provides a way for input device drivers to specify the
+center flat position of joystick axes but not all of them do and some of them
+provide incorrect values.
+
+The center flat position is the neutral position of the axis, such as when
+a directional pad is in the very middle of its range and the user is not
+touching it.
+
+To resolve this issue, an axis declaration may be followed by a `flat`
+option that specifies the value of the center flat position for the axis.
+
+ axis 0x03 Z flat 4096
+
+In the above example, the center flat position is set to `4096`.
+
+### Comments ###
+
+Comment lines begin with '#' and continue to the end of the line. Like this:
+
+ # A comment!
+
+Blank lines are ignored.
+
+### Examples ###
+
+#### Keyboard ####
+
+ # This is an example of a key layout file for a keyboard.
+
+ key 1 ESCAPE
+ key 2 1
+ key 3 2
+ key 4 3
+ key 5 4
+ key 6 5
+ key 7 6
+ key 8 7
+ key 9 8
+ key 10 9
+ key 11 0
+ key 12 MINUS
+ key 13 EQUALS
+ key 14 DEL
+
+ # etc...
+
+#### System Controls ####
+
+ # This is an example of a key layout file for basic system controls, such as
+ # volume and power keys which are typically implemented as GPIO pins that
+ # the device decodes into key presses.
+
+ key 114 VOLUME_DOWN WAKE
+ key 115 VOLUME_UP WAKE
+ key 116 POWER WAKE
+
+#### Capacitive Buttons ####
+
+ # This is an example of a key layout file for a touch device with capacitive buttons.
+
+ key 139 MENU VIRTUAL
+ key 102 HOME VIRTUAL
+ key 158 BACK VIRTUAL
+ key 217 SEARCH VIRTUAL
+
+#### Headset Jack Media Controls ####
+
+ # This is an example of a key layout file for headset mounted media controls.
+ # A typical headset jack interface might have special control wires or detect known
+ # resistive loads as corresponding to media functions or volume controls.
+ # This file assumes that the driver decodes these signals and reports media
+ # controls as key presses.
+
+ key 163 MEDIA_NEXT WAKE
+ key 165 MEDIA_PREVIOUS WAKE
+ key 226 HEADSETHOOK WAKE
+
+#### Joystick ####
+
+ # This is an example of a key layout file for a joystick.
+
+ # These are the buttons that the joystick supports, represented as keys.
+ key 304 BUTTON_A
+ key 305 BUTTON_B
+ key 307 BUTTON_X
+ key 308 BUTTON_Y
+ key 310 BUTTON_L1
+ key 311 BUTTON_R1
+ key 314 BUTTON_SELECT
+ key 315 BUTTON_START
+ key 316 BUTTON_MODE
+ key 317 BUTTON_THUMBL
+ key 318 BUTTON_THUMBR
+
+ # Left and right stick.
+ # The reported value for flat is 128 out of a range from -32767 to 32768, which is absurd.
+ # This confuses applications that rely on the flat value because the joystick actually
+ # settles in a flat range of +/- 4096 or so. We override it here.
+ axis 0x00 X flat 4096
+ axis 0x01 Y flat 4096
+ axis 0x03 Z flat 4096
+ axis 0x04 RZ flat 4096
+
+ # Triggers.
+ axis 0x02 LTRIGGER
+ axis 0x05 RTRIGGER
+
+ # Hat.
+ axis 0x10 HAT_X
+ axis 0x11 HAT_Y
+
+## Wake Keys ##
+
+Wake keys are special keys that wake the device from sleep, such as the power key.
+
+By default, for internal keyboard devices, no key is a wake key. For external
+keyboard device, all keys are wake keys.
+
+To make a key be a wake key, set the `WAKE_DROPPED` flag in the key layout file
+for the keyboard device.
+
+Note that the `WindowManagerPolicy` component is responsible for implementing wake
+key behavior. Moreover, the key guard may prevent certain keys from functioning
+as wake keys. A good place to start understanding wake key behavior is
+`PhoneWindowManager.interceptKeyBeforeQueueing`.
+
+## Virtual Soft Keys ##
+
+The input system provides special features for implementing virtual soft keys.
+
+There are three cases:
+
+1. If the virtual soft keys are displayed graphically on the screen, as on the
+ Galaxy Nexus, then they are implemented by the Navigation Bar component in
+ the System UI package.
+
+ Because graphical virtual soft keys are implemented at a high layer in the
+ system, key layout files are not involved and the following information does
+ not apply.
+
+2. If the virtual soft keys are implemented as an extended touchable region
+ that is part of the main touch screen, as on the Nexus One, then the
+ input system uses a virtual key map file to translate X / Y touch coordinates
+ into Linux key codes, then uses the key layout file to translate
+ Linux key codes into Android key codes.
+
+ Refer to the section on [Touch Devices](/tech/input/touch-devices.html)
+ for more details about virtual key map files.
+
+ The key layout file for the touch screen input device must specify the
+ appropriate key mapping and include the `VIRTUAL` flag for each key.
+
+3. If the virtual soft keys are implemented as capacitive buttons that are
+ separate from the main touch screen, as on the Nexus S, then the kernel
+ device driver or firmware is responsible for translating touches into
+ Linux key codes which the input system then translates into Android
+ key codes using the key layout file.
+
+ The key layout file for the capacitive button input device must specify the
+ appropriate key mapping and include the `VIRTUAL` flag for each key.
+
+When virtual soft key are located within or in close physical proximity of the
+touch screen, it is easy for the user to accidentally press one of the buttons
+when touching near the bottom of the screen or when sliding a finger from top
+to bottom or from bottom to top on the screen.
+
+To prevent this from happening, the input system applies a little debouncing
+such that virtual soft key presses are ignored for a brief period of time
+after the most recent touch on the touch screen. The delay is called the
+virtual key quiet time.
+
+To enable virtual soft key debouncing, we must do two things.
+
+First, we provide a key layout file for the touch screen or capacitive button
+input device with the `VIRTUAL` flag set for each key.
+
+ key 139 MENU VIRTUAL
+ key 102 HOME VIRTUAL
+ key 158 BACK VIRTUAL
+ key 217 SEARCH VIRTUAL
+
+Then, we set the value of the virtual key quiet time in a resource overlay
+for the framework `config.xml` resource.
+
+ <!-- Specifies the amount of time to disable virtual keys after the screen is touched
+ in order to filter out accidental virtual key presses due to swiping gestures
+ or taps near the edge of the display. May be 0 to disable the feature.
+ It is recommended that this value be no more than 250 ms.
+ This feature should be disabled for most devices. -->
+ <integer name="config_virtualKeyQuietTimeMillis">250</integer>
+
+## Validation ##
+
+Make sure to validate your key layout files using the
+[Validate Keymaps](/tech/input/validate-keymaps.html) tool.
diff --git a/src/tech/input/keyboard-devices.md b/src/tech/input/keyboard-devices.md
new file mode 100644
index 0000000..955d579
--- /dev/null
+++ b/src/tech/input/keyboard-devices.md
@@ -0,0 +1,1002 @@
+<!--
+ Copyright 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Keyboard Devices #
+
+Android supports a variety of keyboard devices including special function
+keypads (volume and power controls), compact embedded QWERTY keyboards,
+and fully featured PC-style external keyboards.
+
+This document decribes physical keyboards only. Refer to the Android SDK
+for information about soft keyboards (Input Method Editors).
+
+## Keyboard Classification ##
+
+An input device is classified as a keyboard if either of the following
+conditions hold:
+
+* The input device reports the presence of any Linux key codes used on keyboards
+ including `0` through `0xff` or `KEY_OK` through `KEY_MAX`.
+
+* The input device reports the presence of any Linux key codes used on joysticks
+ and gamepads including `BTN_0` through `BTN_9`, `BTN_TRIGGER` through `BTN_DEAD`,
+ or `BTN_A` through `BTN_THUMBR`.
+
+Joysticks are currently classified as keyboards because joystick and gamepad buttons
+are reported by `EV_KEY` events in the same way keyboard keys are reported. Thus
+joysticks and gamepads also make use of key map files for configuration.
+Refer to the section on [Joystick Devices](/tech/input/joystick-devices.html) for
+more information.
+
+Once an input device has been classified as a keyboard, the system loads the
+input device configuration file and keyboard layout for the keyboard.
+
+The system then tries to determine additional characteristics of the device.
+
+* If the input device has any keys that are mapped to `KEYCODE_Q`, then the
+ device is considered to have an alphabetic keypad (as opposed to numeric).
+ The alphabetic keypad capability is reported in the resource `Configuration`
+ object as `KEYBOARD_QWERTY`.
+
+* If the input device has any keys that are mapped to `KEYCODE_DPAD_UP`,
+ `KEYCODE_DPAD_DOWN`, `KEYCODE_DPAD_LEFT`, `KEYCODE_DPAD_RIGHT`, and
+ `KEYCODE_DPAD_CENTER` (all must be present), then the device is considered
+ to have a directional keypad.
+ The directional keypad capability is reported in the resource `Configuration`
+ object as `NAVIGATION_DPAD`.
+
+* If the input device has any keys that are mapped to `KEYCODE_BUTTON_A`
+ or other gamepad related keys, then the device is considered to have a gamepad.
+
+## Keyboard Driver Requirements ##
+
+1. Keyboard drivers should only register key codes for the keys that they
+ actually support. Registering excess key codes may confuse the device
+ classification algorithm or cause the system to incorrectly detect
+ the supported keyboard capabilities of the device.
+
+2. Keyboard drivers should use `EV_KEY` to report key presses, using a value
+ of `0` to indicate that a key is released, a value of `1` to indicate that
+ a key is pressed, and a value greater than or equal to `2` to indicate that
+ the key is being repeated automatically.
+
+3. Android performs its own keyboard repeating. Auto-repeat functionality
+ should be disabled in the driver.
+
+4. Keyboard drivers may optionally indicate the HID usage or low-level scan
+ code by sending `EV_MSC` with `MSC_SCANCODE` and a valud indicating the usage
+ or scan code when the key is pressed. This information is not currently
+ used by Android.
+
+5. Keyboard drivers should support setting LED states when `EV_LED` is written
+ to the device. The `hid-input` driver handles this automatically.
+ At the time of this writing, Android uses `LED_CAPSLOCK`, `LED_SCROLLLOCK`,
+ and `LED_NUMLOCK`. These LEDs only need to be supported when the
+ keyboard actually has the associated indicator lights.
+
+6. Keyboard drivers for embedded keypads (for example, using a GPIO matrix)
+ should make sure to send `EV_KEY` events with a value of `0` for any keys that
+ are still pressed when the device is going to sleep. Otherwise keys might
+ get stuck down and will auto-repeat forever.
+
+## Keyboard Operation ##
+
+The following is a brief summary of the keyboard operation on Android.
+
+1. The `EventHub` reads raw events from the `evdev` driver and maps Linux key codes
+ (sometimes referred to as scan codes) into Android key codes using the
+ keyboard's key layout map.
+
+2. The `InputReader` consumes the raw events and updates the meta key state.
+ For example, if the left shift key is pressed or released, the reader will
+ set or reset the `META_SHIFT_LEFT_ON` and `META_SHIFT_ON` bits accordingly.
+
+3. The `InputReader` notifies the `InputDispatcher` about the key event.
+
+4. The `InputDispatcher` asks the `WindowManagerPolicy` what to do with the key
+ event by calling `WindowManagerPolicy.interceptKeyBeforeQueueing`. This method
+ is part of a critical path that is responsible for waking the device when
+ certain keys are pressed. The `EventHub` effectively holds a wake lock
+ along this critical path to ensure that it will run to completion.
+
+5. If an `InputFilter` is currently in use, the `InputDispatcher` gives it a
+ chance to consume or transform the key. The `InputFilter` may be used to implement
+ low-level system-wide accessibility policies.
+
+6. The `InputDispatcher` enqueues the key for processing on the dispatch thread.
+
+7. When the `InputDispatcher` dequeues the key, it gives the `WindowManagerPolicy`
+ a second chance to intercept the key event by calling
+ `WindowManagerPolicy.interceptKeyBeforeDispatching`. This method handles system
+ shortcuts and other functions.
+
+8. The `InputDispatcher` then identifies the key event target (the focused window)
+ and waits for them to become ready. Then, the `InputDispatcher` delivers the
+ key event to the application.
+
+9. Inside the application, the key event propagates down the view hierarchy to
+ the focused view for pre-IME key dispatch.
+
+10. If the key event is not handled in the pre-IME dispatch and an IME is in use, the
+ key event is delivered to the IME.
+
+11. If the key event was not consumed by the IME, then the key event propagates
+ down the view hierarchy to the focused view for standard key dispatch.
+
+12. The application reports back to the `InputDispatcher` as to whether the key
+ event was consumed. If the event was not consumed, the `InputDispatcher`
+ calls `WindowManagerPolicy.dispatchUnhandledKey` to apply "fallback" behavior.
+ Depending on the fallback action, the key event dispatch cycle may be restarted
+ using a different key code. For example, if an application does not handle
+ `KEYCODE_ESCAPE`, the system may redispatch the key event as `KEYCODE_BACK` instead.
+
+## Keyboard Configuration ##
+
+Keyboard behavior is determined by the keyboard's key layout, key character
+map and input device configuration.
+
+Refer to the following sections for more details about the files that
+participate in keyboard configuration:
+
+* [Key Layout Files](/tech/input/key-layout-files.html)
+* [Key Character Map Files](/tech/input/key-character-map-files.html)
+* [Input Device Configuration Files](/tech/input/input-device-configuration-files.html)
+
+### Properties ###
+
+The following input device configuration properties are used for keyboards.
+
+#### `keyboard.layout` ####
+
+*Definition:* `keyboard.layout` = <name>
+
+Specifies the name of the key layout file associated with the input device,
+excluding the `.kl` extension. If this file is not found, the input system
+will use the default key layout instead.
+
+Spaces in the name are converted to underscores during lookup.
+
+Refer to the key layout file documentation for more details.
+
+#### `keyboard.characterMap` ####
+
+*Definition:* `keyboard.characterMap` = <name>
+
+Specifies the name of the key character map file associated with the input device,
+excluding the `.kcm` extension. If this file is not found, the input system
+will use the default key character map instead.
+
+Spaces in the name are converted to underscores during lookup.
+
+Refer to the key character map file documentation for more details.
+
+#### `keyboard.orientationAware` ####
+
+*Definition:* `keyboard.orientationAware` = `0` | `1`
+
+Specifies whether the keyboard should react to display orientation changes.
+
+* If the value is `1`, the directional keypad keys are rotated when the
+ associated display orientation changes.
+
+* If the value is `0`, the keyboard is immune to display orientation changes.
+
+The default value is `0`.
+
+Orientation awareness is used to support rotation of directional keypad keys,
+such as on the Motorola Droid. For example, when the device is rotated
+clockwise 90 degrees from its natural orientation, `KEYCODE_DPAD_UP` is
+remapped to produce `KEYCODE_DPAD_RIGHT` since the 'up' key ends up pointing
+'right' when the device is held in that orientation.
+
+#### `keyboard.builtIn` ####
+
+*Definition:* `keyboard.builtIn` = `0` | `1`
+
+Specifies whether the keyboard is the built-in (physically attached)
+keyboard.
+
+The default value is `1` if the device name ends with `-keypad`, `0` otherwise.
+
+The built-in keyboard is always assigned a device id of `0`. Other keyboards
+that are not built-in are assigned unique non-zero device ids.
+
+Using an id of `0` for the built-in keyboard is important for maintaining
+compatibility with the `KeyCharacterMap.BUILT_IN_KEYBOARD` field, which specifies
+the id of the built-in keyboard and has a value of `0`. This field has been
+deprecated in the API but older applications might still be using it.
+
+A special-function keyboard (one whose key character map specifies a
+type of `SPECIAL_FUNCTION`) will never be registered as the built-in keyboard,
+regardless of the setting of this property. This is because a special-function
+keyboard is by definition not intended to be used for general purpose typing.
+
+### Example Configurations ###
+
+ # This is an example input device configuration file for a built-in
+ # keyboard that has a DPad.
+
+ # The keyboard is internal because it is part of the device.
+ device.internal = 1
+
+ # The keyboard is the default built-in keyboard so it should be assigned
+ # an id of 0.
+ keyboard.builtIn = 1
+
+ # The keyboard includes a DPad which is mounted on the device. As the device
+ # is rotated the orientation of the DPad rotates along with it, so the DPad must
+ # be aware of the display orientation. This ensures that pressing 'up' on the
+ # DPad always means 'up' from the perspective of the user, even when the entire
+ # device has been rotated.
+ keyboard.orientationAware = 1
+
+### Compatibility Notes ###
+
+Prior to Honeycomb, the keyboard input mapper did not use any configuration properties.
+All keyboards were assumed to be physically attached and orientation aware. The default
+key layout and key character map was named `qwerty` instead of `Generic`. The key
+character map format was also very different and the framework did not support
+PC-style full keyboards or external keyboards.
+
+When upgrading devices to Honeycomb, make sure to create or update the necessary
+configuration and key map files.
+
+## HID Usages, Linux Key Codes and Android Key Codes ##
+
+The system refers to keys using several different identifiers, depending on the
+layer of abstraction.
+
+For HID devices, each key has an associated HID usage. The Linux `hid-input`
+driver and related vendor and device-specific HID drivers are responsible
+for parsing HID reports and mapping HID usages to Linux key codes.
+
+As Android reads `EV_KEY` events from the Linux kernel, it translates each
+Linux key code into its corresponding Android key code according to the
+key layout file of the device.
+
+When the key event is dispatched to an application, the `android.view.KeyEvent`
+instance reports the Linux key code as the value of `getScanCode()` and the
+Android key code as the value of `getKeyCode()`. For the purposes of the
+framework, only the value of `getKeyCode()` is important.
+
+Note that the HID usage information is not used by Android itself or
+passed to applications.
+
+## Code Tables ##
+
+The following tables show how HID usages, Linux key codes and Android
+key codes are related to one another.
+
+The LKC column specifies the Linux key code in hexadecimal.
+
+The AKC column specifies the Android key code in hexadecimal.
+
+The Notes column refers to notes that are posted after the table.
+
+The Version column specifies the first version of the Android platform
+to have included this key in its default key map. Multiple rows are
+shown in cases where the default key map has changed between versions.
+The oldest version indicated is 1.6.
+
+* In Gingerbread (2.3) and earlier releases, the default key map was
+ `qwerty.kl`. This key map was only intended for use with the Android
+ Emulator and was not intended to be used to support arbitrary
+ external keyboards. Nevertheless, a few OEMs added Bluetooth
+ keyboard support to the platform and relied on `qwerty.kl` to
+ provide the necessary keyboard mappings. Consequently these
+ older mappings may be of interest to OEMs who are building
+ peripherals for these particular devices. Note that the mappings
+ are substantially different from the current ones, particularly
+ with respect to the treatment of the `HOME` key. It is recommended
+ that all new peripherals be developed according to the Honeycomb or more
+ recent key maps (ie. standard HID).
+
+* As of Honeycomb (3.0), the default key map is `Generic.kl`.
+ This key map was designed to support full PC style keyboards.
+ Most functionality of standard HID keyboards should just work out
+ of the box.
+
+The key code mapping may vary across versions of the Linux kernel and Android.
+When changes are known to have occurred in the Android default key maps,
+they are indicated in the version column.
+
+Device-specific HID drivers and key maps may apply different mappings
+than are indicated here.
+
+### HID Keyboard and Keypad Page (0x07) ###
+
+| HID Usage | HID Usage Name | LKC | Linux Key Code Name | Version | AKC | Android Key Code Name | Notes |
+| ----------- | -------------------------------- | ------ | -------------------------------- | ------- | ------ | -------------------------------- | ----- |
+| 0x07 0x0001 | Keyboard Error Roll Over | | | | | | |
+| 0x07 0x0002 | Keyboard POST Fail | | | | | | |
+| 0x07 0x0003 | Keyboard Error Undefined | | | | | | |
+| 0x07 0x0004 | Keyboard a and A | 0x001e | KEY_A | 1.6 | 0x001d | KEYCODE_A | 1 |
+| 0x07 0x0005 | Keyboard b and B | 0x0030 | KEY_B | 1.6 | 0x001e | KEYCODE_B | 1 |
+| 0x07 0x0006 | Keyboard c and C | 0x002e | KEY_C | 1.6 | 0x001f | KEYCODE_C | 1 |
+| 0x07 0x0007 | Keyboard d and D | 0x0020 | KEY_D | 1.6 | 0x0020 | KEYCODE_D | 1 |
+| 0x07 0x0008 | Keyboard e and E | 0x0012 | KEY_E | 1.6 | 0x0021 | KEYCODE_E | 1 |
+| 0x07 0x0009 | Keyboard f and F | 0x0021 | KEY_F | 1.6 | 0x0022 | KEYCODE_F | 1 |
+| 0x07 0x000a | Keyboard g and G | 0x0022 | KEY_G | 1.6 | 0x0023 | KEYCODE_G | 1 |
+| 0x07 0x000b | Keyboard h and H | 0x0023 | KEY_H | 1.6 | 0x0024 | KEYCODE_H | 1 |
+| 0x07 0x000c | Keyboard i and I | 0x0017 | KEY_I | 1.6 | 0x0025 | KEYCODE_I | 1 |
+| 0x07 0x000d | Keyboard j and J | 0x0024 | KEY_J | 1.6 | 0x0026 | KEYCODE_J | 1 |
+| 0x07 0x000e | Keyboard k and K | 0x0025 | KEY_K | 1.6 | 0x0027 | KEYCODE_K | 1 |
+| 0x07 0x000f | Keyboard l and L | 0x0026 | KEY_L | 1.6 | 0x0028 | KEYCODE_L | 1 |
+| 0x07 0x0010 | Keyboard m and M | 0x0032 | KEY_M | 1.6 | 0x0029 | KEYCODE_M | 1 |
+| 0x07 0x0011 | Keyboard n and N | 0x0031 | KEY_N | 1.6 | 0x002a | KEYCODE_N | 1 |
+| 0x07 0x0012 | Keyboard o and O | 0x0018 | KEY_O | 1.6 | 0x002b | KEYCODE_O | 1 |
+| 0x07 0x0013 | Keyboard p and P | 0x0019 | KEY_P | 1.6 | 0x002c | KEYCODE_P | 1 |
+| 0x07 0x0014 | Keyboard q and Q | 0x0010 | KEY_Q | 1.6 | 0x002d | KEYCODE_Q | 1 |
+| 0x07 0x0015 | Keyboard r and R | 0x0013 | KEY_R | 1.6 | 0x002e | KEYCODE_R | 1 |
+| 0x07 0x0016 | Keyboard s and S | 0x001f | KEY_S | 1.6 | 0x002f | KEYCODE_S | 1 |
+| 0x07 0x0017 | Keyboard t and T | 0x0014 | KEY_T | 1.6 | 0x0030 | KEYCODE_T | 1 |
+| 0x07 0x0018 | Keyboard u and U | 0x0016 | KEY_U | 1.6 | 0x0031 | KEYCODE_U | 1 |
+| 0x07 0x0019 | Keyboard v and V | 0x002f | KEY_V | 1.6 | 0x0032 | KEYCODE_V | 1 |
+| 0x07 0x001a | Keyboard w and W | 0x0011 | KEY_W | 1.6 | 0x0033 | KEYCODE_W | 1 |
+| 0x07 0x001b | Keyboard x and X | 0x002d | KEY_X | 1.6 | 0x0034 | KEYCODE_X | 1 |
+| 0x07 0x001c | Keyboard y and Y | 0x0015 | KEY_Y | 1.6 | 0x0035 | KEYCODE_Y | 1 |
+| 0x07 0x001d | Keyboard z and Z | 0x002c | KEY_Z | 1.6 | 0x0036 | KEYCODE_Z | 1 |
+| 0x07 0x001e | Keyboard 1 and ! | 0x0002 | KEY_1 | 1.6 | 0x0008 | KEYCODE_1 | 1 |
+| 0x07 0x001f | Keyboard 2 and @ | 0x0003 | KEY_2 | 1.6 | 0x0009 | KEYCODE_2 | 1 |
+| 0x07 0x0020 | Keyboard 3 and # | 0x0004 | KEY_3 | 1.6 | 0x000a | KEYCODE_3 | 1 |
+| 0x07 0x0021 | Keyboard 4 and $ | 0x0005 | KEY_4 | 1.6 | 0x000b | KEYCODE_4 | 1 |
+| 0x07 0x0022 | Keyboard 5 and % | 0x0006 | KEY_5 | 1.6 | 0x000c | KEYCODE_5 | 1 |
+| 0x07 0x0023 | Keyboard 6 and ^ | 0x0007 | KEY_6 | 1.6 | 0x000d | KEYCODE_6 | 1 |
+| 0x07 0x0024 | Keyboard 7 and & | 0x0008 | KEY_7 | 1.6 | 0x000e | KEYCODE_7 | 1 |
+| 0x07 0x0025 | Keyboard 8 and * | 0x0009 | KEY_8 | 1.6 | 0x000f | KEYCODE_8 | 1 |
+| 0x07 0x0026 | Keyboard 9 and ( | 0x000a | KEY_9 | 1.6 | 0x0010 | KEYCODE_9 | 1 |
+| 0x07 0x0027 | Keyboard 0 and ) | 0x000b | KEY_0 | 1.6 | 0x0007 | KEYCODE_0 | 1 |
+| 0x07 0x0028 | Keyboard Return (ENTER) | 0x001c | KEY_ENTER | 1.6 | 0x0042 | KEYCODE_ENTER | 1 |
+| 0x07 0x0029 | Keyboard ESCAPE | 0x0001 | KEY_ESC | 3.0 | 0x006f | KEYCODE_ESCAPE | |
+| "" | "" | "" | "" | 2.3 | 0x0004 | KEYCODE_BACK | |
+| 0x07 0x002a | Keyboard DELETE (Backspace) | 0x000e | KEY_BACKSPACE | 1.6 | 0x0043 | KEYCODE_DEL | |
+| 0x07 0x002b | Keyboard Tab | 0x000f | KEY_TAB | 1.6 | 0x003d | KEYCODE_TAB | |
+| 0x07 0x002c | Keyboard Spacebar | 0x0039 | KEY_SPACE | 1.6 | 0x003e | KEYCODE_SPACE | |
+| 0x07 0x002d | Keyboard - and _ | 0x000c | KEY_MINUS | 1.6 | 0x0045 | KEYCODE_MINUS | 1 |
+| 0x07 0x002e | Keyboard = and + | 0x000d | KEY_EQUAL | 1.6 | 0x0046 | KEYCODE_EQUALS | 1 |
+| 0x07 0x002f | Keyboard \[ and \{ | 0x001a | KEY_LEFTBRACE | 1.6 | 0x0047 | KEYCODE_LEFT_BRACKET | 1 |
+| 0x07 0x0030 | Keyboard \] and \} | 0x001b | KEY_RIGHTBRACE | 1.6 | 0x0048 | KEYCODE_RIGHT_BRACKET | 1 |
+| 0x07 0x0031 | Keyboard \\ and | | 0x002b | KEY_BACKSLASH | 1.6 | 0x0049 | KEYCODE_BACKSLASH | 1 |
+| 0x07 0x0032 | Keyboard Non-US # and ~ | 0x002b | KEY_BACKSLASH | 1.6 | 0x0049 | KEYCODE_BACKSLASH | 1 |
+| 0x07 0x0033 | Keyboard ; and : | 0x0027 | KEY_SEMICOLON | 1.6 | 0x004a | KEYCODE_SEMICOLON | 1 |
+| 0x07 0x0034 | Keyboard ' and " | 0x0028 | KEY_APOSTROPHE | 1.6 | 0x004b | KEYCODE_APOSTROPHE | 1 |
+| 0x07 0x0035 | Keyboard \` and ~ | 0x0029 | KEY_GRAVE | 3.0 | 0x0044 | KEYCODE_GRAVE | 1 |
+| 0x07 0x0036 | Keyboard , and < | 0x0033 | KEY_COMMA | 1.6 | 0x0037 | KEYCODE_COMMA | 1 |
+| 0x07 0x0037 | Keyboard . and > | 0x0034 | KEY_DOT | 1.6 | 0x0038 | KEYCODE_PERIOD | 1 |
+| 0x07 0x0038 | Keyboard / and ? | 0x0035 | KEY_SLASH | 1.6 | 0x004c | KEYCODE_SLASH | 1 |
+| 0x07 0x0039 | Keyboard Caps Lock | 0x003a | KEY_CAPSLOCK | 3.0 | 0x0073 | KEYCODE_CAPS_LOCK | |
+| 0x07 0x003a | Keyboard F1 | 0x003b | KEY_F1 | 3.0 | 0x0083 | KEYCODE_F1 | |
+| "" | "" | "" | "" | 1.6 | 0x0052 | KEYCODE_MENU | |
+| 0x07 0x003b | Keyboard F2 | 0x003c | KEY_F2 | 3.0 | 0x0084 | KEYCODE_F2 | |
+| "" | "" | "" | "" | 1.6 | 0x0002 | KEYCODE_SOFT_RIGHT | |
+| 0x07 0x003c | Keyboard F3 | 0x003d | KEY_F3 | 3.0 | 0x0085 | KEYCODE_F3 | |
+| "" | "" | "" | "" | 1.6 | 0x0005 | KEYCODE_CALL | |
+| 0x07 0x003d | Keyboard F4 | 0x003e | KEY_F4 | 3.0 | 0x0086 | KEYCODE_F4 | |
+| "" | "" | "" | "" | 1.6 | 0x0006 | KEYCODE_ENDCALL | |
+| 0x07 0x003e | Keyboard F5 | 0x003f | KEY_F5 | 3.0 | 0x0087 | KEYCODE_F5 | |
+| 0x07 0x003f | Keyboard F6 | 0x0040 | KEY_F6 | 3.0 | 0x0088 | KEYCODE_F6 | |
+| 0x07 0x0040 | Keyboard F7 | 0x0041 | KEY_F7 | 3.0 | 0x0089 | KEYCODE_F7 | |
+| 0x07 0x0041 | Keyboard F8 | 0x0042 | KEY_F8 | 3.0 | 0x008a | KEYCODE_F8 | |
+| 0x07 0x0042 | Keyboard F9 | 0x0043 | KEY_F9 | 3.0 | 0x008b | KEYCODE_F9 | |
+| 0x07 0x0043 | Keyboard F10 | 0x0044 | KEY_F10 | 3.0 | 0x008c | KEYCODE_F10 | |
+| "" | "" | "" | "" | 2.3 | 0x0052 | KEYCODE_MENU | |
+| 0x07 0x0044 | Keyboard F11 | 0x0057 | KEY_F11 | 3.0 | 0x008d | KEYCODE_F11 | |
+| 0x07 0x0045 | Keyboard F12 | 0x0058 | KEY_F12 | 3.0 | 0x008e | KEYCODE_F12 | |
+| 0x07 0x0046 | Keyboard Print Screen | 0x0063 | KEY_SYSRQ | 3.0 | 0x0078 | KEYCODE_SYSRQ | |
+| 0x07 0x0047 | Keyboard Scroll Lock | 0x0046 | KEY_SCROLLLOCK | 3.0 | 0x0074 | KEYCODE_SCROLL_LOCK | |
+| 0x07 0x0048 | Keyboard Pause | 0x0077 | KEY_PAUSE | 3.0 | 0x0079 | KEYCODE_BREAK | |
+| 0x07 0x0049 | Keyboard Insert | 0x006e | KEY_INSERT | 3.0 | 0x007c | KEYCODE_INSERT | |
+| 0x07 0x004a | Keyboard Home | 0x0066 | KEY_HOME | 3.0 | 0x007a | KEYCODE_MOVE_HOME | |
+| "" | "" | "" | "" | 1.6 | 0x0003 | KEYCODE_HOME | |
+| 0x07 0x004b | Keyboard Page Up | 0x0068 | KEY_PAGEUP | 3.0 | 0x005c | KEYCODE_PAGE_UP | |
+| 0x07 0x004c | Keyboard Delete Forward | 0x006f | KEY_DELETE | 3.0 | 0x0070 | KEYCODE_FORWARD_DEL | |
+| 0x07 0x004d | Keyboard End | 0x006b | KEY_END | 3.0 | 0x007b | KEYCODE_MOVE_END | |
+| "" | "" | "" | "" | 1.6 | 0x0006 | KEYCODE_ENDCALL | |
+| 0x07 0x004e | Keyboard Page Down | 0x006d | KEY_PAGEDOWN | 3.0 | 0x005d | KEYCODE_PAGE_DOWN | |
+| 0x07 0x004f | Keyboard Right Arrow | 0x006a | KEY_RIGHT | 1.6 | 0x0016 | KEYCODE_DPAD_RIGHT | |
+| 0x07 0x0050 | Keyboard Left Arrow | 0x0069 | KEY_LEFT | 1.6 | 0x0015 | KEYCODE_DPAD_LEFT | |
+| 0x07 0x0051 | Keyboard Down Arrow | 0x006c | KEY_DOWN | 1.6 | 0x0014 | KEYCODE_DPAD_DOWN | |
+| 0x07 0x0052 | Keyboard Up Arrow | 0x0067 | KEY_UP | 1.6 | 0x0013 | KEYCODE_DPAD_UP | |
+| 0x07 0x0053 | Keyboard Num Lock and Clear | 0x0045 | KEY_NUMLOCK | 3.0 | 0x008f | KEYCODE_NUM_LOCK | |
+| 0x07 0x0054 | Keypad / | 0x0062 | KEY_KPSLASH | 3.0 | 0x009a | KEYCODE_NUMPAD_DIVIDE | |
+| 0x07 0x0055 | Keypad * | 0x0037 | KEY_KPASTERISK | 3.0 | 0x009b | KEYCODE_NUMPAD_MULTIPLY | |
+| 0x07 0x0056 | Keypad - | 0x004a | KEY_KPMINUS | 3.0 | 0x009c | KEYCODE_NUMPAD_SUBTRACT | |
+| 0x07 0x0057 | Keypad + | 0x004e | KEY_KPPLUS | 3.0 | 0x009d | KEYCODE_NUMPAD_ADD | |
+| 0x07 0x0058 | Keypad ENTER | 0x0060 | KEY_KPENTER | 3.0 | 0x00a0 | KEYCODE_NUMPAD_ENTER | |
+| 0x07 0x0059 | Keypad 1 and End | 0x004f | KEY_KP1 | 3.0 | 0x0091 | KEYCODE_NUMPAD_1 | |
+| 0x07 0x005a | Keypad 2 and Down Arrow | 0x0050 | KEY_KP2 | 3.0 | 0x0092 | KEYCODE_NUMPAD_2 | |
+| 0x07 0x005b | Keypad 3 and PageDn | 0x0051 | KEY_KP3 | 3.0 | 0x0093 | KEYCODE_NUMPAD_3 | |
+| 0x07 0x005c | Keypad 4 and Left Arrow | 0x004b | KEY_KP4 | 3.0 | 0x0094 | KEYCODE_NUMPAD_4 | |
+| 0x07 0x005d | Keypad 5 | 0x004c | KEY_KP5 | 3.0 | 0x0095 | KEYCODE_NUMPAD_5 | |
+| 0x07 0x005e | Keypad 6 and Right Arrow | 0x004d | KEY_KP6 | 3.0 | 0x0096 | KEYCODE_NUMPAD_6 | |
+| 0x07 0x005f | Keypad 7 and Home | 0x0047 | KEY_KP7 | 3.0 | 0x0097 | KEYCODE_NUMPAD_7 | |
+| 0x07 0x0060 | Keypad 8 and Up Arrow | 0x0048 | KEY_KP8 | 3.0 | 0x0098 | KEYCODE_NUMPAD_8 | |
+| 0x07 0x0061 | Keypad 9 and Page Up | 0x0049 | KEY_KP9 | 3.0 | 0x0099 | KEYCODE_NUMPAD_9 | |
+| 0x07 0x0062 | Keypad 0 and Insert | 0x0052 | KEY_KP0 | 3.0 | 0x0090 | KEYCODE_NUMPAD_0 | |
+| 0x07 0x0063 | Keypad . and Delete | 0x0053 | KEY_KPDOT | 3.0 | 0x009e | KEYCODE_NUMPAD_DOT | |
+| 0x07 0x0064 | Keyboard Non-US \\ and | | 0x0056 | KEY_102ND | 4.0 | 0x0049 | KEYCODE_BACKSLASH | 1 |
+| 0x07 0x0065 | Keyboard Application | 0x007f | KEY_COMPOSE | 3.0 | 0x0052 | KEYCODE_MENU | |
+| "" | "" | "" | "" | 1.6 | 0x0054 | KEYCODE_SEARCH | |
+| 0x07 0x0066 | Keyboard Power | 0x0074 | KEY_POWER | 1.6 | 0x001a | KEYCODE_POWER | |
+| 0x07 0x0067 | Keypad = | 0x0075 | KEY_KPEQUAL | 3.0 | 0x00a1 | KEYCODE_NUMPAD_EQUALS | |
+| 0x07 0x0068 | Keyboard F13 | 0x00b7 | KEY_F13 | | | | |
+| 0x07 0x0069 | Keyboard F14 | 0x00b8 | KEY_F14 | | | | |
+| 0x07 0x006a | Keyboard F15 | 0x00b9 | KEY_F15 | | | | |
+| 0x07 0x006b | Keyboard F16 | 0x00ba | KEY_F16 | | | | |
+| 0x07 0x006c | Keyboard F17 | 0x00bb | KEY_F17 | | | | |
+| 0x07 0x006d | Keyboard F18 | 0x00bc | KEY_F18 | | | | |
+| 0x07 0x006e | Keyboard F19 | 0x00bd | KEY_F19 | | | | |
+| 0x07 0x006f | Keyboard F20 | 0x00be | KEY_F20 | | | | |
+| 0x07 0x0070 | Keyboard F21 | 0x00bf | KEY_F21 | | | | |
+| 0x07 0x0071 | Keyboard F22 | 0x00c0 | KEY_F22 | | | | |
+| 0x07 0x0072 | Keyboard F23 | 0x00c1 | KEY_F23 | | | | |
+| 0x07 0x0073 | Keyboard F24 | 0x00c2 | KEY_F24 | | | | |
+| 0x07 0x0074 | Keyboard Execute | 0x0086 | KEY_OPEN | | | | |
+| 0x07 0x0075 | Keyboard Help | 0x008a | KEY_HELP | | | | |
+| 0x07 0x0076 | Keyboard Menu | 0x0082 | KEY_PROPS | | | | |
+| 0x07 0x0077 | Keyboard Select | 0x0084 | KEY_FRONT | | | | |
+| 0x07 0x0078 | Keyboard Stop | 0x0080 | KEY_STOP | 3.0 | 0x0056 | KEYCODE_MEDIA_STOP | |
+| 0x07 0x0079 | Keyboard Again | 0x0081 | KEY_AGAIN | | | | |
+| 0x07 0x007a | Keyboard Undo | 0x0083 | KEY_UNDO | | | | |
+| 0x07 0x007b | Keyboard Cut | 0x0089 | KEY_CUT | | | | |
+| 0x07 0x007c | Keyboard Copy | 0x0085 | KEY_COPY | | | | |
+| 0x07 0x007d | Keyboard Paste | 0x0087 | KEY_PASTE | | | | |
+| 0x07 0x007e | Keyboard Find | 0x0088 | KEY_FIND | | | | |
+| 0x07 0x007f | Keyboard Mute | 0x0071 | KEY_MUTE | 3.0 | 0x00a4 | KEYCODE_VOLUME_MUTE | |
+| 0x07 0x0080 | Keyboard Volume Up | 0x0073 | KEY_VOLUMEUP | 1.6 | 0x0018 | KEYCODE_VOLUME_UP | |
+| 0x07 0x0081 | Keyboard Volume Down | 0x0072 | KEY_VOLUMEDOWN | 1.6 | 0x0019 | KEYCODE_VOLUME_DOWN | |
+| 0x07 0x0082 | Keyboard Locking Caps Lock | | | | | | |
+| 0x07 0x0083 | Keyboard Locking Num Lock | | | | | | |
+| 0x07 0x0084 | Keyboard Locking Scroll Lock | | | | | | |
+| 0x07 0x0085 | Keypad Comma | 0x0079 | KEY_KPCOMMA | 3.0 | 0x009f | KEYCODE_NUMPAD_COMMA | |
+| 0x07 0x0086 | Keypad Equal Sign | | | | | | |
+| 0x07 0x0087 | Keyboard International1 | 0x0059 | KEY_RO | | | | |
+| 0x07 0x0088 | Keyboard International2 | 0x005d | KEY_KATAKANAHIRAGANA | | | | |
+| 0x07 0x0089 | Keyboard International3 | 0x007c | KEY_YEN | | | | |
+| 0x07 0x008a | Keyboard International4 | 0x005c | KEY_HENKAN | | | | |
+| 0x07 0x008b | Keyboard International5 | 0x005e | KEY_MUHENKAN | | | | |
+| 0x07 0x008c | Keyboard International6 | 0x005f | KEY_KPJPCOMMA | | | | |
+| 0x07 0x008d | Keyboard International7 | | | | | | |
+| 0x07 0x008e | Keyboard International8 | | | | | | |
+| 0x07 0x008f | Keyboard International9 | | | | | | |
+| 0x07 0x0090 | Keyboard LANG1 | 0x007a | KEY_HANGEUL | | | | |
+| 0x07 0x0091 | Keyboard LANG2 | 0x007b | KEY_HANJA | | | | |
+| 0x07 0x0092 | Keyboard LANG3 | 0x005a | KEY_KATAKANA | | | | |
+| 0x07 0x0093 | Keyboard LANG4 | 0x005b | KEY_HIRAGANA | | | | |
+| 0x07 0x0094 | Keyboard LANG5 | 0x0055 | KEY_ZENKAKUHANKAKU | | | | |
+| 0x07 0x0095 | Keyboard LANG6 | | | | | | |
+| 0x07 0x0096 | Keyboard LANG7 | | | | | | |
+| 0x07 0x0097 | Keyboard LANG8 | | | | | | |
+| 0x07 0x0098 | Keyboard LANG9 | | | | | | |
+| 0x07 0x0099 | Keyboard Alternate Erase | | | | | | |
+| 0x07 0x009a | Keyboard SysReq/Attention | | | | | | |
+| 0x07 0x009b | Keyboard Cancel | | | | | | |
+| 0x07 0x009c | Keyboard Clear | | | | | | |
+| 0x07 0x009d | Keyboard Prior | | | | | | |
+| 0x07 0x009e | Keyboard Return | | | | | | |
+| 0x07 0x009f | Keyboard Separator | | | | | | |
+| 0x07 0x00a0 | Keyboard Out | | | | | | |
+| 0x07 0x00a1 | Keyboard Oper | | | | | | |
+| 0x07 0x00a2 | Keyboard Clear/Again | | | | | | |
+| 0x07 0x00a3 | Keyboard CrSel/Props | | | | | | |
+| 0x07 0x00a4 | Keyboard ExSel | | | | | | |
+| 0x07 0x00b0 | Keypad 00 | | | | | | |
+| 0x07 0x00b1 | Keypad 000 | | | | | | |
+| 0x07 0x00b2 | Thousands Separator | | | | | | |
+| 0x07 0x00b3 | Decimal Separator | | | | | | |
+| 0x07 0x00b4 | Currency Unit | | | | | | |
+| 0x07 0x00b5 | Currency Sub-unit | | | | | | |
+| 0x07 0x00b6 | Keypad ( | 0x00b3 | KEY_KPLEFTPAREN | 3.0 | 0x00a2 | KEYCODE_NUMPAD_LEFT_PAREN | |
+| 0x07 0x00b7 | Keypad ) | 0x00b4 | KEY_KPRIGHTPAREN | 3.0 | 0x00a3 | KEYCODE_NUMPAD_RIGHT_PAREN | |
+| 0x07 0x00b8 | Keypad \{ | | | | | | |
+| 0x07 0x00b9 | Keypad \} | | | | | | |
+| 0x07 0x00ba | Keypad Tab | | | | | | |
+| 0x07 0x00bb | Keypad Backspace | | | | | | |
+| 0x07 0x00bc | Keypad A | | | | | | |
+| 0x07 0x00bd | Keypad B | | | | | | |
+| 0x07 0x00be | Keypad C | | | | | | |
+| 0x07 0x00bf | Keypad D | | | | | | |
+| 0x07 0x00c0 | Keypad E | | | | | | |
+| 0x07 0x00c1 | Keypad F | | | | | | |
+| 0x07 0x00c2 | Keypad XOR | | | | | | |
+| 0x07 0x00c3 | Keypad ^ | | | | | | |
+| 0x07 0x00c4 | Keypad % | | | | | | |
+| 0x07 0x00c5 | Keypad < | | | | | | |
+| 0x07 0x00c6 | Keypad > | | | | | | |
+| 0x07 0x00c7 | Keypad & | | | | | | |
+| 0x07 0x00c8 | Keypad && | | | | | | |
+| 0x07 0x00c9 | Keypad | | | | | | | |
+| 0x07 0x00ca | Keypad || | | | | | | |
+| 0x07 0x00cb | Keypad : | | | | | | |
+| 0x07 0x00cc | Keypad # | | | | | | |
+| 0x07 0x00cd | Keypad Space | | | | | | |
+| 0x07 0x00ce | Keypad @ | | | | | | |
+| 0x07 0x00cf | Keypad ! | | | | | | |
+| 0x07 0x00d0 | Keypad Memory Store | | | | | | |
+| 0x07 0x00d1 | Keypad Memory Recall | | | | | | |
+| 0x07 0x00d2 | Keypad Memory Clear | | | | | | |
+| 0x07 0x00d3 | Keypad Memory Add | | | | | | |
+| 0x07 0x00d4 | Keypad Memory Subtract | | | | | | |
+| 0x07 0x00d5 | Keypad Memory Multiply | | | | | | |
+| 0x07 0x00d6 | Keypad Memory Divide | | | | | | |
+| 0x07 0x00d7 | Keypad +/- | | | | | | |
+| 0x07 0x00d8 | Keypad Clear | | | | | | |
+| 0x07 0x00d9 | Keypad Clear Entry | | | | | | |
+| 0x07 0x00da | Keypad Binary | | | | | | |
+| 0x07 0x00db | Keypad Octal | | | | | | |
+| 0x07 0x00dc | Keypad Decimal | | | | | | |
+| 0x07 0x00dd | Keypad Hexadecimal | | | | | | |
+| 0x07 0x00e0 | Keyboard Left Control | 0x001d | KEY_LEFTCTRL | 3.0 | 0x0071 | KEYCODE_CTRL_LEFT | |
+| 0x07 0x00e1 | Keyboard Left Shift | 0x002a | KEY_LEFTSHIFT | 1.6 | 0x003b | KEYCODE_SHIFT_LEFT | |
+| 0x07 0x00e2 | Keyboard Left Alt | 0x0038 | KEY_LEFTALT | 1.6 | 0x0039 | KEYCODE_ALT_LEFT | |
+| 0x07 0x00e3 | Keyboard Left GUI | 0x007d | KEY_LEFTMETA | 3.0 | 0x0075 | KEYCODE_META_LEFT | |
+| 0x07 0x00e4 | Keyboard Right Control | 0x0061 | KEY_RIGHTCTRL | 3.0 | 0x0072 | KEYCODE_CTRL_RIGHT | |
+| 0x07 0x00e5 | Keyboard Right Shift | 0x0036 | KEY_RIGHTSHIFT | 1.6 | 0x003c | KEYCODE_SHIFT_RIGHT | |
+| 0x07 0x00e6 | Keyboard Right Alt | 0x0064 | KEY_RIGHTALT | 1.6 | 0x003a | KEYCODE_ALT_RIGHT | |
+| 0x07 0x00e7 | Keyboard Right GUI | 0x007e | KEY_RIGHTMETA | 3.0 | 0x0076 | KEYCODE_META_RIGHT | |
+| 0x07 0x00e8 | | 0x00a4 | KEY_PLAYPAUSE | 3.0 | 0x0055 | KEYCODE_MEDIA_PLAY_PAUSE | |
+| 0x07 0x00e9 | | 0x00a6 | KEY_STOPCD | 3.0 | 0x0056 | KEYCODE_MEDIA_STOP | |
+| 0x07 0x00ea | | 0x00a5 | KEY_PREVIOUSSONG | 3.0 | 0x0058 | KEYCODE_MEDIA_PREVIOUS | |
+| 0x07 0x00eb | | 0x00a3 | KEY_NEXTSONG | 3.0 | 0x0057 | KEYCODE_MEDIA_NEXT | |
+| 0x07 0x00ec | | 0x00a1 | KEY_EJECTCD | 3.0 | 0x0081 | KEYCODE_MEDIA_EJECT | |
+| 0x07 0x00ed | | 0x0073 | KEY_VOLUMEUP | 1.6 | 0x0018 | KEYCODE_VOLUME_UP | |
+| 0x07 0x00ee | | 0x0072 | KEY_VOLUMEDOWN | 1.6 | 0x0019 | KEYCODE_VOLUME_DOWN | |
+| 0x07 0x00ef | | 0x0071 | KEY_MUTE | 3.0 | 0x00a4 | KEYCODE_VOLUME_MUTE | |
+| 0x07 0x00f0 | | 0x0096 | KEY_WWW | 1.6 | 0x0040 | KEYCODE_EXPLORER | |
+| 0x07 0x00f1 | | 0x009e | KEY_BACK | 1.6 | 0x0004 | KEYCODE_BACK | |
+| 0x07 0x00f2 | | 0x009f | KEY_FORWARD | 3.0 | 0x007d | KEYCODE_FORWARD | |
+| 0x07 0x00f3 | | 0x0080 | KEY_STOP | 3.0 | 0x0056 | KEYCODE_MEDIA_STOP | |
+| 0x07 0x00f4 | | 0x0088 | KEY_FIND | | | | |
+| 0x07 0x00f5 | | 0x00b1 | KEY_SCROLLUP | 3.0 | 0x005c | KEYCODE_PAGE_UP | |
+| 0x07 0x00f6 | | 0x00b2 | KEY_SCROLLDOWN | 3.0 | 0x005d | KEYCODE_PAGE_DOWN | |
+| 0x07 0x00f7 | | 0x00b0 | KEY_EDIT | | | | |
+| 0x07 0x00f8 | | 0x008e | KEY_SLEEP | | | | |
+| 0x07 0x00f9 | | 0x0098 | KEY_COFFEE | 4.0 | 0x001a | KEYCODE_POWER | |
+| 0x07 0x00fa | | 0x00ad | KEY_REFRESH | | | | |
+| 0x07 0x00fb | | 0x008c | KEY_CALC | 4.0.3 | 0x00d2 | KEYCODE_CALCULATOR | |
+
+### HID Generic Desktop Page (0x01) ###
+
+| HID Usage | HID Usage Name | LKC | Linux Key Code Name | Version | AKC | Android Key Code Name | Notes |
+| ----------- | -------------------------------- | ------ | -------------------------------- | ------- | ------ | -------------------------------- | ----- |
+| 0x01 0x0081 | System Power Down | 0x0074 | KEY_POWER | 1.6 | 0x001a | KEYCODE_POWER | |
+| 0x01 0x0082 | System Sleep | 0x008e | KEY_SLEEP | 4.0 | 0x001a | KEYCODE_POWER | |
+| 0x01 0x0083 | System Wake Up | 0x008f | KEY_WAKEUP | 4.0 | 0x001a | KEYCODE_POWER | |
+| 0x01 0x0084 | System Context Menu | | | | | | |
+| 0x01 0x0085 | System Main Menu | | | | | | |
+| 0x01 0x0086 | System App Menu | | | | | | |
+| 0x01 0x0087 | System Menu Help | | | | | | |
+| 0x01 0x0088 | System Menu Exit | | | | | | |
+| 0x01 0x0089 | System Menu Select | | | | | | |
+| 0x01 0x008a | System Menu Right | | | | | | |
+| 0x01 0x008b | System Menu Left | | | | | | |
+| 0x01 0x008c | System Menu Up | | | | | | |
+| 0x01 0x008d | System Menu Down | | | | | | |
+| 0x01 0x008e | System Cold Restart | | | | | | |
+| 0x01 0x008f | System Warm Restart | | | | | | |
+| 0x01 0x00a0 | System Dock | | | | | | |
+| 0x01 0x00a1 | System Undock | | | | | | |
+| 0x01 0x00a2 | System Setup | | | | | | |
+| 0x01 0x00a3 | System Break | | | | | | |
+| 0x01 0x00a4 | System Debugger Break | | | | | | |
+| 0x01 0x00a5 | Application Break | | | | | | |
+| 0x01 0x00a6 | Application Debugger Break | | | | | | |
+| 0x01 0x00a7 | System Speaker Mute | | | | | | |
+| 0x01 0x00a8 | System Hibernate | | | | | | |
+| 0x01 0x00b0 | System Display Invert | | | | | | |
+| 0x01 0x00b1 | System Display Internal | | | | | | |
+| 0x01 0x00b2 | System Display External | | | | | | |
+| 0x01 0x00b3 | System Display Both | | | | | | |
+| 0x01 0x00b4 | System Display Dual | | | | | | |
+| 0x01 0x00b5 | System Display Toggle Int/Ext | | | | | | |
+| 0x01 0x00b6 | System Display Swap Prim./Sec. | | | | | | |
+| 0x01 0x00b7 | System Display LCD Autoscale | | | | | | |
+
+### HID Consumer Page (0x0c) ###
+
+| HID Usage | HID Usage Name | LKC | Linux Key Code Name | Version | AKC | Android Key Code Name | Notes |
+| ----------- | -------------------------------- | ------ | -------------------------------- | ------- | ------ | -------------------------------- | ----- |
+| 0x0c 0x0030 | Power | | | | | | |
+| 0x0c 0x0031 | Reset | | | | | | |
+| 0x0c 0x0032 | Sleep | | | | | | |
+| 0x0c 0x0033 | Sleep After | | | | | | |
+| 0x0c 0x0034 | Sleep Mode | 0x008e | KEY_SLEEP | 4.0 | 0x001a | KEYCODE_POWER | |
+| 0x0c 0x0040 | Menu | 0x008b | KEY_MENU | 1.6 | 0x0052 | KEYCODE_MENU | |
+| 0x0c 0x0041 | Menu Pick | | | | | | |
+| 0x0c 0x0042 | Menu Up | | | | | | |
+| 0x0c 0x0043 | Menu Down | | | | | | |
+| 0x0c 0x0044 | Menu Left | | | | | | |
+| 0x0c 0x0045 | Menu Right | 0x0181 | KEY_RADIO | | | | |
+| 0x0c 0x0046 | Menu Escape | | | | | | |
+| 0x0c 0x0047 | Menu Value Increase | | | | | | |
+| 0x0c 0x0048 | Menu Value Decrease | | | | | | |
+| 0x0c 0x0081 | Assign Selection | | | | | | |
+| 0x0c 0x0082 | Mode Step | | | | | | |
+| 0x0c 0x0083 | Recall Last | 0x0195 | KEY_LAST | | | | |
+| 0x0c 0x0084 | Enter Channel | | | | | | |
+| 0x0c 0x0085 | Order Movie | | | | | | |
+| 0x0c 0x0088 | Media Select Computer | 0x0178 | KEY_PC | | | | |
+| 0x0c 0x0089 | Media Select TV | 0x0179 | KEY_TV | 3.0 | 0x00aa | KEYCODE_TV | |
+| 0x0c 0x008a | Media Select WWW | 0x0096 | KEY_WWW | 1.6 | 0x0040 | KEYCODE_EXPLORER | |
+| 0x0c 0x008b | Media Select DVD | 0x0185 | KEY_DVD | | | | |
+| 0x0c 0x008c | Media Select Telephone | 0x00a9 | KEY_PHONE | 3.0 | 0x0005 | KEYCODE_CALL | |
+| 0x0c 0x008d | Media Select Program Guide | 0x016a | KEY_PROGRAM | 3.0 | 0x00ac | KEYCODE_GUIDE | |
+| 0x0c 0x008e | Media Select Video Phone | 0x01a0 | KEY_VIDEOPHONE | | | | |
+| 0x0c 0x008f | Media Select Games | 0x01a1 | KEY_GAMES | | | | |
+| 0x0c 0x0090 | Media Select Messages | 0x018c | KEY_MEMO | | | | |
+| 0x0c 0x0091 | Media Select CD | 0x017f | KEY_CD | | | | |
+| 0x0c 0x0092 | Media Select VCR | 0x017b | KEY_VCR | | | | |
+| 0x0c 0x0093 | Media Select Tuner | 0x0182 | KEY_TUNER | | | | |
+| 0x0c 0x0094 | Quit | 0x00ae | KEY_EXIT | | | | |
+| 0x0c 0x0095 | Help | 0x008a | KEY_HELP | | | | |
+| 0x0c 0x0096 | Media Select Tape | 0x0180 | KEY_TAPE | | | | |
+| 0x0c 0x0097 | Media Select Cable | 0x017a | KEY_TV2 | | | | |
+| 0x0c 0x0098 | Media Select Satellite | 0x017d | KEY_SAT | | | | |
+| 0x0c 0x0099 | Media Select Security | | | | | | |
+| 0x0c 0x009a | Media Select Home | 0x016e | KEY_PVR | 3.0 | 0x00ad | KEYCODE_DVR | |
+| 0x0c 0x009c | Channel Increment | 0x0192 | KEY_CHANNELUP | 3.0 | 0x00a6 | KEYCODE_CHANNEL_UP | |
+| 0x0c 0x009d | Channel Decrement | 0x0193 | KEY_CHANNELDOWN | 3.0 | 0x00a7 | KEYCODE_CHANNEL_DOWN | |
+| 0x0c 0x009e | Media Select SAP | | | | | | |
+| 0x0c 0x00a0 | VCR Plus | 0x017c | KEY_VCR2 | | | | |
+| 0x0c 0x00a1 | Once | | | | | | |
+| 0x0c 0x00a2 | Daily | | | | | | |
+| 0x0c 0x00a3 | Weekly | | | | | | |
+| 0x0c 0x00a4 | Monthly | | | | | | |
+| 0x0c 0x00b0 | Play | 0x00cf | KEY_PLAY | 3.0 | 0x007e | KEYCODE_MEDIA_PLAY | |
+| 0x0c 0x00b1 | Pause | 0x0077 | KEY_PAUSE | 3.0 | 0x0079 | KEYCODE_BREAK | |
+| 0x0c 0x00b2 | Record | 0x00a7 | KEY_RECORD | 3.0 | 0x0082 | KEYCODE_MEDIA_RECORD | |
+| 0x0c 0x00b3 | Fast Forward | 0x00d0 | KEY_FASTFORWARD | 3.0 | 0x005a | KEYCODE_MEDIA_FAST_FORWARD | |
+| 0x0c 0x00b4 | Rewind | 0x00a8 | KEY_REWIND | 3.0 | 0x0059 | KEYCODE_MEDIA_REWIND | |
+| 0x0c 0x00b5 | Scan Next Track | 0x00a3 | KEY_NEXTSONG | 3.0 | 0x0057 | KEYCODE_MEDIA_NEXT | |
+| 0x0c 0x00b6 | Scan Previous Track | 0x00a5 | KEY_PREVIOUSSONG | 3.0 | 0x0058 | KEYCODE_MEDIA_PREVIOUS | |
+| 0x0c 0x00b7 | Stop | 0x00a6 | KEY_STOPCD | 3.0 | 0x0056 | KEYCODE_MEDIA_STOP | |
+| 0x0c 0x00b8 | Eject | 0x00a1 | KEY_EJECTCD | 3.0 | 0x0081 | KEYCODE_MEDIA_EJECT | |
+| 0x0c 0x00b9 | Random Play | | | | | | |
+| 0x0c 0x00ba | Select Disc | | | | | | |
+| 0x0c 0x00bb | Enter Disc | | | | | | |
+| 0x0c 0x00bc | Repeat | 0x01b7 | KEY_MEDIA_REPEAT | | | | |
+| 0x0c 0x00be | Track Normal | | | | | | |
+| 0x0c 0x00c0 | Frame Forward | | | | | | |
+| 0x0c 0x00c1 | Frame Back | | | | | | |
+| 0x0c 0x00c2 | Mark | | | | | | |
+| 0x0c 0x00c3 | Clear Mark | | | | | | |
+| 0x0c 0x00c4 | Repeat From Mark | | | | | | |
+| 0x0c 0x00c5 | Return To Mark | | | | | | |
+| 0x0c 0x00c6 | Search Mark Forward | | | | | | |
+| 0x0c 0x00c7 | Search Mark Backwards | | | | | | |
+| 0x0c 0x00c8 | Counter Reset | | | | | | |
+| 0x0c 0x00c9 | Show Counter | | | | | | |
+| 0x0c 0x00ca | Tracking Increment | | | | | | |
+| 0x0c 0x00cb | Tracking Decrement | | | | | | |
+| 0x0c 0x00cc | Stop / Eject | | | | | | |
+| 0x0c 0x00cd | Play / Pause | 0x00a4 | KEY_PLAYPAUSE | 3.0 | 0x0055 | KEYCODE_MEDIA_PLAY_PAUSE | |
+| 0x0c 0x00ce | Play / Skip | | | | | | |
+| 0x0c 0x00e2 | Mute | 0x0071 | KEY_MUTE | 3.0 | 0x00a4 | KEYCODE_VOLUME_MUTE | |
+| 0x0c 0x00e5 | Bass Boost | 0x00d1 | KEY_BASSBOOST | | | | |
+| 0x0c 0x00e6 | Surround Mode | | | | | | |
+| 0x0c 0x00e7 | Loudness | | | | | | |
+| 0x0c 0x00e8 | MPX | | | | | | |
+| 0x0c 0x00e9 | Volume Increment | 0x0073 | KEY_VOLUMEUP | 1.6 | 0x0018 | KEYCODE_VOLUME_UP | |
+| 0x0c 0x00ea | Volume Decrement | 0x0072 | KEY_VOLUMEDOWN | 1.6 | 0x0019 | KEYCODE_VOLUME_DOWN | |
+| 0x0c 0x0181 | AL Launch Button Config. Tool | | | | | | |
+| 0x0c 0x0182 | AL Programmable Button Config. | 0x009c | KEY_BOOKMARKS | 3.0 | 0x00ae | KEYCODE_BOOKMARK | |
+| 0x0c 0x0183 | AL Consumer Control Config. | 0x00ab | KEY_CONFIG | 4.0.3 | 0x00d1 | KEYCODE_MUSIC | |
+| 0x0c 0x0184 | AL Word Processor | 0x01a5 | KEY_WORDPROCESSOR | | | | |
+| 0x0c 0x0185 | AL Text Editor | 0x01a6 | KEY_EDITOR | | | | |
+| 0x0c 0x0186 | AL Spreadsheet | 0x01a7 | KEY_SPREADSHEET | | | | |
+| 0x0c 0x0187 | AL Graphics Editor | 0x01a8 | KEY_GRAPHICSEDITOR | | | | |
+| 0x0c 0x0188 | AL Presentation App | 0x01a9 | KEY_PRESENTATION | | | | |
+| 0x0c 0x0189 | AL Database App | 0x01aa | KEY_DATABASE | | | | |
+| 0x0c 0x018a | AL Email Reader | 0x009b | KEY_MAIL | 1.6 | 0x0041 | KEYCODE_ENVELOPE | |
+| 0x0c 0x018b | AL Newsreader | 0x01ab | KEY_NEWS | | | | |
+| 0x0c 0x018c | AL Voicemail | 0x01ac | KEY_VOICEMAIL | | | | |
+| 0x0c 0x018d | AL Contacts / Address Book | 0x01ad | KEY_ADDRESSBOOK | 4.0.3 | 0x00cf | KEYCODE_CONTACTS | |
+| 0x0c 0x018e | AL Calendar / Schedule | 0x018d | KEY_CALENDAR | 4.0.3 | 0x00d0 | KEYCODE_CALENDAR | |
+| 0x0c 0x018f | AL Task / Project Manager | | | | | | |
+| 0x0c 0x0190 | AL Log / Journal / Timecard | | | | | | |
+| 0x0c 0x0191 | AL Checkbook / Finance | 0x00db | KEY_FINANCE | | | | |
+| 0x0c 0x0192 | AL Calculator | 0x008c | KEY_CALC | 4.0.3 | 0x00d2 | KEYCODE_CALCULATOR | |
+| 0x0c 0x0193 | AL A/V Capture / Playback | | | | | | |
+| 0x0c 0x0194 | AL Local Machine Browser | 0x0090 | KEY_FILE | | | | |
+| 0x0c 0x0195 | AL LAN/WAN Browser | | | | | | |
+| 0x0c 0x0196 | AL Internet Browser | 0x0096 | KEY_WWW | 1.6 | 0x0040 | KEYCODE_EXPLORER | |
+| 0x0c 0x0197 | AL Remote Networking/ISP Connect | | | | | | |
+| 0x0c 0x0198 | AL Network Conference | | | | | | |
+| 0x0c 0x0199 | AL Network Chat | 0x00d8 | KEY_CHAT | | | | |
+| 0x0c 0x019a | AL Telephony / Dialer | | | | | | |
+| 0x0c 0x019b | AL Logon | | | | | | |
+| 0x0c 0x019c | AL Logoff | 0x01b1 | KEY_LOGOFF | | | | |
+| 0x0c 0x019d | AL Logon / Logoff | | | | | | |
+| 0x0c 0x019e | AL Terminal Lock / Screensaver | 0x0098 | KEY_COFFEE | 4.0 | 0x001a | KEYCODE_POWER | |
+| 0x0c 0x019f | AL Control Panel | | | | | | |
+| 0x0c 0x01a0 | AL Command Line Processor / Run | | | | | | |
+| 0x0c 0x01a1 | AL Process / Task Manager | | | | | | |
+| 0x0c 0x01a2 | AL Select Task / Application | | | | | | |
+| 0x0c 0x01a3 | AL Next Task / Application | | | | | | |
+| 0x0c 0x01a4 | AL Previous Task / Application | | | | | | |
+| 0x0c 0x01a5 | AL Preemptive Halt Task / App. | | | | | | |
+| 0x0c 0x01a6 | AL Integrated Help Center | 0x008a | KEY_HELP | | | | |
+| 0x0c 0x01a7 | AL Documents | 0x00eb | KEY_DOCUMENTS | | | | |
+| 0x0c 0x01a8 | AL Thesaurus | | | | | | |
+| 0x0c 0x01a9 | AL Dictionary | | | | | | |
+| 0x0c 0x01aa | AL Desktop | | | | | | |
+| 0x0c 0x01ab | AL Spell Check | 0x01b0 | KEY_SPELLCHECK | | | | |
+| 0x0c 0x01ac | AL Grammar Check | | | | | | |
+| 0x0c 0x01ad | AL Wireless Status | | | | | | |
+| 0x0c 0x01ae | AL Keyboard Layout | | | | | | |
+| 0x0c 0x01af | AL Virus Protection | | | | | | |
+| 0x0c 0x01b0 | AL Encryption | | | | | | |
+| 0x0c 0x01b1 | AL Screen Saver | | | | | | |
+| 0x0c 0x01b2 | AL Alarms | | | | | | |
+| 0x0c 0x01b3 | AL Clock | | | | | | |
+| 0x0c 0x01b4 | AL File Browser | | | | | | |
+| 0x0c 0x01b5 | AL Power Status | | | | | | |
+| 0x0c 0x01b6 | AL Image Browser | 0x00e2 | KEY_MEDIA | 3.0 | 0x004f | KEYCODE_HEADSETHOOK | |
+| 0x0c 0x01b7 | AL Audio Browser | 0x00d5 | KEY_SOUND | 4.0.3 | 0x00d1 | KEYCODE_MUSIC | |
+| 0x0c 0x01b8 | AL Movie Browser | | | | | | |
+| 0x0c 0x01b9 | AL Digital Rights Manager | | | | | | |
+| 0x0c 0x01ba | AL Digital Wallet | | | | | | |
+| 0x0c 0x01bc | AL Instant Messaging | 0x01ae | KEY_MESSENGER | | | | |
+| 0x0c 0x01bd | AL OEM Features / Tips Browser | 0x0166 | KEY_INFO | | | | |
+| 0x0c 0x01be | AL OEM Help | | | | | | |
+| 0x0c 0x01bf | AL Online Community | | | | | | |
+| 0x0c 0x01c0 | AL Entertainment Content Browser | | | | | | |
+| 0x0c 0x01c1 | AL Online Shopping Browser | | | | | | |
+| 0x0c 0x01c2 | AL SmartCard Information / Help | | | | | | |
+| 0x0c 0x01c3 | AL Market / Finance Browser | | | | | | |
+| 0x0c 0x01c4 | AL Customized Corp. News Browser | | | | | | |
+| 0x0c 0x01c5 | AL Online Activity Browser | | | | | | |
+| 0x0c 0x01c6 | AL Research / Search Browser | | | | | | |
+| 0x0c 0x01c7 | AL Audio Player | | | | | | |
+| 0x0c 0x0201 | AC New | 0x00b5 | KEY_NEW | | | | |
+| 0x0c 0x0202 | AC Open | 0x0086 | KEY_OPEN | | | | |
+| 0x0c 0x0203 | AC Close | 0x00ce | KEY_CLOSE | | | | |
+| 0x0c 0x0204 | AC Exit | 0x00ae | KEY_EXIT | | | | |
+| 0x0c 0x0205 | AC Maximize | | | | | | |
+| 0x0c 0x0206 | AC Minimize | | | | | | |
+| 0x0c 0x0207 | AC Save | 0x00ea | KEY_SAVE | | | | |
+| 0x0c 0x0208 | AC Print | 0x00d2 | KEY_PRINT | | | | |
+| 0x0c 0x0209 | AC Properties | 0x0082 | KEY_PROPS | | | | |
+| 0x0c 0x021a | AC Undo | 0x0083 | KEY_UNDO | | | | |
+| 0x0c 0x021b | AC Copy | 0x0085 | KEY_COPY | | | | |
+| 0x0c 0x021c | AC Cut | 0x0089 | KEY_CUT | | | | |
+| 0x0c 0x021d | AC Paste | 0x0087 | KEY_PASTE | | | | |
+| 0x0c 0x021e | AC Select All | | | | | | |
+| 0x0c 0x021f | AC Find | 0x0088 | KEY_FIND | | | | |
+| 0x0c 0x0220 | AC Find and Replace | | | | | | |
+| 0x0c 0x0221 | AC Search | 0x00d9 | KEY_SEARCH | 1.6 | 0x0054 | KEYCODE_SEARCH | |
+| 0x0c 0x0222 | AC Go To | 0x0162 | KEY_GOTO | | | | |
+| 0x0c 0x0223 | AC Home | 0x00ac | KEY_HOMEPAGE | 3.0 | 0x0003 | KEYCODE_HOME | |
+| 0x0c 0x0224 | AC Back | 0x009e | KEY_BACK | 1.6 | 0x0004 | KEYCODE_BACK | |
+| 0x0c 0x0225 | AC Forward | 0x009f | KEY_FORWARD | 3.0 | 0x007d | KEYCODE_FORWARD | |
+| 0x0c 0x0226 | AC Stop | 0x0080 | KEY_STOP | 3.0 | 0x0056 | KEYCODE_MEDIA_STOP | |
+| 0x0c 0x0227 | AC Refresh | 0x00ad | KEY_REFRESH | | | | |
+| 0x0c 0x0228 | AC Previous Link | | | | | | |
+| 0x0c 0x0229 | AC Next Link | | | | | | |
+| 0x0c 0x022a | AC Bookmarks | 0x009c | KEY_BOOKMARKS | 3.0 | 0x00ae | KEYCODE_BOOKMARK | |
+| 0x0c 0x022b | AC History | | | | | | |
+| 0x0c 0x022c | AC Subscriptions | | | | | | |
+| 0x0c 0x022d | AC Zoom In | 0x01a2 | KEY_ZOOMIN | | | | |
+| 0x0c 0x022e | AC Zoom Out | 0x01a3 | KEY_ZOOMOUT | | | | |
+| 0x0c 0x022f | AC Zoom | 0x01a4 | KEY_ZOOMRESET | | | | 2 |
+| 0x0c 0x0230 | AC Full Screen View | | | | | | |
+| 0x0c 0x0231 | AC Normal View | | | | | | |
+| 0x0c 0x0232 | AC View Toggle | | | | | | |
+| 0x0c 0x0233 | AC Scroll Up | 0x00b1 | KEY_SCROLLUP | 3.0 | 0x005c | KEYCODE_PAGE_UP | |
+| 0x0c 0x0234 | AC Scroll Down | 0x00b2 | KEY_SCROLLDOWN | 3.0 | 0x005d | KEYCODE_PAGE_DOWN | |
+| 0x0c 0x0236 | AC Pan Left | | | | | | |
+| 0x0c 0x0237 | AC Pan Right | | | | | | |
+| 0x0c 0x0239 | AC New Window | | | | | | |
+| 0x0c 0x023a | AC Tile Horizontally | | | | | | |
+| 0x0c 0x023b | AC Tile Vertically | | | | | | |
+| 0x0c 0x023c | AC Format | | | | | | |
+| 0x0c 0x023d | AC Edit | | | | | | |
+| 0x0c 0x023e | AC Bold | | | | | | |
+| 0x0c 0x023f | AC Italics | | | | | | |
+| 0x0c 0x0240 | AC Underline | | | | | | |
+| 0x0c 0x0241 | AC Strikethrough | | | | | | |
+| 0x0c 0x0242 | AC Subscript | | | | | | |
+| 0x0c 0x0243 | AC Superscript | | | | | | |
+| 0x0c 0x0244 | AC All Caps | | | | | | |
+| 0x0c 0x0245 | AC Rotate | | | | | | |
+| 0x0c 0x0246 | AC Resize | | | | | | |
+| 0x0c 0x0247 | AC Flip horizontal | | | | | | |
+| 0x0c 0x0248 | AC Flip Vertical | | | | | | |
+| 0x0c 0x0249 | AC Mirror Horizontal | | | | | | |
+| 0x0c 0x024a | AC Mirror Vertical | | | | | | |
+| 0x0c 0x024b | AC Font Select | | | | | | |
+| 0x0c 0x024c | AC Font Color | | | | | | |
+| 0x0c 0x024d | AC Font Size | | | | | | |
+| 0x0c 0x024e | AC Justify Left | | | | | | |
+| 0x0c 0x024f | AC Justify Center H | | | | | | |
+| 0x0c 0x0250 | AC Justify Right | | | | | | |
+| 0x0c 0x0251 | AC Justify Block H | | | | | | |
+| 0x0c 0x0252 | AC Justify Top | | | | | | |
+| 0x0c 0x0253 | AC Justify Center V | | | | | | |
+| 0x0c 0x0254 | AC Justify Bottom | | | | | | |
+| 0x0c 0x0255 | AC Justify Block V | | | | | | |
+| 0x0c 0x0256 | AC Indent Decrease | | | | | | |
+| 0x0c 0x0257 | AC Indent Increase | | | | | | |
+| 0x0c 0x0258 | AC Numbered List | | | | | | |
+| 0x0c 0x0259 | AC Restart Numbering | | | | | | |
+| 0x0c 0x025a | AC Bulleted List | | | | | | |
+| 0x0c 0x025b | AC Promote | | | | | | |
+| 0x0c 0x025c | AC Demote | | | | | | |
+| 0x0c 0x025d | AC Yes | | | | | | |
+| 0x0c 0x025e | AC No | | | | | | |
+| 0x0c 0x025f | AC Cancel | 0x00df | KEY_CANCEL | | | | |
+| 0x0c 0x0260 | AC Catalog | | | | | | |
+| 0x0c 0x0261 | AC Buy / Checkout | | | | | | |
+| 0x0c 0x0262 | AC Add to Cart | | | | | | |
+| 0x0c 0x0263 | AC Expand | | | | | | |
+| 0x0c 0x0264 | AC Expand All | | | | | | |
+| 0x0c 0x0265 | AC Collapse | | | | | | |
+| 0x0c 0x0266 | AC Collapse All | | | | | | |
+| 0x0c 0x0267 | AC Print Preview | | | | | | |
+| 0x0c 0x0268 | AC Paste Special | | | | | | |
+| 0x0c 0x0269 | AC Insert Mode | | | | | | |
+| 0x0c 0x026a | AC Delete | | | | | | |
+| 0x0c 0x026b | AC Lock | | | | | | |
+| 0x0c 0x026c | AC Unlock | | | | | | |
+| 0x0c 0x026d | AC Protect | | | | | | |
+| 0x0c 0x026e | AC Unprotect | | | | | | |
+| 0x0c 0x026f | AC Attach Comment | | | | | | |
+| 0x0c 0x0270 | AC Delete Comment | | | | | | |
+| 0x0c 0x0271 | AC View Comment | | | | | | |
+| 0x0c 0x0272 | AC Select Word | | | | | | |
+| 0x0c 0x0273 | AC Select Sentence | | | | | | |
+| 0x0c 0x0274 | AC Select Paragraph | | | | | | |
+| 0x0c 0x0275 | AC Select Column | | | | | | |
+| 0x0c 0x0276 | AC Select Row | | | | | | |
+| 0x0c 0x0277 | AC Select Table | | | | | | |
+| 0x0c 0x0278 | AC Select Object | | | | | | |
+| 0x0c 0x0279 | AC Redo / Repeat | 0x00b6 | KEY_REDO | | | | |
+| 0x0c 0x027a | AC Sort | | | | | | |
+| 0x0c 0x027b | AC Sort Ascending | | | | | | |
+| 0x0c 0x027c | AC Sort Descending | | | | | | |
+| 0x0c 0x027d | AC Filter | | | | | | |
+| 0x0c 0x027e | AC Set Clock | | | | | | |
+| 0x0c 0x027f | AC View Clock | | | | | | |
+| 0x0c 0x0280 | AC Select Time Zone | | | | | | |
+| 0x0c 0x0281 | AC Edit Time Zones | | | | | | |
+| 0x0c 0x0282 | AC Set Alarm | | | | | | |
+| 0x0c 0x0283 | AC Clear Alarm | | | | | | |
+| 0x0c 0x0284 | AC Snooze Alarm | | | | | | |
+| 0x0c 0x0285 | AC Reset Alarm | | | | | | |
+| 0x0c 0x0286 | AC Synchronize | | | | | | |
+| 0x0c 0x0287 | AC Send/Receive | | | | | | |
+| 0x0c 0x0288 | AC Send To | | | | | | |
+| 0x0c 0x0289 | AC Reply | 0x00e8 | KEY_REPLY | | | | |
+| 0x0c 0x028a | AC Reply All | | | | | | |
+| 0x0c 0x028b | AC Forward Msg | 0x00e9 | KEY_FORWARDMAIL | | | | |
+| 0x0c 0x028c | AC Send | 0x00e7 | KEY_SEND | | | | |
+| 0x0c 0x028d | AC Attach File | | | | | | |
+| 0x0c 0x028e | AC Upload | | | | | | |
+| 0x0c 0x028f | AC Download (Save Target As) | | | | | | |
+| 0x0c 0x0290 | AC Set Borders | | | | | | |
+| 0x0c 0x0291 | AC Insert Row | | | | | | |
+| 0x0c 0x0292 | AC Insert Column | | | | | | |
+| 0x0c 0x0293 | AC Insert File | | | | | | |
+| 0x0c 0x0294 | AC Insert Picture | | | | | | |
+| 0x0c 0x0295 | AC Insert Object | | | | | | |
+| 0x0c 0x0296 | AC Insert Symbol | | | | | | |
+| 0x0c 0x0297 | AC Save and Close | | | | | | |
+| 0x0c 0x0298 | AC Rename | | | | | | |
+| 0x0c 0x0299 | AC Merge | | | | | | |
+| 0x0c 0x029a | AC Split | | | | | | |
+| 0x0c 0x029b | AC Distribute Horizontally | | | | | | |
+| 0x0c 0x029c | AC Distribute Vertically | | | | | | |
+
+### Additional non-HID Mappings ###
+
+These mappings describe functions that do not appear in HID but for which Linux
+key codes exist.
+
+| LKC | Linux Key Code Name | Version | AKC | Android Key Code Name | Notes |
+| ------ | -------------------------------- | ------- | ------ | -------------------------------- | ----- |
+| 0x01d0 | KEY_FN | 3.0 | 0x0077 | KEYCODE_FUNCTION | |
+| 0x01d1 | KEY_FN_ESC | 3.0 | 0x006f | KEYCODE_ESCAPE | 3 |
+| 0x01d2 | KEY_FN_F1 | 3.0 | 0x0083 | KEYCODE_F1 | 3 |
+| 0x01d3 | KEY_FN_F2 | 3.0 | 0x0084 | KEYCODE_F2 | 3 |
+| 0x01d4 | KEY_FN_F3 | 3.0 | 0x0085 | KEYCODE_F3 | 3 |
+| 0x01d5 | KEY_FN_F4 | 3.0 | 0x0086 | KEYCODE_F4 | 3 |
+| 0x01d6 | KEY_FN_F5 | 3.0 | 0x0087 | KEYCODE_F5 | 3 |
+| 0x01d7 | KEY_FN_F6 | 3.0 | 0x0088 | KEYCODE_F6 | 3 |
+| 0x01d8 | KEY_FN_F7 | 3.0 | 0x0089 | KEYCODE_F7 | 3 |
+| 0x01d9 | KEY_FN_F8 | 3.0 | 0x008a | KEYCODE_F8 | 3 |
+| 0x01da | KEY_FN_F9 | 3.0 | 0x008b | KEYCODE_F9 | 3 |
+| 0x01db | KEY_FN_F10 | 3.0 | 0x008c | KEYCODE_F10 | 3 |
+| 0x01dc | KEY_FN_F11 | 3.0 | 0x008d | KEYCODE_F11 | 3 |
+| 0x01dd | KEY_FN_F12 | 3.0 | 0x008e | KEYCODE_F12 | 3 |
+| 0x01de | KEY_FN_1 | 3.0 | 0x0008 | KEYCODE_1 | 3 |
+| 0x01df | KEY_FN_2 | 3.0 | 0x0009 | KEYCODE_2 | 3 |
+| 0x01e0 | KEY_FN_D | 3.0 | 0x0020 | KEYCODE_D | 3 |
+| 0x01e1 | KEY_FN_E | 3.0 | 0x0021 | KEYCODE_E | 3 |
+| 0x01e2 | KEY_FN_F | 3.0 | 0x0022 | KEYCODE_F | 3 |
+| 0x01e3 | KEY_FN_S | 3.0 | 0x002f | KEYCODE_S | 3 |
+| 0x01e4 | KEY_FN_B | 3.0 | 0x001e | KEYCODE_B | 3 |
+
+### Legacy Unsupported Keys ###
+
+These mappings appeared in previous versions of Android but were inconsistent with
+HID or used non-standard Linux key codes. They are no longer supported.
+
+| LKC | Linux Key Code Name | Version | AKC | Android Key Code Name | Notes |
+| ------ | -------------------------------- | ------- | ------ | -------------------------------- | ----- |
+| 0x00db | KEY_EMAIL | 1.6 | 0x004d | KEYCODE_AT | 4 |
+| "" | "" | 4.0 | | | 4 |
+| 0x00e3 | KEY_STAR | 1.6 | 0x0011 | KEYCODE_STAR | 4 |
+| "" | "" | 4.0 | | | 4 |
+| 0x00e4 | KEY_SHARP | 1.6 | 0x0012 | KEYCODE_POUND | 4 |
+| "" | "" | 4.0 | | | 4 |
+| 0x00e5 | KEY_SOFT1 | 1.6 | 0x0052 | KEYCODE_MENU | 4 |
+| "" | "" | 4.0 | | | 4 |
+| 0x00e6 | KEY_SOFT2 | 1.6 | 0x0002 | KEYCODE_SOFT_RIGHT | 4 |
+| "" | "" | 4.0 | | | 4 |
+| 0x00e7 | KEY_SEND | 1.6 | 0x0005 | KEYCODE_CALL | 4 |
+| "" | "" | 4.0 | | | 4 |
+| 0x00e8 | KEY_CENTER | 1.6 | 0x0017 | KEYCODE_DPAD_CENTER | 4 |
+| "" | "" | 4.0 | | | 4 |
+| 0x00e9 | KEY_HEADSETHOOK | 1.6 | 0x004f | KEYCODE_HEADSETHOOK | 4 |
+| "" | "" | 4.0 | | | 4 |
+| 0x00ea | KEY_0_5 | 1.6 | | | 4 |
+| 0x00eb | KEY_2_5 | 1.6 | | | 4 |
+
+### Notes ###
+
+1. The Android key code associated with common alphanumeric and symbolic
+ keys may vary based on the keyboard layout and language.
+ For historical reasons, the physical scan codes and HID usages
+ associated with keys on a keyboard are often defined positionally
+ even though the labels printed on those keys may vary from one
+ language to another.
+
+ On a US English (QWERTY) keyboard, the top-left alphabetic key is
+ labeled Q. On a French (AZERTY) keyboard, the key in the same
+ position is labeled A. Despite the label, on both keyboards the
+ top-left alphabetic key is referred to using the HID usage
+ 0x07 0x0014 which is mapped to the Linux key code KEY_Q.
+
+ When Android is configured with a US English keyboard layout, then
+ the Linux key code KEY_Q will be mapped to the Android key code
+ KEYCODE_Q and will produce the characters 'Q' and 'q'.
+ However, when Android is configured with a French keyboard layout,
+ then the Linux key code KEY_Q will be mapped to the Android key code
+ KEYCODE_A and will produce the characters 'A' and 'a'.
+
+ The Android key code typically reflects the language-specific
+ interpretation of the key, so a different Android key code may
+ be used for different languages.
+
+2. `0x0c 0x022f AC Zoom` is defined in the HID as a linear control but
+ the kernel maps it as a key, which is probably incorrect.
+
+3. The Linux function keys `KEY_FN_*` are mapped to simpler
+ key codes but are dispatched with the `META_FUNCTION` meta state
+ bit set to true.
+
+4. Prior to Android Ice Cream Sandwich 4.0, the default key layout
+ contained mappings for some extra key codes that were not defined
+ in the mainline Linux kernel headers. These mappings have since
+ been removed because these previously undefined key codes have
+ since been assigned different meanings in more recent versions
+ of the Linux kernel.
+
+### Sources ###
+
+1. [USB HID Usage Tables v1.12](http://www.usb.org/developers/devclass_docs/Hut1_12v2.pdf)
+2. Linux 2.6.39 kernel: include/linux/input.h, drivers/hid/hid-input.c
+3. Android ICS: qwerty.kl, Generic.kl, KeyEvent.java
diff --git a/src/tech/input/migration-guide.md b/src/tech/input/migration-guide.md
new file mode 100644
index 0000000..e2aee60
--- /dev/null
+++ b/src/tech/input/migration-guide.md
@@ -0,0 +1,71 @@
+<!--
+ Copyright 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Migration Guide #
+
+This document contains a few helpful tips when migrating to new Android releases.
+
+## Migrating to Android Gingerbread 2.3 ##
+
+In Gingerbread, we added the concept of input device configuration files
+(also referred to as input device calibration files in this release).
+
+Make sure to provide an input device configuration file for all touch screens.
+In particular, it is worth spending time providing a calibration reference for
+touch size information.
+
+## Migrating to Android Honeycomb 3.0 ##
+
+In Honeycomb, we revised the key character map file format and started making
+greater use of input device configuration files. We also added support for full
+PC-style keyboards and introduced a new "Generic" key map, which
+replaced the older emulator-specific "qwerty" key map (which was never
+intended to be used as a general-purpose key map.)
+
+Make sure to update all of your key character map files to use the new syntax.
+
+If your peripherals relied on the old "qwerty" key map, then you
+may need to provide new device-specific key maps to emulate the old behavior.
+You should create a new key map for each device identified either by
+USB product id / vendor id or by device name.
+
+It is especially important to provide key character map files for all special
+function input devices. These files should simple contain a line to set
+the keyboard type to `SPECIAL_FUNCTION`.
+
+A good way to ensure that all built-in input devices are appropriately configured
+is to run [Dumpsys](/tech/input/dumpsys.html) and look for devices that
+are inappropriately using `Generic.kcm`.
+
+## Migrating to Android Honeycomb 3.2 ##
+
+In Honeycomb 3.2, we added support for joysticks and extended the key layout file
+format to enable joystick axis mapping.
+
+## Migrating to Android Ice Cream Sandwich 4.0 ##
+
+In Ice Cream Sandwich 4.0, we changed the device driver requirements for touch screens
+to follow the standard Linux multitouch input protocol and added support for
+protocol "B". We also support digitizer tablets and stylus-based touch devices.
+
+You will probably need to update your input device driver to implement the Linux
+multitouch input protocol correctly according to the standard.
+
+You will also need to update your input device configuration files because some
+properties have been changed to be simpler and more systematic.
+
+Refer to [Touch Devices](/tech/input/touch-devices.html) for more details about
+driver requirements.
diff --git a/src/tech/input/overview.md b/src/tech/input/overview.md
new file mode 100644
index 0000000..79e3de7
--- /dev/null
+++ b/src/tech/input/overview.md
@@ -0,0 +1,259 @@
+<!--
+ Copyright 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Overview #
+
+The Android input subsystem nominally consists of an event pipeline
+that traverses multiple layers of the system.
+
+## Input Pipeline ##
+
+At the lowest layer, the physical input device produces signals that
+describe state changes such as key presses and touch contact points.
+The device firmware encodes and transmits these signals in some way
+such as by sending USB HID reports to the system or by producing
+interrupts on an I2C bus.
+
+The signals are then decoded by a device driver in the Linux kernel.
+The Linux kernel provides drivers for many standard peripherals,
+particularly those that adhere to the HID protocol. However, an OEM
+must often provide custom drivers for embedded devices that are
+tightly integrated into the system at a low-level, such as touch screens.
+
+The input device drivers are responsible for translating device-specific
+signals into a standard input event format, by way of the Linux
+input protocol. The Linux input protocol defines a standard set of
+event types and codes in the `linux/input.h` kernel header file.
+In this way, components outside the kernel do not need to care about
+the details such as physical scan codes, HID usages, I2C messages,
+GPIO pins, and the like.
+
+Next, the Android `EventHub` component reads input events from the kernel
+by opening the `evdev` driver associated with each input device.
+The Android InputReader component then decodes the input events
+according to the device class and produces a stream of Android input
+events. As part of this process, the Linux input protocol event codes
+are translated into Android event codes according to the
+input device configuration, keyboard layout files, and various
+mapping tables.
+
+Finally, the `InputReader` sends input events to the InputDispatcher
+which forwards them to the appropriate window.
+
+## Control Points ##
+
+There are several stages in the input pipeline which effect control
+over the behavior of the input device.
+
+### Driver and Firmware Configuration ###
+
+Input device drivers frequently configure the behavior of the input
+device by setting parameters in registers or even uploading the
+firmware itself. This is particularly the case for embedded
+devices such as touch screens where a large part of the calibration
+process involves tuning these parameters or fixing the firmware
+to provide the desired accuracy and responsiveness and to suppress
+noise.
+
+Driver configuration options are often specified as module parameters
+in the kernel board support package (BSP) so that the same driver
+can support multiple different hardware implementations.
+
+This documentation does attempt to describe driver or firmware
+configuration, but it does offer guidance as to device calibration
+in general.
+
+### Board Configuration Properties ###
+
+The kernel board support package (BSP) may export board configuration
+properties via SysFS that are used by the Android InputReader component,
+such as the placement of virtual keys on a touch screen.
+
+Refer to the device class sections for details about how different
+devices use board configuration properties.
+
+### Resource Overlays ###
+
+A few input behaviors are configured by way of resource overlays
+in `config.xml` such as the operation of lid switch.
+
+Here are a few examples:
+
+* `config_lidKeyboardAccessibility`: Specifies the effect of the
+ lid switch on whether the hardware keyboard is accessible or hidden.
+
+* `config_lidNavigationAccessibility`: Specifies the effect of the
+ lid switch on whether the trackpad is accessible or hidden.
+
+* `config_longPressOnPowerBehavior`: Specifies what should happen when
+ the user holds down the power button.
+
+* `config_lidOpenRotation`: Specifies the effect of the lid switch
+ on screen orientation.
+
+Refer to the documentation within `frameworks/base/core/res/res/values/config.xml`
+for details about each configuration option.
+
+### Key Maps ###
+
+Key maps are used by the Android `EventHub` and `InputReader` components
+to configure the mapping from Linux event codes to Android event codes
+for keys, joystick buttons and joystick axes. The mapping may
+be device or language dependent.
+
+Refer to the device class sections for details about how different
+devices use key maps.
+
+### Input Device Configuration Files ###
+
+Input device configuration files are used by the Android `EventHub` and
+`InputReader` components to configure special device characteristics
+such as how touch size information is reported.
+
+Refer to the device class sections for details about how different
+devices use input device configuration maps.
+
+## Understanding HID Usages and Event Codes ##
+
+There are often several different identifiers used to refer to any
+given key on a keyboard, button on a game controller, joystick axis
+or other control. The relationships between these identifiers
+are not always the same: they are dependent on a set of mapping tables,
+some of which are fixed, and some which vary based on characteristics
+of the device, the device driver, the current locale, the system
+configuration, user preferences and other factors.
+
+Physical Scan Code
+: A physical scan code is a device-specific identifier that is associated
+ with each key, button or other control. Because physical scan codes
+ often vary from one device to another, the firmware or device driver
+ is responsible for mapping them to standard identifiers such as
+ HID Usages or Linux key codes.
+
+ Scan codes are mainly of interest for keyboards. Other devices
+ typically communicate at a low-level using GPIO pins, I2C messages
+ or other means. Consequently, the upper layers of the software
+ stack rely on the device drivers to make sense of what is going on.
+
+HID Usage
+: A HID usage is a standard identifier that is used to report the
+ state of a control such as a keyboard key, joystick axis,
+ mouse button, or touch contact point. Most USB and Bluetooth
+ input devices conform to the HID specification, which enables
+ the system to interface with them in a uniform manner.
+
+ The Android Framework relies on the Linux kernel HID drivers to
+ translate HID usage codes into Linux key codes and other identifiers.
+ Therefore HID usages are mainly of interest to peripheral manufacturers.
+
+Linux Key Code
+: A Linux key code is a standard identifier for a key or button.
+ Linux key codes are defined in the `linux/input.h` header file using
+ constants that begin with the prefix `KEY_` or `BTN_`. The Linux
+ kernel input drivers are responsible for translating physical
+ scan codes, HID usages and other device-specific signals into Linux
+ key codes and delivering information about them as part of
+ `EV_KEY` events.
+
+ The Android API sometimes refers to the Linux key code associated
+ with a key as its "scan code". This is technically incorrect in
+ but it helps to distinguish Linux key codes from Android key codes
+ in the API.
+
+Linux Relative or Absolute Axis Code
+: A Linux relative or absolute axis code is a standard identifier
+ for reporting relative movements or absolute positions along an
+ axis, such as the relative movements of a mouse along its X axis
+ or the absolute position of a joystick along its X axis.
+ Linux axis code are defined in the `linux/input.h` header file using
+ constants that begin with the prefix `REL_` or `ABS_`. The Linux
+ kernel input drivers are responsible for translating HID usages
+ and other device-specific signals into Linux axis codes and
+ delivering information about them as part of `EV_REL` and
+ `EV_ABS` events.
+
+Linux Switch Code
+: A Linux switch code is a standard identifier for reporting the
+ state of a switch on a device, such as a lid switch. Linux
+ switch codes are defined in the `linux/input.h` header file
+ using constants that begin with the prefix `SW_`. The Linux
+ kernel input drivers report switch state changes as `EV_SW` events.
+
+ Android applications generally do not receive events from switches,
+ but the system may use them interally to control various
+ device-specific functions.
+
+Android Key Code
+: An Android key code is a standard identifier defined in the Android
+ API for indicating a particular key such as 'HOME'. Android key codes
+ are defined by the `android.view.KeyEvent` class as constants that
+ begin with the prefix `KEYCODE_`.
+
+ The key layout specifies how Linux key codes are mapped to Android
+ key codes. Different key layouts may be used depending on the keyboard
+ model, language, country, layout, or special functions.
+
+ Combinations of Android key codes are transformed into character codes
+ using a device and locale specific key character map. For example,
+ when the keys identified as `KEYCODE_SHIFT` and `KEYCODE_A` are both
+ pressed together, the system looks up the combination in the key
+ character map and finds the capital letter 'A', which is then inserted
+ into the currently focused text widget.
+
+Android Axis Code
+: An Android axis code is a standard identifier defined in the Android
+ API for indicating a particular device axis. Android axis codes are
+ defined by the `android.view.MotionEvent` class as constants that
+ begin with the prefix `AXIS_`.
+
+ The key layout specifies how Linux Axis Codes are mapped to Android
+ axis codes. Different key layouts may be used depending on the device
+ model, language, country, layout, or special functions.
+
+Android Meta State
+: An Android meta state is a standard identifier defined in the Android
+ API for indicating which modifier keys are pressed. Android meta states
+ are defined by the `android.view.KeyEvent` class as constants that
+ begin with the prefix `META_`.
+
+ The current meta state is determined by the Android InputReader
+ component which monitors when modifier keys such as `KEYCODE_SHIFT_LEFT`
+ are pressed / released and sets / resets the appropriate meta state flag.
+
+ The relationship between modifier keys and meta states is hardcoded
+ but the key layout can alter how the modifier keys themselves are
+ mapped which in turns affects the meta states.
+
+Android Button State
+: An Android button state is a standard identifier defined in the Android
+ API for indicating which buttons (on a mouse or stylus) are pressed.
+ Android button states are defined by the `android.view.MotionEvent`
+ class as constants that begin with the prefix `BUTTON_`.
+
+ The current button state is determined by the Android InputReader
+ component which monitors when buttons (on a mouse or stylus) are
+ pressed / released and sets / resets appropriate button state flag.
+
+ The relationship between buttons and button states is hardcoded.
+
+## Further Reading ##
+
+1. [Linux input event codes](http://www.kernel.org/doc/Documentation/input/event-codes.txt)
+2. [Linux multi-touch protocol](http://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt)
+3. [Linux input drivers](http://www.kernel.org/doc/Documentation/input/input.txt)
+4. [Linux force feedback](http://www.kernel.org/doc/Documentation/input/ff.txt)
+5. [HID information, including HID usage tables](http://www.usb.org/developers/hidpage)
+
diff --git a/src/tech/input/sidebar2.md b/src/tech/input/sidebar2.md
new file mode 100644
index 0000000..6746bcd
--- /dev/null
+++ b/src/tech/input/sidebar2.md
@@ -0,0 +1,18 @@
+# Input Concepts #
+
+- [Overview](/tech/input/overview.html)
+- [Key Layout Files](/tech/input/key-layout-files.html)
+- [Key Character Map Files](/tech/input/key-character-map-files.html)
+- [Input Device Configuration Files](/tech/input/input-device-configuration-files.html)
+- [Migration Guide](/tech/input/migration-guide.html)
+
+# Input Device Classes #
+
+- [Keyboard Devices](/tech/input/keyboard-devices.html)
+- [Touch Devices](/tech/input/touch-devices.html)
+
+# Tools #
+
+- [Dumpsys](/tech/input/dumpsys.html)
+- [Getevent](/tech/input/getevent.html)
+- [Validate Keymaps](/tech/input/validate-keymaps.html)
diff --git a/src/tech/input/touch-devices.md b/src/tech/input/touch-devices.md
new file mode 100644
index 0000000..234188f
--- /dev/null
+++ b/src/tech/input/touch-devices.md
@@ -0,0 +1,1186 @@
+<!--
+ Copyright 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Touch Devices #
+
+Android supports a variety of touch screens and touch pads, including
+stylus-based digitizer tablets.
+
+Touch screens are touch devices that are associated with a display such that
+the user has the impression of directly manipulating items on screen.
+
+Touch pads are touch devices that are not associated with a display such as a
+digitizer tablet. Touch pads are typically used for pointing or for
+absolute indirect positioning or gesture-based control of a user interface.
+
+Touch devices may have buttons whose functions are similar to mouse buttons.
+
+Touch devices can sometimes be manipulated using a variety of different tools
+such as fingers or a stylus depending on the underlying touch sensor technology.
+
+Touch devices are sometimes used to implement virtual keys. For example, on
+some Android devices, the touch screen sensor area extends beyond the edge of
+the display and serves dual purpose as part of a touch sensitive key pad.
+
+Due to the great variety of touch devices, Android relies on a large number of
+configuration properties to describe the characteristics and desired behavior
+of each device.
+
+## Touch Device Classification ##
+
+An input device is classified as a *multi-touch* device if both of
+the following conditions hold:
+
+* The input device reports the presence of the `ABS_MT_POSITION_X` and
+ `ABS_MT_POSITION_Y` absolute axes.
+
+* The input device does not have any gamepad buttons. This condition
+ resolves an ambiguity with certain gamepads that report axes with codes
+ that overlaps those of the MT axes.
+
+An input device is classified as a *single-touch* device if both of the
+following conditions hold:
+
+* The input device is not classified as a multi-touch device. An input device
+ is either classified as a single-touch device or as a multi-touch device,
+ never both.
+
+* The input device reports the presence of the `ABS_X` and `ABS_Y` absolute
+ axes, and the presence of the `BTN_TOUCH` key code.
+
+Once an input device has been classified as a touch device, the presence
+of virtual keys is determined by attempting to load the virtual key map file
+for the device. If a virtual key map is available, then the key layout
+file for the device is also loaded.
+
+Refer to the section below about the location and format of virtual key map
+files.
+
+Next, the system loads the input device configuration file for the touch device.
+
+**All built-in touch devices should have input device configuration files.**
+If no input device configuration file is present, the system will
+choose a default configuration that is appropriate for typical general-purpose
+touch peripherals such as external USB or Bluetooth HID touch screens
+or touch pads. These defaults are not designed for built-in touch screens and
+will most likely result in incorrect behavior.
+
+After the input device configuration loaded, the system will classify the
+input device as a *touch screen*, *touch pad* or *pointer* device.
+
+* A *touch screen* device is used for direct manipulation of objects on the
+ screen. Since the user is directly touching the screen, the system does
+ not require any additional affordances to indicate the objects being
+ manipulated.
+
+* A *touch pad* device is used to provide absolute positioning information
+ to an application about touches on a given sensor area. It may be useful
+ for digitizer tablets.
+
+* A *pointer* device is used for indirect manipulation of objects on the
+ screen using a cursor. Fingers are interpreted as multi-touch pointer
+ gestures. Other tools, such as styluses, are interpreted using
+ absolute positions.
+
+ See [Indirect Multi-touch Pointer Gestures](#indirect-multi-touch-pointer-gestures)
+ for more information.
+
+The following rules are used to classify the input device as a *touch screen*,
+*touch pad* or *pointer* device.
+
+* If the `touch.deviceType` property is set, then the device type will be
+ set as indicated.
+
+* If the input device reports the presence of the `INPUT_PROP_DIRECT`
+ input property (via the `EVIOCGPROP` ioctl), then the device type will
+ be set to *touch screen*. This condition assumes that direct input touch
+ devices are attached to a display that is also connected.
+
+* If the input device reports the presence of the `INPUT_PROP_POINTER`
+ input property (via the `EVIOCGPROP` ioctl), then the device type will
+ be set to *pointer*.
+
+* If the input device reports the presence of the `REL_X` or `REL_Y` relative
+ axes, then the device type will be set to *touch pad*. This condition
+ resolves an ambiguity for input devices that consist of both a mouse and
+ a touch pad. In this case, the touch pad will not be used to control
+ the pointer because the mouse already controls it.
+
+* Otherwise, the device type will be set to *pointer*. This default ensures
+ that touch pads that have not been designated any other special purpose
+ will serve to control the pointer.
+
+## Buttons ##
+
+Buttons are *optional* controls that may be used by applications to perform
+additional functions. Buttons on touch devices behave similarly to mouse
+buttons and are mainly of use with *pointer* type touch devices or with a
+stylus.
+
+The following buttons are supported:
+
+* `BTN_LEFT`: mapped to `MotionEvent.BUTTON_PRIMARY`.
+
+* `BTN_RIGHT`: mapped to `MotionEvent.BUTTON_SECONDARY`.
+
+* `BTN_MIDDLE`: mapped to `MotionEvent.BUTTON_MIDDLE`.
+
+* `BTN_BACK` and `BTN_SIDE`: mapped to `MotionEvent.BUTTON_BACK`.
+ Pressing this button also synthesizes a key press with the key code
+ `KeyEvent.KEYCODE_BACK`.
+
+* `BTN_FORWARD` and `BTN_EXTRA`: mapped to `MotionEvent.BUTTON_FORWARD`.
+ Pressing this button also synthesizes a key press with the key code
+ `KeyEvent.KEYCODE_FORWARD`.
+
+* `BTN_STYLUS`: mapped to `MotionEvent.BUTTON_SECONDARY`.
+
+* `BTN_STYLUS2`: mapped to `MotionEvent.BUTTON_TERTIARY`.
+
+## Tools and Tool Types ##
+
+A *tool* is a finger, stylus or other apparatus that is used to interact with
+the touch device. Some touch devices can distinguish between different
+types of tools.
+
+Elsewhere in Android, as in the `MotionEvent` API, a *tool* is often referred
+to as a *pointer*.
+
+The following tool types are supported:
+
+* `BTN_TOOL_FINGER` and `MT_TOOL_FINGER`: mapped to `MotionEvent.TOOL_TYPE_FINGER`.
+
+* `BTN_TOOL_PEN` and `MT_TOOL_PEN`: mapped to `MotionEvent.TOOL_TYPE_STYLUS`.
+
+* `BTN_TOOL_RUBBER`: mapped to `MotionEvent.TOOL_TYPE_ERASER`.
+
+* `BTN_TOOL_BRUSH`: mapped to `MotionEvent.TOOL_TYPE_STYLUS`.
+
+* `BTN_TOOL_PENCIL`: mapped to `MotionEvent.TOOL_TYPE_STYLUS`.
+
+* `BTN_TOOL_AIRBRUSH`: mapped to `MotionEvent.TOOL_TYPE_STYLUS`.
+
+* `BTN_TOOL_MOUSE`: mapped to `MotionEvent.TOOL_TYPE_MOUSE`.
+
+* `BTN_TOOL_LENS`: mapped to `MotionEvent.TOOL_TYPE_MOUSE`.
+
+* `BTN_TOOL_DOUBLETAP`, `BTN_TOOL_TRIPLETAP`, and `BTN_TOOL_QUADTAP`:
+ mapped to `MotionEvent.TOOL_TYPE_FINGER`.
+
+## Hovering vs. Touching Tools ##
+
+Tools can either be in contact with the touch device or in range and hovering
+above it. Not all touch devices are able to sense the presence of a tool
+hovering above the touch device. Those that do, such as RF-based stylus digitizers,
+can often detect when the tool is within a limited range of the digitizer.
+
+The `InputReader` component takes care to distinguish touching tools from hovering
+tools. Likewise, touching tools and hovering tools are reported to applications
+in different ways.
+
+Touching tools are reported to applications as touch events
+using `MotionEvent.ACTION_DOWN`, `MotionEvent.ACTION_MOVE`, `MotionEvent.ACTION_DOWN`,
+`MotionEvent.ACTION_POINTER_DOWN` and `MotionEvent.ACTION_POINTER_UP`.
+
+Hovering tools are reported to applications as generic motion events using
+`MotionEvent.ACTION_HOVER_ENTER`, `MotionEvent.ACTION_HOVER_MOVE`
+and `MotionEvent.ACTION_HOVER_EXIT`.
+
+## Touch Device Driver Requirements ##
+
+1. Touch device drivers should only register axes and key codes for the axes
+ and buttons that they actually support. Registering excess axes or key codes
+ may confuse the device classification algorithm or cause the system to incorrectly
+ detect the capabilities of the device.
+
+ For example, if the device reports the `BTN_TOUCH` key code, the system will
+ assume that `BTN_TOUCH` will always be used to indicate whether the tool is
+ actually touching the screen or is merely in range and hovering.
+
+2. Single-touch devices use the following Linux input events:
+
+ * `ABS_X`: *(REQUIRED)* Reports the X coordinate of the tool.
+
+ * `ABS_Y`: *(REQUIRED)* Reports the Y coordinate of the tool.
+
+ * `ABS_PRESSURE`: *(optional)* Reports the physical pressure applied to the tip
+ of the tool or the signal strength of the touch contact.
+
+ * `ABS_TOOL_WIDTH`: *(optional)* Reports the cross-sectional area or width of the
+ touch contact or of the tool itself.
+
+ * `ABS_DISTANCE`: *(optional)* Reports the distance of the tool from the surface of
+ the touch device.
+
+ * `ABS_TILT_X`: *(optional)* Reports the tilt of the tool from the surface of the
+ touch device along the X axis.
+
+ * `ABS_TILT_Y`: *(optional)* Reports the tilt of the tool from the surface of the
+ touch device along the Y axis.
+
+ * `BTN_TOUCH`: *(REQUIRED)* Indicates whether the tool is touching the device.
+
+ * `BTN_LEFT`, `BTN_RIGHT`, `BTN_MIDDLE`, `BTN_BACK`, `BTN_SIDE`, `BTN_FORWARD`,
+ `BTN_EXTRA`, `BTN_STYLUS`, `BTN_STYLUS2`:
+ *(optional)* Reports [button](#buttons) states.
+
+ * `BTN_TOOL_FINGER`, `BTN_TOOL_PEN`, `BTN_TOOL_RUBBER`, `BTN_TOOL_BRUSH`,
+ `BTN_TOOL_PENCIL`, `BTN_TOOL_AIRBRUSH`, `BTN_TOOL_MOUSE`, `BTN_TOOL_LENS`,
+ `BTN_TOOL_DOUBLETAP`, `BTN_TOOL_TRIPLETAP`, `BTN_TOOL_QUADTAP`:
+ *(optional)* Reports the [tool type](#tools-and-tool-types).
+
+3. Multi-touch devices use the following Linux input events:
+
+ * `ABS_MT_POSITION_X`: *(REQUIRED)* Reports the X coordinate of the tool.
+
+ * `ABS_MT_POSITION_Y`: *(REQUIRED)* Reports the Y coordinate of the tool.
+
+ * `ABS_MT_PRESSURE`: *(optional)* Reports the physical pressure applied to the
+ tip of the tool or the signal strength of the touch contact.
+
+ * `ABS_MT_TOUCH_MAJOR`: *(optional)* Reports the cross-sectional area of the
+ touch contact, or the length of the longer dimension of the touch contact.
+
+ * `ABS_MT_TOUCH_MINOR`: *(optional)* Reports the length of the shorter dimension of the
+ touch contact. This axis should not be used if `ABS_MT_TOUCH_MAJOR` is reporting an
+ area measurement.
+
+ * `ABS_MT_WIDTH_MAJOR`: *(optional)* Reports the cross-sectional area of the tool itself,
+ or the length of the longer dimension of the tool itself.
+ This axis should not be used if the dimensions of the tool itself are unknown.
+
+ * `ABS_MT_WIDTH_MINOR`: *(optional)* Reports the length of the shorter dimension of
+ the tool itself. This axis should not be used if `ABS_MT_WIDTH_MAJOR` is reporting
+ an area measurement or if the dimensions of the tool itself are unknown.
+
+ * `ABS_MT_ORIENTATION`: *(optional)* Reports the orientation of the tool.
+
+ * `ABS_MT_DISTANCE`: *(optional)* Reports the distance of the tool from the
+ surface of the touch device.
+
+ * `ABS_MT_TOOL_TYPE`: *(optional)* Reports the [tool type](#tools-and-tool-types) as
+ `MT_TOOL_FINGER` or `MT_TOOL_PEN`.
+
+ * `ABS_MT_TRACKING_ID`: *(optional)* Reports the tracking id of the tool.
+ The tracking id is an arbitrary non-negative integer that is used to identify
+ and track each tool independently when multiple tools are active. For example,
+ when multiple fingers are touching the device, each finger should be assigned a distinct
+ tracking id that is used as long as the finger remains in contact. Tracking ids
+ may be reused when their associated tools move out of range.
+
+ * `ABS_MT_SLOT`: *(optional)* Reports the slot id of the tool, when using the Linux
+ multi-touch protocol 'B'. Refer to the Linux multi-touch protocol documentation
+ for more details.
+
+ * `BTN_TOUCH`: *(REQUIRED)* Indicates whether the tool is touching the device.
+
+ * `BTN_LEFT`, `BTN_RIGHT`, `BTN_MIDDLE`, `BTN_BACK`, `BTN_SIDE`, `BTN_FORWARD`,
+ `BTN_EXTRA`, `BTN_STYLUS`, `BTN_STYLUS2`:
+ *(optional)* Reports [button](#buttons) states.
+
+ * `BTN_TOOL_FINGER`, `BTN_TOOL_PEN`, `BTN_TOOL_RUBBER`, `BTN_TOOL_BRUSH`,
+ `BTN_TOOL_PENCIL`, `BTN_TOOL_AIRBRUSH`, `BTN_TOOL_MOUSE`, `BTN_TOOL_LENS`,
+ `BTN_TOOL_DOUBLETAP`, `BTN_TOOL_TRIPLETAP`, `BTN_TOOL_QUADTAP`:
+ *(optional)* Reports the [tool type](#tools-and-tool-types).
+
+4. If axes for both the single-touch and multi-touch protocol are defined, then
+ only the multi-touch axes will be used and the single-touch axes will be ignored.
+
+5. The minimum and maximum values of the `ABS_X`, `ABS_Y`, `ABS_MT_POSITION_X`
+ and `ABS_MT_POSITION_Y` axes define the bounds of the active area of the device
+ in device-specific surface units. In the case of a touch screen, the active area
+ describes the part of the touch device that actually covers the display.
+
+ For a touch screen, the system automatically interpolates the reported touch
+ positions in surface units to obtain touch positions in display pixels according
+ to the following calculation:
+
+ displayX = (x - minX) * displayWidth / (maxX - minX + 1)
+ displayY = (y - minY) * displayHeight / (maxY - minY + 1)
+
+ A touch screen may report touches outside of the reported active area.
+
+ Touches that are initiated outside the active area are not delivered to applications
+ but may be used for virtual keys.
+
+ Touches that are initiated inside the active area, or that enter and exit the display
+ area are delivered to applications. Consequently, if a touch starts within the
+ bounds of an application and then moves outside of the active area, the application
+ may receive touch events with display coordinates that are negative or beyond the
+ bounds of the display. This is expected behavior.
+
+ A touch device should never clamp touch coordinates to the bounds of the active
+ area. If a touch exits the active area, it should be reported as being outside of
+ the active area, or it should not be reported at all.
+
+ For example, if the user's finger is touching near the top-left corner of the
+ touch screen, it may report a coordinate of (minX, minY). If the finger continues
+ to move further outside of the active area, the touch screen should either start
+ reporting coordinates with components less than minX and minY, such as
+ (minX - 2, minY - 3), or it should stop reporting the touch altogether.
+ In other words, the touch screen should *not* be reporting (minX, minY)
+ when the user's finger is really touching outside of the active area.
+
+ Clamping touch coordinates to the display edge creates an artificial
+ hard boundary around the edge of the screen which prevents the system from
+ smoothly tracking motions that enter or exit the bounds of the display area.
+
+6. The values reported by `ABS_PRESSURE` or `ABS_MT_PRESSURE`, if they
+ are reported at all, must be non-zero when the tool is touching the device
+ and zero otherwise to indicate that the tool is hovering.
+
+ Reporting pressure information is *optional* but strongly recommended.
+ Applications can use pressure information to implement pressure-sensitive drawing
+ and other effects.
+
+7. The values reported by `ABS_TOOL_WIDTH`, `ABS_MT_TOUCH_MAJOR`, `ABS_MT_TOUCH_MINOR`,
+ `ABS_MT_WIDTH_MAJOR`, or `ABS_MT_WIDTH_MINOR` should be non-zero when the tool
+ is touching the device and zero otherwise, but this is not required.
+ For example, the touch device may be able to measure the size of finger touch
+ contacts but not stylus touch contacts.
+
+ Reporting size information is *optional* but strongly recommended.
+ Applications can use pressure information to implement size-sensitive drawing
+ and other effects.
+
+8. The values reported by `ABS_DISTANCE` or `ABS_MT_DISTANCE` should approach
+ zero when the tool is touching the device. The distance may remain non-zero
+ even when the tool is in direct contact. The exact values reported depend
+ on the manner in which the hardware measures distance.
+
+ Reporting distance information is *optional* but recommended for
+ stylus devices.
+
+9. The values reported by `ABS_TILT_X` and `ABS_TILT_Y` should be zero when the
+ tool is perpendicular to the device. A non-zero tilt is taken as an indication
+ that the tool is held at an incline.
+
+ The tilt angles along the X and Y axes are assumed to be specified in degrees
+ from perpendicular. The center point (perfectly perpendicular) is given
+ by `(max + min) / 2` for each axis. Values smaller than the center point
+ represent a tilt up or to the left, values larger than the center point
+ represent a tilt down or to the right.
+
+ The `InputReader` converts the X and Y tilt components into a perpendicular
+ tilt angle ranging from 0 to `PI / 2` radians and a planar orientation angle
+ ranging from `-PI` to `PI` radians. This representation results in a
+ description of orientation that is compatible with what is used to describe
+ finger touches.
+
+ Reporting tilt information is *optional* but recommended for stylus devices.
+
+10. If the tool type is reported by `ABS_MT_TOOL_TYPE`, it will supercede any tool
+ type information reported by `BTN_TOOL_*`.
+ If no tool type information is available at all, the tool type defaults to
+ `MotionEvent.TOOL_TYPE_FINGER`.
+
+11. A tool is determined to be active based on the following conditions:
+
+ * When using the single-touch protocol, the tool is active if `BTN_TOUCH`,
+ or `BTN_TOOL_*` is 1.
+
+ This condition implies that the `InputReader` needs to have at least some
+ information about the nature of the tool, either whether it is touching,
+ or at least its tool type. If no information is available,
+ then the tool is assumed to be inactive (out of range).
+
+ * When using the multi-touch protocol 'A', the tool is active whenever it
+ appears in the most recent sync report. When the tool stops appearing in
+ sync reports, it ceases to exist.
+
+ * When using the multi-touch protocol 'B', the tool is active as long as
+ it has an active slot. When the slot it cleared, the tool ceases to exist.
+
+12. A tool is determined to be hovering based on the following conditions:
+
+ * If the tool is `BTN_TOOL_MOUSE` or `BTN_TOOL_LENS`, then the tool
+ is not hovering, even if either of the following conditions are true.
+
+ * If the tool is active and the driver reports pressure information,
+ and the reported pressure is zero, then the tool is hovering.
+
+ * If the tool is active and the driver supports the `BTN_TOUCH` key code and
+ `BTN_TOUCH` has a value of zero, then the tool is hovering.
+
+13. The `InputReader` supports both multi-touch protocol 'A' and 'B'. New drivers
+ should use the 'B' protocol but either will work.
+
+14. **As of Android Ice Cream Sandwich 4.0, touch screen drivers may need to be changed
+ to comply with the Linux input protocol specification.**
+
+ The following changes may be required:
+
+ * When a tool becomes inactive (finger goes "up"), it should stop appearing
+ in subsequent multi-touch sync reports. When all tools become inactive
+ (all fingers go "up"), the driver should send an empty sync report packet,
+ such as `SYN_MT_REPORT` followed by `SYN_REPORT`.
+
+ Previous versions of Android expected "up" events to be reported by sending
+ a pressure value of 0. The old behavior was incompatible with the
+ Linux input protocol specification and is no longer supported.
+
+ * Physical pressure or signal strength information should be reported using
+ `ABS_MT_PRESSURE`.
+
+ Previous versions of Android retrieved pressure information from
+ `ABS_MT_TOUCH_MAJOR`. The old behavior was incompatible with the
+ Linux input protocol specification and is no longer supported.
+
+ * Touch size information should be reported using `ABS_MT_TOUCH_MAJOR`.
+
+ Previous versions of Android retrieved size information from
+ `ABS_MT_TOOL_MAJOR`. The old behavior was incompatible with the
+ Linux input protocol specification and is no longer supported.
+
+ Touch device drivers no longer need Android-specific customizations.
+ By relying on the standard Linux input protocol, Android can support a
+ wider variety of touch peripherals, such as external HID multi-touch
+ touch screens, using unmodified drivers.
+
+## Touch Device Operation ##
+
+The following is a brief summary of the touch device operation on Android.
+
+1. The `EventHub` reads raw events from the `evdev` driver.
+
+2. The `InputReader` consumes the raw events and updates internal state about
+ the position and other characteristics of each tool. It also tracks
+ button states.
+
+3. If the BACK or FORWARD buttons were pressed or released, the `InputReader`
+ notifies the `InputDispatcher` about the key event.
+
+4. The `InputReader` determines whether a virtual key press occurred. If so,
+ it notifies the `InputDispatcher` about the key event.
+
+5. The `InputReader` determines whether the touch was initiated within the
+ bounds of the display. If so, it notifies the `InputDispatcher` about
+ the touch event.
+
+6. If there are no touching tools but there is at least one hovering tool,
+ the `InputReader` notifies the `InputDispatcher` about the hover event.
+
+7. If the touch device type is *pointer*, the `InputReader` performs pointer
+ gesture detection, moves the pointer and spots accordingly and notifies
+ the `InputDispatcher` about the pointer event.
+
+8. The `InputDispatcher` uses the `WindowManagerPolicy` to determine whether
+ the events should be dispatched and whether they should wake the device.
+ Then, the `InputDispatcher` delivers the events to the appropriate applications.
+
+## Touch Device Configuration ##
+
+Touch device behavior is determined by the device's axes, buttons, input properties,
+input device configuration, virtual key map and key layout.
+
+Refer to the following sections for more details about the files that
+participate in keyboard configuration:
+
+* [Input Device Configuration Files](/tech/input/input-device-configuration-files.html)
+* [Virtual Key Map Files](#virtual-key-map-files)
+
+### Properties ###
+
+The system relies on many input device configuration properties to configure
+and calibrate touch device behavior.
+
+One reason for this is that the device drivers for touch devices often report
+the characteristics of touches using device-specific units.
+
+For example, many touch devices measure the touch contact area
+using an internal device-specific scale, such as the total number of
+sensor nodes that were triggered by the touch. This raw size value would
+not be meaningful applications because they would need to know about the
+physical size and other characteristics of the touch device sensor nodes.
+
+The system uses calibration parameters encoded in input device configuration
+files to decode, transform, and normalize the values reported by the touch
+device into a simpler standard representation that applications can understand.
+
+### Documentation Conventions ###
+
+For documentation purposes, we will use the following conventions to describe
+the values used by the system during the calibration process.
+
+#### Raw Axis Values ####
+
+The following expressions denote the raw values reported by the touch
+device driver as `EV_ABS` events.
+
+`raw.x`
+: The value of the `ABS_X` or `ABS_MT_POSITION_X` axis.
+
+`raw.y`
+: The value of the `ABS_Y` or `ABS_MT_POSITION_Y` axis.
+
+`raw.pressure`
+: The value of the `ABS_PRESSURE` or `ABS_MT_PRESSURE` axis, or 0 if not available.
+
+`raw.touchMajor`
+: The value of the `ABS_MT_TOUCH_MAJOR` axis, or 0 if not available.
+
+`raw.touchMinor`
+: The value of the `ABS_MT_TOUCH_MINOR` axis, or `raw.touchMajor` if not available.
+
+`raw.toolMajor`
+: The value of the `ABS_TOOL_WIDTH` or `ABS_MT_WIDTH_MAJOR` axis, or 0 if not available.
+
+`raw.toolMinor`
+: The value of the `ABS_MT_WIDTH_MINOR` axis, or `raw.toolMajor` if not available.
+
+`raw.orientation`
+: The value of the `ABS_MT_ORIENTATION` axis, or 0 if not available.
+
+`raw.distance`
+: The value of the `ABS_DISTANCE` or `ABS_MT_DISTANCE` axis, or 0 if not available.
+
+`raw.tiltX`
+: The value of the `ABS_TILT_X` axis, or 0 if not available.
+
+`raw.tiltY`
+: The value of the `ABS_TILT_Y` axis, or 0 if not available.
+
+#### Raw Axis Ranges ####
+
+The following expressions denote the bounds of raw values. They are obtained
+by calling `EVIOCGABS` ioctl for each axis.
+
+`raw.*.min`
+: The inclusive minimum value of the raw axis.
+
+`raw.*.max`
+: The inclusive maximum value of the raw axis.
+
+`raw.*.range`
+: Equivalent to `raw.*.max - raw.*.min`.
+
+`raw.*.fuzz`
+: The accuracy of the raw axis. eg. fuzz = 1 implies values are accurate to +/- 1 unit.
+
+`raw.width`
+: The inclusive width of the touch area, equivalent to `raw.x.range + 1`.
+
+`raw.height`
+: The inclusive height of the touch area, equivalent to `raw.y.range + 1`.
+
+#### Output Ranges ####
+
+The following expressions denote the characteristics of the output coordinate system.
+The system uses linear interpolation to translate touch position information from
+the surface units used by the touch device into the output units that will
+be reported to applications such as display pixels.
+
+`output.width`
+: The output width. For touch screens (associated with a display), this
+ is the display width in pixels. For touch pads (not associated with a display),
+ the output width equals `raw.width`, indicating that no interpolation will
+ be performed.
+
+`output.height`
+: The output height. For touch screens (associated with a display), this
+ is the display height in pixels. For touch pads (not associated with a display),
+ the output height equals `raw.height`, indicating that no interpolation will
+ be performed.
+
+`output.diag`
+: The diagonal length of the output coordinate system, equivalent to
+ `sqrt(output.width ^2 + output.height ^2)`.
+
+### Basic Configuration ###
+
+The touch input mapper uses many configuration properties in the input device
+configuration file to specify calibration values. The following table describes
+some general purpose configuration properties. All other properties are described
+in the following sections along with the fields they are used to calibrate.
+
+#### `touch.deviceType` ####
+
+*Definition:* `touch.deviceType` = `touchScreen` | `touchPad` | `pointer` | `default`
+
+Specifies the touch device type.
+
+* If the value is `touchScreen`, the touch device is a touch screen associated
+ with a display.
+
+* If the value is `touchPad`, the touch device is a touch pad not associated
+ with a display.
+
+* If the value is `pointer`, the touch device is a touch pad not associated
+ with a display, and its motions are used for
+ [indirect multi-touch pointer gestures](#indirect-multi-touch-pointer-gestures).
+
+* If the value is `default`, the system automatically detects the device type
+ according to the classification algorithm.
+
+Refer to the [Classification](#touch-device-classification) section for more details
+about how the device type influences the behavior of the touch device.
+
+Prior to Honeycomb, all touch devices were assumed to be touch screens.
+
+#### `touch.orientationAware` ####
+
+*Definition:* `touch.orientationAware` = `0` | `1`
+
+Specifies whether the touch device should react to display orientation changes.
+
+* If the value is `1`, touch positions reported by the touch device are rotated
+ whenever the display orientation changes.
+
+* If the value is `0`, touch positions reported by the touch device are immune
+ to display orientation changes.
+
+The default value is `1` if the device is a touch screen, `0` otherwise.
+
+The system distinguishes between internal and external touch screens and displays.
+An orientation aware internal touch screen is rotated based on the orientation
+of the internal display. An orientation aware external touch screen is rotated
+based on the orientation of the external display.
+
+Orientation awareness is used to support rotation of touch screens on devices
+like the Nexus One. For example, when the device is rotated clockwise 90 degrees
+from its natural orientation, the absolute positions of touches are remapped such
+that a touch in the top-left corner of the touch screen's absolute coordinate system
+is reported as a touch in the top-left corner of the display's rotated coordinate system.
+This is done so that touches are reported with the same coordinate system that
+applications use to draw their visual elements.
+
+Prior to Honeycomb, all touch devices were assumed to be orientation aware.
+
+#### `touch.gestureMode` ####
+
+*Definition:* `touch.gestureMode` = `pointer` | `spots` | `default`
+
+Specifies the presentation mode for pointer gestures. This configuration property
+is only relevant when the touch device is of type *pointer*.
+
+* If the value is `pointer`, the touch pad gestures are presented by way of a cursor
+ similar to a mouse pointer.
+
+* If the value is `spots`, the touch pad gestures are presented by an anchor
+ that represents the centroid of the gesture and a set of circular spots
+ that represent the position of individual fingers.
+
+The default value is `pointer` when the `INPUT_PROP_SEMI_MT` input property
+is set, or `spots` otherwise.
+
+### `X` and `Y` Fields ###
+
+The X and Y fields provide positional information for the center of the contact area.
+
+#### Calculation ####
+
+The calculation is straightforward: positional information from the touch driver is
+linearly interpolated to the output coordinate system.
+
+ xScale = output.width / raw.width
+ yScale = output.height / raw.height
+
+ If not orientation aware or screen rotation is 0 degrees:
+ output.x = (raw.x - raw.x.min) * xScale
+ output.y = (raw.y - raw.y.min) * yScale
+ Else If rotation is 90 degrees:
+ output.x = (raw.y - raw.y.min) * yScale
+ output.y = (raw.x.max - raw.x) * xScale
+ Else If rotation is 180 degrees:
+ output.x = (raw.x.max - raw.x) * xScale
+ output.y = (raw.y.max - raw.y) * yScale
+ Else If rotation is 270 degrees:
+ output.x = (raw.y.max - raw.y) * yScale
+ output.y = (raw.x - raw.x.min) * xScale
+ End If
+
+### `TouchMajor`, `TouchMinor`, `ToolMajor`, `ToolMinor`, `Size` Fields ###
+
+The `TouchMajor` and `TouchMinor` fields describe the approximate dimensions
+of the contact area in output units (pixels).
+
+The `ToolMajor` and `ToolMinor` fields describe the approximate dimensions
+of the [tool](#tools-and-tool-types) itself in output units (pixels).
+
+The `Size` field describes the normalized size of the touch relative to
+the largest possible touch that the touch device can sense. The smallest
+possible normalized size is 0.0 (no contact, or it is unmeasurable), and the largest
+possible normalized size is 1.0 (sensor area is saturated).
+
+When both the approximate length and breadth can be measured, then the `TouchMajor` field
+specifies the longer dimension and the `TouchMinor` field specifies the shorter dimension
+of the contact area. When only the approximate diameter of the contact area can be measured,
+then the `TouchMajor` and `TouchMinor` fields will be equal.
+
+Likewise, the `ToolMajor` field specifies the longer dimension and the `ToolMinor`
+field specifies the shorter dimension of the tool's cross-sectional area.
+
+If the touch size is unavailable but the tool size is available, then the tool size
+will be set equal to the touch size. Conversely, if the tool size is unavailable
+but the touch size is available, then the touch size will be set equal to the tool size.
+
+Touch devices measure or report the touch size and tool size in various ways.
+The current implementation supports three different kinds of measurements:
+diameter, area, and geometric bounding box in surface units.
+
+#### `touch.size.calibration` ####
+
+*Definition:* `touch.size.calibration` = `none` | `geometric` | `diameter`
+| `area` | `default`
+
+Specifies the kind of measurement used by the touch driver to report the
+touch size and tool size.
+
+* If the value is `none`, the size is set to zero.
+
+* If the value is `geometric`, the size is assumed to be specified in the same
+ surface units as the position, so it is scaled in the same manner.
+
+* If the value is `diameter`, the size is assumed to be proportional to
+ the diameter (width) of the touch or tool.
+
+* If the value is `area`, the size is assumed to be proportional to the
+ area of the touch or tool.
+
+* If the value is `default`, the system uses the `geometric` calibration if the
+ `raw.touchMajor` or `raw.toolMajor` axis is available, otherwise it uses
+ the `none` calibration.
+
+#### `touch.size.scale` ####
+
+*Definition:* `touch.size.scale` = <a non-negative floating point number>
+
+Specifies a constant scale factor used in the calibration.
+
+The default value is `1.0`.
+
+#### `touch.size.bias` ####
+
+*Definition:* `touch.size.bias` = <a non-negative floating point number>
+
+Specifies a constant bias value used in the calibration.
+
+The default value is `0.0`.
+
+#### `touch.size.isSummed` ####
+
+*Definition:* `touch.size.isSummed` = `0` | `1`
+
+Specifies whether the size is reported as the sum of the sizes of all
+active contacts, or is reported individually for each contact.
+
+* If the value is `1`, the reported size will be divided by the number
+ of contacts prior to use.
+
+* If the value is `0`, the reported size will be used as is.
+
+The default value is `0`.
+
+Some touch devices, particularly "Semi-MT" devices cannot distinguish the
+individual dimensions of multiple contacts so they report a size measurement
+that represents their total area or width. This property should only be set to
+`1` for such devices. If in doubt, set this value to `0`.
+
+#### Calculation ####
+
+The calculation of the `TouchMajor`, `TouchMinor`, `ToolMajor`, `ToolMinor`
+and `Size` fields depends on the specified calibration parameters.
+
+ If raw.touchMajor and raw.toolMajor are available:
+ touchMajor = raw.touchMajor
+ touchMinor = raw.touchMinor
+ toolMajor = raw.toolMajor
+ toolMinor = raw.toolMinor
+ Else If raw.touchMajor is available:
+ toolMajor = touchMajor = raw.touchMajor
+ toolMinor = touchMinor = raw.touchMinor
+ Else If raw.toolMajor is available:
+ touchMajor = toolMajor = raw.toolMajor
+ touchMinor = toolMinor = raw.toolMinor
+ Else
+ touchMajor = toolMajor = 0
+ touchMinor = toolMinor = 0
+ size = 0
+ End If
+
+ size = avg(touchMajor, touchMinor)
+
+ If touch.size.isSummed == 1:
+ touchMajor = touchMajor / numberOfActiveContacts
+ touchMinor = touchMinor / numberOfActiveContacts
+ toolMajor = toolMajor / numberOfActiveContacts
+ toolMinor = toolMinor / numberOfActiveContacts
+ size = size / numberOfActiveContacts
+ End If
+
+ If touch.size.calibration == "none":
+ touchMajor = toolMajor = 0
+ touchMinor = toolMinor = 0
+ size = 0
+ Else If touch.size.calibration == "geometric":
+ outputScale = average(output.width / raw.width, output.height / raw.height)
+ touchMajor = touchMajor * outputScale
+ touchMinor = touchMinor * outputScale
+ toolMajor = toolMajor * outputScale
+ toolMinor = toolMinor * outputScale
+ Else If touch.size.calibration == "area":
+ touchMajor = sqrt(touchMajor)
+ touchMinor = touchMajor
+ toolMajor = sqrt(toolMajor)
+ toolMinor = toolMajor
+ Else If touch.size.calibration == "diameter":
+ touchMinor = touchMajor
+ toolMinor = toolMajor
+ End If
+
+ If touchMajor != 0:
+ output.touchMajor = touchMajor * touch.size.scale + touch.size.bias
+ Else
+ output.touchMajor = 0
+ End If
+
+ If touchMinor != 0:
+ output.touchMinor = touchMinor * touch.size.scale + touch.size.bias
+ Else
+ output.touchMinor = 0
+ End If
+
+ If toolMajor != 0:
+ output.toolMajor = toolMajor * touch.size.scale + touch.size.bias
+ Else
+ output.toolMajor = 0
+ End If
+
+ If toolMinor != 0:
+ output.toolMinor = toolMinor * touch.size.scale + touch.size.bias
+ Else
+ output.toolMinor = 0
+ End If
+
+ output.size = size
+
+### `Pressure` Field ###
+
+The `Pressure` field describes the approximate physical pressure applied to the
+touch device as a normalized value between 0.0 (no touch) and 1.0 (full force).
+
+A zero pressure indicates that the tool is hovering.
+
+#### `touch.pressure.calibration` ####
+
+*Definition:* `touch.pressure.calibration` = `none` | `physical` | `amplitude` | `default`
+
+Specifies the kind of measurement used by the touch driver to report the pressure.
+
+* If the value is `none`, the pressure is unknown so it is set to 1.0 when
+ touching and 0.0 when hovering.
+
+* If the value is `physical`, the pressure axis is assumed to measure the actual
+ physical intensity of pressure applied to the touch pad.
+
+* If the value is `amplitude`, the pressure axis is assumed to measure the signal
+ amplitude, which is related to the size of the contact and the pressure applied.
+
+* If the value is `default`, the system uses the `physical` calibration if the
+ pressure axis available, otherwise uses `none`.
+
+#### `touch.pressure.scale` ####
+
+*Definition:* `touch.pressure.scale` = <a non-negative floating point number>
+
+Specifies a constant scale factor used in the calibration.
+
+The default value is `1.0 / raw.pressure.max`.
+
+#### Calculation ####
+
+The calculation of the `Pressure` field depends on the specified calibration parameters.
+
+ If touch.pressure.calibration == "physical" or "amplitude":
+ output.pressure = raw.pressure * touch.pressure.scale
+ Else
+ If hovering:
+ output.pressure = 0
+ Else
+ output.pressure = 1
+ End If
+ End If
+
+### `Orientation` and `Tilt` Fields ###
+
+The `Orientation` field describes the orientation of the touch and tool as an
+angular measurement. An orientation of `0` indicates that the major axis is
+oriented vertically, `-PI/2` indicates that the major axis is oriented to the left,
+`PI/2` indicates that the major axis is oriented to the right. When a stylus
+tool is present, the orientation range may be described in a full circle range
+from `-PI` or `PI`.
+
+The `Tilt` field describes the inclination of the tool as an angular measurement.
+A tilt of `0` indicates that the tool is perpendicular to the surface.
+A tilt of `PI/2` indicates that the tool is flat on the surface.
+
+#### `touch.orientation.calibration` ####
+
+*Definition:* `touch.orientation.calibration` = `none` | `interpolated` | `vector` | `default`
+
+Specifies the kind of measurement used by the touch driver to report the orientation.
+
+* If the value is `none`, the orientation is unknown so it is set to 0.
+
+* If the value is `interpolated`, the orientation is linearly interpolated such that a
+ raw value of `raw.orientation.min` maps to `-PI/2` and a raw value of
+ `raw.orientation.max` maps to `PI/2`. The center value of
+ `(raw.orientation.min + raw.orientation.max) / 2` maps to `0`.
+
+* If the value is `vector`, the orientation is interpreted as a packed vector consisiting
+ of two signed 4-bit fields. This representation is used on Atmel Object Based Protocol
+ parts. When decoded, the vector yields an orientation angle and confidence
+ magnitude. The confidence magnitude is used to scale the size information,
+ unless it is geometric.
+
+* If the value is `default`, the system uses the `interpolated` calibration if the
+ orientation axis available, otherwise uses `none`.
+
+#### Calculation ####
+
+The calculation of the `Orientation` and `Tilt` fields depends on the specified
+calibration parameters and available input.
+
+ If touch.tiltX and touch.tiltY are available:
+ tiltXCenter = average(raw.tiltX.min, raw.tiltX.max)
+ tiltYCenter = average(raw.tiltY.min, raw.tiltY.max)
+ tiltXAngle = (raw.tiltX - tiltXCenter) * PI / 180
+ tiltYAngle = (raw.tiltY - tiltYCenter) * PI / 180
+ output.orientation = atan2(-sin(tiltXAngle), sinf(tiltYAngle))
+ output.tilt = acos(cos(tiltXAngle) * cos(tiltYAngle))
+ Else If touch.orientation.calibration == "interpolated":
+ center = average(raw.orientation.min, raw.orientation.max)
+ output.orientation = PI / (raw.orientation.max - raw.orientation.min)
+ output.tilt = 0
+ Else If touch.orientation.calibration == "vector":
+ c1 = (raw.orientation & 0xF0) >> 4
+ c2 = raw.orientation & 0x0F
+
+ If c1 != 0 or c2 != 0:
+ If c1 >= 8 Then c1 = c1 - 16
+ If c2 >= 8 Then c2 = c2 - 16
+ angle = atan2(c1, c2) / 2
+ confidence = sqrt(c1*c1 + c2*c2)
+
+ output.orientation = angle
+
+ If touch.size.calibration == "diameter" or "area":
+ scale = 1.0 + confidence / 16
+ output.touchMajor *= scale
+ output.touchMinor /= scale
+ output.toolMajor *= scale
+ output.toolMinor /= scale
+ End If
+ Else
+ output.orientation = 0
+ End If
+ output.tilt = 0
+ Else
+ output.orientation = 0
+ output.tilt = 0
+ End If
+
+ If orientation aware:
+ If screen rotation is 90 degrees:
+ output.orientation = output.orientation - PI / 2
+ Else If screen rotation is 270 degrees:
+ output.orientation = output.orientation + PI / 2
+ End If
+ End If
+
+### `Distance` Field ###
+
+The `Distance` field describes the distance between the tool and the touch device
+surface. A value of 0.0 indicates direct contact and larger values indicate
+increasing distance from the surface.
+
+#### `touch.distance.calibration` ####
+
+*Definition:* `touch.distance.calibration` = `none` | `scaled` | `default`
+
+Specifies the kind of measurement used by the touch driver to report the distance.
+
+* If the value is `none`, the distance is unknown so it is set to 0.
+
+* If the value is `scaled`, the reported distance is multiplied by a
+ constant scale factor.
+
+* If the value is `default`, the system uses the `scaled` calibration if the
+ distance axis available, otherwise uses `none`.
+
+#### `touch.distance.scale` ####
+
+*Definition:* `touch.distance.scale` = <a non-negative floating point number>
+
+Specifies a constant scale factor used in the calibration.
+
+The default value is `1.0`.
+
+#### Calculation ####
+
+The calculation of the `Distance` field depends on the specified calibration parameters.
+
+ If touch.distance.calibration == "scaled":
+ output.distance = raw.distance * touch.distance.scale
+ Else
+ output.distance = 0
+ End If
+
+### Example ###
+
+ # Input device configuration file for a touch screen that supports pressure,
+ # size and orientation. The pressure and size scale factors were obtained
+ # by measuring the characteristics of the device itself and deriving
+ # useful approximations based on the resolution of the touch sensor and the
+ # display.
+ #
+ # Note that these parameters are specific to a particular device model.
+ # Different parameters will need to be used for other devices.
+
+ # Basic Parameters
+ touch.deviceType = touchScreen
+ touch.orientationAware = 1
+
+ # Size
+ # Based on empirical measurements, we estimate the size of the contact
+ # using size = sqrt(area) * 28 + 0.
+ touch.size.calibration = area
+ touch.size.scale = 28
+ touch.size.bias = 0
+ touch.size.isSummed = 0
+
+ # Pressure
+ # Driver reports signal strength as pressure.
+ #
+ # A normal index finger touch typically registers about 80 signal strength
+ # units although we don't expect these values to be accurate.
+ touch.pressure.calibration = amplitude
+ touch.pressure.scale = 0.0125
+
+ # Orientation
+ touch.orientation.calibration = vector
+
+### Compatibility Notes ###
+
+The configuration properties for touch devices changed significantly in
+Android Ice Cream Sandwich 4.0. **All input device configuration files for touch
+devices must be updated to use the new configuration properties.**
+
+Older touch device [drivers](#touch-device-driver-requirements) may also need to be
+updated.
+
+## Virtual Key Map Files ##
+
+Touch devices are often used to implement virtual keys.
+
+There are several ways of doing this, depending on the capabilities of the
+touch controller. Some touch controllers can be directly configured to implement
+soft keys by setting firmware registers. Other times it is desirable to perform
+the mapping from touch coordinates to key codes in software.
+
+When virtual keys are implemented in software, the kernel must export a virtual key map
+file called `virtualkeys.<devicename>` as a board property. For example,
+if the touch screen device drivers reports its name as "touchyfeely" then
+the virtual key map file must have the path `/sys/board_properties/virtualkeys.touchyfeely`.
+
+A virtual key map file describes the coordinates and Linux key codes of virtual keys
+on the touch screen.
+
+In addition to the virtual key map file, there must be a corresponding key layout
+file and key character map file to map the Linux key codes to Android key codes and
+to specify the type of the keyboard device (usually `SPECIAL_FUNCTION`).
+
+### Syntax ###
+
+A virtual key map file is a plain text file consisting of a sequence of virtual key
+layout descriptions either separated by newlines or by colons.
+
+Comment lines begin with '#' and continue to the end of the line.
+
+Each virtual key is described by 6 colon-delimited components:
+
+* `0x01`: A version code. Must always be `0x01`.
+* <Linux key code>: The Linux key code of the virtual key.
+* <centerX>: The X pixel coordinate of the center of the virtual key.
+* <centerY>: The Y pixel coordinate of the center of the virtual key.
+* <width>: The width of the virtual key in pixels.
+* <height>: The height of the virtual key in pixels.
+
+All coordinates and sizes are specified in terms of the display coordinate system.
+
+Here is a virtual key map file all written on one line.
+
+ # All on one line
+ 0x01:158:55:835:90:55:0x01:139:172:835:125:55:0x01:102:298:835:115:55:0x01:217:412:835:95:55
+
+The same virtual key map file can also be written on multiple lines.
+
+ # One key per line
+ 0x01:158:55:835:90:55
+ 0x01:139:172:835:125:55
+ 0x01:102:298:835:115:55
+ 0x01:217:412:835:95:55
+
+In the above example, the touch screen has a resolution of 480x800. Accordingly, all of
+the virtual keys have a <centerY> coordinate of 835, which is a little bit below
+the visible area of the touch screen.
+
+The first key has a Linux scan code of `158` (`KEY_BACK`), centerX of `55`,
+centerY of `835`, width of `90` and height of `55`.
+
+### Example ###
+
+Virtual key map file: `/sys/board_properties/virtualkeys.touchyfeely`.
+
+ 0x01:158:55:835:90:55
+ 0x01:139:172:835:125:55
+ 0x01:102:298:835:115:55
+ 0x01:217:412:835:95:55
+
+Key layout file: `/system/usr/keylayout/touchyfeely.kl`.
+
+ key 158 BACK
+ key 139 MENU
+ key 102 HOME
+ key 217 SEARCH
+
+Key character map file: `/system/usr/keychars/touchyfeely.kcm`.
+
+ type SPECIAL_FUNCTION
+
+## Indirect Multi-touch Pointer Gestures ##
+
+In pointer mode, the system interprets the following gestures:
+
+1. Single finger tap: click.
+
+2. Single finger motion: move the pointer.
+
+3. Single finger motion plus button presses: drag the pointer.
+
+4. Two finger motion both fingers moving in the same direction: drag the area under the pointer
+ in that direction. The pointer itself does not move.
+
+5. Two finger motion both fingers moving towards each other or apart in
+ different directions: pan/scale/rotate the area surrounding the pointer.
+ The pointer itself does not move.
+
+6. Multiple finger motion: freeform gesture.
+
+## Further Reading ##
+
+1. [Linux multi-touch protocol](http://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt)
+2. [ENAC list of available multitouch devices on Linux](http://lii-enac.fr/en/architecture/linux-input/multitouch-devices.html)
diff --git a/src/tech/input/validate-keymaps.md b/src/tech/input/validate-keymaps.md
new file mode 100644
index 0000000..8d8df9a
--- /dev/null
+++ b/src/tech/input/validate-keymaps.md
@@ -0,0 +1,96 @@
+<!--
+ Copyright 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Validate Keymaps Tool #
+
+The Android framework has a small tool called `validatekeymaps` to validate the
+syntax of input device configuration files, key layout files, key character
+maps files and virtual key definition files.
+
+## Compilation ##
+
+To compile `validatekeymaps`, set up the development environment, download
+the Android source tree, compile it, then run:
+
+ $ mmm frameworks/base/tools/validatekeymaps
+
+This command should compile a host tool called validatekeymaps into the
+`out/host/<os>/bin` directory.
+
+## Usage ##
+
+If you ran `envsetup.sh` to set up your development environment, then the
+`validatekeymaps` tool should already be on your path. You can verify
+this by running `validatekeymaps`.
+
+ $ validatekeymaps
+
+ Keymap Validation Tool
+
+ Usage:
+ validatekeymaps [*.kl] [*.kcm] [*.idc] [virtualkeys.*] [...]
+ Validates the specified key layouts, key character maps,
+ input device configurations, or virtual key definitions.
+
+Then all you need to do is run `validatekeymaps` an give it the path of
+one or more files to validate.
+
+ $ validatekeymaps frameworks/base/data/keyboards/Generic.kl
+
+ Validating file 'frameworks/base/data/keyboards/Generic.kl'...
+ No errors.
+
+ Success.
+
+And if there is an error...
+
+ $ validatekeymaps Bad.kl
+
+ Validating file 'Bad.kl'...
+ E/KeyLayoutMap(87688): Bad.kl:24: Expected keyword, got 'ke'.
+ Error -22 parsing key layout file.
+
+ Failed!
+
+## Automation ##
+
+It is a *very* good idea to run `validatekeymaps` on all configuration files
+before installing them on a device.
+
+The process can easily be automated as part of the build system by using a
+script or a makefile.
+
+The following sample makefile is based on the contents of
+`frameworks/base/data/keyboards/Android.mk`.
+
+ # This makefile performs build time validation of framework keymap files.
+
+ LOCAL_PATH := $(call my-dir)
+
+ # Validate all key maps.
+ include $(CLEAR_VARS)
+
+ validatekeymaps := $(HOST_OUT_EXECUTABLES)/validatekeymaps$(HOST_EXECUTABLE_SUFFIX)
+ files := MyKeyboard.kl MyKeyboard.kcm MyTouchScreen.idc
+
+ LOCAL_MODULE := validate_framework_keymaps
+ LOCAL_MODULE_TAGS := optional
+ LOCAL_REQUIRED_MODULES := validatekeymaps
+
+ validate_framework_keymaps: $(files)
+ $(hide) $(validatekeymaps) $(files)
+
+ include $(BUILD_PHONY_PACKAGE)
diff --git a/src/tech/security/index.md b/src/tech/security/index.md
index e64e987..054a70b 100644
--- a/src/tech/security/index.md
+++ b/src/tech/security/index.md
@@ -319,6 +319,7 @@
exploit. The Android SDK, compilers, and OS use tools to make common memory
corruption issues significantly harder to exploit, including:
++ Address Space Layout Randomization (ASLR) to randomize key locations in memory
+ Hardware-based No eXecute (NX) to prevent code execution on the stack and heap
+ ProPolice to prevent stack buffer overruns
+ safe_iop to reduce integer overflows
diff --git a/src/tech/sidebar.md b/src/tech/sidebar.md
index 67ec0a4..c3701fd 100644
--- a/src/tech/sidebar.md
+++ b/src/tech/sidebar.md
@@ -3,3 +3,5 @@
- [Debugging](/tech/debugging/index.html)
- [Encryption](/tech/encryption/index.html)
- [Security](/tech/security/index.html)
+- [Input](/tech/input/index.html)
+- [Data Usage](/tech/datausage/index.html)
diff --git a/templates/footer b/templates/footer
index 9e4f297..4bf07fc 100644
--- a/templates/footer
+++ b/templates/footer
@@ -4,8 +4,7 @@
<div id="footerLeft">
<p>
- <a href="http://www.android.com/terms.html">Site Terms of Service</a> -
- <a href="http://www.android.com/privacy.html">Privacy Policy</a>
+ <a href="http://www.google.com/intl/en/policies/">Privacy & Terms</a>
</p>
</div>
diff --git a/templates/sidebar b/templates/sidebar
index 16e8000..748a2fc 100644
--- a/templates/sidebar
+++ b/templates/sidebar
@@ -1,4 +1,4 @@
<div id=sidebar>
- $sidebar$sidebar2
+ $sidebar$sidebar2$sidebar3
</div>