resolved conflicts for merge of 2d7a1617 to lmp-mr1-ub-dev
diff --git a/README b/README
index 08a3bdf..77a76b8 100644
--- a/README
+++ b/README
@@ -58,7 +58,7 @@
3. Edit the Javadoc file(s) and save your changes.
-4. If a page was added or removed, update the corresponding *.toc.cs file to
+4. If a page was added or removed, update the corresponding _toc.cs file to
reflect the change.
5. Run the following make command from the root of the project parent directory:
diff --git a/src/accessories/audio.jd b/src/accessories/audio.jd
index 1674710..92ce6fe 100644
--- a/src/accessories/audio.jd
+++ b/src/accessories/audio.jd
@@ -38,17 +38,17 @@
<h2 id="audio-over-usb">Audio over USB</h2>
<p>Android can use USB in several modes:</p>
<ul>
- <li>debug
+ <li>development
<li>accessory
<li>host
</ul>
-<p>In the traditional debug mode, there is no audio capability.</p>
+<p>In the development mode, there is no audio capability.</p>
<p>Accessory mode is provided by the Open Accessory (AOA) protocol version 2.0.
There is limited audio capability in accessory mode, as described in <a
href="custom.html#audio-over-usb">Connecting custom audio over USB</a>.</p>
<p>Host mode enables the Android device to drive the USB bus and operate with a
wide range of USB-based peripherals, including audio interfaces. Host mode
-audio is described in <a href="{@docRoot}devices/audio_usb.html">USB Digital Audio</a>
+audio is described in <a href="{@docRoot}devices/audio/usb.html">USB Digital Audio</a>
<h2 id="audio-over-bluetooth">Audio over Bluetooth</h2>
<p>An accessory that connects with Android over Bluetooth can use an Advanced Audio Distribution
diff --git a/src/accessories/headset-spec.jd b/src/accessories/headset-spec.jd
index d87c19a..c9a749e 100644
--- a/src/accessories/headset-spec.jd
+++ b/src/accessories/headset-spec.jd
@@ -24,7 +24,7 @@
</div>
</div>
-<p><em>Version 1.0</em></p>
+<p><em>Version 1.1</em></p>
<p>This document specifies the requirements for headsets and mobile devices to
function uniformly across the Android ecosystem. It is separated into two
@@ -127,7 +127,7 @@
<p>Optional</p>
</td>
<td>
-<p>Reserved (Nexus devices will use this reserved function to launch Google Now
+<p>Reserved (Nexus devices will use this reserved function to launch Google
voice search)</p>
</td>
</tr>
@@ -284,25 +284,40 @@
</tr>
</table>
+<p>In the following diagrams, Button A is mapped to Function A, Button B to
+Function B, and so on.</p>
+
<h3 id=reference_headset_test_circuit_1>Reference Headset Test Circuit 1</h3>
<img src="images/headset-circuit1.png" alt="Reference Headset Test Circuit 1" />
<p class="img-caption"><strong>Figure 1.</strong> Reference headset test circuit 1</p>
-<p class="note"><strong>Note:</strong> Four-segment plug shows CTIA pinout. For
-OMTP pinout, please swap MIC and GND segments.</p>
+<p class="note"><strong>Note:</strong> The above diagram shows the CTIA pinout
+for a 4-segment plug. For the OMTP pinout, switch the positions of the MIC and
+GND segments.</p>
<h3 id=reference_headset_test_circuit_2>Reference Headset Test Circuit 2</h3>
+<p>The second reference circuit shows how the actual resistor values (R1 - R4)
+are altered to meet this specification.</p>
+
<img src="images/headset-circuit2.png" alt="Reference Headset Test Circuit 2" />
<p class="img-caption"><strong>Figure 2.</strong> Reference headset test circuit 2</p>
-<p class="note"><strong>Note:</strong> The second reference circuit above
-illustrates how the actual resistor values (R1 - R4) will change based on the
-microphone capsule resistance to achieve the equivalent impedance values as
-required by the specification. The example above assumes a 5 kOhm microphone
-impedance. Therefore, as an example, to achieve an equivalent R4 impedance of
-135 Ohm, the actual R4 resistor value needs to be 139 Ohms.</p>
+<p>The actual resistance of the buttons parallel with the microphone (R1-R4) is
+based on the microphone capsule resistance (Rmic) and the equivalent impedance
+values (ReqA-ReqD). Use the following formula:</p>
+
+<p><em>Rn=(Rmic*ReqN) / (ReqN-Rmic)</em></p>
+
+<p>Where R<em>n</em> is the actual resistance of a button, Req<em>N</em> is the
+equivalent impedance value of that button (provided), and Rmic is the
+microphone impedance value.</p>
+
+<p>The example above assumes a 5 kohm microphone impedance (Rmic). Therefore, to
+achieve an equivalent R4 impedance of 135 ohm (ReqD), the actual resistor value
+(R4) needs to be 139 ohms.</p>
+
<h2 id=mobile_device_jack_specifications>Mobile Device (Jack) Specifications</h2>
@@ -548,7 +563,7 @@
</tr>
<tr>
<td>
-<p>Minimum output voltage drive capacity </p>
+<p>Maximum output voltage drive</p>
</td>
<td>
<p>150mV </p>
diff --git a/src/accessories/images/headset-circuit1.png b/src/accessories/images/headset-circuit1.png
index c69df98..f3e622a 100644
--- a/src/accessories/images/headset-circuit1.png
+++ b/src/accessories/images/headset-circuit1.png
Binary files differ
diff --git a/src/accessories/images/headset-circuit2.png b/src/accessories/images/headset-circuit2.png
index 67bd5b4..ff6b541 100644
--- a/src/accessories/images/headset-circuit2.png
+++ b/src/accessories/images/headset-circuit2.png
Binary files differ
diff --git a/src/accessories/index.jd b/src/accessories/index.jd
index 1157d5d..d30c0ce 100644
--- a/src/accessories/index.jd
+++ b/src/accessories/index.jd
@@ -22,21 +22,26 @@
Android-powered devices.
</p>
-<div class="layout-content-row">
+<div class="layout-content-row">
<div class="layout-content-col span-6">
- <h4 id="audio-accessories">Audio Accessories</h4>
- <p>Android supports local on-device audio and remote off-device audio
- over a wired 3.5 mm headset jack, USB connection, or Bluetooth.</p>
- <p><a href="{@docRoot}accessories/audio.html">» Audio Accessories</a></p>
+ <h4 id="audio-accessories">Audio Accessories</h4>
+ <p>Android supports local on-device audio and remote off-device audio
+ over a wired 3.5 mm headset jack, USB connection, or Bluetooth.
+ Manufacturers should see the <a
+ href="{@docRoot}accessories/headset-spec.html">wired audio headset
+ specification</a>, while users may learn how to <a
+ href="https://support.google.com/nexus/answer/6127700">record and play
+ back audio using USB host mode</a>.</p>
+ <p><a href="{@docRoot}accessories/audio.html">» Audio Accessories</a></p>
</div>
-
+
<div class="layout-content-col span-6">
- <h4 id="custom-accessories">Custom Accessories</h4>
- <p>What do you want to connect to your Android device? Alarm clock? Keyboard? Thermostat? Robot?
- Learn how to connect existing equipment or your own unique hardware to
+ <h4 id="custom-accessories">Custom Accessories</h4>
+ <p>What do you want to connect to your Android device? Alarm clock? Keyboard? Thermostat? Robot?
+ Learn how to connect existing equipment or your own unique hardware to
Android using the Android Open Accessory Protocol.</p>
- <p><a href="{@docRoot}accessories/custom.html">» Custom Accessories</a></p>
+ <p><a href="{@docRoot}accessories/custom.html">» Custom Accessories</a></p>
</div>
</div>
diff --git a/src/app.yaml b/src/app.yaml
index f8f4788..1fdcdda 100644
--- a/src/app.yaml
+++ b/src/app.yaml
@@ -1,38 +1,16 @@
-application: androidsourcedocs-staging
+application: google.com:sourceandroid-staging
version: 1
-runtime: python
+runtime: python27
api_version: 1
-
-# This file defines two mutually exclusive
-# hander blocks:
-# - a handler for use on a local dev_appserver
-# during development or non-production doc build
-# - a handler for use on a production gae
-# instance. This handler requires that the
-# docs files in the app have been compressed
-# with divide_and_compress.py and that main.py
-# and gae_shell/ are present.
-#
-# Only one of the handler blocks should be
-# uncommented at any given time. By default,
-# the development handler is exposed.
+threadsafe: true
handlers:
-
-# DEVELOPMENT HANDLER
-# (this handler block *must* be commented
-# out before pushing to a production server)
+# re-direct to index.html if no path is given
- url: /
- static_dir: /
+ static_files: index.html
+ upload: index.html
-# PRODUCTION GAE HANDLER
-#- url: /gae_shell/static
-# static_dir: gae_shell/static
-# expiration: 1d
-#
-#- url: /gae_shell/.*
-# script: /gae_shell/shell.py
-# login: admin
-#
-#- url: .*
-# script: main.py
+# access the static resources in the root directory
+- url: /(.*)
+ static_files: \1
+ upload: (.*)
diff --git a/src/compatibility/2.1/android-2.1-cdd.xhtml b/src/compatibility/2.1/android-2.1-cdd.xhtml
new file mode 100644
index 0000000..cd7a7ca
--- /dev/null
+++ b/src/compatibility/2.1/android-2.1-cdd.xhtml
@@ -0,0 +1,1193 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>Android 2.1 Compatibility Definition</title>
+<link rel="stylesheet" type="text/css" href="cdd.css"/>
+</head>
+<body>
+<div><img src="header.jpg" alt="Android logo"/></div>
+<h1>Android 2.1 Compatibility Definition</h1>
+<p>Copyright © 2010, Google Inc. All rights reserved.<br/>
+<a href="mailto:compatibility@android.com">compatibility@android.com</a>
+</p>
+
+<h2>1. Introduction</h2>
+<p>This document enumerates the requirements that must be met in order for
+mobile phones to be compatible with Android 2.1.</p>
+<p>The use of "must", "must not", "required", "shall", "shall not", "should",
+"should not", "recommended", "may" and "optional" is per the IETF standard
+defined in RFC2119 [<a href="#resources01">Resources, 1</a>].</p>
+<p>As used in this document, a "device implementer" or "implementer" is a
+person or organization developing a hardware/software solution running Android
+2.1. A "device implementation" or "implementation" is the hardware/software
+solution so developed.</p>
+<p>To be considered compatible with Android 2.1, device implementations:</p>
+<ul>
+<li>MUST meet the requirements presented in this Compatibility Definition,
+including any documents incorporated via reference.</li>
+<li>MUST pass the most recent version of the Android Compatibility Test Suite
+(CTS) available at the time of the device implementation's software is
+completed. (The CTS is available as part of the Android Open Source Project [<a
+href="#resources02">Resources, 2</a>].) The CTS tests many, but not all, of the
+components outlined in this document.</li>
+</ul>
+<p>Where this definition or the CTS is silent, ambiguous, or incomplete, it is
+the responsibility of the device implementer to ensure compatibility with
+existing implementations. For this reason, the Android Open Source Project [<a
+href="#resources03">Resources, 3</a>] is both the reference and preferred
+implementation of Android. Device implementers are strongly encouraged to base
+their implementations on the "upstream" source code available from the Android
+Open Source Project. While some components can hypothetically be replaced with
+alternate implementations this practice is strongly discouraged, as passing
+the CTS tests will become substantially more difficult. It is the
+implementer's responsibility to ensure full behavioral compatibility with the
+standard Android implementation, including and beyond the Compatibility Test
+Suite. Finally, note that certain component substitutions and modifications
+are explicitly forbidden by this document.</p>
+
+<a name="resources"/><h2>2. Resources</h2>
+<ol>
+<a name="resources01"/><li>IETF RFC2119 Requirement Levels: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a></li>
+<a name="resources02"/><li>Android Compatibility Program Overview: <a href="http://source.android.com/compatibility/index.html">http://source.android.com/compatibility/index.html</a></li>
+<a name="resources03"/><li>Android Open Source Project: <a href="http://source.android.com/">http://source.android.com/</a></li>
+<a name="resources04"/><li>API definitions and documentation: <a href="http://developer.android.com/reference/packages.html">http://developer.android.com/reference/packages.html</a></li>
+<a name="resources05"/><li>Android Permissions reference: <a href="http://developer.android.com/reference/android/Manifest.permission.html">http://developer.android.com/reference/android/Manifest.permission.html</a></li>
+<a name="resources06"/><li>android.os.Build reference: <a href="http://developer.android.com/reference/android/os/Build.html">http://developer.android.com/reference/android/os/Build.html</a></li>
+<a name="resources07"/><li>Android 2.1 allowed version strings: <a href="http://source.android.com/compatibility/2.1/versions.xhtml">http://source.android.com/compatibility/2.1/versions.xhtml</a></li>
+<a name="resources08"/><li>android.webkit.WebView class: <a href="http://developer.android.com/reference/android/webkit/WebView.html">http://developer.android.com/reference/android/webkit/WebView.html</a></li>
+<a name="resources09"/><li>HTML5: <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">http://www.whatwg.org/specs/web-apps/current-work/multipage/</a></li>
+<a name="resources10"/><li>Dalvik Virtual Machine specification: available in the Android source code, at dalvik/docs</li>
+<a name="resources11"/><li>AppWidgets: <a href="http://developer.android.com/guide/practices/ui_guidelines/widget_design.html">http://developer.android.com/guide/practices/ui_guidelines/widget_design.html</a></li>
+<a name="resources12"/><li>Notifications: <a href="http://developer.android.com/guide/topics/ui/notifiers/notifications.html">http://developer.android.com/guide/topics/ui/notifiers/notifications.html</a></li>
+<a name="resources13"/><li>Application Resources: <a href="http://code.google.com/android/reference/available-resources.html">http://code.google.com/android/reference/available-resources.html</a></li>
+<a name="resources14"/><li>Status Bar icon style guide: <a href="http://developer.android.com/guide/practices/ui_guidelines/icon_design.html#statusbarstructure">http://developer.android.com/guide/practices/ui_guideline /icon_design.html#statusbarstructure</a></li>
+<a name="resources15"/><li>Search Manager: <a href="http://developer.android.com/reference/android/app/SearchManager.html">http://developer.android.com/reference/android/app/SearchManager.html</a></li>
+<a name="resources16"/><li>Toasts: <a href="http://developer.android.com/reference/android/widget/Toast.html">http://developer.android.com/reference/android/widget/Toast.html</a></li>
+<a name="resources17"/><li>Live Wallpapers: <a href="http://developer.android.com/resources/articles/live-wallpapers.html">http://developer.android.com/resources/articles/live-wallpapers.html</a></li>
+<a name="resources18"/><li>Apps for Android: <a href="http://code.google.com/p/apps-for-android">http://code.google.com/p/apps-for-android</a></li>
+<a name="resources19"/><li>Reference tool documentation (for adb, aapt, ddms): <a href="http://developer.android.com/guide/developing/tools/index.html">http://developer.android.com/guide/developing/tools/index.html</a></li>
+<a name="resources20"/><li>Android apk file description: <a href="http://developer.android.com/guide/topics/fundamentals.html">http://developer.android.com/guide/topics/fundamentals.html</a></li>
+<a name="resources21"/><li>Manifest files: <a href="http://developer.android.com/guide/topics/manifest/manifest-intro.html">http://developer.android.com/guide/topics/manifest/manifest-intro.html</a></li>
+<a name="resources22"/><li>Monkey testing tool: <a href="http://developer.android.com/guide/developing/tools/monkey.html">http://developer.android.com/guide/developing/tools/monkey.html</a></li>
+<a name="resources23"/><li>Supporting Multiple Screens: <a href="http://developer.android.com/guide/practices/screens_support.html">http://developer.android.com/guide/practices/screens_support.html</a></li>
+<a name="resources24"/><li>android.content.res.Configuration: <a href="http://developer.android.com/reference/android/content/res/Configuration.html">http://developer.android.com/reference/android/content/res/Configuration.html</a></li>
+<a name="resources25"/><li>android.util.DisplayMetrics: <a href="http://developer.android.com/reference/android/util/DisplayMetrics.html">http://developer.android.com/reference/android/util/DisplayMetrics.html</a></li>
+<a name="resources26"/><li>android.hardware.Camera: <a href="http://developer.android.com/reference/android/hardware/Camera.html">http://developer.android.com/reference/android/hardware/Camera.html</a></li>
+<a name="resources27"/><li>Sensor coordinate space: <a href="http://developer.android.com/reference/android/hardware/SensorEvent.html">http://developer.android.com/reference/android/hardware/SensorEvent.html</a></li>
+<a name="resources28"/><li>Android Security and Permissions reference: <a href="http://developer.android.com/guide/topics/security/security.html">http://developer.android.com/guide/topics/security/security.html</a></li>
+<a name="resources29"/><li>Bluetooth API: <a href="http://developer.android.com/reference/android/bluetooth/package-summary.html">http://developer.android.com/reference/android/bluetooth/package-summary.html</a></li>
+</ol>
+<p>Many of these resources are derived directly or indirectly from the Android
+2.1 SDK, and will be functionally identical to the information in that SDK's
+documentation. In any cases where this Compatibility Definition or the
+Compatibility Test Suite disagrees with the SDK documentation, the SDK
+documentation is considered authoritative. Any technical details provided in
+the references included above are considered by inclusion to be part of this
+Compatibility Definition.</p>
+
+<h2>3. Software</h2>
+<p>The Android platform includes a set of managed APIs, a set of native APIs,
+and a body of so-called "soft" APIs such as the Intent system and
+web-application APIs. This section details the hard and soft APIs that are
+integral to compatibility, as well as certain other relevant technical and
+user interface behaviors. Device implementations MUST comply with all the
+requirements in this section.</p>
+
+<h3>3.1. Managed API Compatibility</h3>
+<p>The managed (Dalvik-based) execution environment is the primary vehicle for
+Android applications. The Android application programming interface (API) is
+the set of Android platform interfaces exposed to applications running in the
+managed VM environment. Device implementations MUST provide complete
+implementations, including all documented behaviors, of any documented API
+exposed by the Android 2.1 SDK [<a href="#resources04">Resources, 4</a>].</p>
+<p>Device implementations MUST NOT omit any managed APIs, alter API interfaces
+or signatures, deviate from the documented behavior, or include no-ops, except
+where specifically allowed by this Compatibility Definition.</p>
+
+<h3>3.2. Soft API Compatibility</h3>
+<p>In addition to the managed APIs from Section 3.1, Android also includes a
+significant runtime-only "soft" API, in the form of such things such as
+Intents, permissions, and similar aspects of Android applications that cannot
+be enforced at application compile time. This section details the "soft" APIs
+and system behaviors required for compatibility with Android 2.1. Device
+implementations MUST meet all the requirements presented in this section.</p>
+<h4>3.2.1. Permissions</h4>
+<p>Device implementers MUST support and enforce all permission constants as
+documented by the Permission reference page [<a
+href="#resources05">Resources, 5</a>]. Note that Section 10 lists addtional
+requirements related to the Android security model.</p>
+<h4>3.2.2. Build Parameters</h4>
+<p>The Android APIs include a number of constants on the <code>android.os.Build</code>
+class [<a href="#resources06">Resources, 6</a>] that are intended to describe
+the current device. To provide consistent, meaningful values across device
+implementations, the table below includes additional restrictions on the
+formats of these values to which device implementations MUST conform.</p>
+<table>
+<tbody>
+<tr>
+<td><b>Parameter</b></td>
+<td><b>Comments</b></td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.RELEASE</td>
+<td>The version of the currently-executing Android system, in human-readable
+format. This field MUST have one of the string values defined in [<a
+href="#resources07">Resources, 7</a>].</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.SDK</td>
+<td>The version of the currently-executing Android system, in a format
+accessible to third-party application code. For Android 2.1, this field MUST have
+the integer value 7.</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.INCREMENTAL</td>
+<td>A value chosen by the device implementer designating the specific build of
+the currently-executing Android system, in human-readable format. This value
+MUST NOT be re-used for different builds shipped to end users. A typical use
+of this field is to indicate which build number or source-control change
+identifier was used to generate the build. There are no requirements on the
+specific format of this field, except that it MUST NOT be null or the empty
+string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.BOARD</td>
+<td>A value chosen by the device implementer identifying the specific internal
+hardware used by the device, in human-readable format. A possible use of this
+field is to indicate the specific revision of the board powering the device.
+There are no requirements on the specific format of this field, except that it
+MUST NOT be null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.BRAND</td>
+<td>A value chosen by the device implementer identifying the name of the
+company, organization, individual, etc. who produced the device, in
+human-readable format. A possible use of this field is to indicate the OEM
+and/or carrier who sold the device. There are no requirements on the specific
+format of this field, except that it MUST NOT be null or the empty string
+("").</td>
+</tr>
+<tr>
+<td>android.os.Build.DEVICE</td>
+<td>A value chosen by the device implementer identifying the specific
+configuration or revision of the body (sometimes called "industrial design")
+of the device. There are no requirements on the specific format of this field,
+except that it MUST NOT be null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.FINGERPRINT</td>
+<td>A string that uniquely identifies this build. It SHOULD be reasonably
+human-readable. It MUST follow this template:
+<br/><code>$(BRAND)/$(PRODUCT)/$(DEVICE)/$(BOARD):$(VERSION.RELEASE)/$(ID)/$(VERSION.INCREMENTAL):$(TYPE)/$(TAGS)</code><br/>
+For example:
+<br/><code>acme/mydevice/generic/generic:2.1-update1/ERC77/3359:userdebug/test-keys</code><br/>
+The fingerprint MUST NOT include spaces. If other fields included in the
+template above have spaces, they SHOULD be replaced with the ASCII underscore
+("_") character in the fingerprint.</td>
+</tr>
+<tr>
+<td>android.os.Build.HOST</td>
+<td>A string that uniquely identifies the host the build was built on, in
+human readable format. There are no requirements on the specific format of
+this field, except that it MUST NOT be null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.ID</td>
+<td>An identifier chosen by the device implementer to refer to a specific
+release, in human readable format. This field can be the same as
+android.os.Build.VERSION.INCREMENTAL, but SHOULD be a value sufficiently
+meaningful for end users to distinguish between software builds. There are no
+requirements on the specific format of this field, except that it MUST NOT be
+null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.MODEL</td>
+<td>A value chosen by the device implementer containing the name of the device
+as known to the end user. This SHOULD be the same name under which the device
+is marketed and sold to end users. There are no requirements on the specific
+format of this field, except that it MUST NOT be null or the empty string
+("").</td>
+</tr>
+<tr>
+<td>android.os.Build.PRODUCT</td>
+<td>A value chosen by the device implementer containing the development name
+or code name of the device. MUST be human-readable, but is not necessarily
+intended for view by end users. There are no requirements on the specific
+format of this field, except that it MUST NOT be null or the empty string
+("").</td>
+</tr>
+<tr>
+<td>android.os.Build.TAGS</td>
+<td>A comma-separated list of tags chosen by the device implementer that
+further distinguish the build. For example, "unsigned,debug". This field MUST
+NOT be null or the empty string (""), but a single tag (such as "release") is
+fine.</td>
+</tr>
+<tr>
+<td>android.os.Build.TIME</td>
+<td>A value representing the timestamp of when the build occurred.</td>
+</tr>
+<tr>
+<td>android.os.Build.TYPE</td>
+<td>A value chosen by the device implementer specifying the runtime
+configuration of the build. This field SHOULD have one of the values
+corresponding to the three typical Android runtime configurations: "user",
+"userdebug", or "eng".</td>
+</tr>
+<tr>
+<td>android.os.Build.USER</td>
+<td>A name or user ID of the user (or automated user) that generated the
+build. There are no requirements on the specific format of this field, except
+that it MUST NOT be null or the empty string ("").</td>
+</tr>
+</tbody>
+</table>
+<h4>3.2.3. Intent Compatibility</h4>
+<p>Android uses Intents to achieve loosely-coupled integration between
+applications. This section describes requirements related to the Intent
+patterns that MUST be honored by device implementations. By "honored", it is
+meant that the device implementer MUST provide an Android Activity or Service
+that specifies a matching Intent filter and binds to and implements correct
+behavior for each specified Intent pattern.</p>
+<h4>3.2.3.1. Core Application Intents</h4>
+<p>The Android upstream project defines a number of core applications, such as
+a phone dialer, calendar, contacts book, music player, and so on. Device
+implementers MAY replace these applications with alternative versions.</p>
+<p>However, any such alternative versions MUST honor the same Intent patterns
+provided by the upstream project. For example, if a device contains an
+alternative music player, it must still honor the Intent pattern issued by
+third-party applications to pick a song.</p>
+<p>The following applications are considered core Android system
+applications:</p>
+<ul>
+<li>Desk Clock</li>
+<li>Browser</li>
+<li>Calendar</li>
+<li>Calculator</li>
+<li>Camera</li>
+<li>Contacts</li>
+<li>Email</li>
+<li>Gallery</li>
+<li>GlobalSearch</li>
+<li>Launcher</li>
+<li>LivePicker (that is, the Live Wallpaper picker application; MAY be omitted
+if the device does not support Live Wallpapers, per Section 3.8.5.)</li>
+<li>Messaging (AKA "Mms")</li>
+<li>Music</li>
+<li>Phone</li>
+<li>Settings</li>
+<li>SoundRecorder</li>
+</ul>
+<p>The core Android system applications include various Activity, or Service
+components that are considered "public".
+That is, the attribute "android:exported" may be absent, or may have the value
+"true".</p>
+<p>For every Activity or Service defined
+in one of the core Android system apps that is not marked as non-public via an
+android:exported attribute with the value "false", device implementations MUST
+include a compontent of the same type implementing the same Intent filter
+patterns as the core Android system app.</p>
+<p>In other words, a device implementation MAY replace core Android system
+apps; however, if it does, the device implementation MUST support all Intent
+patterns defined by each core Android system app being replaced.</p>
+<h4>3.2.3.2. Intent Overrides</h4>
+<p>As Android is an extensible platform, device implementers MUST allow each
+Intent pattern defined in core system apps to be overridden by third-party
+applications. The upstream Android open source project allows this by default;
+device implementers MUST NOT attach special privileges to system applications'
+use of these Intent patterns, or prevent third-party applications from binding
+to and assuming control of these patterns. This prohibition specifically
+includes but is not limited to disabling the "Chooser" user interface which
+allows the user to select between multiple applications which all handle the
+same Intent pattern.</p>
+<div class="cdd-erratum">Note: this section was modified by Erratum EX6580.</div>
+<h4>3.2.3.3. Intent Namespaces</h4>
+<p>Device implementers MUST NOT include any Android component that honors any
+new Intent or Broadcast Intent patterns using an ACTION, CATEGORY, or other
+key string in the android.* namespace. Device implementers MUST NOT include
+any Android components that honor any new Intent or Broadcast Intent patterns
+using an ACTION, CATEGORY, or other key string in a package space belonging to
+another organization. Device implementers MUST NOT alter or extend any of the
+Intent patterns used by the core apps listed in Section 3.2.3.1.</p>
+<p>This prohibition is analogous to that specified for Java language classes
+in Section 3.6.</p>
+<h4>3.2.3.4. Broadcast Intents</h4>
+<p>Third-party applications rely on the platform to broadcast certain Intents
+to notify them of changes in the hardware or software environment.
+Android-compatible devices MUST broadcast the public broadcast Intents in
+response to appropriate system events. Broadcast Intents are described in the
+SDK documentation.</p>
+
+<h3>3.3. Native API Compatibility</h3>
+<p>Managed code running in Dalvik can call into native code provided in the
+application .apk file as an ELF .so file compiled for the appropriate device
+hardware architecture. Device implementations MUST include support for code
+running in the managed environment to call into native code, using the
+standard Java Native Interface (JNI) semantics. The following APIs MUST be
+available to native code:</p>
+<ul>
+<li>libc (C library)</li>
+<li>libm (math library)</li>
+<li>JNI interface</li>
+<li>libz (Zlib compression)</li>
+<li>liblog (Android logging)</li>
+<li>Minimal support for C++</li>
+<li>Support for OpenGL, as described below</li>
+</ul>
+<p>Device implementations MUST support OpenGL ES 1.0. Devices that lack
+hardware acceleration MUST implement OpenGL ES 1.0 using a software renderer.
+Device implementations SHOULD implement as much of OpenGL ES 1.1 as the device
+hardware supports. Device implementations SHOULD provide an implementation
+for OpenGL ES 2.0, if the hardware is capable of reasonable performance on
+those APIs.</p>
+<p>These libraries MUST be source-compatible (i.e. header compatible) and
+binary-compatible (for a given processor architecture) with the versions
+provided in Bionic by the Android Open Source project. Since the Bionic
+implementations are not fully compatible with other implementations such as
+the GNU C library, device implementers SHOULD use the Android implementation.
+If device implementers use a different implementation of these libraries, they
+MUST ensure header, binary, and behavioral compatibility.</p>
+<p>Device implementations MUST accurately report the native Application Binary
+Interface (ABI) supported by the device, via the
+<code>android.os.Build.CPU_ABI</code> API. The ABI MUST be one of the entries
+documented in the latest version of the Android NDK, in the file
+<code>docs/CPU-ARCH-ABIS.txt</code>. Note that additional releases of the
+Android NDK may introduce support for additional ABIs.</p>
+<p>Native code compatibility is challenging. For this reason, it should be
+repeated that device implementers are VERY strongly encouraged to use the
+upstream implementations of the libraries listed above, to help ensure
+compatibility.</p>
+
+<h3>3.4. Web API Compatibility</h3>
+<p>Many developers and applications rely on the behavior of the
+<code>android.webkit.WebView</code> class [<a
+href="#resources08">Resources, 8</a>]
+for their user interfaces, so the WebView implementation must be
+compatible across Android implementations. The Android Open Source
+implementation uses the WebKit rendering engine to implement the
+WebView.</p>
+<p>Because it is not feasible to develop a comprehensive test suite for a web
+browser, device implementers MUST use the specific upstream build of WebKit in
+the WebView implementation. Specifically:</p>
+<ul>
+<li>WebView MUST use the 530.17 WebKit build from the upstream Android Open
+Source tree for Android 2.1. This build includes a specific set of functionality
+and security fixes for the WebView.</li>
+<li>The user agent string reported by the WebView MUST be in this format:<br/>
+ <code>Mozilla/5.0 (Linux; U; Android $(VERSION); $(LOCALE); $(MODEL) Build/$(BUILD)) AppleWebKit/530.17 (KHTML, like Gecko) Version/4.0 Mobile Safari/530.17</code>
+ <ul>
+ <li>The value of the $(VERSION) string MUST be the same as the value for <code>android.os.Build.VERSION.RELEASE</code></li>
+ <li>The value of the $(LOCALE) string SHOULD follow the ISO conventions for country code and language, and SHOULD refer to the current configured locale of the device</li>
+ <li>The value of the $(MODEL) string MUST be the same as the value for <code>android.os.Build.MODEL</code></li>
+ <li>The value of the $(BUILD) string MUST be the same as the value for <code>android.os.Build.ID</code></li>
+ </ul></li>
+</ul>
+<p>Implementations MAY ship a custom user agent string in the standalone
+Browser application. What's more, the standalone Browser MAY be based on an
+alternate browser technology (such as Firefox, Opera, etc.) However, even if an
+alternate Browser application is shipped, the WebView component provided to
+third-party applications MUST be based on WebKit, as above.</p>
+<p>The WebView configuration MUST include support for the HTML5 database,
+application cache, and geolocation APIs [<a href="#resources09">Resources,
+9</a>]. The WebView MUST include support for
+the HTML5 <code><video></code> tag in
+some form. The standalone Browser application (whether based on the upstream
+WebKit Browser application or a third-party replacement) MUST include support
+for the same HTML5 features just listed for WebView.</p>
+
+<h3>3.5. API Behavioral Compatibility</h3>
+<p>The behaviors of each of the API types (managed, soft, native, and web)
+must be consistent with the preferred implementation of the upstream Android
+open-source project [<a href="#resources03">Resources, 3</a>]. Some specific areas
+of compatibility are:</p>
+<ul>
+<li>Devices MUST NOT change the behavior or meaning of a standard Intent</li>
+<li>Devices MUST NOT alter the lifecycle or lifecycle semantics of a particular type of system component (such as Service, Activity, ContentProvider, etc.)</li>
+<li>Devices MUST NOT change the semantics of a particular permission</li>
+</ul>
+<p>The above list is not comprehensive, and the onus is on device implementers
+to ensure behavioral compatibility. For this reason, device implementers
+SHOULD use the source code available via the Android Open Source Project where
+possible, rather than re-implement significant parts of the system.</p>
+<p>The Compatibility Test Suite (CTS) tests significant portions of the
+platform for behavioral compatibility, but not all. It is the responsibility
+of the implementer to ensure behavioral compatibility with the Android Open
+Source Project.</p>
+
+<h3>3.6. API Namespaces</h3>
+<p>Android follows the package and class namespace conventions defined by the
+Java programming language. To ensure compatibility with third-party
+applications, device implementers MUST NOT make any prohibited modifications
+(see below) to these package namespaces:</p>
+<ul>
+<li>java.*</li>
+<li>javax.*</li>
+<li>sun.*</li>
+<li>android.*</li>
+<li>com.android.*</li>
+</ul>
+<p>Prohibited modifications include:</p>
+<ul>
+<li>Device implementations MUST NOT modify the publicly exposed APIs on the
+Android platform by changing any method or class signatures, or by removing
+classes or class fields.</li>
+<li>Device implementers MAY modify the underlying implementation of the APIs,
+but such modifications MUST NOT impact the stated behavior and Java-language
+signature of any publicly exposed APIs.</li>
+<li>Device implementers MUST NOT add any publicly exposed elements (such as
+classes or interfaces, or fields or methods to existing classes or interfaces)
+to the APIs above.</li>
+</ul>
+<p>A "publicly exposed element" is any construct which is not decorated with
+the "@hide" marker in the upstream Android source code. In other words, device
+implementers MUST NOT expose new APIs or alter existing APIs in the namespaces
+noted above. Device implementers MAY make internal-only modifications, but
+those modifications MUST NOT be advertised or otherwise exposed to
+developers.</p>
+<p>Device implementers MAY add custom APIs, but any such APIs MUST NOT be in a
+namespace owned by or referring to another organization. For instance, device
+implementers MUST NOT add APIs to the com.google.* or similar namespace; only
+Google may do so. Similarly, Google MUST NOT add APIs to other companies'
+namespaces.</p>
+<p>If a device implementer proposes to improve one of the package namespaces
+above (such as by adding useful new functionality to an existing API, or
+adding a new API), the implementer SHOULD visit source.android.com and begin
+the process for contributing changes and code, according to the information on
+that site.</p>
+<p>Note that the restrictions above correspond to standard conventions for
+naming APIs in the Java programming language; this section simply aims to
+reinforce those conventions and make them binding through inclusion in this
+compatibility definition.</p>
+
+<h3>3.7. Virtual Machine Compatibility</h3>
+<p>Device implementations MUST support the full Dalvik Executable (DEX)
+bytecode specification and Dalvik Virtual Machine semantics [<a
+href="#resources10">Resources, 10</a>].</p>
+<p>Device implementations MUST configure Dalvik to allocate at least 16MB of
+memory to each application on devices with screens classified as medium- or
+low-density. Device implementations MUST configure Dalvik to allocate at least
+24MB of memory to each application on devices with screens classified as
+high-density. Note that device implementations MAY allocate more memory than
+these figures, but are not required to.</p>
+
+<h3>3.8. User Interface Compatibility</h3>
+<p>The Android platform includes some developer APIs that allow developers to
+hook into the system user interface. Device implementations MUST incorporate
+these standard UI APIs into custom user interfaces they develop, as explained
+below.</p>
+<h4>3.8.1. Widgets</h4>
+<p>Android defines a component type and corresponding API and lifecycle that
+allows applications to expose an "AppWidget" to the end user [<a
+href="#resources11">Resources, 11</a>].
+The Android Open Source reference release includes a Launcher application that
+includes user interface elements allowing the user to add, view, and remove
+AppWidgets from the home screen.</p>
+<p>Device implementers MAY substitute an alternative to the reference Launcher
+(i.e. home screen). Alternative Launchers SHOULD include built-in support for
+AppWidgets, and expose user interface elements to add, configure, view, and remove
+AppWidgets directly within the Launcher. Alternative Launchers MAY omit these
+user interface elements; however, if they are omitted, the device implementer
+MUST provide a separate application accessible from the Launcher that allows
+users to add, configure, view, and remove AppWidgets.</p>
+<h4>3.8.2. Notifications</h4>
+<p>Android includes APIs that allow developers to notify users of notable
+events [<a href="#resources12">Resources, 12</a>]. Device implementers MUST provide support for each
+class of notification so defined; specifically: sounds, vibration, light and
+status bar.</p>
+<p>Additionally, the implementation MUST correctly render all resources
+(icons, sound files, etc.) provided for in the APIs [<a
+href="#resources13">Resources, 13</a>], or in the
+Status Bar icon style guide [<a href="#resources14">Resources, 14</a>]. Device implementers MAY provide
+an alternative user experience for notifications than that provided by the
+reference Android Open Source implementation; however, such alternative
+notification systems MUST support existing notification resources, as
+above.</p>
+<h4>3.8.3. Search</h4>
+<p>Android includes APIs [<a href="#resources15">Resources, 15</a>] that allow developers to incorporate
+search into their applications, and expose their application's data into the
+global system search. Generally speaking, this functionality consists of a
+single, system-wide user interface that allows users to enter queries,
+displays suggestions as users type, and displays results. The Android APIs
+allow developers to reuse this interface to provide search within their own
+apps, and allow developers to supply results to the common global search user
+interface.</p>
+<p>Device implementations MUST include a single, shared, system-wide search
+user interface capable of real-time suggestions in response to user input.
+Device implementations MUST implement the APIs that allow developers to reuse
+this user interface to provide search within their own applications. Device
+implementations MUST implement the APIs that allow third-party applications to
+add suggestions to the search box when it is run in global search mode. If no
+third-party applications are installed that make use of this functionality,
+the default behavior SHOULD be to display web search engine results and
+suggestions.</p>
+<p>Device implementations MAY ship alternate search user interfaces, but
+SHOULD include a hard or soft dedicated search button, that can be used at any
+time within any app to invoke the search framework, with the behavior provided
+for in the API documentation.</p>
+<h4>3.8.4. Toasts</h4>
+<p>Applications can use the "Toast" API (defined in [<a
+href="#resources16">Resources, 16</a>]) to
+display short non-modal strings to the end user, that disappear after a brief
+period of time. Device implementations MUST display Toasts from applications
+to end users in some high-visibility manner.</p>
+<h4>3.8.5. Live Wallpapers</h4>
+<p>Android defines a component type and corresponding API and lifecycle that
+allows applications to expose one or more "Live Wallpapers" to the end user
+[<a href="#resources17">Resources, 17</a>]. Live Wallpapers are animations,
+patterns, or similar images with limited input capabilities that display as a
+wallpaper, behind other applications.</p>
+<p>Hardware is considered capable of reliably running live wallpapers if it
+can run all live wallpapers, with no limitations on functionality, at a
+reasonable framerate with no adverse affects on other applications. If
+limitations in the hardware cause wallpapers and/or applications to crash,
+malfunction, consume excessive CPU or battery power, or run at unacceptably
+low frame rates, the hardware is considered incapable of running live
+wallpaper. As an example, some live wallpapers may use an Open GL 1.0 or 2.0
+context to render their content. Live wallpaper will not run reliably on
+hardware that does not support multiple OpenGL contexts because the live
+wallpaper use of an OpenGL context may conflict with other applications that
+also use an OpenGL context. </p>
+<p>Device implemenations capable of running live wallpapers reliably as
+described above SHOULD implement live wallpapers. Device implementations
+determined to not run live wallpapers reliably as described above MUST NOT
+implement live wallpapers.</p>
+
+<h2>4. Reference Software Compatibility</h2>
+<p>Device implementers MUST test implementation compatibility using the
+following open-source applications:</p>
+<ul>
+<li>Calculator (included in SDK)</li>
+<li>Lunar Lander (included in SDK)</li>
+<li>The "Apps for Android" applications [<a href="#resources18">Resources, 18</a>].</li>
+</ul>
+<p>Each app above MUST launch and behave correctly on the implementation, for
+the implementation to be considered compatible.</p>
+<p>Additionally, device implementations MUST test each menu item (including all
+sub-menus) of each of these smoke-test applications:</p>
+<ul>
+<li>ApiDemos (included in SDK)</li>
+<li>ManualSmokeTests (included in CTS)</li>
+</ul>
+<p>Each test case in the applications above MUST run correctly on the device
+implementation.</p>
+
+<h2>5. Application Packaging Compatibility</h2>
+<p>Device implementations MUST install and run Android ".apk" files as
+generated by the "aapt" tool included in the official Android SDK [<a
+href="#resources19">Resources, 19</a>].</p>
+<p>Devices implementations MUST NOT extend either the .apk [<a
+href="#resources20">Resources, 20</a>], Android Manifest [<a
+href="#resources21">Resources, 21</a>],
+or Dalvik bytecode [<a href="#resources10">Resources, 10</a>] formats in such
+a way that would prevent those files from
+installing and running correctly on other compatible devices. Device
+implementers SHOULD use the reference upstream implementation of Dalvik, and
+the reference implementation's package management system.</p>
+
+<h2>6. Multimedia Compatibility</h2>
+<p>Device implemenations MUST support the following multimedia codecs. All of
+these codecs are provided as software implementations in the preferred Android
+implementation from the Android Open Source Project.</p>
+<p>Please note that neither Google nor the Open Handset Alliance make any
+representation that these codecs are unencumbered by third-party patents.
+Those intending to use this source code in hardware or software products are
+advised that implementations of this code, including in open source software
+or shareware, may require patent licenses from the relevant patent
+holders.</p>
+<table><tbody>
+<tr>
+<td rowspan="11"><b>Audio</b></td>
+</tr>
+<tr>
+<td><b>Name</b></td>
+<td><b>Encoder</b></td>
+<td><b>Decoder</b></td>
+<td><b>Details</b></td>
+<td><b>File/Container Format</b></td>
+</tr>
+<tr>
+<td>AAC LC/LTP</td>
+<td> </td>
+<td>X</td>
+<td rowspan="3">Mono/Stereo content in any combination of standard bit rates up to 160 kbps and sampling rates between 8 to 48kHz</td>
+<td rowspan="3">3GPP (.3gp) and MPEG-4 (.mp4, .m4a). No support for raw AAC (.aac)</td>
+</tr>
+<tr>
+<td>HE-AACv1 (AAC+)</td>
+<td> </td>
+<td>X</td>
+</tr>
+<tr>
+<td>HE-AACv2 (enhanced AAC+)</td>
+<td> </td>
+<td>X</td>
+</tr>
+<tr>
+<td>AMR-NB</td>
+<td>X</td>
+<td>X</td>
+<td>4.75 to 12.2 kbps sampled @ 8kHz</td>
+<td>3GPP (.3gp)</td>
+</tr>
+<tr>
+<td>AMR-WB</td>
+<td> </td>
+<td>X</td>
+<td>9 rates from 6.60 kbit/s to 23.85 kbit/s sampled @ 16kHz</td>
+<td>3GPP (.3gp)</td>
+</tr>
+<tr>
+<td>MP3</td>
+<td> </td>
+<td>X</td>
+<td>Mono/Stereo 8-320Kbps constant (CBR) or variable bit-rate (VBR)</td>
+<td>MP3 (.mp3)</td>
+</tr>
+<tr>
+<td>MIDI</td>
+<td> </td>
+<td>X</td>
+<td>MIDI Type 0 and 1. DLS Version 1 and 2. XMF and Mobile XMF. Support for ringtone formats RTTTL/RTX, OTA, and iMelody</td>
+<td>Type 0 and 1 (.mid, .xmf, .mxmf). Also RTTTL/RTX (.rtttl, .rtx), OTA (.ota), and iMelody (.imy)</td>
+</tr>
+<tr>
+<td>Ogg Vorbis</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td>Ogg (.ogg)</td>
+</tr>
+<tr>
+<td>PCM</td>
+<td> </td>
+<td>X</td>
+<td>8- and 16-bit linear PCM (rates up to limit of hardware)</td>
+<td>WAVE (.wav)</td>
+</tr>
+<tr>
+<td rowspan="5"><b>Image</b></td>
+</tr>
+<tr>
+<td>JPEG</td>
+<td>X</td>
+<td>X</td>
+<td>base+progressive</td>
+<td> </td>
+</tr>
+<tr>
+<td>GIF</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+<tr>
+<td>PNG</td>
+<td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+<tr>
+<td>BMP</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+<tr>
+<td rowspan="4"><b>Video</b></td>
+</tr>
+<tr>
+<td>H.263</td>
+<td>X</td>
+<td>X</td>
+<td> </td>
+<td>3GPP (.3gp) files</td>
+</tr>
+<tr>
+<td>H.264</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td>3GPP (.3gp) and MPEG-4 (.mp4) files</td>
+</tr>
+<tr>
+<td>MPEG4 Simple Profile</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td>3GPP (.3gp) file</td>
+</tr>
+</tbody>
+</table>
+<p>Note that the table above does not list specific bitrate requirements for
+most video codecs. The reason for this is that in practice, current device
+hardware does not necessarily support bitrates that map exactly to the
+required bitrates specified by the relevant standards. Instead, device
+implementations SHOULD support the highest bitrate practical on the hardware,
+up to the limits defined by the specifications.</p>
+
+<h2>7. Developer Tool Compatibility</h2>
+<p>Device implemenations MUST support the Android Developer Tools provided in
+the Android SDK. Specifically, Android-compatible devices MUST be compatible
+with:</p>
+<ul>
+<li><b>Android Debug Bridge (known as adb)</b> [<a href="#resources19">Resources, 19</a>]<br/>
+Device implementations MUST support all <code>adb</code> functions as
+documented in the Android SDK. The device-side <code>adb</code> daemon SHOULD
+be inactive by default, but there MUST be a user-accessible mechanism to turn
+on the Android Debug Bridge.</li>
+<li><b>Dalvik Debug Monitor Service (known as ddms)</b> [<a href="#resources19">Resources, 19</a>]<br/>
+Device implementations MUST support all <code>ddms</code> features as documented in the
+Android SDK. As <code>ddms</code> uses <code>adb</code>, support for
+<code>ddms</code> SHOULD be inactive by default,
+but MUST be supported whenever the user has activated the Android Debug
+Bridge, as above.</li>
+<li><b>Monkey</b> [<a href="#resources22">Resources, 22</a>]<br/>
+Device implementations MUST include the Monkey framework, and make it
+available for applications to use.</li>
+</ul>
+
+<h2>8. Hardware Compatibility</h2>
+<p>Android is intended to support device implementers creating innovative form
+factors and configurations. At the same time Android developers expect
+certain hardware, sensors and APIs across all Android device. This section
+lists the hardware features that all Android 2.1 compatible devices must
+support.</p>
+<p>If a device includes a particular hardware component that has a
+corresponding API for third-party developers, the device implementation MUST
+implement that API as defined in the Android SDK documentation. If an API in
+the SDK interacts with a hardware component that is stated to be optional and the device
+implementation does not possess that component:</p>
+<ul>
+<li>class definitions for the component's APIs MUST be present</li>
+<li>the API's behaviors MUST be implemented as no-ops in some reasonable fashion</li>
+<li>API methods MUST return null values where permitted by the SDK documentation</li>
+<li>API methods MUST return no-op implementations of classes where null values are not permitted by the SDK documentation</li>
+</ul>
+<p>A typical example of a scenario where these requirements apply is the
+telephony API: even on non-phone devices, these APIs must be implemented as
+reasonable no-ops.</p>
+<p>Device implementations MUST accurate report accurate hardware configuration
+information via the <code>getSystemAvailableFeatures()</code> and
+<code>hasSystemFeature(String)</code> methods on the
+<code>android.content.pm.PackageManager</code> class.</p>
+
+<h3>8.1. Display</h3>
+<p>Android 2.1 includes facilities that perform certain automatic scaling and
+transformation operations under some circumstances, to ensure that third-party
+applications run reasonably well on a variety of hardware configurations [<a
+href="#resources23">Resources, 23</a>]. Devices MUST properly implement these
+behaviors, as detailed in this section.</p>
+<p>For Android 2.1, this are the most common display configurations:</p>
+<table><tbody>
+<tr>
+<td>Screen Type</td>
+<td>Width (Pixels)</td>
+<td>Height (Pixels)</td>
+<td>Diagonal Length Range (inches)</td>
+<td>Screen Size Group</td>
+<td>Screen Density Group</td>
+</tr>
+<tr>
+<td>QVGA</td>
+<td>240</td>
+<td>320</td>
+<td>2.6 - 3.0</td>
+<td>Small</td>
+<td>Low</td>
+</tr>
+<tr>
+<td>WQVGA</td>
+<td>240</td>
+<td>400</td>
+<td>3.2 - 3.5</td>
+<td>Normal</td>
+<td>Low</td>
+</tr>
+<tr>
+<td>FWQVGA</td>
+<td>240</td>
+<td>432</td>
+<td>3.5 - 3.8</td>
+<td>Normal</td>
+<td>Low</td>
+</tr>
+<tr>
+<td>HVGA</td>
+<td>320</td>
+<td>480</td>
+<td>3.0 - 3.5</td>
+<td>Normal</td>
+<td>Medium</td>
+</tr>
+<tr>
+<td>WVGA</td>
+<td>480</td>
+<td>800</td>
+<td>3.3 - 4.0</td>
+<td>Normal</td>
+<td>High</td>
+</tr>
+<tr>
+<td>FWVGA</td>
+<td>480</td>
+<td>854</td>
+<td>3.5 - 4.0</td>
+<td>Normal</td>
+<td>High</td>
+</tr>
+<tr>
+<td>WVGA </td>
+<td>480 </td>
+<td>800 </td>
+<td>4.8 - 5.5 </td>
+<td>Large </td>
+<td>Medium</td>
+</tr>
+<tr>
+<td>FWVGA</td>
+<td>480</td>
+<td>854</td>
+<td>5.0 - 5.8</td>
+<td>Large</td>
+<td>Medium</td>
+</tr>
+</tbody></table>
+
+<p>Device implementations corresponding to one of the standard configurations
+above MUST be configured to report the indicated screen size to applications
+via the <code>android.content.res.Configuration</code> [<a href="#resources24">Resources,
+24</a>] class.</p>
+<p>Some .apk packages have manifests that do not identify them as supporting a
+specific density range. When running such applications, the following
+constraints apply:</p>
+<ul>
+<li>Device implementations MUST interpret resources in a .apk that lack a
+density qualifier as defaulting to "medium" (known as "mdpi" in the SDK
+documentation.)</li>
+<li>When operating on a "low" density screen, device implementations MUST
+scale down medium/mdpi assets by a factor of 0.75.</li>
+<li>When operating on a "high" density screen, device implementations MUST
+scale up medium/mdpi assets by a factor of 1.5.</li>
+<li>Device implementations MUST NOT scale assets within a density range, and
+MUST scale assets by exactly these factors between density ranges.</li>
+</ul>
+
+<h4>8.1.2. Non-Standard Display Configurations</h4>
+<p>Display configurations that do not match one of the standard configurations
+listed in Section 8.1.1 require additional consideration and work to be
+compatible. Device implementers MUST contact Android Compatibility Team as
+provided for in Section 12 to obtain classifications for screen-size bucket,
+density, and scaling factor. When provided with this information, device
+implementations MUST implement them as specified.</p>
+<p>Note that some display configurations (such as very large or very small
+screens, and some aspect ratios) are fundamentally incompatible with Android
+2.1; therefore device implementers are encouraged to contact Android
+Compatibility Team as early as possible in the development process.</p>
+<h4>8.1.3. Display Metrics</h4>
+<p>Device implementations MUST report correct valuesfor all display metrics
+defined in <code>android.util.DisplayMetrics</code> [<a
+href="#resources25">Resources, 25</a>].</p>
+
+<h3>8.2. Keyboard</h3>
+<p>Device implementations:</p>
+<ul>
+<li>MUST include support for the Input Management Framework (which allows third party developers to create Input Management Engines -- i.e. soft keyboard) as detailed at developer.android.com</li>
+<li>MUST provide at least one soft keyboard implementation (regardless of whether a hard keyboard is present)</li>
+<li>MAY include additional soft keyboard implementations</li>
+<li>MAY include a hardware keyboard</li>
+<li>MUST NOT include a hardware keyboard that does not match one of the
+formats specified in <code>android.content.res.Configuration.keyboard</code>
+[<a href="#resources24">Resources, 24</a>] (that is, QWERTY, or 12-key)</li>
+</ul>
+<h3>8.3. Non-touch Navigation</h3>
+<p>Device implementations:</p>
+<ul>
+<li>MAY omit a non-touch navigation options (that is, may omit a trackball, d-pad, or wheel)</li>
+<li>MUST report the correct value for
+<code>android.content.res.Configuration.navigation</code> [<a href="#resources24">Resources, 24</a>]</li>
+</ul>
+<h3>8.4. Screen Orientation</h3>
+<p>Compatible devices MUST support dynamic orientation by applications to
+either portrait or landscape screen orientation. That is, the device must
+respect the application's request for a specific screen orientation. Device
+implementations MAY select either portrait or landscape orientation as the
+default.</p>
+<p>Devices MUST report the correct value for the device's current orientation,
+whenever queried via the android.content.res.Configuration.orientation,
+android.view.Display.getOrientation(), or other APIs.</p>
+
+<h3>8.5. Touchscreen input</h3>
+<p>Device implementations:</p>
+<ul>
+<li>MUST have a touchscreen</li>
+<li>MAY have either capacative or resistive touchscreen</li>
+<li>MUST report the value of <code>android.content.res.Configuration</code>
+[<a href="#resources24">Resources, 24</a>]
+reflecting corresponding to the type of the specific touchscreen on the
+device</li>
+</ul>
+
+<h3>8.6. USB</h3>
+<p>Device implementations:</p>
+<ul>
+<li>MUST implement a USB client, connectable to a USB host with a standard
+USB-A port</li>
+<li>MUST implement the Android Debug Bridge over USB (as described in Section
+7)</li>
+<li>MUST implement the USB mass storage specification, to allow a host
+connected to the device to access the contents of the /sdcard volume </li>
+<li>SHOULD use the micro USB form factor on the device side</li>
+<li>MAY include a non-standard port on the device side, but if so MUST ship
+with a cable capable of connecting the custom pinout to standard USB-A
+port</li>
+</ul>
+
+<h3>8.7. Navigation keys</h3>
+<p>The Home, Menu and Back functions are essential to the Android navigation
+paradigm. Device implementations MUST make these functions available to the
+user at all times, regardless of application state. These functions SHOULD be
+implemented via dedicated buttons. They MAY be implemented using software,
+gestures, touch panel, etc., but if so they MUST be always accessible and not
+obscure or interfere with the available application display area.</p>
+<p>Device implementers SHOULD also provide a dedicated search key. Device
+implementers MAY also provide send and end keys for phone calls.</p>
+
+<h3>8.8. Wireless Data Networking</h3>
+<p>Device implementations MUST include support for wireless high-speed data
+networking. Specifically, device implementations MUST include support for at
+least one wireless data standard capable of 200Kbit/sec or greater. Examples of
+technologies that satisfy this requirement include EDGE, HSPA, EV-DO, 802.11g, etc.</p>
+<p>If a device implementation includes a particular modality for which the
+Android SDK includes an API (that is, WiFi, GSM, or CDMA), the implementation
+MUST support the API.</p>
+<p>Devices MAY implement more than one form of wireless data connectivity.
+Devices MAY implement wired data connectivity (such as Ethernet), but MUST
+nonetheless include at least one form of wireless connectivity, as above.</p>
+<h3>8.9. Camera</h3>
+<p>Device implementations MUST include a camera. The included camera:</p>
+<ul>
+<li>MUST have a resolution of at least 2 megapixels</li>
+<li>SHOULD have either hardware auto-focus, or software auto-focus implemented
+in the camera driver (transparent to application software)</li>
+<li>MAY have fixed-focus or EDOF (extended depth of field) hardware</li>
+<li>MAY include a flash. If the Camera includes a flash, the flash lamp MUST
+NOT be lit while an android.hardware.Camera.PreviewCallback instance has been
+registered on a Camera preview surface, unless the application has explicitly
+enabled the flash by enabling the <code>FLASH_MODE_AUTO</code> or
+<code>FLASH_MODE_ON</code> attributes of a <code>Camera.Parameters</code>
+object. Note that this constraint does not apply to the device's built-in
+system camera application, but only to third-party applications using
+<code>Camera.PreviewCallback</code>.</li>
+</ul>
+<p>Device implementations MUST implement the following behaviors for the
+camera-related APIs:</p>
+<ol>
+<li>If an application has never called
+android.hardware.Camera.Parameters.setPreviewFormat(int), then the device MUST
+use android.hardware.PixelFormat.YCbCr_420_SP for preview data provided to
+application callbacks.</li>
+<li>If an application registers an android.hardware.Camera.PreviewCallback
+instance and the system calls the onPreviewFrame() method when the preview
+format is YCbCr_420_SP, the data in the byte[] passed into onPreviewFrame()
+must further be in the NV21 encoding format. (This is the format used natively
+by the 7k hardware family.) That is, NV21 MUST be the default.</li>
+</ol>
+<p>Device implementations MUST implement the full Camera API included in the
+Android 2.1 SDK documentation [<a href="#resources26">Resources, 26</a>]),
+regardless of whether the device includes hardware autofocus or other
+capabilities. For instance, cameras that lack autofocus MUST still call any
+registered <code>android.hardware.Camera.AutoFocusCallback</code> instances (even though
+this has no relevance to a non-autofocus camera.)</p>
+<p>Device implementations MUST recognize and honor each parameter name defined
+as a constant on the <code>android.hardware.Camera.Parameters</code> class, if the
+underlying hardware supports the feature. If the device hardware does not
+support a feature, the API must behave as documented. Conversely, Device
+implementations MUST NOT honor or recognize string constants passed
+to the <code>android.hardware.Camera.setParameters()</code> method other than
+those documented as constants on the
+<code>android.hardware.Camera.Parameters</code>, unless the constants are
+prefixed with a string indicating the name of the device implementer. That is,
+device implementations MUST support all standard Camera parameters if the
+hardware allows, and MUST NOT support custom Camera parameter types unless
+the parameter names are clearly indicated via a string prefix to be non-standard.</p>
+
+<h3>8.10. Accelerometer</h3>
+<p>Device implementations MUST include a 3-axis accelerometer and MUST be able
+to deliver events at 50 Hz or greater. The coordinate system used by the
+accelerometer MUST comply with the Android sensor coordinate system as detailed
+in the Android APIs (see [<a href="#resources27">Resources, 27</a>]).</p>
+
+<h3>8.11. Compass</h3>
+<p>Device implementations MUST include a 3-axis compass and MUST be able to
+deliver events 10 Hz or greater. The coordinate system used by the compass
+MUST comply with the Android sensor coordinate system as defined in the Android
+API (see [<a href="#resources27">Resources, 27</a>]).</p>
+
+<h3>8.12. GPS</h3>
+<p>Device implementations MUST include a GPS, and SHOULD include some form of
+"assisted GPS" technique to minimize GPS lock-on time.</p>
+
+<h3>8.13. Telephony</h3>
+<p>Android 2.1 MAY be used on devices that do not include telephony hardware.
+That is, Android 2.1 is compatible with devices that are not phones.
+However, if a device implementation does include GSM or CDMA telephony, it
+MUST implement the full support for the API for that technology. Device
+implementations that do not include telephony hardware MUST implement the full
+APIs as no-ops.</p>
+<p>See also Section 8.8, Wireless Data Networking.</p>
+
+<h3>8.14. Memory and Storage</h3>
+<p>Device implementations MUST have at least 92MB of memory available to the
+kernel and userspace. The 92MB MUST be in addition to any memory dedicated to
+hardware components such as radio, memory, and so on that is not under the
+kernel's control.</p>
+<p>Device implementations MUST have at least 150MB of non-volatile storage
+available for user data. That is, the <code>/data</code> partition must be at
+least 150MB.</p>
+<div class="cdd-erratum">Note: this section was modified by Erratum EX6580.</div>
+
+<h3>8.15. Application Shared Storage</h3>
+<p>Device implementations MUST offer shared storage for applications. The
+shared storage provided MUST be at least 2GB in size.</p>
+<p>Device implementations MUST be configured with shared storage mounted by
+default, "out of the box". If the shared storage is not mounted on the Linux
+path <code>/sdcard</code>, then the device MUST include a Linux symbolic link
+from <code>/sdcard</code> to the actual mount point.</p>
+<p>Device implementations MUST enforce as documented the
+<code>android.permission.WRITE_EXTERNAL_STORAGE</code> permission on this
+shared storage. Shared storage MUST otherwise be writable by any application
+that obtains that permission.</p>
+<p>Device implementations MAY have hardware for user-accessible removable
+storage, such as a Secure Digital card. Alternatively, device implementations
+MAY allocate internal (non-removable) storage as shared storage for apps.</p>
+<p>Regardless of the form of shared storage used, the shared storage MUST
+implement USB mass storage, as described in Section 8.6. As shipped out of the
+box, the shared storage MUST be mounted with the FAT filesystem.</p>
+<p>It is illustrative to consider two common examples. If a device
+implementation includes an SD card slot to satisfy the shared storage
+requirement, a FAT-formatted SD card 2GB in size or larger MUST be included
+with the device as sold to users, and MUST be mounted by default.
+Alternatively, if a device implementation uses internal fixed storage to
+satisfy this requirement, that storage MUST be 2GB in size or larger and
+mounted on <code>/sdcard</code> (or <code>/sdcard</code> MUST be a symbolic
+link to the physical location if it is mounted elsewhere.)</p>
+<div class="cdd-erratum">Note: this section was added by Erratum EX6580.</div>
+
+<h3>8.16. Bluetooth</h3>
+<p>Device implementations MUST include a Bluetooth transceiver. Device
+implementations MUST enable the RFCOMM-based Bluetooth API as described in the
+SDK documentation [<a href="#resources29">Resources, 29</a>]. Device
+implementations SHOULD implement relevant Bluetooth profiles, such as A2DP,
+AVRCP, OBEX, etc. as appropriate for the device.</p>
+<div class="cdd-erratum">Note: this section was added by Erratum EX6580.</div>
+
+<h2>9. Performance Compatibility</h2>
+<p>One of the goals of the Android Compatibility Program is to enable
+consistent application experience to consumers. Compatible implementations
+must ensure not only that applications simply run correctly on the device, but
+that they do so with reasonable performance and overall good user experience.
+Device implementations MUST meet the key performance metrics of an Android 2.1
+compatible device defined in the table below:</p>
+<table><tbody><tr>
+<td><b>Metric</b></td>
+<td><b>Performance Threshold</b></td>
+<td><b>Comments</b></td>
+</tr>
+<tr>
+<td>Application Launch Time</td>
+<td>The following applications should launch within the specified time.<ul>
+<li>Browser: less than 1300ms</li>
+<li>MMS/SMS: less than 700ms</li>
+<li>AlarmClock: less than 650ms</li>
+</ul></td>
+<td>The launch time is measured as the total time to
+complete loading the default activity for the application, including the time
+it takes to start the Linux process, load the Android package into the Dalvik
+VM, and call onCreate.</td>
+</tr>
+<tr>
+<td>Simultaneous Applications</td>
+<td>When multiple applications have been launched, re-launching an
+already-running application after it has been launched must take less than the
+original launch time.</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+
+<h2>10. Security Model Compatibility</h2>
+<p>Device implementations MUST implement a security model consistent with the
+Android platform security model as defined in Security and Permissions
+reference document in the APIs [<a href="#resources28">Resources, 28</a>] in the
+Android developer documentation. Device implementations MUST support
+installation of self-signed applications without requiring any additional
+permissions/certificates from any third parties/authorities. Specifically,
+compatible devices MUST support the security mechanisms described in the
+follow sub-sections.</p>
+<h3>10.1. Permissions</h3>
+<p>Device implementations MUST support the Android permissions model as
+defined in the Android developer documentation [<a
+href="#resources28">Resources, 28</a>]. Specifically,
+implementations MUST enforce each permission defined as described in the SDK
+documentation; no permissions may be omitted, altered, or ignored.
+Implementations MAY add additional permissions, provided the new permission ID
+strings are not in the android.* namespace.</p>
+<h3>10.2. UID and Process Isolation</h3>
+<p>Device implementations MUST support the Android application sandbox model,
+in which each application runs as a unique Unix-style UID and in a separate
+process. Device implementations MUST support running multiple applications as
+the same Linux user ID, provided that the applications are properly signed and
+constructed, as defined in the Security and Permissions reference [<a
+href="#resources28">Resources, 28</a>].</p>
+<h3>10.3. Filesystem Permissions</h3>
+<p>Device implementations MUST support the Android file access permissions
+model as defined in as defined in the Security and Permissions reference [<a
+href="#resources28">Resources, 28</a>].</p>
+
+<h2>11. Compatibility Test Suite</h2>
+<p>Device implementations MUST pass the Android Compatibility Test Suite (CTS)
+[<a href="#resources02">Resources, 2</a>] available from the Android Open Source
+Project, using the final shipping software on the device. Additionally, device
+implementers SHOULD use the reference implementation in the Android Open
+Source tree as much as possible, and MUST ensure compatibility in cases of
+ambiguity in CTS and for any reimplementations of parts of the reference
+source code.</p>
+<p>The CTS is designed to be run on an actual device. Like any software, the
+CTS may itself contain bugs. The CTS will be versioned independently of this
+Compatibility Definition, and multiple revisions of the CTS may be released
+for Android 2.1. Device implementations MUST pass the latest CTS version
+available at the time the device software is completed.</p>
+
+<h2>12. Updatable Software</h2>
+<p>Device implementations MUST include a mechanism to replace the entirety of
+the system software. The mechanism need not perform "live" upgrades -- that
+is, a device restart MAY be required.</p>
+<p>Any method can be used, provided that it can replace the entirety of the
+software preinstalled on the device. For instance, any of the following
+approaches will satisfy this requirement:</p>
+<ul>
+<li>Over-the-air (OTA) downloads with offline update via reboot</li>
+<li>"Tethered" updates over USB from a host PC</li>
+<li>"Offline" updates via a reboot and update from a file on removable
+storage</li>
+</ul>
+<p>The update mechanism used MUST support updates without wiping user data.
+Note that the upstream Android software includes an update mechanism that
+satisfies this requirement.</p>
+<p>If an error is found in a device implementation after it has been released
+but within its reasonable product lifetime that is determined in consultation
+with the Android Compatibility Team to affect the compatibility of thid-party
+applications, the device implementer MUST correct the error via a software
+update available that can be applied per the mechanism just described.</p>
+
+<h2>13. Contact Us</h2>
+<p>You can contact the document authors at <a
+href="mailto:compatibility@android.com">compatibility@android.com</a> for
+clarifications and to bring up any issues that you think the document does not
+cover.</p>
+</body>
+</html>
diff --git a/src/compatibility/2.2/android-2.2-cdd.xhtml b/src/compatibility/2.2/android-2.2-cdd.xhtml
new file mode 100644
index 0000000..c486dc9
--- /dev/null
+++ b/src/compatibility/2.2/android-2.2-cdd.xhtml
@@ -0,0 +1,1515 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>Android 2.2 Compatibility Definition</title>
+<link rel="stylesheet" type="text/css" href="cdd.css"/>
+</head>
+<body>
+<div><img src="header.jpg" alt="Android logo"/></div>
+<h1>Android 2.2 Compatibility Definition</h1>
+<!--<span style="color: red; font-weight: bold;"><h2>DRAFT</h2></span>-->
+<p>Copyright © 2010, Google Inc. All rights reserved.<br/>
+<a href="mailto:compatibility@android.com">compatibility@android.com</a>
+</p>
+
+<h2> Table of Contents</h2>
+<div style="margin-left: 2em;">
+ <a href="#section-1">1. Introduction</a><br/>
+ <a href="#section-2">2. Resources</a><br/>
+ <a href="#section-3">3. Software</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.1">3.1. Managed API Compatibility</a><br/>
+ <a href="#section-3.2">3.2. Soft API Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.2.1">3.2.1. Permissions</a><br/>
+ <a href="#section-3.2.2">3.2.2. Build Parameters</a><br/>
+ <a href="#section-3.2.3">3.2.3. Intent Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.2.3.1">3.2.3.1. Core Application Intents</a><br/>
+ <a href="#section-3.2.3.2">3.2.3.2. Intent Overrides</a><br/>
+ <a href="#section-3.2.3.3">3.2.3.3. Intent Namespaces</a><br/>
+ <a href="#section-3.2.3.4">3.2.3.4. Broadcast Intents</a><br/>
+ </div>
+ </div>
+ <a href="#section-3.3">3.3. Native API Compatibility</a><br/>
+ <a href="#section-3.4">3.4. Web Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.4.1">3.4.1. WebView Compatibility</a><br/>
+ <a href="#section-3.4.2">3.4.2. Browser Compatibility</a><br/>
+ </div>
+ <a href="#section-3.5">3.5. API Behavioral Compatibility</a><br/>
+ <a href="#section-3.6">3.6. API Namespaces</a><br/>
+ <a href="#section-3.7">3.7. Virtual Machine Compatibility</a><br/>
+ <a href="#section-3.8">3.8. User Interface Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.8.1">3.8.1. Widgets</a><br/>
+ <a href="#section-3.8.2">3.8.2. Notifications</a><br/>
+ <a href="#section-3.8.3">3.8.3. Search</a><br/>
+ <a href="#section-3.8.4">3.8.4. Toasts</a><br/>
+ <a href="#section-3.8.5">3.8.5. Live Wallpapers</a><br/>
+ </div>
+ </div>
+ <a href="#section-4">4. Reference Software Compatibility</a><br/>
+ <a href="#section-5">5. Application Packaging Compatibility</a><br/>
+ <a href="#section-6">6. Multimedia Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-6.1">6.1. Media Codecs</a><br/>
+ <a href="#section-6.2">6.2. Audio Recording</a><br/>
+ <a href="#section-6.3">6.3. Audio Latency</a><br/>
+ </div>
+ <a href="#section-7">7. Developer Tool Compatibility</a><br/>
+ <a href="#section-8">8. Hardware Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-8.1">8.1. Display</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-8.1.2">8.1.2. Non-Standard Display Configurations</a><br/>
+ <a href="#section-8.1.3">8.1.3. Display Metrics</a><br/>
+ <a href="#section-8.1.4">8.1.4. Declared Screen Support</a><br/>
+ </div>
+ <a href="#section-8.2">8.2. Keyboard</a><br/>
+ <a href="#section-8.3">8.3. Non-touch Navigation</a><br/>
+ <a href="#section-8.4">8.4. Screen Orientation</a><br/>
+ <a href="#section-8.5">8.5. Touchscreen input</a><br/>
+ <a href="#section-8.6">8.6. USB</a><br/>
+ <a href="#section-8.7">8.7. Navigation keys</a><br/>
+ <a href="#section-8.8">8.8. Wireless Data Networking</a><br/>
+ <a href="#section-8.9">8.9. Camera</a><br/>
+ <a href="#section-8.10">8.10. Accelerometer</a><br/>
+ <a href="#section-8.11">8.11. Compass</a><br/>
+ <a href="#section-8.12">8.12. GPS</a><br/>
+ <a href="#section-8.13">8.13. Telephony</a><br/>
+ <a href="#section-8.14">8.14. Memory and Storage</a><br/>
+ <a href="#section-8.15">8.15. Application Shared Storage</a><br/>
+ <a href="#section-8.16">8.16. Bluetooth</a><br/>
+ </div>
+ <a href="#section-9">9. Performance Compatibility</a><br/>
+ <a href="#section-10">10. Security Model Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-10.1">10.1. Permissions</a><br/>
+ <a href="#section-10.2">10.2. UID and Process Isolation</a><br/>
+ <a href="#section-10.3">10.3. Filesystem Permissions</a><br/>
+ <a href="#section-10.4">10.4. Alternate Execution Environments</a><br/>
+ </div>
+ <a href="#section-11">11. Compatibility Test Suite</a><br/>
+ <a href="#section-12">12. Updatable Software</a><br/>
+ <a href="#section-13">13. Contact Us</a><br/>
+ <a href="#appendix-A">Appendix A - Bluetooth Test Procedure</a><br/>
+</div>
+
+<div style="page-break-before: always;"></div>
+
+<a name="section-1"></a><h2>1. Introduction</h2>
+<p>This document enumerates the requirements that must be met in order for
+mobile phones to be compatible with Android 2.2.</p>
+<p>The use of "must", "must not", "required", "shall", "shall not", "should",
+"should not", "recommended", "may" and "optional" is per the IETF standard
+defined in RFC2119 [<a href="#resources01">Resources, 1</a>].</p>
+<p>As used in this document, a "device implementer" or "implementer" is a
+person or organization developing a hardware/software solution running Android
+2.2. A "device implementation" or "implementation" is the hardware/software
+solution so developed.</p>
+<p>To be considered compatible with Android 2.2, device implementations:</p>
+<ul>
+<li>MUST meet the requirements presented in this Compatibility Definition,
+including any documents incorporated via reference.</li>
+<li>MUST pass the most recent version of the Android Compatibility Test Suite
+(CTS) available at the time of the device implementation's software is
+completed. (The CTS is available as part of the Android Open Source Project [<a
+href="#resources02">Resources, 2</a>].) The CTS tests many, but not all, of the
+components outlined in this document.</li>
+</ul>
+<p>Where this definition or the CTS is silent, ambiguous, or incomplete, it is
+the responsibility of the device implementer to ensure compatibility with
+existing implementations. For this reason, the Android Open Source Project [<a
+href="#resources03">Resources, 3</a>] is both the reference and preferred
+implementation of Android. Device implementers are strongly encouraged to base
+their implementations on the "upstream" source code available from the Android
+Open Source Project. While some components can hypothetically be replaced with
+alternate implementations this practice is strongly discouraged, as passing
+the CTS tests will become substantially more difficult. It is the
+implementer's responsibility to ensure full behavioral compatibility with the
+standard Android implementation, including and beyond the Compatibility Test
+Suite. Finally, note that certain component substitutions and modifications
+are explicitly forbidden by this document.</p>
+
+<a name="section-2"></a><h2>2. Resources</h2>
+<ol>
+<a name="resources01"></a><li>IETF RFC2119 Requirement Levels: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a></li>
+<a name="resources02"></a><li>Android Compatibility Program Overview: <a href="http://source.android.com/compatibility/index.html">http://source.android.com/compatibility/index.html</a></li>
+<a name="resources03"></a><li>Android Open Source Project: <a href="http://source.android.com/">http://source.android.com/</a></li>
+<a name="resources04"></a><li>API definitions and documentation: <a href="http://developer.android.com/reference/packages.html">http://developer.android.com/reference/packages.html</a></li>
+<a name="resources05"></a><li>Android Permissions reference: <a href="http://developer.android.com/reference/android/Manifest.permission.html">http://developer.android.com/reference/android/Manifest.permission.html</a></li>
+<a name="resources06"></a><li>android.os.Build reference: <a href="http://developer.android.com/reference/android/os/Build.html">http://developer.android.com/reference/android/os/Build.html</a></li>
+<a name="resources07"></a><li>Android 2.2 allowed version strings: <a href="http://source.android.com/compatibility/2.2/versions.html">http://source.android.com/compatibility/2.2/versions.html</a></li>
+<a name="resources08"></a><li>android.webkit.WebView class: <a href="http://developer.android.com/reference/android/webkit/WebView.html">http://developer.android.com/reference/android/webkit/WebView.html</a></li>
+<a name="resources09"></a><li>HTML5: <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">http://www.whatwg.org/specs/web-apps/current-work/multipage/</a></li>
+<a name="resources10"></a><li>Dalvik Virtual Machine specification: available in the Android source code, at dalvik/docs</li>
+<a name="resources11"></a><li>AppWidgets: <a href="http://developer.android.com/guide/practices/ui_guidelines/widget_design.html">http://developer.android.com/guide/practices/ui_guidelines/widget_design.html</a></li>
+<a name="resources12"></a><li>Notifications: <a href="http://developer.android.com/guide/topics/ui/notifiers/notifications.html">http://developer.android.com/guide/topics/ui/notifiers/notifications.html</a></li>
+<a name="resources13"></a><li>Application Resources: <a href="http://code.google.com/android/reference/available-resources.html">http://code.google.com/android/reference/available-resources.html</a></li>
+<a name="resources14"></a><li>Status Bar icon style guide: <a href="http://developer.android.com/guide/practices/ui_guidelines/icon_design.html#statusbarstructure">http://developer.android.com/guide/practices/ui_guideline /icon_design.html#statusbarstructure</a></li>
+<a name="resources15"></a><li>Search Manager: <a href="http://developer.android.com/reference/android/app/SearchManager.html">http://developer.android.com/reference/android/app/SearchManager.html</a></li>
+<a name="resources16"></a><li>Toasts: <a href="http://developer.android.com/reference/android/widget/Toast.html">http://developer.android.com/reference/android/widget/Toast.html</a></li>
+<a name="resources17"></a><li>Live Wallpapers: <a href="http://developer.android.com/resources/articles/live-wallpapers.html">http://developer.android.com/resources/articles/live-wallpapers.html</a></li>
+<a name="resources18"></a><li>Apps for Android: <a href="http://code.google.com/p/apps-for-android">http://code.google.com/p/apps-for-android</a></li>
+<a name="resources19"></a><li>Reference tool documentation (for adb, aapt, ddms): <a href="http://developer.android.com/guide/developing/tools/index.html">http://developer.android.com/guide/developing/tools/index.html</a></li>
+<a name="resources20"></a><li>Android apk file description: <a href="http://developer.android.com/guide/topics/fundamentals.html">http://developer.android.com/guide/topics/fundamentals.html</a></li>
+<a name="resources21"></a><li>Manifest files: <a href="http://developer.android.com/guide/topics/manifest/manifest-intro.html">http://developer.android.com/guide/topics/manifest/manifest-intro.html</a></li>
+<a name="resources22"></a><li>Monkey testing tool: <a href="http://developer.android.com/guide/developing/tools/monkey.html">http://developer.android.com/guide/developing/tools/monkey.html</a></li>
+<a name="resources23"></a><li>Android Hardware Features List: <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html">http://developer.android.com/reference/android/content/pm/PackageManager.html</a></li>
+<a name="resources24"></a><li>Supporting Multiple Screens: <a href="http://developer.android.com/guide/practices/screens_support.html">http://developer.android.com/guide/practices/screens_support.html</a></li>
+<a name="resources25"></a><li>android.content.res.Configuration: <a href="http://developer.android.com/reference/android/content/res/Configuration.html">http://developer.android.com/reference/android/content/res/Configuration.html</a></li>
+<a name="resources26"></a><li>android.util.DisplayMetrics: <a href="http://developer.android.com/reference/android/util/DisplayMetrics.html">http://developer.android.com/reference/android/util/DisplayMetrics.html</a></li>
+<a name="resources27"></a><li>android.hardware.Camera: <a href="http://developer.android.com/reference/android/hardware/Camera.html">http://developer.android.com/reference/android/hardware/Camera.html</a></li>
+<a name="resources28"></a><li>Sensor coordinate space: <a href="http://developer.android.com/reference/android/hardware/SensorEvent.html">http://developer.android.com/reference/android/hardware/SensorEvent.html</a></li>
+<a name="resources29"></a><li>Android Security and Permissions reference: <a href="http://developer.android.com/guide/topics/security/security.html">http://developer.android.com/guide/topics/security/security.html</a></li>
+<a name="resources30"></a><li>Bluetooth API: <a href="http://developer.android.com/reference/android/bluetooth/package-summary.html">http://developer.android.com/reference/android/bluetooth/package-summary.html</a></li>
+</ol>
+<p>Many of these resources are derived directly or indirectly from the Android
+2.2 SDK, and will be functionally identical to the information in that SDK's
+documentation. In any cases where this Compatibility Definition or the
+Compatibility Test Suite disagrees with the SDK documentation, the SDK
+documentation is considered authoritative. Any technical details provided in
+the references included above are considered by inclusion to be part of this
+Compatibility Definition.</p>
+
+<a name="section-3"></a><h2>3. Software</h2>
+<p>The Android platform includes a set of managed APIs, a set of native APIs,
+and a body of so-called "soft" APIs such as the Intent system and
+web-application APIs. This section details the hard and soft APIs that are
+integral to compatibility, as well as certain other relevant technical and
+user interface behaviors. Device implementations MUST comply with all the
+requirements in this section.</p>
+
+<a name="section-3.1"></a><h3>3.1. Managed API Compatibility</h3>
+<p>The managed (Dalvik-based) execution environment is the primary vehicle for
+Android applications. The Android application programming interface (API) is
+the set of Android platform interfaces exposed to applications running in the
+managed VM environment. Device implementations MUST provide complete
+implementations, including all documented behaviors, of any documented API
+exposed by the Android 2.2 SDK [<a href="#resources04">Resources, 4</a>].</p>
+<p>Device implementations MUST NOT omit any managed APIs, alter API interfaces
+or signatures, deviate from the documented behavior, or include no-ops, except
+where specifically allowed by this Compatibility Definition.</p>
+
+<a name="section-3.2"></a><h3>3.2. Soft API Compatibility</h3>
+<p>In addition to the managed APIs from Section 3.1, Android also includes a
+significant runtime-only "soft" API, in the form of such things such as
+Intents, permissions, and similar aspects of Android applications that cannot
+be enforced at application compile time. This section details the "soft" APIs
+and system behaviors required for compatibility with Android 2.2. Device
+implementations MUST meet all the requirements presented in this section.</p>
+<a name="section-3.2.1"></a><h4>3.2.1. Permissions</h4>
+<p>Device implementers MUST support and enforce all permission constants as
+documented by the Permission reference page [<a
+href="#resources05">Resources, 5</a>]. Note that Section 10 lists additional
+requirements related to the Android security model.</p>
+<a name="section-3.2.2"></a><h4>3.2.2. Build Parameters</h4>
+<p>The Android APIs include a number of constants on the <code>android.os.Build</code>
+class [<a href="#resources06">Resources, 6</a>] that are intended to describe
+the current device. To provide consistent, meaningful values across device
+implementations, the table below includes additional restrictions on the
+formats of these values to which device implementations MUST conform.</p>
+<table>
+<tbody>
+<tr>
+<td><b>Parameter</b></td>
+<td><b>Comments</b></td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.RELEASE</td>
+<td>The version of the currently-executing Android system, in human-readable
+format. This field MUST have one of the string values defined in [<a
+href="#resources07">Resources, 7</a>].</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.SDK</td>
+<td>The version of the currently-executing Android system, in a format
+accessible to third-party application code. For Android 2.2, this field MUST have
+the integer value 8.</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.INCREMENTAL</td>
+<td>A value chosen by the device implementer designating the specific build of
+the currently-executing Android system, in human-readable format. This value
+MUST NOT be re-used for different builds made available to end users. A typical use
+of this field is to indicate which build number or source-control change
+identifier was used to generate the build. There are no requirements on the
+specific format of this field, except that it MUST NOT be null or the empty
+string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.BOARD</td>
+<td>A value chosen by the device implementer identifying the specific internal
+hardware used by the device, in human-readable format. A possible use of this
+field is to indicate the specific revision of the board powering the device.
+There are no requirements on the specific format of this field, except that it
+MUST NOT be null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.BRAND</td>
+<td>A value chosen by the device implementer identifying the name of the
+company, organization, individual, etc. who produced the device, in
+human-readable format. A possible use of this field is to indicate the OEM
+and/or carrier who sold the device. There are no requirements on the specific
+format of this field, except that it MUST NOT be null or the empty string
+("").</td>
+</tr>
+<tr>
+<td>android.os.Build.DEVICE</td>
+<td>A value chosen by the device implementer identifying the specific
+configuration or revision of the body (sometimes called "industrial design")
+of the device. There are no requirements on the specific format of this field,
+except that it MUST NOT be null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.FINGERPRINT</td>
+<td>A string that uniquely identifies this build. It SHOULD be reasonably
+human-readable. It MUST follow this template:
+<br/><code>$(BRAND)/$(PRODUCT)/$(DEVICE)/$(BOARD):$(VERSION.RELEASE)/$(ID)/$(VERSION.INCREMENTAL):$(TYPE)/$(TAGS)</code><br/>
+For example:
+<br/><code>acme/mydevice/generic/generic:2.2/ERC77/3359:userdebug/test-keys</code><br/>
+The fingerprint MUST NOT include whitespace characters. If other fields included in the
+template above have whitespace characters, they MUST be replaced in the build
+fingerprint with another character, such as the underscore ("_") character.</td>
+</tr>
+<tr>
+<td>android.os.Build.HOST</td>
+<td>A string that uniquely identifies the host the build was built on, in
+human readable format. There are no requirements on the specific format of
+this field, except that it MUST NOT be null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.ID</td>
+<td>An identifier chosen by the device implementer to refer to a specific
+release, in human readable format. This field can be the same as
+android.os.Build.VERSION.INCREMENTAL, but SHOULD be a value sufficiently
+meaningful for end users to distinguish between software builds. There are no
+requirements on the specific format of this field, except that it MUST NOT be
+null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.MODEL</td>
+<td>A value chosen by the device implementer containing the name of the device
+as known to the end user. This SHOULD be the same name under which the device
+is marketed and sold to end users. There are no requirements on the specific
+format of this field, except that it MUST NOT be null or the empty string
+("").</td>
+</tr>
+<tr>
+<td>android.os.Build.PRODUCT</td>
+<td>A value chosen by the device implementer containing the development name
+or code name of the device. MUST be human-readable, but is not necessarily
+intended for view by end users. There are no requirements on the specific
+format of this field, except that it MUST NOT be null or the empty string
+("").</td>
+</tr>
+<tr>
+<td>android.os.Build.TAGS</td>
+<td>A comma-separated list of tags chosen by the device implementer that
+further distinguish the build. For example, "unsigned,debug". This field MUST
+NOT be null or the empty string (""), but a single tag (such as "release") is
+fine.</td>
+</tr>
+<tr>
+<td>android.os.Build.TIME</td>
+<td>A value representing the timestamp of when the build occurred.</td>
+</tr>
+<tr>
+<td>android.os.Build.TYPE</td>
+<td>A value chosen by the device implementer specifying the runtime
+configuration of the build. This field SHOULD have one of the values
+corresponding to the three typical Android runtime configurations: "user",
+"userdebug", or "eng".</td>
+</tr>
+<tr>
+<td>android.os.Build.USER</td>
+<td>A name or user ID of the user (or automated user) that generated the
+build. There are no requirements on the specific format of this field, except
+that it MUST NOT be null or the empty string ("").</td>
+</tr>
+</tbody>
+</table>
+<a name="section-3.2.3"></a><h4>3.2.3. Intent Compatibility</h4>
+<p>Android uses Intents to achieve loosely-coupled integration between
+applications. This section describes requirements related to the Intent
+patterns that MUST be honored by device implementations. By "honored", it is
+meant that the device implementer MUST provide an Android Activity or Service
+that specifies a matching Intent filter and binds to and implements correct
+behavior for each specified Intent pattern.</p>
+<a name="section-3.2.3.1"></a><h4>3.2.3.1. Core Application Intents</h4>
+<p>The Android upstream project defines a number of core applications, such as
+a phone dialer, calendar, contacts book, music player, and so on. Device
+implementers MAY replace these applications with alternative versions.</p>
+<p>However, any such alternative versions MUST honor the same Intent patterns
+provided by the upstream project. For example, if a device contains an
+alternative music player, it must still honor the Intent pattern issued by
+third-party applications to pick a song.</p>
+<p>The following applications are considered core Android system
+applications:</p>
+<ul>
+<li>Desk Clock</li>
+<li>Browser</li>
+<li>Calendar</li>
+<li>Calculator</li>
+<li>Camera</li>
+<li>Contacts</li>
+<li>Email</li>
+<li>Gallery</li>
+<li>GlobalSearch</li>
+<li>Launcher</li>
+<li>LivePicker (that is, the Live Wallpaper picker application; MAY be omitted
+if the device does not support Live Wallpapers, per Section 3.8.5.)</li>
+<li>Messaging (AKA "Mms")</li>
+<li>Music</li>
+<li>Phone</li>
+<li>Settings</li>
+<li>SoundRecorder</li>
+</ul>
+<p>The core Android system applications include various Activity, or Service
+components that are considered "public".
+That is, the attribute "android:exported" may be absent, or may have the value
+"true".</p>
+<p>For every Activity or Service defined
+in one of the core Android system apps that is not marked as non-public via an
+android:exported attribute with the value "false", device implementations MUST
+include a compontent of the same type implementing the same Intent filter
+patterns as the core Android system app.</p>
+<p>In other words, a device implementation MAY replace core Android system
+apps; however, if it does, the device implementation MUST support all Intent
+patterns defined by each core Android system app being replaced.</p>
+<a name="section-3.2.3.2"></a><h4>3.2.3.2. Intent Overrides</h4>
+<p>As Android is an extensible platform, device implementers MUST allow each
+Intent pattern referenced in Section 3.2.3.1 to be overridden by third-party
+applications. The upstream Android open source project allows this by default;
+device implementers MUST NOT attach special privileges to system applications'
+use of these Intent patterns, or prevent third-party applications from binding
+to and assuming control of these patterns. This prohibition specifically
+includes but is not limited to disabling the "Chooser" user interface which
+allows the user to select between multiple applications which all handle the
+same Intent pattern.</p>
+<a name="section-3.2.3.3"></a><h4>3.2.3.3. Intent Namespaces</h4>
+<p>Device implementers MUST NOT include any Android component that honors any
+new Intent or Broadcast Intent patterns using an ACTION, CATEGORY, or other
+key string in the android.* namespace. Device implementers MUST NOT include
+any Android components that honor any new Intent or Broadcast Intent patterns
+using an ACTION, CATEGORY, or other key string in a package space belonging to
+another organization. Device implementers MUST NOT alter or extend any of the
+Intent patterns used by the core apps listed in Section 3.2.3.1.</p>
+<p>This prohibition is analogous to that specified for Java language classes
+in Section 3.6.</p>
+<a name="section-3.2.3.4"></a><h4>3.2.3.4. Broadcast Intents</h4>
+<p>Third-party applications rely on the platform to broadcast certain Intents
+to notify them of changes in the hardware or software environment.
+Android-compatible devices MUST broadcast the public broadcast Intents in
+response to appropriate system events. Broadcast Intents are described in the
+SDK documentation.</p>
+
+<a name="section-3.3"></a><h3>3.3. Native API Compatibility</h3>
+<p>Managed code running in Dalvik can call into native code provided in the
+application .apk file as an ELF .so file compiled for the appropriate device
+hardware architecture. Device implementations MUST include support for code
+running in the managed environment to call into native code, using the
+standard Java Native Interface (JNI) semantics. The following APIs MUST be
+available to native code:</p>
+<ul>
+<li>libc (C library)</li>
+<li>libm (math library)</li>
+<li>JNI interface</li>
+<li>libz (Zlib compression)</li>
+<li>liblog (Android logging)</li>
+<li>Minimal support for C++</li>
+<li>Support for OpenGL, as described below</li>
+</ul>
+<p>Device implementations MUST support OpenGL ES 1.0. Devices that lack
+hardware acceleration MUST implement OpenGL ES 1.0 using a software renderer.
+Device implementations SHOULD implement as much of OpenGL ES 1.1 as the device
+hardware supports. Device implementations SHOULD provide an implementation
+for OpenGL ES 2.0, if the hardware is capable of reasonable performance on
+those APIs.</p>
+<p>These libraries MUST be source-compatible (i.e. header compatible) and
+binary-compatible (for a given processor architecture) with the versions
+provided in Bionic by the Android Open Source project. Since the Bionic
+implementations are not fully compatible with other implementations such as
+the GNU C library, device implementers SHOULD use the Android implementation.
+If device implementers use a different implementation of these libraries, they
+MUST ensure header, binary, and behavioral compatibility.</p>
+<p>Device implementations MUST accurately report the native Application Binary
+Interface (ABI) supported by the device, via the
+<code>android.os.Build.CPU_ABI</code> API. The ABI MUST be one of the entries
+documented in the latest version of the Android NDK, in the file
+<code>docs/CPU-ARCH-ABIS.txt</code>. Note that additional releases of the
+Android NDK may introduce support for additional ABIs.</p>
+<p>Native code compatibility is challenging. For this reason, it should be
+repeated that device implementers are VERY strongly encouraged to use the
+upstream implementations of the libraries listed above to help ensure
+compatibility.</p>
+
+<a name="section-3.4"></a><h3>3.4. Web Compatibility</h3>
+<p>Many developers and applications rely on the behavior of the
+<code>android.webkit.WebView</code> class [<a
+href="#resources08">Resources, 8</a>]
+for their user interfaces, so the WebView implementation must be
+compatible across Android implementations. Similarly, a full web experience is
+central to the Android user experience. Device implementations MUST include a
+version of <code>android.webkit.WebView</code> consistent with the upstream
+Android software, and MUST include a modern HTML5-capable browser, as
+described below.</p>
+<a name="section-3.4.1"></a><h4>3.4.1. WebView Compatibility</h4>
+<p>The Android Open Source implementation uses the WebKit rendering engine to
+implement the <code>android.webkit.WebView</code>. Because it is not feasible
+to develop a comprehensive test suite for a web rendering system, device
+implementers MUST use the specific upstream build of WebKit in the WebView
+implementation. Specifically:</p>
+<ul>
+<li>Device implementations' <code>android.webkit.WebView</code>
+implementations MUST be based on the 533.1 WebKit build from the upstream
+Android Open Source tree for Android 2.2. This build includes a specific set
+of functionality and security fixes for the WebView. Device implementers MAY
+include customizations to the WebKit implementation; however, any such
+customizations MUST NOT alter the behavior of the WebView, including rendering
+behavior.</li>
+<li>The user agent string reported by the WebView MUST be in this format:<br/>
+ <code>Mozilla/5.0 (Linux; U; Android $(VERSION); $(LOCALE); $(MODEL) Build/$(BUILD)) AppleWebKit/533.1 (KHTML, like Gecko) Version/4.0 Mobile Safari/533.1</code>
+ <ul>
+ <li>The value of the $(VERSION) string MUST be the same as the value for <code>android.os.Build.VERSION.RELEASE</code></li>
+ <li>The value of the $(LOCALE) string SHOULD follow the ISO conventions for country code and language, and SHOULD refer to the current configured locale of the device</li>
+ <li>The value of the $(MODEL) string MUST be the same as the value for <code>android.os.Build.MODEL</code></li>
+ <li>The value of the $(BUILD) string MUST be the same as the value for <code>android.os.Build.ID</code></li>
+ </ul></li>
+</ul>
+<p>The WebView configuration MUST include support for the HTML5 database,
+application cache, and geolocation APIs [<a href="#resources09">Resources,
+9</a>]. The WebView MUST include support for the HTML5
+<code><video></code> tag. HTML5 APIs, like all JavaScript APIs, MUST be
+disabled by default in a WebView, unless the developer explicitly enables them
+via the usual Android APIs.</p>
+<a name="section-3.4.2"></a><h4>3.4.2. Browser Compatibility</h4>
+<p>Device implementations MUST include a standalone Browser application for
+general user web browsing. The standalone Browser MAY be based on an
+browser technology other than WebKit. However, even if an alternate Browser
+application is shipped, the <code>android.webkit.WebView</code> component
+provided to third-party applications MUST be based on WebKit, as described in
+Section 3.4.1.</p>
+<p>Implementations MAY ship a custom user agent string in the standalone
+Browser application.</p>
+<p>The standalone Browser application (whether based on the upstream
+WebKit Browser application or a third-party replacement) SHOULD include support
+for as much of HTML5 [<a href="#resources09">Resources, 9</a>] as possible.
+Minimally, device implementations MUST support HTML5 geolocation, application
+cache, and database APIs and the <video> tag in standalone the Browser
+application.</p>
+
+<a name="section-3.5"></a><h3>3.5. API Behavioral Compatibility</h3>
+<p>The behaviors of each of the API types (managed, soft, native, and web)
+must be consistent with the preferred implementation of the upstream Android
+open-source project [<a href="#resources03">Resources, 3</a>]. Some specific areas
+of compatibility are:</p>
+<ul>
+<li>Devices MUST NOT change the behavior or meaning of a standard Intent</li>
+<li>Devices MUST NOT alter the lifecycle or lifecycle semantics of a particular type of system component (such as Service, Activity, ContentProvider, etc.)</li>
+<li>Devices MUST NOT change the semantics of a particular permission</li>
+</ul>
+<p>The above list is not comprehensive, and the onus is on device implementers
+to ensure behavioral compatibility. For this reason, device implementers
+SHOULD use the source code available via the Android Open Source Project where
+possible, rather than re-implement significant parts of the system.</p>
+<p>The Compatibility Test Suite (CTS) tests significant portions of the
+platform for behavioral compatibility, but not all. It is the responsibility
+of the implementer to ensure behavioral compatibility with the Android Open
+Source Project.</p>
+
+<a name="section-3.6"></a><h3>3.6. API Namespaces</h3>
+<p>Android follows the package and class namespace conventions defined by the
+Java programming language. To ensure compatibility with third-party
+applications, device implementers MUST NOT make any prohibited modifications
+(see below) to these package namespaces:</p>
+<ul>
+<li>java.*</li>
+<li>javax.*</li>
+<li>sun.*</li>
+<li>android.*</li>
+<li>com.android.*</li>
+</ul>
+<p>Prohibited modifications include:</p>
+<ul>
+<li>Device implementations MUST NOT modify the publicly exposed APIs on the
+Android platform by changing any method or class signatures, or by removing
+classes or class fields.</li>
+<li>Device implementers MAY modify the underlying implementation of the APIs,
+but such modifications MUST NOT impact the stated behavior and Java-language
+signature of any publicly exposed APIs.</li>
+<li>Device implementers MUST NOT add any publicly exposed elements (such as
+classes or interfaces, or fields or methods to existing classes or interfaces)
+to the APIs above.</li>
+</ul>
+<p>A "publicly exposed element" is any construct which is not decorated with
+the "@hide" marker in the upstream Android source code. In other words, device
+implementers MUST NOT expose new APIs or alter existing APIs in the namespaces
+noted above. Device implementers MAY make internal-only modifications, but
+those modifications MUST NOT be advertised or otherwise exposed to
+developers.</p>
+<p>Device implementers MAY add custom APIs, but any such APIs MUST NOT be in a
+namespace owned by or referring to another organization. For instance, device
+implementers MUST NOT add APIs to the com.google.* or similar namespace; only
+Google may do so. Similarly, Google MUST NOT add APIs to other companies'
+namespaces.</p>
+<p>If a device implementer proposes to improve one of the package namespaces
+above (such as by adding useful new functionality to an existing API, or
+adding a new API), the implementer SHOULD visit source.android.com and begin
+the process for contributing changes and code, according to the information on
+that site.</p>
+<p>Note that the restrictions above correspond to standard conventions for
+naming APIs in the Java programming language; this section simply aims to
+reinforce those conventions and make them binding through inclusion in this
+compatibility definition.</p>
+
+<a name="section-3.7"></a><h3>3.7. Virtual Machine Compatibility</h3>
+<p>Device implementations MUST support the full Dalvik Executable (DEX)
+bytecode specification and Dalvik Virtual Machine semantics [<a
+href="#resources10">Resources, 10</a>].</p>
+<p>Device implementations with screens classified as medium- or low-density
+MUST configure Dalvik to allocate at least 16MB of memory to each application.
+Device implementations with screens classified as high-density MUST configure
+Dalvik to allocate at least 24MB of memory to each application. Note that
+device implementations MAY allocate more memory than these figures.</p>
+
+<a name="section-3.8"></a><h3>3.8. User Interface Compatibility</h3>
+<p>The Android platform includes some developer APIs that allow developers to
+hook into the system user interface. Device implementations MUST incorporate
+these standard UI APIs into custom user interfaces they develop, as explained
+below.</p>
+<a name="section-3.8.1"></a><h4>3.8.1. Widgets</h4>
+<p>Android defines a component type and corresponding API and lifecycle that
+allows applications to expose an "AppWidget" to the end user [<a
+href="#resources11">Resources, 11</a>].
+The Android Open Source reference release includes a Launcher application that
+includes user interface elements allowing the user to add, view, and remove
+AppWidgets from the home screen.</p>
+<p>Device implementers MAY substitute an alternative to the reference Launcher
+(i.e. home screen). Alternative Launchers SHOULD include built-in support for
+AppWidgets, and expose user interface elements to add, configure, view, and remove
+AppWidgets directly within the Launcher. Alternative Launchers MAY omit these
+user interface elements; however, if they are omitted, the device implementer
+MUST provide a separate application accessible from the Launcher that allows
+users to add, configure, view, and remove AppWidgets.</p>
+<a name="section-3.8.2"></a><h4>3.8.2. Notifications</h4>
+<p>Android includes APIs that allow developers to notify users of notable
+events [<a href="#resources12">Resources, 12</a>]. Device implementers MUST provide support for each
+class of notification so defined; specifically: sounds, vibration, light and
+status bar.</p>
+<p>Additionally, the implementation MUST correctly render all resources
+(icons, sound files, etc.) provided for in the APIs [<a
+href="#resources13">Resources, 13</a>], or in the
+Status Bar icon style guide [<a href="#resources14">Resources, 14</a>]. Device implementers MAY provide
+an alternative user experience for notifications than that provided by the
+reference Android Open Source implementation; however, such alternative
+notification systems MUST support existing notification resources, as
+above.</p>
+<a name="section-3.8.3"></a><h4>3.8.3. Search</h4>
+<p>Android includes APIs [<a href="#resources15">Resources, 15</a>] that allow developers to incorporate
+search into their applications, and expose their application's data into the
+global system search. Generally speaking, this functionality consists of a
+single, system-wide user interface that allows users to enter queries,
+displays suggestions as users type, and displays results. The Android APIs
+allow developers to reuse this interface to provide search within their own
+apps, and allow developers to supply results to the common global search user
+interface.</p>
+<p>Device implementations MUST include a single, shared, system-wide search
+user interface capable of real-time suggestions in response to user input.
+Device implementations MUST implement the APIs that allow developers to reuse
+this user interface to provide search within their own applications. Device
+implementations MUST implement the APIs that allow third-party applications to
+add suggestions to the search box when it is run in global search mode. If no
+third-party applications are installed that make use of this functionality,
+the default behavior SHOULD be to display web search engine results and
+suggestions.</p>
+<p>Device implementations MAY ship alternate search user interfaces, but
+SHOULD include a hard or soft dedicated search button, that can be used at any
+time within any app to invoke the search framework, with the behavior provided
+for in the API documentation.</p>
+<a name="section-3.8.4"></a><h4>3.8.4. Toasts</h4>
+<p>Applications can use the "Toast" API (defined in [<a
+href="#resources16">Resources, 16</a>]) to
+display short non-modal strings to the end user, that disappear after a brief
+period of time. Device implementations MUST display Toasts from applications
+to end users in some high-visibility manner.</p>
+<a name="section-3.8.5"></a><h4>3.8.5. Live Wallpapers</h4>
+<p>Android defines a component type and corresponding API and lifecycle that
+allows applications to expose one or more "Live Wallpapers" to the end user
+[<a href="#resources17">Resources, 17</a>]. Live Wallpapers are animations,
+patterns, or similar images with limited input capabilities that display as a
+wallpaper, behind other applications.</p>
+<p>Hardware is considered capable of reliably running live wallpapers if it
+can run all live wallpapers, with no limitations on functionality, at a
+reasonable framerate with no adverse affects on other applications. If
+limitations in the hardware cause wallpapers and/or applications to crash,
+malfunction, consume excessive CPU or battery power, or run at unacceptably
+low frame rates, the hardware is considered incapable of running live
+wallpaper. As an example, some live wallpapers may use an Open GL 1.0 or 2.0
+context to render their content. Live wallpaper will not run reliably on
+hardware that does not support multiple OpenGL contexts because the live
+wallpaper use of an OpenGL context may conflict with other applications that
+also use an OpenGL context. </p>
+<p>Device implementations capable of running live wallpapers reliably as
+described above SHOULD implement live wallpapers. Device implementations
+determined to not run live wallpapers reliably as described above MUST NOT
+implement live wallpapers.</p>
+
+<a name="section-4"></a><h2>4. Reference Software Compatibility</h2>
+<p>Device implementers MUST test implementation compatibility using the
+following open-source applications:</p>
+<ul>
+<li>Calculator (included in SDK)</li>
+<li>Lunar Lander (included in SDK)</li>
+<li>The "Apps for Android" applications [<a href="#resources18">Resources, 18</a>].</li>
+<li>Replica Island (available in Android Market; only required for device
+ implementations that support with OpenGL ES 2.0)</li>
+</ul>
+<p>Each app above MUST launch and behave correctly on the implementation, for
+the implementation to be considered compatible.</p>
+<p>Additionally, device implementations MUST test each menu item (including all
+sub-menus) of each of these smoke-test applications:</p>
+<ul>
+<li>ApiDemos (included in SDK)</li>
+<li>ManualSmokeTests (included in CTS)</li>
+</ul>
+<p>Each test case in the applications above MUST run correctly on the device
+implementation.</p>
+
+<a name="section-5"></a><h2>5. Application Packaging Compatibility</h2>
+<p>Device implementations MUST install and run Android ".apk" files as
+generated by the "aapt" tool included in the official Android SDK [<a
+href="#resources19">Resources, 19</a>].</p>
+<p>Devices implementations MUST NOT extend either the .apk [<a
+href="#resources20">Resources, 20</a>], Android Manifest [<a
+href="#resources21">Resources, 21</a>],
+or Dalvik bytecode [<a href="#resources10">Resources, 10</a>] formats in such
+a way that would prevent those files from
+installing and running correctly on other compatible devices. Device
+implementers SHOULD use the reference upstream implementation of Dalvik, and
+the reference implementation's package management system.</p>
+
+<a name="section-6"></a><h2>6. Multimedia Compatibility</h2>
+<p>Device implementations MUST fully implement all multimedia APIs. Device
+implementations MUST include support for all multimedia codecs described
+below, and SHOULD meet the sound processing guidelines described below.</p>
+<a name="section-6.1"></a><h3>6.1. Media Codecs</h3>
+<p>Device implementations MUST support the following multimedia codecs. All of
+these codecs are provided as software implementations in the preferred Android
+implementation from the Android Open Source Project.</p>
+<p>Please note that neither Google nor the Open Handset Alliance make any
+representation that these codecs are unencumbered by third-party patents.
+Those intending to use this source code in hardware or software products are
+advised that implementations of this code, including in open source software
+or shareware, may require patent licenses from the relevant patent
+holders.</p>
+<table><tbody>
+<tr>
+<td rowspan="11"><b>Audio</b></td>
+</tr>
+<tr>
+<td><b>Name</b></td>
+<td><b>Encoder</b></td>
+<td><b>Decoder</b></td>
+<td><b>Details</b></td>
+<td><b>File/Container Format</b></td>
+</tr>
+<tr>
+<td>AAC LC/LTP</td>
+<td> </td>
+<td>X</td>
+<td rowspan="3">Mono/Stereo content in any combination of standard bit rates up to 160 kbps and sampling rates between 8 to 48kHz</td>
+<td rowspan="3">3GPP (.3gp) and MPEG-4 (.mp4, .m4a). No support for raw AAC (.aac)</td>
+</tr>
+<tr>
+<td>HE-AACv1 (AAC+)</td>
+<td> </td>
+<td>X</td>
+</tr>
+<tr>
+<td>HE-AACv2 (enhanced AAC+)</td>
+<td> </td>
+<td>X</td>
+</tr>
+<tr>
+<td>AMR-NB</td>
+<td>X</td>
+<td>X</td>
+<td>4.75 to 12.2 kbps sampled @ 8kHz</td>
+<td>3GPP (.3gp)</td>
+</tr>
+<tr>
+<td>AMR-WB</td>
+<td> </td>
+<td>X</td>
+<td>9 rates from 6.60 kbit/s to 23.85 kbit/s sampled @ 16kHz</td>
+<td>3GPP (.3gp)</td>
+</tr>
+<tr>
+<td>MP3</td>
+<td> </td>
+<td>X</td>
+<td>Mono/Stereo 8-320Kbps constant (CBR) or variable bit-rate (VBR)</td>
+<td>MP3 (.mp3)</td>
+</tr>
+<tr>
+<td>MIDI</td>
+<td> </td>
+<td>X</td>
+<td>MIDI Type 0 and 1. DLS Version 1 and 2. XMF and Mobile XMF. Support for ringtone formats RTTTL/RTX, OTA, and iMelody</td>
+<td>Type 0 and 1 (.mid, .xmf, .mxmf). Also RTTTL/RTX (.rtttl, .rtx), OTA (.ota), and iMelody (.imy)</td>
+</tr>
+<tr>
+<td>Ogg Vorbis</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td>Ogg (.ogg)</td>
+</tr>
+<tr>
+<td>PCM</td>
+<td> </td>
+<td>X</td>
+<td>8- and 16-bit linear PCM (rates up to limit of hardware)</td>
+<td>WAVE (.wav)</td>
+</tr>
+<tr>
+<td rowspan="5"><b>Image</b></td>
+</tr>
+<tr>
+<td>JPEG</td>
+<td>X</td>
+<td>X</td>
+<td>base+progressive</td>
+<td> </td>
+</tr>
+<tr>
+<td>GIF</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+<tr>
+<td>PNG</td>
+<td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+<tr>
+<td>BMP</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+<tr>
+<td rowspan="4"><b>Video</b></td>
+</tr>
+<tr>
+<td>H.263</td>
+<td>X</td>
+<td>X</td>
+<td> </td>
+<td>3GPP (.3gp) files</td>
+</tr>
+<tr>
+<td>H.264</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td>3GPP (.3gp) and MPEG-4 (.mp4) files</td>
+</tr>
+<tr>
+<td>MPEG4 Simple Profile</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td>3GPP (.3gp) file</td>
+</tr>
+</tbody>
+</table>
+<p>Note that the table above does not list specific bitrate requirements for
+most video codecs. The reason for this is that in practice, current device
+hardware does not necessarily support bitrates that map exactly to the
+required bitrates specified by the relevant standards. Instead, device
+implementations SHOULD support the highest bitrate practical on the hardware,
+up to the limits defined by the specifications.</p>
+
+<a name="section-6.2"></a><h3>6.2. Audio Recording</h3>
+<p>When an application has used the <code>android.media.AudioRecord</code> API to
+start recording an audio stream, device implementations SHOULD sample and
+record audio with each of these behaviors:</p>
+<ul>
+<li>Noise reduction processing, if present, SHOULD be disabled.</li>
+<li>Automatic gain control, if present, SHOULD be disabled.</li>
+<li>The device SHOULD exhibit approximately flat amplitude versus frequency
+ characteristics; specifically, ±3 dB, from 100 Hz to 4000 Hz</li>
+<li>Audio input sensitivity SHOULD be set such that a 90 dB sound power level
+ (SPL) source at 1000 Hz yields RMS of 5000 for 16-bit samples.</li>
+<li>PCM amplitude levels SHOULD linearly track input SPL changes over at least
+ a 30 dB range from -18 dB to +12 dB re 90 dB SPL at the microphone.</li>
+<li>Total harmonic distortion SHOULD be less than 1% from 100 Hz to 4000 Hz at
+ 90 dB SPL input level.</li>
+</ul>
+<p><b>Note:</b> while the requirements outlined above are stated as "SHOULD"
+for Android 2.2, the Compatibility Definition for a future version is planned
+to change these to "MUST". That is, these requirements are optional in Android
+2.2 but <b>will be required</b> by a future version. Existing and new devices
+that run Android 2.2 Android are <b>very strongly encouraged to meet
+these requirements in Android 2.2</b>, or they will not be able to attain
+Android compatibility when upgraded to the future version.</p>
+
+<a name="section-6.3"></a><h3>6.3. Audio Latency</h3>
+<p>Audio latency is broadly defined as the interval between when an
+application requests an audio playback or record operation, and when the
+device implementation actually begins the operation. Many classes of
+applications rely on short latencies, to achieve real-time effects such sound
+effects or VOIP communication. Device implementations SHOULD meet all audio
+latency requirements outlined in this section.</p>
+<p>For the purposes of this section:</p>
+<ul>
+<li>"cold output latency" is defined to be the interval between when an
+ application requests audio playback and when sound begins playing, when
+ the audio system has been idle and powered down prior to the request</li>
+<li>"warm output latency" is defined to be the interval between when an
+ application requests audio playback and when sound begins playing, when
+ the audio system has been recently used but is currently idle (that is,
+ silent)</li>
+<li>"continuous output latency" is defined to be the interval between when an
+ application issues a sample to be played and when the speaker physically
+ plays the corresponding sound, while the device is currently playing back
+ audio</li>
+<li>"cold input latency" is defined to be the interval between when an
+ application requests audio recording and when the first sample is
+ delivered to the application via its callback, when the audio system and
+ microphone has been idle and powered down prior to the request</li>
+<li>"continuous input latency" is defined to be when an ambient sound occurs
+ and when the sample corresponding to that sound is delivered to a
+ recording application via its callback, while the device is in recording
+ mode</li>
+</ul>
+<p>Using the above definitions, device implementations SHOULD exhibit each of
+these properties:</p>
+<ul>
+<li>cold output latency of 100 milliseconds or less</li>
+<li>warm output latency of 10 milliseconds or less</li>
+<li>continuous output latency of 45 milliseconds or less</li>
+<li>cold input latency of 100 milliseconds or less</li>
+<li>continuous input latency of 50 milliseconds or less</li>
+</ul>
+<p><b>Note:</b> while the requirements outlined above are stated as "SHOULD"
+for Android 2.2, the Compatibility Definition for a future version is planned
+to change these to "MUST". That is, these requirements are optional in Android
+2.2 but <b>will be required</b> by a future version. Existing and new devices
+that run Android 2.2 Android are <b>very strongly encouraged to meet
+these requirements in Android 2.2</b>, or they will not be able to attain
+Android compatibility when upgraded to the future version.</p>
+
+<a name="section-7"></a><h2>7. Developer Tool Compatibility</h2>
+<p>Device implementations MUST support the Android Developer Tools provided in
+the Android SDK. Specifically, Android-compatible devices MUST be compatible
+with:</p>
+<ul>
+<li><b>Android Debug Bridge (known as adb)</b> [<a href="#resources19">Resources, 19</a>]<br/>
+Device implementations MUST support all <code>adb</code> functions as
+documented in the Android SDK. The device-side <code>adb</code> daemon SHOULD
+be inactive by default, but there MUST be a user-accessible mechanism to turn
+on the Android Debug Bridge.</li>
+<li><b>Dalvik Debug Monitor Service (known as ddms)</b> [<a href="#resources19">Resources, 19</a>]<br/>
+Device implementations MUST support all <code>ddms</code> features as documented in the
+Android SDK. As <code>ddms</code> uses <code>adb</code>, support for
+<code>ddms</code> SHOULD be inactive by default,
+but MUST be supported whenever the user has activated the Android Debug
+Bridge, as above.</li>
+<li><b>Monkey</b> [<a href="#resources22">Resources, 22</a>]<br/>
+Device implementations MUST include the Monkey framework, and make it
+available for applications to use.</li>
+</ul>
+
+<a name="section-8"></a><h2>8. Hardware Compatibility</h2>
+<p>Android is intended to support device implementers creating innovative form
+factors and configurations. At the same time Android developers expect
+certain hardware, sensors and APIs across all Android device. This section
+lists the hardware features that all Android 2.2 compatible devices must
+support.</p>
+<p>If a device includes a particular hardware component that has a
+corresponding API for third-party developers, the device implementation MUST
+implement that API as defined in the Android SDK documentation. If an API in
+the SDK interacts with a hardware component that is stated to be optional and the device
+implementation does not possess that component:</p>
+<ul>
+<li>class definitions for the component's APIs MUST be present</li>
+<li>the API's behaviors MUST be implemented as no-ops in some reasonable fashion</li>
+<li>API methods MUST return null values where permitted by the SDK documentation</li>
+<li>API methods MUST return no-op implementations of classes where null values are not permitted by the SDK documentation</li>
+</ul>
+<p>A typical example of a scenario where these requirements apply is the
+telephony API: even on non-phone devices, these APIs must be implemented as
+reasonable no-ops.</p>
+<p>Device implementations MUST accurately report accurate hardware configuration
+information via the <code>getSystemAvailableFeatures()</code> and
+<code>hasSystemFeature(String)</code> methods on the
+<code>android.content.pm.PackageManager</code> class. [<a
+href="#resources23">Resources, 23</a>]</p>
+
+<a name="section-8.1"></a><h3>8.1. Display</h3>
+<p>Android 2.2 includes facilities that perform certain automatic scaling and
+transformation operations under some circumstances, to ensure that third-party
+applications run reasonably well on a variety of hardware configurations [<a
+href="#resources24">Resources, 24</a>]. Devices MUST properly implement these
+behaviors, as detailed in this section.</p>
+<p>For Android 2.2, these are the most common display configurations:</p>
+<table><tbody>
+<tr>
+<td>Screen Type</td>
+<td>Width (Pixels)</td>
+<td>Height (Pixels)</td>
+<td>Diagonal Length Range (inches)</td>
+<td>Screen Size Group</td>
+<td>Screen Density Group</td>
+</tr>
+<tr>
+<td>QVGA</td>
+<td>240</td>
+<td>320</td>
+<td>2.6 - 3.0</td>
+<td>Small</td>
+<td>Low</td>
+</tr>
+<tr>
+<td>WQVGA</td>
+<td>240</td>
+<td>400</td>
+<td>3.2 - 3.5</td>
+<td>Normal</td>
+<td>Low</td>
+</tr>
+<tr>
+<td>FWQVGA</td>
+<td>240</td>
+<td>432</td>
+<td>3.5 - 3.8</td>
+<td>Normal</td>
+<td>Low</td>
+</tr>
+<tr>
+<td>HVGA</td>
+<td>320</td>
+<td>480</td>
+<td>3.0 - 3.5</td>
+<td>Normal</td>
+<td>Medium</td>
+</tr>
+<tr>
+<td>WVGA</td>
+<td>480</td>
+<td>800</td>
+<td>3.3 - 4.0</td>
+<td>Normal</td>
+<td>High</td>
+</tr>
+<tr>
+<td>FWVGA</td>
+<td>480</td>
+<td>854</td>
+<td>3.5 - 4.0</td>
+<td>Normal</td>
+<td>High</td>
+</tr>
+<tr>
+<td>WVGA </td>
+<td>480 </td>
+<td>800 </td>
+<td>4.8 - 5.5 </td>
+<td>Large </td>
+<td>Medium</td>
+</tr>
+<tr>
+<td>FWVGA</td>
+<td>480</td>
+<td>854</td>
+<td>5.0 - 5.8</td>
+<td>Large</td>
+<td>Medium</td>
+</tr>
+
+</tbody></table>
+
+<p>Device implementations corresponding to one of the standard configurations
+above MUST be configured to report the indicated screen size to applications
+via the <code>android.content.res.Configuration</code> [<a href="#resources25">Resources,
+24</a>] class.</p>
+<p>Some .apk packages have manifests that do not identify them as supporting a
+specific density range. When running such applications, the following
+constraints apply:</p>
+<ul>
+<li>Device implementations MUST interpret resources in a .apk that lack a
+density qualifier as defaulting to "medium" (known as "mdpi" in the SDK
+documentation.)</li>
+<li>When operating on a "low" density screen, device implementations MUST
+scale down medium/mdpi assets by a factor of 0.75.</li>
+<li>When operating on a "high" density screen, device implementations MUST
+scale up medium/mdpi assets by a factor of 1.5.</li>
+<li>Device implementations MUST NOT scale assets within a density range, and
+MUST scale assets by exactly these factors between density ranges.</li>
+</ul>
+
+<a name="section-8.1.2"></a><h4>8.1.2. Non-Standard Display Configurations</h4>
+<p>Display configurations that do not match one of the standard configurations
+listed in Section 8.1.1 require additional consideration and work to be
+compatible. Device implementers MUST contact Android Compatibility Team as
+described in Section 13 to obtain classifications for screen-size bucket,
+density, and scaling factor. When provided with this information, device
+implementations MUST implement them as specified.</p>
+<p>Note that some display configurations (such as very large or very small
+screens, and some aspect ratios) are fundamentally incompatible with Android
+2.2; therefore device implementers are encouraged to contact Android
+Compatibility Team as early as possible in the development process.</p>
+
+<a name="section-8.1.3"></a><h4>8.1.3. Display Metrics</h4>
+<p>Device implementations MUST report correct valuesfor all display metrics
+defined in <code>android.util.DisplayMetrics</code> [<a
+href="#resources26">Resources, 26</a>].</p>
+
+<a name="section-8.1.4"></a><h4>8.1.4. Declared Screen Support</h4>
+<p>Applications may indicate which screen sizes they support via the
+<code><supports-screens></code> attribute in the AndroidManifest.xml
+file. Device implementations MUST correctly honor applications' stated support
+for small, medium, and large screens, as described in the Android
+SDK documentation.</p>
+
+<a name="section-8.2"></a><h3>8.2. Keyboard</h3>
+<p>Device implementations:</p>
+<ul>
+<li>MUST include support for the Input Management Framework (which allows third party developers to create Input Management Engines -- i.e. soft keyboard) as detailed at developer.android.com</li>
+<li>MUST provide at least one soft keyboard implementation (regardless of whether a hard keyboard is present)</li>
+<li>MAY include additional soft keyboard implementations</li>
+<li>MAY include a hardware keyboard</li>
+<li>MUST NOT include a hardware keyboard that does not match one of the
+formats specified in <code>android.content.res.Configuration.keyboard</code>
+[<a href="#resources25">Resources, 25</a>] (that is, QWERTY, or 12-key)</li>
+</ul>
+<a name="section-8.3"></a><h3>8.3. Non-touch Navigation</h3>
+<p>Device implementations:</p>
+<ul>
+<li>MAY omit a non-touch navigation options (that is, may omit a trackball, d-pad, or wheel)</li>
+<li>MUST report the correct value for
+<code>android.content.res.Configuration.navigation</code> [<a href="#resources25">Resources, 25</a>]</li>
+</ul>
+<a name="section-8.4"></a><h3>8.4. Screen Orientation</h3>
+<p>Compatible devices MUST support dynamic orientation by applications to
+either portrait or landscape screen orientation. That is, the device must
+respect the application's request for a specific screen orientation. Device
+implementations MAY select either portrait or landscape orientation as the
+default.</p>
+<p>Devices MUST report the correct value for the device's current orientation,
+whenever queried via the android.content.res.Configuration.orientation,
+android.view.Display.getOrientation(), or other APIs.</p>
+
+<a name="section-8.5"></a><h3>8.5. Touchscreen input</h3>
+<p>Device implementations:</p>
+<ul>
+<li>MUST have a touchscreen</li>
+<li>MAY have either capacative or resistive touchscreen</li>
+<li>MUST report the value of <code>android.content.res.Configuration</code>
+[<a href="#resources25">Resources, 25</a>]
+reflecting corresponding to the type of the specific touchscreen on the
+device</li>
+<li>SHOULD support fully independently tracked pointers, if the touchscreen supports multiple pointers</li>
+</ul>
+
+<a name="section-8.6"></a><h3>8.6. USB</h3>
+<p>Device implementations:</p>
+<ul>
+<li>MUST implement a USB client, connectable to a USB host with a standard
+USB-A port</li>
+<li>MUST implement the Android Debug Bridge over USB (as described in Section
+7)</li>
+<li>MUST implement the USB mass storage specification, to allow a host
+connected to the device to access the contents of the /sdcard volume </li>
+<li>SHOULD use the micro USB form factor on the device side</li>
+<li>MAY include a non-standard port on the device side, but if so MUST ship
+with a cable capable of connecting the custom pinout to standard USB-A
+port</li>
+<li>SHOULD implement support for the USB Mass Storage specification (so that
+either removable or fixed storage on the device can be accessed from a host
+PC)</li>
+</ul>
+
+<a name="section-8.7"></a><h3>8.7. Navigation keys</h3>
+<p>The Home, Menu and Back functions are essential to the Android navigation
+paradigm. Device implementations MUST make these functions available to the
+user at all times, regardless of application state. These functions SHOULD be
+implemented via dedicated buttons. They MAY be implemented using software,
+gestures, touch panel, etc., but if so they MUST be always accessible and not
+obscure or interfere with the available application display area.</p>
+<p>Device implementers SHOULD also provide a dedicated search key. Device
+implementers MAY also provide send and end keys for phone calls.</p>
+
+<a name="section-8.8"></a><h3>8.8. Wireless Data Networking</h3>
+<p>Device implementations MUST include support for wireless high-speed data
+networking. Specifically, device implementations MUST include support for at
+least one wireless data standard capable of 200Kbit/sec or greater. Examples of
+technologies that satisfy this requirement include EDGE, HSPA, EV-DO, 802.11g, etc.</p>
+<p>If a device implementation includes a particular modality for which the
+Android SDK includes an API (that is, WiFi, GSM, or CDMA), the implementation
+MUST support the API.</p>
+<p>Devices MAY implement more than one form of wireless data connectivity.
+Devices MAY implement wired data connectivity (such as Ethernet), but MUST
+nonetheless include at least one form of wireless connectivity, as above.</p>
+
+<a name="section-8.9"></a><h3>8.9. Camera</h3>
+<p>Device implementations MUST include a rear-facing camera. The included
+rear-facing camera:</p>
+<ul>
+<li>MUST have a resolution of at least 2 megapixels</li>
+<li>SHOULD have either hardware auto-focus, or software auto-focus implemented
+in the camera driver (transparent to application software)</li>
+<li>MAY have fixed-focus or EDOF (extended depth of field) hardware</li>
+<li>MAY include a flash. If the Camera includes a flash, the flash lamp MUST
+NOT be lit while an android.hardware.Camera.PreviewCallback instance has been
+registered on a Camera preview surface, unless the application has explicitly
+enabled the flash by enabling the <code>FLASH_MODE_AUTO</code> or
+<code>FLASH_MODE_ON</code> attributes of a <code>Camera.Parameters</code>
+object. Note that this constraint does not apply to the device's built-in
+system camera application, but only to third-party applications using
+<code>Camera.PreviewCallback</code>.</li>
+</ul>
+<p>Device implementations MUST implement the following behaviors for the
+camera-related APIs:</p>
+<ol>
+<li>If an application has never called
+android.hardware.Camera.Parameters.setPreviewFormat(int), then the device MUST
+use android.hardware.PixelFormat.YCbCr_420_SP for preview data provided to
+application callbacks.</li>
+<li>If an application registers an android.hardware.Camera.PreviewCallback
+instance and the system calls the onPreviewFrame() method when the preview
+format is YCbCr_420_SP, the data in the byte[] passed into onPreviewFrame()
+must further be in the NV21 encoding format. (This is the format used natively
+by the 7k hardware family.) That is, NV21 MUST be the default.</li>
+</ol>
+<p>Device implementations MUST implement the full Camera API included in the
+Android 2.2 SDK documentation [<a href="#resources27">Resources, 27</a>]),
+regardless of whether the device includes hardware autofocus or other
+capabilities. For instance, cameras that lack autofocus MUST still call any
+registered <code>android.hardware.Camera.AutoFocusCallback</code> instances (even though
+this has no relevance to a non-autofocus camera.)</p>
+<p>Device implementations MUST recognize and honor each parameter name defined
+as a constant on the <code>android.hardware.Camera.Parameters</code> class, if the
+underlying hardware supports the feature. If the device hardware does not
+support a feature, the API must behave as documented. Conversely, Device
+implementations MUST NOT honor or recognize string constants passed
+to the <code>android.hardware.Camera.setParameters()</code> method other than
+those documented as constants on the
+<code>android.hardware.Camera.Parameters</code>. That is,
+device implementations MUST support all standard Camera parameters if the
+hardware allows, and MUST NOT support custom Camera parameter types.</p>
+<p>Device implementations MAY include a front-facing camera. However, if
+a device implementation includes a front-facing camera, the camera API as
+implemented on the device MUST NOT use the front-facing camera by default.
+That is, the camera API in Android 2.2 is for rear-facing cameras only, and
+device implementations MUST NOT reuse or overload the API to act on a
+front-facing camera, if one is present. Note that any custom APIs added by
+device implementers to support front-facing cameras MUST abide by sections 3.5
+and 3.6; for instance, if a custom <code>android.hardware.Camera</code> or
+<code>Camera.Parameters</code> subclass is provided to support front-facing
+cameras, it MUST NOT be located in an existing namespace, as described by
+sections 3.5 and 3.6. Note that the inclusion of a front-facing camera does
+not meet the requirement that devices include a rear-facing camera.</p>
+
+<a name="section-8.10"></a><h3>8.10. Accelerometer</h3>
+<p>Device implementations MUST include a 3-axis accelerometer and MUST be able
+to deliver events at 50 Hz or greater. The coordinate system used by the
+accelerometer MUST comply with the Android sensor coordinate system as detailed
+in the Android APIs (see [<a href="#resources28">Resources, 28</a>]).</p>
+
+<a name="section-8.11"></a><h3>8.11. Compass</h3>
+<p>Device implementations MUST include a 3-axis compass and MUST be able to
+deliver events 10 Hz or greater. The coordinate system used by the compass
+MUST comply with the Android sensor coordinate system as defined in the Android
+API (see [<a href="#resources28">Resources, 28</a>]).</p>
+
+<a name="section-8.12"></a><h3>8.12. GPS</h3>
+<p>Device implementations MUST include a GPS receiver, and SHOULD include
+some form of "assisted GPS" technique to minimize GPS lock-on time.</p>
+
+<a name="section-8.13"></a><h3>8.13. Telephony</h3>
+<p>Android 2.2 MAY be used on devices that do not include telephony hardware.
+That is, Android 2.2 is compatible with devices that are not phones.
+However, if a device implementation does include GSM or CDMA telephony, it
+MUST implement the full support for the API for that technology. Device
+implementations that do not include telephony hardware MUST implement the full
+APIs as no-ops.</p>
+<p>See also Section 8.8, Wireless Data Networking.</p>
+
+<a name="section-8.14"></a><h3>8.14. Memory and Storage</h3>
+<p>Device implementations MUST have at least 92MB of memory available to the
+kernel and userspace. The 92MB MUST be in addition to any memory dedicated to
+hardware components such as radio, memory, and so on that is not under the
+kernel's control.</p>
+<p>Device implementations MUST have at least 150MB of non-volatile storage
+available for user data. That is, the <code>/data</code> partition MUST be at
+least 150MB.</p>
+<p>Beyond the requirements above, device implementations SHOULD have at least
+128MB of memory available to kernel and userspace, in addition to any memory
+dedicated to hardware components that is not under the kernel's control.
+Device implementations SHOULD have at least 1GB of non-volatile storage
+available for user data. Note that these higher requirements are planned to
+become hard minimums in a future version of Android. Device implementations are
+strongly encouraged to meet these requirements now, or else they may not be
+eligible for compatibility for a future version of Android.</p>
+
+<a name="section-8.15"></a><h3>8.15. Application Shared Storage</h3>
+<p>Device implementations MUST offer shared storage for applications. The
+shared storage provided MUST be at least 2GB in size.</p>
+<p>Device implementations MUST be configured with shared storage mounted by
+default, "out of the box". If the shared storage is not mounted on the Linux
+path <code>/sdcard</code>, then the device MUST include a Linux symbolic link
+from <code>/sdcard</code> to the actual mount point.</p>
+<p>Device implementations MUST enforce as documented the
+<code>android.permission.WRITE_EXTERNAL_STORAGE</code> permission on this
+shared storage. Shared storage MUST otherwise be writable by any application
+that obtains that permission.</p>
+<p>Device implementations MAY have hardware for user-accessible removable
+storage, such as a Secure Digital card. Alternatively, device implementations
+MAY allocate internal (non-removable) storage as shared storage for apps.</p>
+<p>Regardless of the form of shared storage used, the shared storage MUST
+implement USB mass storage, as described in Section 8.6. As shipped out of the
+box, the shared storage MUST be mounted with the FAT filesystem.</p>
+<p>It is illustrative to consider two common examples. If a device
+implementation includes an SD card slot to satisfy the shared storage
+requirement, a FAT-formatted SD card 2GB in size or larger MUST be included
+with the device as sold to users, and MUST be mounted by default.
+Alternatively, if a device implementation uses internal fixed storage to
+satisfy this requirement, that storage MUST be 2GB in size or larger,
+formatted as FAT, and mounted on <code>/sdcard</code> (or <code>/sdcard</code>
+MUST be a symbolic link to the physical location if it is mounted elsewhere.)</p>
+<p>Device implementations that include multiple shared storage paths (such as
+both an SD card slot and shared internal storage) SHOULD modify the core
+applications such as the media scanner and ContentProvider to transparently
+support files placed in both locations.</p>
+
+<a name="section-8.16"></a><h3>8.16. Bluetooth</h3>
+<p>Device implementations MUST include a Bluetooth transceiver. Device
+implementations MUST enable the RFCOMM-based Bluetooth API as described in the
+SDK documentation [<a href="#resources30">Resources, 30</a>]. Device
+implementations SHOULD implement relevant Bluetooth profiles, such as A2DP,
+AVRCP, OBEX, etc. as appropriate for the device.</p>
+<p>The Compatibility Test Suite includes cases that cover basic operation of
+the Android RFCOMM Bluetooth API. However, since Bluetooth is a communications
+protocol between devices, it cannot be fully tested by unit tests running on a
+single device. Consequently, device implementations MUST also pass the
+human-driven Bluetooth test procedure described in Appendix A.</p>
+
+<a name="section-9"></a><h2>9. Performance Compatibility</h2>
+<p>One of the goals of the Android Compatibility Program is to enable
+consistent application experience to consumers. Compatible implementations
+must ensure not only that applications simply run correctly on the device, but
+that they do so with reasonable performance and overall good user experience.
+Device implementations MUST meet the key performance metrics of an Android 2.2
+compatible device defined in the table below:</p>
+<table><tbody><tr>
+<td><b>Metric</b></td>
+<td><b>Performance Threshold</b></td>
+<td><b>Comments</b></td>
+</tr>
+<tr>
+<td>Application Launch Time</td>
+<td>The following applications should launch within the specified time.<ul>
+<li>Browser: less than 1300ms</li>
+<li>MMS/SMS: less than 700ms</li>
+<li>AlarmClock: less than 650ms</li>
+</ul></td>
+<td>The launch time is measured as the total time to
+complete loading the default activity for the application, including the time
+it takes to start the Linux process, load the Android package into the Dalvik
+VM, and call onCreate.</td>
+</tr>
+<tr>
+<td>Simultaneous Applications</td>
+<td>When multiple applications have been launched, re-launching an
+already-running application after it has been launched must take less than the
+original launch time.</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+
+<a name="section-10"></a><h2>10. Security Model Compatibility</h2>
+<p>Device implementations MUST implement a security model consistent with the
+Android platform security model as defined in Security and Permissions
+reference document in the APIs [<a href="#resources29">Resources, 29</a>] in the
+Android developer documentation. Device implementations MUST support
+installation of self-signed applications without requiring any additional
+permissions/certificates from any third parties/authorities. Specifically,
+compatible devices MUST support the security mechanisms described in the
+follow sub-sections.</p>
+<a name="section-10.1"></a><h3>10.1. Permissions</h3>
+<p>Device implementations MUST support the Android permissions model as
+defined in the Android developer documentation [<a
+href="#resources29">Resources, 29</a>]. Specifically,
+implementations MUST enforce each permission defined as described in the SDK
+documentation; no permissions may be omitted, altered, or ignored.
+Implementations MAY add additional permissions, provided the new permission ID
+strings are not in the android.* namespace.</p>
+<a name="section-10.2"></a><h3>10.2. UID and Process Isolation</h3>
+<p>Device implementations MUST support the Android application sandbox model,
+in which each application runs as a unique Unix-style UID and in a separate
+process. Device implementations MUST support running multiple applications as
+the same Linux user ID, provided that the applications are properly signed and
+constructed, as defined in the Security and Permissions reference [<a
+href="#resources29">Resources, 29</a>].</p>
+<a name="section-10.3"></a><h3>10.3. Filesystem Permissions</h3>
+<p>Device implementations MUST support the Android file access permissions
+model as defined in as defined in the Security and Permissions reference [<a
+href="#resources29">Resources, 29</a>].</p>
+<a name="section-10.4"></a><h3>10.4. Alternate Execution Environments</h3>
+<p>Device implementations MAY include runtime environments that execute
+applications using some other software or technology than the Dalvik virtual
+machine or native code. However, such alternate execution environments MUST
+NOT compromise the Android security model or the security of installed Android
+applications, as described in this section.</p>
+<p>Alternate runtimes MUST themselves be Android applications, and abide by
+ the standard Android security model, as described elsewhere in Section 10.</p>
+<p>Alternate runtimes MUST NOT be granted access to resources protected by
+ permissions not requested in the runtime's AndroidManifest.xml file via the
+ <code><uses-permission></code> mechanism.</p>
+<p>Alternate runtimes MUST NOT permit applications to make use of features
+ protected by Android permissions restricted to system applications.</p>
+<p>Alternate runtimes MUST abide by the Android sandbox model. Specifically:</p>
+<ul>
+<li>Alternate runtimes SHOULD install apps via the PackageManager into
+ separate Android sandboxes (that is, Linux user IDs, etc.)</li>
+<li>Alternate runtimes MAY provide a single Android sandbox shared by all
+ applications using the alternate runtime.</li>
+<li>Alternate runtimes and installed applications using an alternate runtime
+ MUST NOT reuse the sandbox of any other app installed on the device, except
+ through the standard Android mechanisms of shared user ID and signing
+ certificate</li>
+<li>Alternate runtimes MUST NOT launch with, grant, or be granted access to
+ the sandboxes corresponding to other Android applications.</li>
+</ul>
+<p>Alternate runtimes MUST NOT be launched with, be granted, or grant to other
+ applications any privileges of the superuser (root), or of any other user ID.</p>
+<p>The .apk files of alternate runtimes MAY be included in the system image of
+ a device implementation, but MUST be signed with a key distinct
+ from the key used to sign other applications included with the device
+ implementation.</p>
+<p>When installing applications, alternate runtimes MUST obtain user consent
+ for the Android permissions used by the application. That is, if an
+ application needs to make use of a device resource for which there is a
+ corresponding Android permission (such as Camera, GPS, etc.), the alternate
+ runtime MUST inform the user that the application will be able to access
+ that resource. If the runtime environment does not record application
+ capabilities in this manner, the runtime environment MUST list all
+ permissions held by the runtime itself when installing any application
+ using that runtime.</p>
+
+<a name="section-11"></a><h2>11. Compatibility Test Suite</h2>
+<p>Device implementations MUST pass the Android Compatibility Test Suite (CTS)
+[<a href="#resources02">Resources, 2</a>] available from the Android Open Source
+Project, using the final shipping software on the device. Additionally, device
+implementers SHOULD use the reference implementation in the Android Open
+Source tree as much as possible, and MUST ensure compatibility in cases of
+ambiguity in CTS and for any reimplementations of parts of the reference
+source code.</p>
+<p>The CTS is designed to be run on an actual device. Like any software, the
+CTS may itself contain bugs. The CTS will be versioned independently of this
+Compatibility Definition, and multiple revisions of the CTS may be released
+for Android 2.2. Device implementations MUST pass the latest CTS version
+available at the time the device software is completed.</p>
+
+<a name="section-12"></a><h2>12. Updatable Software</h2>
+<p>Device implementations MUST include a mechanism to replace the entirety of
+the system software. The mechanism need not perform "live" upgrades -- that
+is, a device restart MAY be required.</p>
+<p>Any method can be used, provided that it can replace the entirety of the
+software preinstalled on the device. For instance, any of the following
+approaches will satisfy this requirement:</p>
+<ul>
+<li>Over-the-air (OTA) downloads with offline update via reboot</li>
+<li>"Tethered" updates over USB from a host PC</li>
+<li>"Offline" updates via a reboot and update from a file on removable
+storage</li>
+</ul>
+<p>The update mechanism used MUST support updates without wiping user data.
+Note that the upstream Android software includes an update mechanism that
+satisfies this requirement.</p>
+<p>If an error is found in a device implementation after it has been released
+but within its reasonable product lifetime that is determined in consultation
+with the Android Compatibility Team to affect the compatibility of thid-party
+applications, the device implementer MUST correct the error via a software
+update available that can be applied per the mechanism just described.</p>
+
+<a name="section-13"></a><h2>13. Contact Us</h2>
+<p>You can contact the document authors at <a
+href="mailto:compatibility@android.com">compatibility@android.com</a> for
+clarifications and to bring up any issues that you think the document does not
+cover.</p>
+
+<div style="page-break-before: always;"></div>
+
+<a name="appendix-A"></a><h2>Appendix A - Bluetooth Test Procedure</h2>
+<p>The Compatibility Test Suite includes cases that cover basic operation of
+the Android RFCOMM Bluetooth API. However, since Bluetooth is a communications
+protocol between devices, it cannot be fully tested by unit tests running on a
+single device. Consequently, device implementations MUST also pass the
+human-driven Bluetooth test procedure described below.</p>
+<p>The test procedure is based on the BluetoothChat sample app included in the
+Android open-source project tree. The procedure requires two devices:</p>
+<ul>
+<li>a candidate device implementation running the software build to be tested</li>
+<li>a separate device implementation already known to be compatible, and of a
+ model from the device implementation being tested -- that is, a "known
+ good" device implementation</li>
+</ul>
+<p>The test procedure below refers to these devices as the "candidate" and "known
+good" devices, respectively.</p>
+<h3>Setup and Installation</h3>
+<ol>
+<li>Build BluetoothChat.apk via 'make samples' from an Android source code tree.</li>
+<li>Install BluetoothChat.apk on the known-good device.</li>
+<li>Install BluetoothChat.apk on the candidate device.</li>
+</ol>
+<h3>Test Bluetooth Control by Apps</h3>
+<ol>
+<li>Launch BluetoothChat on the candidate device, while Bluetooth is disabled.</li>
+<li>Verify that the candidate device either turns on Bluetooth, or prompts the user with a dialog to turn on Bluetooth.</li>
+</ol>
+<h3>Test Pairing and Communication</h3>
+<ol>
+<li>Launch the Bluetooth Chat app on both devices.</li>
+<li>Make the known-good device discoverable from within BluetoothChat (using the Menu).</li>
+<li>On the candidate device, scan for Bluetooth devices from within BluetoothChat (using the Menu) and pair with the known-good device.</li>
+<li>Send 10 or more messages from each device, and verify that the other device receives them correctly.</li>
+<li>Close the BluetoothChat app on both devices by pressing <b>Home</b>.</li>
+<li>Unpair each device from the other, using the device Settings app.</li>
+</ol>
+<h3>Test Pairing and Communication in the Reverse Direction</h3>
+<ol>
+<li>Launch the Bluetooth Chat app on both devices.</li>
+<li>Make the candidate device discoverable from within BluetoothChat (using the Menu).</li>
+<li>On the known-good device, scan for Bluetooth devices from within BluetoothChat (using the Menu) and pair with the candidate device.</li>
+<li>Send 10 or messages from each device, and verify that the other device receives them correctly.</li>
+<li>Close the Bluetooth Chat app on both devices by pressing Back repeatedly to get to the Launcher.</li>
+</ol>
+<h3>Test Re-Launches</h3>
+<ol>
+<li>Re-launch the Bluetooth Chat app on both devices.</li>
+<li>Send 10 or messages from each device, and verify that the other device receives them correctly.</li>
+</ol>
+<p>Note: the above tests have some cases which end a test section by using
+Home, and some using Back. These tests are not redundant and are not optional:
+the objective is to verify that the Bluetooth API and stack works correctly
+both when Activities are explicitly terminated (via the user pressing Back,
+which calls finish()), and implicitly sent to background (via the user
+pressing Home.) Each test sequence MUST be performed as described.</p>
+<div id="footerContent">
+<pdf:pagenumber/>
+</div>
+</body>
+</html>
diff --git a/src/compatibility/2.3/android-2.3-cdd.xhtml b/src/compatibility/2.3/android-2.3-cdd.xhtml
new file mode 100644
index 0000000..fd6ed7c
--- /dev/null
+++ b/src/compatibility/2.3/android-2.3-cdd.xhtml
@@ -0,0 +1,1866 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>Android 2.3 Compatibility Definition</title>
+<link rel="stylesheet" type="text/css" href="cdd.css"/>
+</head>
+<body>
+<div><img src="header.jpg" alt="Android logo"/></div>
+<h1>Android 2.3 Compatibility Definition</h1>
+<!-- <span style="color: red; font-weight: bold;"><h2>DRAFT</h2></span> -->
+<p>Copyright © 2010, Google Inc. All rights reserved.<br/>
+<a href="mailto:compatibility@android.com">compatibility@android.com</a>
+</p>
+
+<h2> Table of Contents</h2>
+<div style="margin-left: 2em;">
+ <a href="#section-1">1. Introduction</a><br/>
+ <a href="#section-2">2. Resources</a><br/>
+ <a href="#section-3">3. Software</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.1">3.1. Managed API Compatibility</a><br/>
+ <a href="#section-3.2">3.2. Soft API Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.2.1">3.2.1. Permissions</a><br/>
+ <a href="#section-3.2.3">3.2.2. Build Parameters</a><br/>
+ <a href="#section-3.2.3">3.2.3. Intent Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.2.3.1">3.2.3.1. Core Application Intents</a><br/>
+ <a href="#section-3.2.3.2">3.2.3.2. Intent Overrides</a><br/>
+ <a href="#section-3.2.3.3">3.2.3.3. Intent Namespaces</a><br/>
+ <a href="#section-3.2.3.4">3.2.3.4. Broadcast Intents</a><br/>
+ </div>
+ </div>
+ <a href="#section-3.3">3.3. Native API Compatibility</a><br/>
+ <a href="#section-3.4">3.4. Web Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.4.1">3.4.1. WebView Compatibility</a><br/>
+ <a href="#section-3.4.2">3.4.2. Browser Compatibility</a><br/>
+ </div>
+ <a href="#section-3.5">3.5. API Behavioral Compatibility</a><br/>
+ <a href="#section-3.6">3.6. API Namespaces</a><br/>
+ <a href="#section-3.7">3.7. Virtual Machine Compatibility</a><br/>
+ <a href="#section-3.8">3.8. User Interface Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.8.1">3.8.1. Widgets</a><br/>
+ <a href="#section-3.8.2">3.8.2. Notifications</a><br/>
+ <a href="#section-3.8.3">3.8.3. Search</a><br/>
+ <a href="#section-3.8.4">3.8.4. Toasts</a><br/>
+ <a href="#section-3.8.5">3.8.5. Live Wallpapers</a><br/>
+ </div>
+ </div>
+ <a href="#section-4">4. Application Packaging Compatibility</a><br/>
+ <a href="#section-5">5. Multimedia Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-5.1">5.1. Media Codecs</a><br/>
+ <a href="#section-5.1.1">5.1.1. Media Decoders</a><br/>
+ <a href="#section-5.1.2">5.1.2. Media Encoders</a><br/>
+ <a href="#section-5.2">5.2. Audio Recording</a><br/>
+ <a href="#section-5.3">5.3. Audio Latency</a><br/>
+ </div>
+ <a href="#section-6">6. Developer Tool Compatibility</a><br/>
+ <a href="#section-7">7. Hardware Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.1">7.1. Display and Graphics</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.1.1">7.1.1. Screen Configurations</a><br/>
+ <a href="#section-7.1.2">7.1.2. Display Metrics</a><br/>
+ <a href="#section-7.1.3">7.1.3. Declared Screen Support</a><br/>
+ <a href="#section-7.1.4">7.1.4. Screen Orientation</a><br/>
+ <a href="#section-7.1.5">7.1.5. 3D Graphics Accleration</a><br/>
+ </div>
+ <a href="#section-7.2">7.2. Input Devices</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.2.1">7.2.1. Keyboard</a><br/>
+ <a href="#section-7.2.2">7.2.2. Non-touch Navigation</a><br/>
+ <a href="#section-7.2.3">7.2.3. Navigation keys</a><br/>
+ <a href="#section-7.2.4">7.2.4. Touchscreen input</a><br/>
+ </div>
+ <a href="#section-7.3">7.3. Sensors</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.3.1">7.3.1. Accelerometer</a><br/>
+ <a href="#section-7.3.2">7.3.2. Magnetometer</a><br/>
+ <a href="#section-7.3.3">7.3.3. GPS</a><br/>
+ <a href="#section-7.3.4">7.3.4. Gyroscope</a><br/>
+ <a href="#section-7.3.5">7.3.5. Barometer</a><br/>
+ <a href="#section-7.3.6">7.3.6. Thermometer</a><br/>
+ <a href="#section-7.3.7">7.3.7. Photometer</a><br/>
+ <a href="#section-7.3.8">7.3.8. Proximity Sensor</a><br/>
+ </div>
+ <a href="#section-7.4">7.4. Data Connectivity</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.4.1">7.4.1. Telephony</a><br/>
+ <a href="#section-7.4.2">7.4.2. IEEE 802.11 (WiFi)</a><br/>
+ <a href="#section-7.4.3">7.4.3. Bluetooth</a><br/>
+ <a href="#section-7.4.4">7.4.4. Near-Field Communications</a><br/>
+ <a href="#section-7.4.5">7.4.5. Minimum Network Capability</a><br/>
+ </div>
+ <a href="#section-7.5">7.5. Cameras</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.5.1">7.5.1. Rear-Facing Camera</a><br/>
+ <a href="#section-7.5.2">7.5.2. Front-Facing Camera</a><br/>
+ <a href="#section-7.5.3">7.5.3. Camera API Behavior</a><br/>
+ <a href="#section-7.5.4">7.5.4. Camera Orientation</a><br/>
+ </div>
+ <a href="#section-7.6">7.6. Memory and Storage</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.6.1">7.6.1. Minimum Memory and Storage</a><br/>
+ <a href="#section-7.6.2">7.6.2. Application Shared Storage</a><br/>
+ </div>
+ <a href="#section-7.7">7.7. USB</a><br/>
+ </div>
+ <a href="#section-8">8. Performance Compatibility</a><br/>
+ <a href="#section-9">9. Security Model Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-9.1">9.1. Permissions</a><br/>
+ <a href="#section-9.2">9.2. UID and Process Isolation</a><br/>
+ <a href="#section-9.3">9.3. Filesystem Permissions</a><br/>
+ <a href="#section-9.4">9.4. Alternate Execution Environments</a><br/>
+ </div>
+ <a href="#section-10">10. Software Compatibility Testing</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-10.1">10.1. Compatibility Test Suite</a><br/>
+ <a href="#section-10.2">10.2. CTS Verifier</a><br/>
+ <a href="#section-10.3">10.3. Reference Applications</a><br/>
+ </div>
+ <a href="#section-11">11. Updatable Software</a><br/>
+ <a href="#section-12">12. Contact Us</a><br/>
+ <a href="#appendix-A">Appendix A - Bluetooth Test Procedure</a><br/>
+</div>
+
+<div style="page-break-before: always;"></div>
+
+<a name="section-1"></a><h2>1. Introduction</h2>
+<p>This document enumerates the requirements that must be met in order for
+mobile phones to be compatible with Android 2.3.</p>
+<p>The use of "must", "must not", "required", "shall", "shall not", "should",
+"should not", "recommended", "may" and "optional" is per the IETF standard
+defined in RFC2119 [<a href="#resources01">Resources, 1</a>].</p>
+<p>As used in this document, a "device implementer" or "implementer" is a
+person or organization developing a hardware/software solution running Android
+2.3. A "device implementation" or "implementation" is the hardware/software
+solution so developed.</p>
+<p>To be considered compatible with Android 2.3, device implementations
+MUST meet the requirements presented in this Compatibility Definition,
+including any documents incorporated via reference.</p>
+<p>Where this definition or the software tests described in <a
+href="#section-10">Section 10</a> is silent, ambiguous, or incomplete, it is
+the responsibility of the device implementer to ensure compatibility with
+existing implementations. For this reason, the Android Open Source Project [<a
+href="#resources03">Resources, 3</a>] is both the reference and preferred
+implementation of Android. Device implementers are strongly encouraged to base
+their implementations to the greatest extent possible on the "upstream" source
+code available from the Android Open Source Project. While some components can
+hypothetically be replaced with alternate implementations this practice is
+strongly discouraged, as passing the software tests will become substantially
+more difficult. It is the implementer's responsibility to ensure full
+behavioral compatibility with the standard Android implementation, including
+and beyond the Compatibility Test Suite. Finally, note that certain component
+substitutions and modifications are explicitly forbidden by this document.</p>
+<p>Please note that this Compatibility Definition is issued to correspond with
+the 2.3.3 update to Android, which is API level 10. This Definition obsoletes
+and replaces the Compatibility Definition for Android 2.3 versions prior to
+2.3.3. (That is, versions 2.3.1 and 2.3.2 are obsolete.) Future
+Android-compatible devices running Android 2.3 MUST ship with version 2.3.3 or
+later.</p>
+<a name="section-2"></a><h2>2. Resources</h2>
+<ol>
+<a name="resources01"></a><li>IETF RFC2119 Requirement Levels: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a></li>
+<a name="resources02"></a><li>Android Compatibility Program Overview: <a href="http://source.android.com/compatibility/index.html">http://source.android.com/compatibility/index.html</a></li>
+<a name="resources03"></a><li>Android Open Source Project: <a href="http://source.android.com/">http://source.android.com/</a></li>
+<a name="resources04"></a><li>API definitions and documentation: <a href="http://developer.android.com/reference/packages.html">http://developer.android.com/reference/packages.html</a></li>
+<a name="resources05"></a><li>Android Permissions reference: <a href="http://developer.android.com/reference/android/Manifest.permission.html">http://developer.android.com/reference/android/Manifest.permission.html</a></li>
+<a name="resources06"></a><li>android.os.Build reference: <a href="http://developer.android.com/reference/android/os/Build.html">http://developer.android.com/reference/android/os/Build.html</a></li>
+<a name="resources07"></a><li>Android 2.3 allowed version strings: <a href="http://source.android.com/compatibility/2.3/versions.html">http://source.android.com/compatibility/2.3/versions.html</a></li>
+<a name="resources08"></a><li>android.webkit.WebView class: <a href="http://developer.android.com/reference/android/webkit/WebView.html">http://developer.android.com/reference/android/webkit/WebView.html</a></li>
+<a name="resources09"></a><li>HTML5: <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">http://www.whatwg.org/specs/web-apps/current-work/multipage/</a></li>
+<a name="resources10"></a><li>HTML5 offline capabilities: <a href="http://dev.w3.org/html5/spec/Overview.html#offline">http://dev.w3.org/html5/spec/Overview.html#offline</a></li>
+<a name="resources11"></a><li>HTML5 video tag: <a href="http://dev.w3.org/html5/spec/Overview.html#video">http://dev.w3.org/html5/spec/Overview.html#video</a></li>
+<a name="resources12"></a><li>HTML5/W3C geolocation API: <a href="http://www.w3.org/TR/geolocation-API/">http://www.w3.org/TR/geolocation-API/</a></li>
+<a name="resources13"></a><li>HTML5/W3C webdatabase API: <a href="http://www.w3.org/TR/webdatabase/">http://www.w3.org/TR/webdatabase/</a></li>
+<a name="resources14"></a><li>HTML5/W3C IndexedDB API: <a href="http://www.w3.org/TR/IndexedDB/">http://www.w3.org/TR/IndexedDB/</a></li>
+<a name="resources15"></a><li>Dalvik Virtual Machine specification: available in the Android source code, at dalvik/docs</li>
+<a name="resources16"></a><li>AppWidgets: <a href="http://developer.android.com/guide/practices/ui_guidelines/widget_design.html">http://developer.android.com/guide/practices/ui_guidelines/widget_design.html</a></li>
+<a name="resources17"></a><li>Notifications: <a href="http://developer.android.com/guide/topics/ui/notifiers/notifications.html">http://developer.android.com/guide/topics/ui/notifiers/notifications.html</a></li>
+<a name="resources18"></a><li>Application Resources: <a href="http://code.google.com/android/reference/available-resources.html">http://code.google.com/android/reference/available-resources.html</a></li>
+<a name="resources19"></a><li>Status Bar icon style guide: <a href="http://developer.android.com/guide/practices/ui_guidelines/icon_design.html#statusbarstructure">http://developer.android.com/guide/practices/ui_guideline /icon_design.html#statusbarstructure</a></li>
+<a name="resources20"></a><li>Search Manager: <a href="http://developer.android.com/reference/android/app/SearchManager.html">http://developer.android.com/reference/android/app/SearchManager.html</a></li>
+<a name="resources21"></a><li>Toasts: <a href="http://developer.android.com/reference/android/widget/Toast.html">http://developer.android.com/reference/android/widget/Toast.html</a></li>
+<a name="resources22"></a><li>Live Wallpapers: <a href="http://developer.android.com/resources/articles/live-wallpapers.html">http://developer.android.com/resources/articles/live-wallpapers.html</a></li>
+<a name="resources23"></a><li>Reference tool documentation (for adb, aapt, ddms): <a href="http://developer.android.com/guide/developing/tools/index.html">http://developer.android.com/guide/developing/tools/index.html</a></li>
+<a name="resources24"></a><li>Android apk file description: <a href="http://developer.android.com/guide/topics/fundamentals.html">http://developer.android.com/guide/topics/fundamentals.html</a></li>
+<a name="resources25"></a><li>Manifest files: <a href="http://developer.android.com/guide/topics/manifest/manifest-intro.html">http://developer.android.com/guide/topics/manifest/manifest-intro.html</a></li>
+<a name="resources26"></a><li>Monkey testing tool: <a href="http://developer.android.com/guide/developing/tools/monkey.html">http://developer.android.com/guide/developing/tools/monkey.html</a></li>
+<a name="resources27"></a><li>Android Hardware Features List: <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html">http://developer.android.com/reference/android/content/pm/PackageManager.html</a></li>
+<a name="resources28"></a><li>Supporting Multiple Screens: <a href="http://developer.android.com/guide/practices/screens_support.html">http://developer.android.com/guide/practices/screens_support.html</a></li>
+<a name="resources29"></a><li>android.util.DisplayMetrics: <a href="http://developer.android.com/reference/android/util/DisplayMetrics.html">http://developer.android.com/reference/android/util/DisplayMetrics.html</a></li>
+<a name="resources30"></a><li>android.content.res.Configuration: <a href="http://developer.android.com/reference/android/content/res/Configuration.html">http://developer.android.com/reference/android/content/res/Configuration.html</a></li>
+<a name="resources31"></a><li>Sensor coordinate space: <a href="http://developer.android.com/reference/android/hardware/SensorEvent.html">http://developer.android.com/reference/android/hardware/SensorEvent.html</a></li>
+<a name="resources32"></a><li>Bluetooth API: <a href="http://developer.android.com/reference/android/bluetooth/package-summary.html">http://developer.android.com/reference/android/bluetooth/package-summary.html</a></li>
+<a name="resources33"></a><li>NDEF Push Protocol: <a href="http://source.android.com/compatibility/ndef-push-protocol.pdf">http://source.android.com/compatibility/ndef-push-protocol.pdf</a></li>
+<a name="resources34"></a><li>MIFARE MF1S503X: <a href="http://www.nxp.com/documents/data_sheet/MF1S503x.pdf">http://www.nxp.com/documents/data_sheet/MF1S503x.pdf</a></li>
+<a name="resources35"></a><li>MIFARE MF1S703X: <a href="http://www.nxp.com/documents/data_sheet/MF1S703x.pdf">http://www.nxp.com/documents/data_sheet/MF1S703x.pdf</a></li>
+<a name="resources36"></a><li>MIFARE MF0ICU1: <a href="http://www.nxp.com/documents/data_sheet/MF0ICU1.pdf">http://www.nxp.com/documents/data_sheet/MF0ICU1.pdf</a></li>
+<a name="resources37"></a><li>MIFARE MF0ICU2: <a href="http://www.nxp.com/documents/short_data_sheet/MF0ICU2_SDS.pdf">http://www.nxp.com/documents/short_data_sheet/MF0ICU2_SDS.pdf</a></li>
+<a name="resources38"></a><li>MIFARE AN130511: <a href="http://www.nxp.com/documents/application_note/AN130511.pdf">http://www.nxp.com/documents/application_note/AN130511.pdf</a></li>
+<a name="resources39"></a><li>MIFARE AN130411: <a href="http://www.nxp.com/documents/application_note/AN130411.pdf">http://www.nxp.com/documents/application_note/AN130411.pdf</a></li>
+<a name="resources40"></a><li>Camera orientation API: <a href="http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)">http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)</a></li>
+<a name="resources41"></a><li>android.hardware.Camera: <a href="http://developer.android.com/reference/android/hardware/Camera.html">http://developer.android.com/reference/android/hardware/Camera.html</a></li>
+<a name="resources42"></a><li>Android Security and Permissions reference: <a href="http://developer.android.com/guide/topics/security/security.html">http://developer.android.com/guide/topics/security/security.html</a></li>
+<a name="resources43"></a><li>Apps for Android: <a href="http://code.google.com/p/apps-for-android">http://code.google.com/p/apps-for-android</a></li>
+</ol>
+<p>Many of these resources are derived directly or indirectly from the Android
+2.3 SDK, and will be functionally identical to the information in that SDK's
+documentation. In any cases where this Compatibility Definition or the
+Compatibility Test Suite disagrees with the SDK documentation, the SDK
+documentation is considered authoritative. Any technical details provided in
+the references included above are considered by inclusion to be part of this
+Compatibility Definition.</p>
+
+<a name="section-3"></a><h2>3. Software</h2>
+<p>The Android platform includes a set of managed APIs, a set of native APIs,
+and a body of so-called "soft" APIs such as the Intent system and
+web-application APIs. This section details the hard and soft APIs that are
+integral to compatibility, as well as certain other relevant technical and
+user interface behaviors. Device implementations MUST comply with all the
+requirements in this section.</p>
+
+<a name="section-3.1"></a><h3>3.1. Managed API Compatibility</h3>
+<p>The managed (Dalvik-based) execution environment is the primary vehicle for
+Android applications. The Android application programming interface (API) is
+the set of Android platform interfaces exposed to applications running in the
+managed VM environment. Device implementations MUST provide complete
+implementations, including all documented behaviors, of any documented API
+exposed by the Android 2.3 SDK [<a href="#resources04">Resources, 4</a>].</p>
+<p>Device implementations MUST NOT omit any managed APIs, alter API interfaces
+or signatures, deviate from the documented behavior, or include no-ops, except
+where specifically allowed by this Compatibility Definition.</p>
+<p>This Compatibility Definition permits some types of hardware for which
+Android includes APIs to be omitted by device implementations. In such cases,
+the APIs MUST still be present and behave in a reasonable way. See Section 7
+for specific requirements for this scenario.</p>
+
+<a name="section-3.2"></a><h3>3.2. Soft API Compatibility</h3>
+<p>In addition to the managed APIs from Section 3.1, Android also includes a
+significant runtime-only "soft" API, in the form of such things such as
+Intents, permissions, and similar aspects of Android applications that cannot
+be enforced at application compile time. This section details the "soft" APIs
+and system behaviors required for compatibility with Android 2.3. Device
+implementations MUST meet all the requirements presented in this section.</p>
+<a name="section-3.2.1"></a><h4>3.2.1. Permissions</h4>
+<p>Device implementers MUST support and enforce all permission constants as
+documented by the Permission reference page [<a
+href="#resources05">Resources, 5</a>]. Note that Section 10 lists additional
+requirements related to the Android security model.</p>
+<a name="section-3.2.3"></a><h4>3.2.2. Build Parameters</h4>
+<p>The Android APIs include a number of constants on the <code>android.os.Build</code>
+class [<a href="#resources06">Resources, 6</a>] that are intended to describe
+the current device. To provide consistent, meaningful values across device
+implementations, the table below includes additional restrictions on the
+formats of these values to which device implementations MUST conform.</p>
+<table>
+<tbody>
+<tr>
+<td><b>Parameter</b></td>
+<td><b>Comments</b></td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.RELEASE</td>
+<td>The version of the currently-executing Android system, in human-readable
+format. This field MUST have one of the string values defined in [<a
+href="#resources07">Resources, 7</a>].</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.SDK</td>
+<td>The version of the currently-executing Android system, in a format
+accessible to third-party application code. For Android 2.3, this field MUST have
+the integer value 9.</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.INCREMENTAL</td>
+<td>A value chosen by the device implementer designating the specific build of
+the currently-executing Android system, in human-readable format. This value
+MUST NOT be re-used for different builds made available to end users. A typical use
+of this field is to indicate which build number or source-control change
+identifier was used to generate the build. There are no requirements on the
+specific format of this field, except that it MUST NOT be null or the empty
+string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.BOARD</td>
+<td>A value chosen by the device implementer identifying the specific internal
+hardware used by the device, in human-readable format. A possible use of this
+field is to indicate the specific revision of the board powering the device.
+The value of this field MUST be encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.BRAND</td>
+<td>A value chosen by the device implementer identifying the name of the
+company, organization, individual, etc. who produced the device, in
+human-readable format. A possible use of this field is to indicate the OEM
+and/or carrier who sold the device. The value of this field MUST be
+encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.DEVICE</td>
+<td>A value chosen by the device implementer identifying the specific
+configuration or revision of the body (sometimes called "industrial design")
+of the device. The value of this field MUST be encodable as 7-bit ASCII and
+match the regular expression <code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.FINGERPRINT</td>
+<td>A string that uniquely identifies this build. It SHOULD be reasonably
+human-readable. It MUST follow this template:
+<br/><code>$(BRAND)/$(PRODUCT)/$(DEVICE):$(VERSION.RELEASE)/$(ID)/$(VERSION.INCREMENTAL):$(TYPE)/$(TAGS)</code><br/>
+For example:
+<br/><code>acme/mydevice/generic/generic:2.3/ERC77/3359:userdebug/test-keys</code><br/>
+The fingerprint MUST NOT include whitespace characters. If other fields included in the
+template above have whitespace characters, they MUST be replaced in the build
+fingerprint with another character, such as the underscore ("_") character.
+The value of this field MUST be encodable as 7-bit ASCII.</td>
+</tr>
+<tr>
+<td>android.os.Build.HOST</td>
+<td>A string that uniquely identifies the host the build was built on, in
+human readable format. There are no requirements on the specific format of
+this field, except that it MUST NOT be null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.ID</td>
+<td>An identifier chosen by the device implementer to refer to a specific
+release, in human readable format. This field can be the same as
+android.os.Build.VERSION.INCREMENTAL, but SHOULD be a value sufficiently
+meaningful for end users to distinguish between software builds. The value of
+this field MUST be encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.MODEL</td>
+<td>A value chosen by the device implementer containing the name of the device
+as known to the end user. This SHOULD be the same name under which the device
+is marketed and sold to end users. There are no requirements on the specific
+format of this field, except that it MUST NOT be null or the empty string
+("").</td>
+</tr>
+<tr>
+<td>android.os.Build.PRODUCT</td>
+<td>A value chosen by the device implementer containing the development name
+or code name of the device. MUST be human-readable, but is not necessarily
+intended for view by end users. The value of this field MUST be
+encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.TAGS</td>
+<td>A comma-separated list of tags chosen by the device implementer that
+further distinguish the build. For example, "unsigned,debug". The value of
+this field MUST be encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.TIME</td>
+<td>A value representing the timestamp of when the build occurred.</td>
+</tr>
+<tr>
+<td>android.os.Build.TYPE</td>
+<td>A value chosen by the device implementer specifying the runtime
+configuration of the build. This field SHOULD have one of the values
+corresponding to the three typical Android runtime configurations: "user",
+"userdebug", or "eng". The value of this field MUST be
+encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.USER</td>
+<td>A name or user ID of the user (or automated user) that generated the
+build. There are no requirements on the specific format of this field, except
+that it MUST NOT be null or the empty string ("").</td>
+</tr>
+</tbody>
+</table>
+<a name="section-3.2.3"></a><h4>3.2.3. Intent Compatibility</h4>
+<p>Android uses Intents to achieve loosely-coupled integration between
+applications. This section describes requirements related to the Intent
+patterns that MUST be honored by device implementations. By "honored", it is
+meant that the device implementer MUST provide an Android Activity or Service
+that specifies a matching Intent filter and binds to and implements correct
+behavior for each specified Intent pattern.</p>
+<a name="section-3.2.3.1"></a><h4>3.2.3.1. Core Application Intents</h4>
+<p>The Android upstream project defines a number of core applications, such as
+a phone dialer, calendar, contacts book, music player, and so on. Device
+implementers MAY replace these applications with alternative versions.</p>
+<p>However, any such alternative versions MUST honor the same Intent patterns
+provided by the upstream project. For example, if a device contains an
+alternative music player, it must still honor the Intent pattern issued by
+third-party applications to pick a song.</p>
+<p>The following applications are considered core Android system
+applications:</p>
+<ul>
+<li>Desk Clock</li>
+<li>Browser</li>
+<li>Calendar</li>
+<li>Calculator</li>
+<!-- <li>Camera</li> -->
+<li>Contacts</li>
+<li>Email</li>
+<li>Gallery</li>
+<li>GlobalSearch</li>
+<li>Launcher</li>
+<!-- <li>LivePicker (that is, the Live Wallpaper picker application; MAY be omitted
+if the device does not support Live Wallpapers, per Section 3.8.5.)</li> -->
+<!-- <li>Messaging (AKA "Mms")</li> -->
+<li>Music</li>
+<!-- <li>Phone</li> -->
+<li>Settings</li>
+<!-- <li>SoundRecorder</li> -->
+</ul>
+<p>The core Android system applications include various Activity, or Service
+components that are considered "public". That is, the attribute
+"android:exported" may be absent, or may have the value "true".</p>
+<p>For every Activity or Service defined
+in one of the core Android system apps that is not marked as non-public via an
+android:exported attribute with the value "false", device implementations MUST
+include a compontent of the same type implementing the same Intent filter
+patterns as the core Android system app.</p>
+<p>In other words, a device implementation MAY replace core Android system
+apps; however, if it does, the device implementation MUST support all Intent
+patterns defined by each core Android system app being replaced.</p>
+<a name="section-3.2.3.2"></a><h4>3.2.3.2. Intent Overrides</h4>
+<p>As Android is an extensible platform, device implementers MUST allow each
+Intent pattern referenced in Section 3.2.3.1 to be overridden by third-party
+applications. The upstream Android open source project allows this by default;
+device implementers MUST NOT attach special privileges to system applications'
+use of these Intent patterns, or prevent third-party applications from binding
+to and assuming control of these patterns. This prohibition specifically
+includes but is not limited to disabling the "Chooser" user interface which
+allows the user to select between multiple applications which all handle the
+same Intent pattern.</p>
+<a name="section-3.2.3.3"></a><h4>3.2.3.3. Intent Namespaces</h4>
+<p>Device implementers MUST NOT include any Android component that honors any
+new Intent or Broadcast Intent patterns using an ACTION, CATEGORY, or other
+key string in the android.* namespace. Device implementers MUST NOT include
+any Android components that honor any new Intent or Broadcast Intent patterns
+using an ACTION, CATEGORY, or other key string in a package space belonging to
+another organization. Device implementers MUST NOT alter or extend any of the
+Intent patterns used by the core apps listed in Section 3.2.3.1.</p>
+<p>This prohibition is analogous to that specified for Java language classes
+in Section 3.6.</p>
+<a name="section-3.2.3.4"></a><h4>3.2.3.4. Broadcast Intents</h4>
+<p>Third-party applications rely on the platform to broadcast certain Intents
+to notify them of changes in the hardware or software environment.
+Android-compatible devices MUST broadcast the public broadcast Intents in
+response to appropriate system events. Broadcast Intents are described in the
+SDK documentation.</p>
+
+<a name="section-3.3"></a><h3>3.3. Native API Compatibility</h3>
+<p>Managed code running in Dalvik can call into native code provided in the
+application .apk file as an ELF .so file compiled for the appropriate device
+hardware architecture. As native code is highly dependent on the underlying
+processor technology, Android defines a number of Application Binary
+Interfaces (ABIs) in the Android NDK, in the file
+<code>docs/CPU-ARCH-ABIS.txt</code>. If a device implementation is compatible
+with one or more defined ABIs, it SHOULD implement compatibility with the
+Android NDK, as below.</p>
+<p>If a device implementation includes support for an Android ABI, it:</p>
+<ul>
+<li>MUST include support for code running in the managed environment to call
+into native code, using the standard Java Native Interface (JNI)
+semantics.</li>
+<li>MUST be source-compatible (i.e. header compatible) and binary-compatible
+(for the ABI) with each required library in the list below</li>
+<li>MUST accurately report the native Application Binary Interface (ABI)
+supported by the device, via the <code>android.os.Build.CPU_ABI</code>
+API</li>
+<li>MUST report only those ABIs documented in the latest version of the
+Android NDK, in the file <code>docs/CPU-ARCH-ABIS.txt</code></li>
+<li>SHOULD be built using the source code and header files available in the
+upstream Android open-source project</li>
+</ul>
+<p>The following native code APIs MUST be available to apps that include
+native code:</p>
+<ul>
+<li>libc (C library)</li>
+<li>libm (math library)</li>
+<li>Minimal support for C++</li>
+<li>JNI interface</li>
+<li>liblog (Android logging)</li>
+<li>libz (Zlib compression)</li>
+<li>libdl (dynamic linker)</li>
+<li>libGLESv1_CM.so (OpenGL ES 1.0)</li>
+<li>libGLESv2.so (OpenGL ES 2.0)</li>
+<li>libEGL.so (native OpenGL surface management)</li>
+<li>libjnigraphics.so</li>
+<li>libOpenSLES.so (Open Sound Library audio support)</li>
+<li>libandroid.so (native Android activity support)</li>
+<li>Support for OpenGL, as described below</li>
+</ul>
+<p>Note that future releases of the Android NDK may introduce support for
+additional ABIs. If a device implementation is not compatible with an existing
+predefined ABI, it MUST NOT report support for any ABI at all.</p>
+<p>Native code compatibility is challenging. For this reason, it should be
+repeated that device implementers are VERY strongly encouraged to use the
+upstream implementations of the libraries listed above to help ensure
+compatibility.</p>
+
+<a name="section-3.4"></a><h3>3.4. Web Compatibility</h3>
+<p>Many developers and applications rely on the behavior of the
+<code>android.webkit.WebView</code> class [<a
+href="#resources08">Resources, 8</a>]
+for their user interfaces, so the WebView implementation must be
+compatible across Android implementations. Similarly, a complete, modern web
+broswer is central to the Android user experience. Device implementations MUST
+include a version of <code>android.webkit.WebView</code> consistent with the
+upstream Android software, and MUST include a modern HTML5-capable browser, as
+described below.</p>
+<a name="section-3.4.1"></a><h4>3.4.1. WebView Compatibility</h4>
+<p>The Android Open Source implementation uses the WebKit rendering engine to
+implement the <code>android.webkit.WebView</code>. Because it is not feasible
+to develop a comprehensive test suite for a web rendering system, device
+implementers MUST use the specific upstream build of WebKit in the WebView
+implementation. Specifically:</p>
+<ul>
+<li>Device implementations' <code>android.webkit.WebView</code>
+implementations MUST be based on the 533.1 WebKit build from the upstream
+Android Open Source tree for Android 2.3. This build includes a specific set
+of functionality and security fixes for the WebView. Device implementers MAY
+include customizations to the WebKit implementation; however, any such
+customizations MUST NOT alter the behavior of the WebView, including rendering
+behavior.</li>
+<li>The user agent string reported by the WebView MUST be in this format:<br/>
+ <code>Mozilla/5.0 (Linux; U; Android $(VERSION); $(LOCALE); $(MODEL) Build/$(BUILD)) AppleWebKit/533.1 (KHTML, like Gecko) Version/4.0 Mobile Safari/533.1</code>
+ <ul>
+ <li>The value of the $(VERSION) string MUST be the same as the value for <code>android.os.Build.VERSION.RELEASE</code></li>
+ <li>The value of the $(LOCALE) string SHOULD follow the ISO conventions for country code and language, and SHOULD refer to the current configured locale of the device</li>
+ <li>The value of the $(MODEL) string MUST be the same as the value for <code>android.os.Build.MODEL</code></li>
+ <li>The value of the $(BUILD) string MUST be the same as the value for <code>android.os.Build.ID</code></li>
+ </ul></li>
+</ul>
+<p>The WebView component SHOULD include support for as much of HTML5 [<a
+href="#resources09">Resources, 9</a>] as possible.
+Minimally, device implementations MUST support each of these APIs associated
+with HTML5 in the WebView:</p>
+<ul>
+<li>application cache/offline operation [<a href="#resources10">Resources, 10</a>]</li>
+<li>the <video> tag [<a href="#resources11">Resources, 11</a>]</li>
+<li>geolocation [<a href="#resources12">Resources, 12</a>]</li>
+</ul>
+<p>Additionally, device implementations MUST support the HTML5/W3C webstorage
+API [<a href="#resources13">Resources, 13</a>], and SHOULD support the
+HTML5/W3C IndexedDB API [<a href="#resources14">Resources, 14</a>]. <i>Note
+that as the web development standards bodies are transitioning to favor
+IndexedDB over webstorage, IndexedDB is expected to become a required
+component in a future version of Android.</i></p>
+<p>HTML5 APIs, like all JavaScript APIs, MUST be disabled by default in a
+WebView, unless the developer explicitly enables them via the usual Android
+APIs.</p>
+
+<a name="section-3.4.2"></a><h4>3.4.2. Browser Compatibility</h4>
+<p>Device implementations MUST include a standalone Browser application for
+general user web browsing. The standalone Browser MAY be based on a
+browser technology other than WebKit. However, even if an alternate Browser
+application is used, the <code>android.webkit.WebView</code> component
+provided to third-party applications MUST be based on WebKit, as described in
+Section 3.4.1.</p>
+<p>Implementations MAY ship a custom user agent string in the standalone
+Browser application.</p>
+<p>The standalone Browser application (whether based on the upstream
+WebKit Browser application or a third-party replacement) SHOULD include support
+for as much of HTML5 [<a href="#resources09">Resources, 9</a>] as possible.
+Minimally, device implementations MUST support each of these APIs associated
+with HTML5:</p>
+<ul>
+<li>application cache/offline operation [<a href="#resources10">Resources, 10</a>]</li>
+<li>the <video> tag [<a href="#resources11">Resources, 11</a>]</li>
+<li>geolocation [<a href="#resources12">Resources, 12</a>]</li>
+</ul>
+<p>Additionally, device implementations MUST support the HTML5/W3C webstorage
+API [<a href="#resources13">Resources, 13</a>], and SHOULD support the
+HTML5/W3C IndexedDB API [<a href="#resources14">Resources, 14</a>]. <i>Note
+that as the web development standards bodies are transitioning to favor
+IndexedDB over webstorage, IndexedDB is expected to become a required
+component in a future version of Android.</i></p>
+
+<a name="section-3.5"></a><h3>3.5. API Behavioral Compatibility</h3>
+<p>The behaviors of each of the API types (managed, soft, native, and web)
+must be consistent with the preferred implementation of the upstream Android
+open-source project [<a href="#resources03">Resources, 3</a>]. Some specific areas
+of compatibility are:</p>
+<ul>
+<li>Devices MUST NOT change the behavior or semantics of a standard Intent</li>
+<li>Devices MUST NOT alter the lifecycle or lifecycle semantics of a
+ particular type of system component (such as Service, Activity,
+ ContentProvider, etc.)</li>
+<li>Devices MUST NOT change the semantics of a standard permission</li>
+</ul>
+<p>The above list is not comprehensive. The Compatibility Test Suite (CTS)
+tests significant portions of the platform for behavioral compatibility, but
+not all. It is the responsibility of the implementer to ensure behavioral
+compatibility with the Android Open Source Project. For this reason, device
+implementers SHOULD use the source code available via the Android Open Source
+Project where possible, rather than re-implement significant parts of the
+system.</p>
+
+
+<a name="section-3.6"></a><h3>3.6. API Namespaces</h3>
+<p>Android follows the package and class namespace conventions defined by the
+Java programming language. To ensure compatibility with third-party
+applications, device implementers MUST NOT make any prohibited modifications
+(see below) to these package namespaces:</p>
+<ul>
+<li>java.*</li>
+<li>javax.*</li>
+<li>sun.*</li>
+<li>android.*</li>
+<li>com.android.*</li>
+</ul>
+<p>Prohibited modifications include:</p>
+<ul>
+<li>Device implementations MUST NOT modify the publicly exposed APIs on the
+Android platform by changing any method or class signatures, or by removing
+classes or class fields.</li>
+<li>Device implementers MAY modify the underlying implementation of the APIs,
+but such modifications MUST NOT impact the stated behavior and Java-language
+signature of any publicly exposed APIs.</li>
+<li>Device implementers MUST NOT add any publicly exposed elements (such as
+classes or interfaces, or fields or methods to existing classes or interfaces)
+to the APIs above.</li>
+</ul>
+<p>A "publicly exposed element" is any construct which is not decorated with
+the "@hide" marker as used in the upstream Android source code. In other
+words, device implementers MUST NOT expose new APIs or alter existing APIs in
+the namespaces noted above. Device implementers MAY make internal-only
+modifications, but those modifications MUST NOT be advertised or otherwise
+exposed to developers.</p>
+<p>Device implementers MAY add custom APIs, but any such APIs MUST NOT be in a
+namespace owned by or referring to another organization. For instance, device
+implementers MUST NOT add APIs to the com.google.* or similar namespace; only
+Google may do so. Similarly, Google MUST NOT add APIs to other companies'
+namespaces. Additionally, if a device implementation includes custom APIs
+outside the standard Android namespace, those APIs MUST be packaged in an
+Android shared library so that only apps that explicitly use them (via the
+<code><uses-library></code> mechanism) are affected by the increased
+memory usage of such APIs.</p>
+<p>If a device implementer proposes to improve one of the package namespaces
+above (such as by adding useful new functionality to an existing API, or
+adding a new API), the implementer SHOULD visit source.android.com and begin
+the process for contributing changes and code, according to the information on
+that site.</p>
+<p>Note that the restrictions above correspond to standard conventions for
+naming APIs in the Java programming language; this section simply aims to
+reinforce those conventions and make them binding through inclusion in this
+compatibility definition.</p>
+
+<a name="section-3.7"></a><h3>3.7. Virtual Machine Compatibility</h3>
+<p>Device implementations MUST support the full Dalvik Executable (DEX)
+bytecode specification and Dalvik Virtual Machine semantics [<a
+href="#resources15">Resources, 15</a>].</p>
+<p>Device implementations with screens classified as medium- or low-density
+MUST configure Dalvik to allocate at least 16MB of memory to each application.
+Device implementations with screens classified as high-density or
+extra-high-density MUST configure Dalvik to allocate at least 24MB of memory
+to each application. Note that device implementations MAY allocate more memory
+than these figures.</p>
+
+<a name="section-3.8"></a><h3>3.8. User Interface Compatibility</h3>
+<p>The Android platform includes some developer APIs that allow developers to
+hook into the system user interface. Device implementations MUST incorporate
+these standard UI APIs into custom user interfaces they develop, as explained
+below.</p>
+<a name="section-3.8.1"></a><h4>3.8.1. Widgets</h4>
+<p>Android defines a component type and corresponding API and lifecycle that
+allows applications to expose an "AppWidget" to the end user [<a
+href="#resources16">Resources, 16</a>].
+The Android Open Source reference release includes a Launcher application that
+includes user interface elements allowing the user to add, view, and remove
+AppWidgets from the home screen.</p>
+<p>Device implementers MAY substitute an alternative to the reference Launcher
+(i.e. home screen). Alternative Launchers SHOULD include built-in support for
+AppWidgets, and expose user interface elements to add, configure, view, and remove
+AppWidgets directly within the Launcher. Alternative Launchers MAY omit these
+user interface elements; however, if they are omitted, the device implementer
+MUST provide a separate application accessible from the Launcher that allows
+users to add, configure, view, and remove AppWidgets.</p>
+<a name="section-3.8.2"></a><h4>3.8.2. Notifications</h4>
+<p>Android includes APIs that allow developers to notify users of notable
+events [<a href="#resources17">Resources, 17</a>]. Device implementers MUST provide support for each
+class of notification so defined; specifically: sounds, vibration, light and
+status bar.</p>
+<p>Additionally, the implementation MUST correctly render all resources
+(icons, sound files, etc.) provided for in the APIs [<a
+href="#resources18">Resources, 18</a>], or in the
+Status Bar icon style guide [<a href="#resources19">Resources, 19</a>]. Device implementers MAY provide
+an alternative user experience for notifications than that provided by the
+reference Android Open Source implementation; however, such alternative
+notification systems MUST support existing notification resources, as
+above.</p>
+<a name="section-3.8.3"></a><h4>3.8.3. Search</h4>
+<p>Android includes APIs [<a href="#resources20">Resources, 20</a>] that allow developers to incorporate
+search into their applications, and expose their application's data into the
+global system search. Generally speaking, this functionality consists of a
+single, system-wide user interface that allows users to enter queries,
+displays suggestions as users type, and displays results. The Android APIs
+allow developers to reuse this interface to provide search within their own
+apps, and allow developers to supply results to the common global search user
+interface.</p>
+<p>Device implementations MUST include a single, shared, system-wide search
+user interface capable of real-time suggestions in response to user input.
+Device implementations MUST implement the APIs that allow developers to reuse
+this user interface to provide search within their own applications. Device
+implementations MUST implement the APIs that allow third-party applications to
+add suggestions to the search box when it is run in global search mode. If no
+third-party applications are installed that make use of this functionality,
+the default behavior SHOULD be to display web search engine results and
+suggestions.</p>
+<p>Device implementations MAY ship alternate search user interfaces, but
+SHOULD include a hard or soft dedicated search button, that can be used at any
+time within any app to invoke the search framework, with the behavior provided
+for in the API documentation.</p>
+<a name="section-3.8.4"></a><h4>3.8.4. Toasts</h4>
+<p>Applications can use the "Toast" API (defined in [<a
+href="#resources21">Resources, 21</a>]) to
+display short non-modal strings to the end user, that disappear after a brief
+period of time. Device implementations MUST display Toasts from applications
+to end users in some high-visibility manner.</p>
+<a name="section-3.8.5"></a><h4>3.8.5. Live Wallpapers</h4>
+<p>Android defines a component type and corresponding API and lifecycle that
+allows applications to expose one or more "Live Wallpapers" to the end user
+[<a href="#resources22">Resources, 22</a>]. Live Wallpapers are animations,
+patterns, or similar images with limited input capabilities that display as a
+wallpaper, behind other applications.</p>
+<p>Hardware is considered capable of reliably running live wallpapers if it
+can run all live wallpapers, with no limitations on functionality, at a
+reasonable framerate with no adverse affects on other applications. If
+limitations in the hardware cause wallpapers and/or applications to crash,
+malfunction, consume excessive CPU or battery power, or run at unacceptably
+low frame rates, the hardware is considered incapable of running live
+wallpaper. As an example, some live wallpapers may use an Open GL 1.0 or 2.0
+context to render their content. Live wallpaper will not run reliably on
+hardware that does not support multiple OpenGL contexts because the live
+wallpaper use of an OpenGL context may conflict with other applications that
+also use an OpenGL context.</p>
+<p>Device implementations capable of running live wallpapers reliably as
+described above SHOULD implement live wallpapers. Device implementations
+determined to not run live wallpapers reliably as described above MUST NOT
+implement live wallpapers.</p>
+
+<a name="section-4"></a><h2>4. Application Packaging Compatibility</h2>
+<p>Device implementations MUST install and run Android ".apk" files as
+generated by the "aapt" tool included in the official Android SDK [<a
+href="#resources23">Resources, 23</a>].</p>
+<p>Devices implementations MUST NOT extend either the .apk [<a
+href="#resources24">Resources, 24</a>], Android Manifest [<a
+href="#resources25">Resources, 25</a>],
+or Dalvik bytecode [<a href="#resources15">Resources, 15</a>] formats in such
+a way that would prevent those files from
+installing and running correctly on other compatible devices. Device
+implementers SHOULD use the reference upstream implementation of Dalvik, and
+the reference implementation's package management system.</p>
+
+<a name="section-5"></a><h2>5. Multimedia Compatibility</h2>
+<p>Device implementations MUST fully implement all multimedia APIs. Device
+implementations MUST include support for all multimedia codecs described
+below, and SHOULD meet the sound processing guidelines described below. Device
+implementations MUST include at least one form of audio output, such as
+speakers, headphone jack, external speaker connection, etc.</p>
+<a name="section-5.1"></a><h3>5.1. Media Codecs</h3>
+<p>Device implementations MUST support the multimedia codecs as detailed in
+the following sections. All of these codecs are provided as software
+implementations in the preferred Android implementation from the Android
+Open-Source Project.</p>
+<p>Please note that neither Google nor the Open Handset Alliance make any
+representation that these codecs are unencumbered by third-party patents.
+Those intending to use this source code in hardware or software products are
+advised that implementations of this code, including in open source software
+or shareware, may require patent licenses from the relevant patent
+holders.</p>
+<p>The tables below do not list specific bitrate requirements for
+most video codecs. The reason for this is that in practice, current device
+hardware does not necessarily support bitrates that map exactly to the
+required bitrates specified by the relevant standards. Instead, device
+implementations SHOULD support the highest bitrate practical on the hardware,
+up to the limits defined by the specifications.</p>
+<a name="section-5.1.1"></a><h3>5.1.1. Media Decoders</h3>
+<p>Device implementations MUST include an implementation of an decoder for
+each codec and format described in the table below. Note that decoders for
+each of these media types are provided by the upstream Android Open-Source
+Project.</p>
+<table><tbody>
+<tr>
+<td rowspan="11"><b>Audio</b></td>
+</tr>
+<tr>
+<td><b>Name</b></td>
+<td><b>Details</b></td>
+<td><b>File/Container Format</b></td>
+</tr>
+<tr>
+<td>AAC LC/LTP</td>
+<td rowspan="3">Mono/Stereo content in any combination of standard bit rates up to 160 kbps and sampling rates between 8 to 48kHz</td>
+<td rowspan="3">3GPP (.3gp) and MPEG-4 (.mp4, .m4a). No support for raw AAC (.aac)</td>
+</tr>
+<tr>
+<td>HE-AACv1 (AAC+)</td>
+</tr>
+<tr>
+<td>HE-AACv2 (enhanced AAC+)</td>
+</tr>
+<tr>
+<td>AMR-NB</td>
+<td>4.75 to 12.2 kbps sampled @ 8kHz</td>
+<td>3GPP (.3gp)</td>
+</tr>
+<tr>
+<td>AMR-WB</td>
+<td>9 rates from 6.60 kbit/s to 23.85 kbit/s sampled @ 16kHz</td>
+<td>3GPP (.3gp)</td>
+</tr>
+<tr>
+<td>MP3</td>
+<td>Mono/Stereo 8-320Kbps constant (CBR) or variable bit-rate (VBR)</td>
+<td>MP3 (.mp3)</td>
+</tr>
+<tr>
+<td>MIDI</td>
+<td>MIDI Type 0 and 1. DLS Version 1 and 2. XMF and Mobile XMF. Support for ringtone formats RTTTL/RTX, OTA, and iMelody</td>
+<td>Type 0 and 1 (.mid, .xmf, .mxmf). Also RTTTL/RTX (.rtttl, .rtx), OTA (.ota), and iMelody (.imy)</td>
+</tr>
+<tr>
+<td>Ogg Vorbis</td>
+<td> </td>
+<td>Ogg (.ogg)</td>
+</tr>
+<tr>
+<td>PCM</td>
+<td>8- and 16-bit linear PCM (rates up to limit of hardware)</td>
+<td>WAVE (.wav)</td>
+</tr>
+<tr>
+<td rowspan="5"><b>Image</b></td>
+</tr>
+<tr>
+<td>JPEG</td>
+<td>base+progressive</td>
+<td> </td>
+</tr>
+<tr>
+<td>GIF</td>
+<td> </td>
+<td> </td>
+</tr>
+<tr>
+<td>PNG</td>
+<td> </td>
+<td> </td>
+</tr>
+<tr>
+<td>BMP</td>
+<td> </td>
+<td> </td>
+</tr>
+<tr>
+<td rowspan="4"><b>Video</b></td>
+</tr>
+<tr>
+<td>H.263</td>
+<td> </td>
+<td>3GPP (.3gp) files</td>
+</tr>
+<tr>
+<td>H.264</td>
+<td> </td>
+<td>3GPP (.3gp) and MPEG-4 (.mp4) files</td>
+</tr>
+<tr>
+<td>MPEG4 Simple Profile</td>
+<td> </td>
+<td>3GPP (.3gp) file</td>
+</tr>
+</tbody>
+</table>
+
+<a name="section-5.1.2"></a><h3>5.1.2. Media Encoders</h3>
+<p>Device implementations SHOULD include encoders for as many of the media
+formats listed in Section 5.1.1. as possible. However, some encoders do not
+make sense for devices that lack certain optional hardware; for instance,
+an encoder for the H.263 video does not make sense, if the device lacks any
+cameras. Device implementations MUST therefore implement media encoders
+according to the conditions described in the table below.</p>
+<p>See Section 7 for details on the conditions under which hardware may be
+omitted by device implementations.</p>
+<table><tbody>
+<tr>
+<td rowspan="5"><b>Audio</b></td>
+</tr>
+<tr>
+<td><b>Name</b></td>
+<td><b>Details</b></td>
+<td><b>File/Container Format</b></td>
+<td><b>Conditions</b></td>
+</tr>
+<tr>
+<td>AMR-NB</td>
+<td>4.75 to 12.2 kbps sampled @ 8kHz</td>
+<td>3GPP (.3gp)</td>
+<td rowspan="3">Device implementations that include microphone hardware and define
+<code>android.hardware.microphone</code> MUST include encoders for these audio
+formats.</td>
+</tr>
+<tr>
+<td>AMR-WB</td>
+<td>9 rates from 6.60 kbit/s to 23.85 kbit/s sampled @ 16kHz</td>
+<td>3GPP (.3gp)</td>
+</tr>
+<tr>
+<td>AAC LC/LTP</td>
+<td rowspan="1">Mono/Stereo content in any combination of standard bit rates up to 160 kbps and sampling rates between 8 to 48kHz</td>
+<td rowspan="1">3GPP (.3gp) and MPEG-4 (.mp4, .m4a).</td>
+</tr>
+<tr>
+<td rowspan="2"><b>Image</b></td>
+<td>JPEG</td>
+<td>base+progressive</td>
+<td> </td>
+<td rowspan="2">All device implementations MUST include encoders for these
+image formats, as Android 2.3 includes APIs that applications can use to
+programmatically generate files of these types.</td>
+</tr>
+<tr>
+<td>PNG</td>
+<td> </td>
+<td> </td>
+</tr>
+<tr>
+<td><b>Video</b></td>
+<td>H.263</td>
+<td> </td>
+<td>3GPP (.3gp) files</td>
+<td>Device implementations that include camera hardware and define
+either <code>android.hardware.camera</code> or
+<code>android.hardware.camera.front</code> MUST include encoders for these
+video formats.</td>
+</tr>
+</tbody>
+</table>
+<p>In addition to the encoders listed above, device implementations SHOULD include an H.264
+encoder. Note that the Compatibility Definition for a future version is planned
+to change this requirement to "MUST". That is, H.264 encoding is optional in Android
+2.3 but <b>will be required</b> by a future version. Existing and new devices
+that run Android 2.3 are <b>very strongly encouraged to meet
+this requirement in Android 2.3</b>, or they will not be able to attain
+Android compatibility when upgraded to the future version.</p>
+
+<a name="section-5.2"></a><h3>5.2. Audio Recording</h3>
+<p>When an application has used the <code>android.media.AudioRecord</code> API to
+start recording an audio stream, device implementations SHOULD sample and
+record audio with each of these behaviors:</p>
+<ul>
+<li>Noise reduction processing, if present, SHOULD be disabled.</li>
+<li>Automatic gain control, if present, SHOULD be disabled.</li>
+<li>The device SHOULD exhibit approximately flat amplitude versus frequency
+ characteristics; specifically, ±3 dB, from 100 Hz to 4000 Hz</li>
+<li>Audio input sensitivity SHOULD be set such that a 90 dB sound power level
+ (SPL) source at 1000 Hz yields RMS of 5000 for 16-bit samples.</li>
+<li>PCM amplitude levels SHOULD linearly track input SPL changes over at least
+ a 30 dB range from -18 dB to +12 dB re 90 dB SPL at the microphone.</li>
+<li>Total harmonic distortion SHOULD be less than 1% from 100 Hz to 4000 Hz at
+ 90 dB SPL input level.</li>
+</ul>
+<p><b>Note:</b> while the requirements outlined above are stated as "SHOULD"
+for Android 2.3, the Compatibility Definition for a future version is planned
+to change these to "MUST". That is, these requirements are optional in Android
+2.3 but <b>will be required</b> by a future version. Existing and new devices
+that run Android 2.3 are <b>very strongly encouraged to meet
+these requirements in Android 2.3</b>, or they will not be able to attain
+Android compatibility when upgraded to the future version.</p>
+
+<a name="section-5.3"></a><h3>5.3. Audio Latency</h3>
+<p>Audio latency is broadly defined as the interval between when an
+application requests an audio playback or record operation, and when the
+device implementation actually begins the operation. Many classes of
+applications rely on short latencies, to achieve real-time effects such sound
+effects or VOIP communication. Device implementations that include microphone
+hardware and declare <code>android.hardware.microphone</code> SHOULD meet all
+audio latency requirements outlined in this section. See Section 7 for
+details on the conditions under which microphone hardware may be omitted by
+device implementations.</p>
+<p>For the purposes of this section:</p>
+<ul>
+<li>"cold output latency" is defined to be the interval between when an
+ application requests audio playback and when sound begins playing, when
+ the audio system has been idle and powered down prior to the request</li>
+<li>"warm output latency" is defined to be the interval between when an
+ application requests audio playback and when sound begins playing, when
+ the audio system has been recently used but is currently idle (that is,
+ silent)</li>
+<li>"continuous output latency" is defined to be the interval between when an
+ application issues a sample to be played and when the speaker physically
+ plays the corresponding sound, while the device is currently playing back
+ audio</li>
+<li>"cold input latency" is defined to be the interval between when an
+ application requests audio recording and when the first sample is
+ delivered to the application via its callback, when the audio system and
+ microphone has been idle and powered down prior to the request</li>
+<li>"continuous input latency" is defined to be when an ambient sound occurs
+ and when the sample corresponding to that sound is delivered to a
+ recording application via its callback, while the device is in recording
+ mode</li>
+</ul>
+<p>Using the above definitions, device implementations SHOULD exhibit each of
+these properties:</p>
+<ul>
+<li>cold output latency of 100 milliseconds or less</li>
+<li>warm output latency of 10 milliseconds or less</li>
+<li>continuous output latency of 45 milliseconds or less</li>
+<li>cold input latency of 100 milliseconds or less</li>
+<li>continuous input latency of 50 milliseconds or less</li>
+</ul>
+<p><b>Note:</b> while the requirements outlined above are stated as "SHOULD"
+for Android 2.3, the Compatibility Definition for a future version is planned
+to change these to "MUST". That is, these requirements are optional in Android
+2.3 but <b>will be required</b> by a future version. Existing and new devices
+that run Android 2.3 are <b>very strongly encouraged to meet
+these requirements in Android 2.3</b>, or they will not be able to attain
+Android compatibility when upgraded to the future version.</p>
+<p>If a device implementation meets the requirements of this section, it MAY
+report support for low-latency audio, by reporting the feature
+"android.hardware.audio.low-latency" via the
+<code>android.content.pm.PackageManager</code> class. [<a
+href="#resources27">Resources, 27</a>] Conversely, if the device
+implementation does not meet these requirements it MUST NOT report support for
+low-latency audio.</p>
+
+<a name="section-6"></a><h2>6. Developer Tool Compatibility</h2>
+<p>Device implementations MUST support the Android Developer Tools provided in
+the Android SDK. Specifically, Android-compatible devices MUST be compatible
+with:</p>
+<ul>
+<li><b>Android Debug Bridge (known as adb)</b> [<a href="#resources23">Resources, 23</a>]<br/>
+Device implementations MUST support all <code>adb</code> functions as
+documented in the Android SDK. The device-side <code>adb</code> daemon SHOULD
+be inactive by default, but there MUST be a user-accessible mechanism to turn
+on the Android Debug Bridge.</li>
+<li><b>Dalvik Debug Monitor Service (known as ddms)</b> [<a href="#resources23">Resources, 23</a>]<br/>
+Device implementations MUST support all <code>ddms</code> features as documented in the
+Android SDK. As <code>ddms</code> uses <code>adb</code>, support for
+<code>ddms</code> SHOULD be inactive by default,
+but MUST be supported whenever the user has activated the Android Debug
+Bridge, as above.</li>
+<li><b>Monkey</b> [<a href="#resources26">Resources, 26</a>]<br/>
+Device implementations MUST include the Monkey framework, and make it
+available for applications to use.</li>
+</ul>
+<p>Most Linux-based systems and Apple Macintosh systems recognize Android
+devices using the standard Android SDK tools, without additional support;
+however Microsoft Windows systems typically require a driver for new Android
+devices. (For instance, new vendor IDs and sometimes new device IDs require
+custom USB drivers for Windows systems.) If a device implementation is
+unrecognized by the <code>adb</code> tool as provided in the standard Android
+SDK, device implementers MUST provide Windows drivers allowing developers to
+connect to the device using the <code>adb</code> protocol. These drivers MUST
+be provided for Windows XP, Windows Vista, and Windows 7, in both 32-bit and
+64-bit versions.</p>
+
+<a name="section-7"></a><h2>7. Hardware Compatibility</h2>
+<p>Android is intended to enable device implementers to create innovative form
+factors and configurations. At the same time Android developers write
+innovative applications that rely on the various hardware and features
+available through the Android APIs. The requirements in this section strike a
+balance between innovations available to device implementers, and the needs of
+developers to ensure their apps are only available to devices where they will
+run properly.</p>
+<p>If a device includes a particular hardware component that has a
+corresponding API for third-party developers, the device implementation MUST
+implement that API as described in the Android SDK documentation. If an API in
+the SDK interacts with a hardware component that is stated to be optional and the device
+implementation does not possess that component:</p>
+<ul>
+<li>complete class definitions (as documented by the SDK) for the component's APIs MUST still be present</li>
+<li>the API's behaviors MUST be implemented as no-ops in some reasonable fashion</li>
+<li>API methods MUST return null values where permitted by the SDK documentation</li>
+<li>API methods MUST return no-op implementations of classes where null values are not permitted by the SDK documentation</li>
+<li>API methods MUST NOT throw exceptions not documented by the SDK documentation</li>
+</ul>
+<p>A typical example of a scenario where these requirements apply is the
+telephony API: even on non-phone devices, these APIs must be implemented as
+reasonable no-ops.</p>
+<p>Device implementations MUST accurately report accurate hardware configuration
+information via the <code>getSystemAvailableFeatures()</code> and
+<code>hasSystemFeature(String)</code> methods on the
+<code>android.content.pm.PackageManager</code> class. [<a
+href="#resources27">Resources, 27</a>]</p>
+
+<a name="section-7.1"></a><h3>7.1. Display and Graphics</h3>
+<p>Android 2.3 includes facilities that automatically adjust application
+assets and UI layouts appropriately for the device, to ensure that third-party
+applications run well on a variety of hardware configurations [<a
+href="#resources28">Resources, 28</a>]. Devices MUST properly implement these
+APIs and behaviors, as detailed in this section.</p>
+<a name="section-7.1.1"></a><h4>7.1.1. Screen Configurations</h4>
+<p>Device implementations MAY use screens of any pixel dimensions, provided
+that they meet the following requirements:</p>
+<ul>
+<li>screens MUST be at least 2.5 inches in physical diagonal size</li>
+<li>density MUST be at least 100 dpi</li>
+<li>the aspect ratio MUST be between 1.333 (4:3) and 1.779 (16:9)</li>
+<li>the display technology used consists of square pixels</li>
+</ul>
+<p>Device implementations with a screen meeting the requirements above are
+considered compatible, and no additional action is necessary. The Android
+framework implementation automatically computes display characteristics such
+as screen size bucket and density bucket. In the majority of cases, the
+framework decisions are the correct ones. If the default framework
+computations are used, no additional action is necessary. Device implementers
+wishing to change the defaults, or use a screen that does not meet the
+requirements above MUST contact the Android Compatibility Team for guidance,
+as provided for in Section 12.</p>
+<p>The units used by the requirements above are defined as follows:</p>
+<ul>
+<li>"Physical diagonal size" is the distance in inches between two opposing
+corners of the illuminated portion of the display.</li>
+<li>"dpi" (meaning "dots per inch") is the number of pixels encompassed by a
+linear horizontal or vertical span of 1". Where dpi values are listed, both
+horizontal and vertical dpi must fall within the range.</li>
+<li>"Aspect ratio" is the ratio of the longer dimension of the screen to the
+shorter dimension. For example, a display of 480x854 pixels would be 854 / 480
+= 1.779, or roughly "16:9".</li>
+</ul>
+<p>Device implementations MUST use only displays with a single static
+configuration. That is, device implementations MUST NOT enable multiple
+screen configurations. For instance, since a typical television supports
+multiple resolutions such as 1080p, 720p, and so on, this configuration is not
+compatible with Android 2.3. (However, support for such configurations is
+under investigation and planned for a future version of Android.)</p>
+<a name="section-7.1.2"></a><h4>7.1.2. Display Metrics</h4>
+<p>Device implementations MUST report correct values for all display metrics
+defined in <code>android.util.DisplayMetrics</code> [<a
+href="#resources29">Resources, 29</a>].</p>
+<a name="section-7.1.3"></a><h4>7.1.3. Declared Screen Support</h4>
+<p>Applications optionally indicate which screen sizes they support via the
+<code><supports-screens></code> attribute in the AndroidManifest.xml
+file. Device implementations MUST correctly honor applications' stated support
+for small, medium, and large screens, as described in the Android
+SDK documentation.</p>
+<a name="section-7.1.4"></a><h4>7.1.4. Screen Orientation</h4>
+<p>Compatible devices MUST support dynamic orientation by applications to
+either portrait or landscape screen orientation. That is, the device must
+respect the application's request for a specific screen orientation. Device
+implementations MAY select either portrait or landscape orientation as the
+default. Devices that cannot be physically rotated MAY meet this requirement
+by "letterboxing" applications that request portrait mode, using only a
+portion of the available display.</p>
+<p>Devices MUST report the correct value for the device's current orientation,
+whenever queried via the android.content.res.Configuration.orientation,
+android.view.Display.getOrientation(), or other APIs.</p>
+<a name="section-7.1.5"></a><h4>7.1.5. 3D Graphics Acceleration</h4>
+<p>Device implementations MUST support OpenGL ES 1.0, as required by the
+Android 2.3 APIs. For devices that lack 3D acceleration hardware, a software
+implementation of OpenGL ES 1.0 is provided by the upstream Android
+Open-Source Project. Device implementations SHOULD support OpenGL ES 2.0.</p>
+<p>Implementations MAY omit Open GL ES 2.0 support; however if support is
+ommitted, device implementations MUST NOT report as supporting OpenGL ES 2.0.
+Specifically, if a device implementations lacks OpenGL ES 2.0 support:</p>
+<ul>
+<li>the managed APIs (such as via the <code>GLES10.getString()</code> method)
+MUST NOT report support for OpenGL ES 2.0</li>
+<li>the native C/C++ OpenGL APIs (that is, those available to apps via
+libGLES_v1CM.so, libGLES_v2.so, or libEGL.so) MUST NOT report support for
+OpenGL ES 2.0.</li>
+</ul>
+<p>Conversely, if a device implementation <i>does</i> support OpenGL ES 2.0,
+it MUST accurately report that support via the routes just listed.</p>
+<p>Note that Android 2.3 includes support for applications to optionally
+specify that they require specific OpenGL texture compression formats. These
+formats are typically vendor-specific. Device implementations are not required
+by Android 2.3 to implement any specific texture compression format. However,
+they SHOULD accurately report any texture compression formats that they do
+support, via the <code>getString()</code> method in the OpenGL API.</p>
+
+<a name="section-7.2"></a><h3>7.2. Input Devices</h3>
+<p>Android 2.3 supports a number of modalities for user input. Device
+implementations MUST support user input devices as provided for in this
+section.</p>
+<a name="section-7.2.1"></a><h4>7.2.1. Keyboard</h4>
+<p>Device implementations:</p>
+<ul>
+<li>MUST include support for the Input Management Framework (which allows third party developers to create Input Management Engines -- i.e. soft keyboard) as detailed at developer.android.com</li>
+<li>MUST provide at least one soft keyboard implementation (regardless of whether a hard keyboard is present)</li>
+<li>MAY include additional soft keyboard implementations</li>
+<li>MAY include a hardware keyboard</li>
+<li>MUST NOT include a hardware keyboard that does not match one of the
+formats specified in <code>android.content.res.Configuration.keyboard</code>
+[<a href="#resources30">Resources, 30</a>] (that is, QWERTY, or 12-key)</li>
+</ul>
+<a name="section-7.2.2"></a><h4>7.2.2. Non-touch Navigation</h4>
+<p>Device implementations:</p>
+<ul>
+<li>MAY omit a non-touch navigation option (that is, may omit a trackball, d-pad, or wheel)</li>
+<li>MUST report the correct value for
+<code>android.content.res.Configuration.navigation</code> [<a href="#resources30">Resources, 30</a>]</li>
+<li>MUST provide a reasonable alternative user interface mechanism for the
+selection and editing of text, compatible with Input Management Engines. The
+upstream Android Open-Source code includes a selection mechanism suitable for
+use with devices that lack non-touch navigation inputs.</li>
+</ul>
+<a name="section-7.2.3"></a><h4>7.2.3. Navigation keys</h4>
+<p>The Home, Menu and Back functions are essential to the Android navigation
+paradigm. Device implementations MUST make these functions available to the
+user at all times, regardless of application state. These functions SHOULD be
+implemented via dedicated buttons. They MAY be implemented using software,
+gestures, touch panel, etc., but if so they MUST be always accessible and not
+obscure or interfere with the available application display area.</p>
+<p>Device implementers SHOULD also provide a dedicated search key. Device
+implementers MAY also provide send and end keys for phone calls.</p>
+<a name="section-7.2.4"></a><h4>7.2.4. Touchscreen input</h4>
+<p>Device implementations:</p>
+<ul>
+<li>MUST have a touchscreen</li>
+<li>MAY have either capacitive or resistive touchscreen</li>
+<li>MUST report the value of <code>android.content.res.Configuration</code>
+[<a href="#resources30">Resources, 30</a>]
+reflecting corresponding to the type of the specific touchscreen on the
+device</li>
+<li>SHOULD support fully independently tracked pointers, if the touchscreen supports multiple pointers</li>
+</ul>
+
+<a name="section-7.3"></a><h3>7.3. Sensors</h3>
+<p>Android 2.3 includes APIs for accessing a variety of sensor types. Devices
+implementations generally MAY omit these sensors, as provided for in the
+following subsections. If a device includes a particular sensor type that has a
+corresponding API for third-party developers, the device implementation MUST
+implement that API as described in the Android SDK documentation. For example,
+device implementations:</p>
+<ul>
+<li>MUST accurately report the presence or absence of sensors per the
+<code>android.content.pm.PackageManager</code> class. [<a
+href="#resources27">Resources, 27</a>]</li>
+<li>MUST return an accurate list of supported sensors via the
+<code>SensorManager.getSensorList()</code> and similar methods</li>
+<li>MUST behave reasonably for all other sensor APIs (for example, by
+returning true or false as appropriate when applications attempt to register
+listeners, not calling sensor listeners when the corresponding sensors are not
+present; etc.)</li>
+</ul>
+<p>The list above is not comprehensive; the documented behavior of the Android
+SDK is to be considered authoritative.</p>
+<p>Some sensor types are synthetic, meaning they can be derived from data
+provided by one or more other sensors. (Examples include the orientation
+sensor, and the linear acceleration sensor.) Device implementations SHOULD
+implement these sensor types, when they include the prerequisite physical
+sensors.</p>
+<p>The Android 2.3 APIs introduce a notion of a "streaming" sensor, which is
+one that returns data continuously, rather than only when the data changes.
+Device implementations MUST continuously provide periodic data samples for any
+API indicated by the Android 2.3 SDK documentation to be a streaming
+sensor.</p>
+<a name="section-7.3.1"></a><h4>7.3.1. Accelerometer</h4>
+<p>Device implementations SHOULD include a 3-axis accelerometer. If a device
+implementation does include a 3-axis accelerometer, it:</p>
+<ul>
+<li>MUST be able to deliver events at 50 Hz or greater</li>
+<li>MUST comply with the Android sensor coordinate system as detailed
+in the Android APIs (see [<a href="#resources31">Resources, 31</a>])</li>
+<li>MUST be capable of measuring from freefall up to twice gravity (2g) or
+more on any three-dimensional vector</li>
+<li>MUST have 8-bits of accuracy or more</li>
+<li>MUST have a standard deviation no greater than 0.05 m/s^2</li>
+</ul>
+<a name="section-7.3.2"></a><h4>7.3.2. Magnetometer</h4>
+<p>Device implementations SHOULD include a 3-axis magnetometer (i.e. compass.)
+If a device does include a 3-axis magnetometer, it:</p>
+<ul>
+<li>MUST be able to deliver events at 10 Hz or greater</li>
+<li>MUST comply with the Android sensor coordinate system as detailed
+in the Android APIs (see [<a href="#resources31">Resources, 31</a>]).</li>
+<li>MUST be capable of sampling a range of field strengths adequate to cover the geomagnetic field</li>
+<li>MUST have 8-bits of accuracy or more</li>
+<li>MUST have a standard deviation no greater than 0.5 µT</li>
+</ul>
+<a name="section-7.3.3"></a><h4>7.3.3. GPS</h4>
+<p>Device implementations SHOULD include a GPS receiver. If a device
+implementation does include a GPS receiver, it SHOULD include
+some form of "assisted GPS" technique to minimize GPS lock-on time.</p>
+<a name="section-7.3.4"></a><h4>7.3.4. Gyroscope</h4>
+<p>Device implementations SHOULD include a gyroscope (i.e. angular change
+sensor.) Devices SHOULD NOT include a gyroscope sensor unless a 3-axis
+accelerometer is also included. If a device implementation includes a
+gyroscope, it:</p>
+<ul>
+<li>MUST be capable of measuring orientation changes up to 5.5*Pi
+radians/second (that is, approximately 1,000 degrees per second)</li>
+<li>MUST be able to deliver events at 100 Hz or greater</li>
+<li>MUST have 8-bits of accuracy or more</li>
+</ul>
+<a name="section-7.3.5"></a><h4>7.3.5. Barometer</h4>
+<p>Device implementations MAY include a barometer (i.e. ambient air pressure
+sensor.) If a device implementation includes a barometer, it:</p>
+<ul>
+<li>MUST be able to deliver events at 5 Hz or greater</li>
+<li>MUST have adequate precision to enable estimating altitude</li>
+</ul>
+<a name="section-7.3.6"></a><h4>7.3.7. Thermometer</h4>
+<p>Device implementations MAY but SHOULD NOT include a thermometer (i.e.
+temperature sensor.) If a device implementation does include a thermometer, it
+MUST measure the temperature of the device CPU. It MUST NOT measure any other
+temperature. (Note that this sensor type is deprecated in the Android 2.3
+APIs.)</p>
+<a name="section-7.3.7"></a><h4>7.3.7. Photometer</h4>
+<p>Device implementations MAY include a photometer (i.e. ambient light
+sensor.)</p>
+<a name="section-7.3.8"></a><h4>7.3.8. Proximity Sensor</h4>
+<p>Device implementations MAY include a proximity sensor. If a device
+implementation does include a proximity sensor, it MUST measure the proximity
+of an object in the same direction as the screen. That is, the proximity
+sensor MUST be oriented to detect objects close to the screen, as the
+primary intent of this sensor type is to detect a phone in use by the
+user. If a device implementation includes a proximity sensor with any other
+orientation, it MUST NOT be accessible through this API. If a device
+implementation has a proximity sensor, it MUST be have 1-bit of accuracy or
+more.</p>
+
+<a name="section-7.4"></a><h3>7.4. Data Connectivity</h3>
+<p>Network connectivity and access to the Internet are vital features of
+Android. Meanwhile, device-to-device interaction adds significant value to
+Android devices and applications. Device implementations MUST meet the
+data connectivity requirements in this section.</p>
+<a name="section-7.4.1"></a><h4>7.4.1. Telephony</h4>
+<p>"Telephony" as used by the Android 2.3 APIs and this document refers
+specifically to hardware related to placing voice calls and sending SMS
+messages via a GSM or CDMA network. While these voice calls may or may not be
+packet-switched, they are for the purposes of Android 2.3 considered
+independent of any data connectivity that may be implemented using the same
+network. In other words, the Android "telephony" functionality and APIs refer
+specifically to voice calls and SMS; for instance, device implementations that
+cannot place calls or send/receive SMS messages MUST NOT report the
+"android.hardware.telephony" feature or any sub-features, regardless of
+whether they use a cellular network for data connectivity.</p>
+<p>Android 2.3 MAY be used on devices that do not include telephony hardware.
+That is, Android 2.3 is compatible with devices that are not phones.
+However, if a device implementation does include GSM or CDMA telephony, it
+MUST implement full support for the API for that technology. Device
+implementations that do not include telephony hardware MUST implement the full
+APIs as no-ops.</p>
+<a name="section-7.4.2"></a><h4>7.4.2. IEEE 802.11 (WiFi)</h4>
+<p>Android 2.3 device implementations SHOULD include support for one or more
+forms of 802.11 (b/g/a/n, etc.) If a device implementation does include
+support for 802.11, it MUST implement the corresponding Android API.</p>
+<a name="section-7.4.3"></a><h4>7.4.3. Bluetooth</h4>
+<p>Device implementations SHOULD include a Bluetooth transceiver. Device
+implementations that do include a Bluetooth transceiver MUST enable the
+RFCOMM-based Bluetooth API as described in the SDK documentation [<a
+href="#resources32">Resources, 32</a>]. Device implementations SHOULD
+implement relevant Bluetooth profiles, such as A2DP, AVRCP, OBEX, etc. as
+appropriate for the device.</p>
+<p>The Compatibility Test Suite includes cases that cover basic operation of
+the Android RFCOMM Bluetooth API. However, since Bluetooth is a communications
+protocol between devices, it cannot be fully tested by unit tests running on a
+single device. Consequently, device implementations MUST also pass the
+human-driven Bluetooth test procedure described in Appendix A.</p>
+<a name="section-7.4.4"></a><h4>7.4.4. Near-Field Communications</h4>
+<p>Device implementations SHOULD include a transceiver and related hardware
+for Near-Field Communications (NFC). If a device implementation does include
+NFC hardware, then it:</p>
+<ul>
+<li>MUST report the android.hardware.nfc feature from the
+<code>android.content.pm.PackageManager.hasSystemFeature()</code> method. [<a href="#resources27">Resources, 27</a>]</li>
+<li>MUST be capable of reading and writing NDEF messages via the following NFC
+standards:<ul>
+<li>MUST be capable of acting as an NFC Forum reader/writer
+(as defined by the NFC Forum technical specification
+NFCForum-TS-DigitalProtocol-1.0) via the following NFC standards:<ul>
+ <li>NfcA (ISO14443-3A)</li>
+ <li>NfcB (ISO14443-3B) </li>
+ <li>NfcF (JIS 6319-4)</li>
+ <li>NfcV (ISO 15693)</li>
+ <li>IsoDep (ISO 14443-4)</li>
+ <li>NFC Forum Tag Types 1, 2, 3, 4 (defined by the NFC Forum)</li>
+</ul></li>
+<li>MUST be capable of transmitting and receiving data via the following
+peer-to-peer standards and protocols:<ul>
+ <li>ISO 18092</li>
+ <li>LLCP 1.0 (defined by the NFC Forum)</li>
+ <li>SDP 1.0 (defined by the NFC Forum)</li>
+ <li>NDEF Push Protocol [<a href="#resources33">Resources, 33</a>]</li>
+</ul></li>
+<li>MUST scan for all supported technologies while in NFC discovery mode.</li>
+<li>SHOULD be in NFC discovery mode while the device is awake with the screen active.</li>
+</ul>
+<p>(Note that publicly available links are not available for the JIS, ISO, and
+NFC Forum specifications cited above.)</p>
+<p>Additionally, device implementations SHOULD support the following
+widely-deployed MIFARE technologies.</p>
+<ul>
+ <li>MIFARE Classic (NXP MF1S503x [<a href="#resources34">Resources, 34</a>], MF1S703x [<a href="#resources35">Resources, 35</a>])</li>
+ <li>MIFARE Ultralight (NXP MF0ICU1 [<a href="#resources36">Resources, 36</a>], MF0ICU2 [<a href="#resources37">Resources, 37</a>])</li>
+ <li>NDEF on MIFARE Classic (NXP AN130511 [<a href="#resources38">Resources, 38</a>], AN130411 [<a href="#resources39">Resources, 39</a>])</li>
+</ul>
+<p>Note that Android 2.3.3 includes APIs for these MIFARE types. If a
+device implementation supports MIFARE, it:</p>
+<ul>
+ <li>MUST implement the corresponding Android APIs as documented by the
+ Android SDK</li>
+ <li>MUST report the feature com.nxp.mifare from the
+ <code>android.content.pm.PackageManager.hasSystemFeature()</code> method.
+ [<a href="#resources27">Resources, 27</a>] Note that this is not a standard
+ Android feature, and as such does not appear as a constant on the
+ <code>PackageManager</code> class.</li>
+ <li>MUST NOT implement the corresponding Android APIs nor report the
+ com.nxp.mifare feature unless it also implements general NFC support as
+ described in this section</li>
+</ul>
+<p>If a device implementation does not include NFC hardware, it MUST NOT
+declare the android.hardware.nfc feature from the
+<code>android.content.pm.PackageManager.hasSystemFeature()</code> method [<a
+href="#resources27">Resources, 27</a>], and MUST implement the Android 2.3 NFC
+API as a no-op.</p>
+<p>As the classes <code>android.nfc.NdefMessage</code> and
+<code>android.nfc.NdefRecord</code> represent a protocol-independent data
+representation format, device implementations MUST implement these APIs even
+if they do not include support for NFC or declare the android.hardware.nfc
+feature.</p>
+<a name="section-7.4.5"></a><h4>7.4.5. Minimum Network Capability</h4>
+<p>Device implementations MUST include support for one or more forms of data
+networking. Specifically, device implementations MUST include support for at
+least one data standard capable of 200Kbit/sec or greater. Examples of
+technologies that satisfy this requirement include EDGE, HSPA, EV-DO, 802.11g,
+Ethernet, etc.</p>
+<p>Device implementations where a physical networking standard (such as
+Ethernet) is the primary data connection SHOULD also include support for at
+least one common wireless data standard, such as 802.11 (WiFi).</p>
+<p>Devices MAY implement more than one form of data connectivity.</p>
+
+
+<a name="section-7.5"></a><h3>7.5. Cameras</h3>
+<p>Device implementations SHOULD include a rear-facing camera, and MAY include
+a front-facing camera. A rear-facing camera is a camera located on the side of
+the device opposite the display; that is, it images scenes on the far side of
+the device, like a traditional camera. A front-facing camera is a camera
+located on the same side of the device as the display; that is, a camera
+typically used to image the user, such as for video conferencing and similar
+applications.</p>
+<a name="section-7.5.1"></a><h4>7.5.1. Rear-Facing Camera</h4>
+<p>Device implementations SHOULD include a rear-facing camera. If a device
+implementation includes a rear-facing camera, it:</p>
+<ul>
+<li>MUST have a resolution of at least 2 megapixels</li>
+<li>SHOULD have either hardware auto-focus, or software auto-focus implemented
+in the camera driver (transparent to application software)</li>
+<li>MAY have fixed-focus or EDOF (extended depth of field) hardware</li>
+<li>MAY include a flash. If the Camera includes a flash, the flash lamp MUST
+NOT be lit while an android.hardware.Camera.PreviewCallback instance has been
+registered on a Camera preview surface, unless the application has explicitly
+enabled the flash by enabling the <code>FLASH_MODE_AUTO</code> or
+<code>FLASH_MODE_ON</code> attributes of a <code>Camera.Parameters</code>
+object. Note that this constraint does not apply to the device's built-in
+system camera application, but only to third-party applications using
+<code>Camera.PreviewCallback</code>.</li>
+</ul>
+<a name="section-7.5.2"></a><h4>7.5.2. Front-Facing Camera</h4>
+<p>Device implementations MAY include a front-facing camera. If a device
+implementation includes a front-facing camera, it:</p>
+<ul>
+<li>MUST have a resolution of at least VGA (that is, 640x480 pixels)</li>
+<li>MUST NOT use a front-facing camera as the default for the Camera API.
+That is, the camera API in Android 2.3 has specific support for front-facing
+cameras, and device implementations MUST NOT configure the API to to treat a
+front-facing camera as the default rear-facing camera, even if it is the only
+camera on the device.</li>
+<li>MAY include features (such as auto-focus, flash, etc.)
+available to rear-facing cameras as described in Section 7.5.1.</li>
+<li>MUST horizontally reflect (i.e. mirror) the stream displayed by an app in a
+CameraPreview, as follows:</li>
+<ul>
+<li>If the device implementation is capable of being rotated by user (such as
+automatically via an accelerometer or manually via user input), the camera
+preview MUST be mirrored horizontally relative to the device's current
+orientation.</li>
+<li>If the current application has explicitly requested that the Camera
+display be rotated via a call to the
+<code>android.hardware.Camera.setDisplayOrientation()</code> [<a
+href="#resources40">Resources, 40</a>] method, the camera preview MUST be
+mirrored horizontally relative to the orientation specified by the
+application.</li>
+<li>Otherwise, the preview MUST be mirrored along the device's default horizontal axis.</li>
+</ul>
+<li>MUST mirror the image data returned to any "postview" camera callback
+handlers, in the same manner as the camera preview image stream. (If the device
+implementation does not support postview callbacks, this requirement obviously
+does not apply.)</li>
+<li>MUST NOT mirror the final captured still image or video streams returned
+to application callbacks or committed to media storage</li>
+</ul>
+<a name="section-7.5.3"></a><h4>7.5.3. Camera API Behavior</h4>
+<p>Device implementations MUST implement the following behaviors for the
+camera-related APIs, for both front- and rear-facing cameras:</p>
+<ol>
+<li>If an application has never called
+android.hardware.Camera.Parameters.setPreviewFormat(int), then the device MUST
+use android.hardware.PixelFormat.YCbCr_420_SP for preview data provided to
+application callbacks.</li>
+<li>If an application registers an android.hardware.Camera.PreviewCallback
+instance and the system calls the onPreviewFrame() method when the preview
+format is YCbCr_420_SP, the data in the byte[] passed into onPreviewFrame()
+must further be in the NV21 encoding format. That is, NV21 MUST be the default.</li>
+<li>Device implementations SHOULD support the YV12 format (as denoted by the
+<code>android.graphics.ImageFormat.YV12</code> constant) for camera previews
+for both front- and rear-facing cameras. Note that the Compatibility
+Definition for a future version is planned to change this requirement to
+"MUST". That is, YV12 support is optional in Android 2.3 but <b>will be
+required</b> by a future version. Existing and new devices that run Android
+2.3 are <b>very strongly encouraged to meet this requirement in Android
+2.3</b>, or they will not be able to attain Android compatibility when
+upgraded to the future version.</li>
+</ol>
+<p>Device implementations MUST implement the full Camera API included in the
+Android 2.3 SDK documentation [<a href="#resources41">Resources, 41</a>]),
+regardless of whether the device includes hardware autofocus or other
+capabilities. For instance, cameras that lack autofocus MUST still call any
+registered <code>android.hardware.Camera.AutoFocusCallback</code> instances (even though
+this has no relevance to a non-autofocus camera.) Note that this does apply
+to front-facing cameras; for instance, even though most front-facing cameras
+do not support autofocus, the API callbacks must still be "faked" as
+described.</p>
+<p>Device implementations MUST recognize and honor each parameter name defined
+as a constant on the <code>android.hardware.Camera.Parameters</code> class, if the
+underlying hardware supports the feature. If the device hardware does not
+support a feature, the API must behave as documented. Conversely, Device
+implementations MUST NOT honor or recognize string constants passed
+to the <code>android.hardware.Camera.setParameters()</code> method other than
+those documented as constants on the
+<code>android.hardware.Camera.Parameters</code>. That is,
+device implementations MUST support all standard Camera parameters if the
+hardware allows, and MUST NOT support custom Camera parameter types.</p>
+<a name="section-7.5.4"></a><h4>7.5.4. Camera Orientation</h4>
+<p>Both front- and rear-facing cameras, if present, MUST be oriented so that
+the long dimension of the camera aligns with the screen's long dimention. That
+is, when the device is held in the landscape orientation, a cameras MUST
+capture images in the landscape orientation. This applies regardless of the
+device's natural orientation; that is, it applies to landscape-primary devices
+as well as portrait-primary devices.</p>
+
+
+<a name="section-7.6"></a><h3>7.6. Memory and Storage</h3>
+<p>The fundamental function of Android 2.3 is to run applications. Device
+implementations MUST the requirements of this section, to ensure adequate
+storage and memory for applications to run properly.</p>
+<a name="section-7.6.1"></a><h4>7.6.1. Minimum Memory and Storage</h4>
+<p>Device implementations MUST have at least 128MB of memory available to the
+kernel and userspace. The 128MB MUST be in addition to any memory dedicated to
+hardware components such as radio, memory, and so on that is not under the
+kernel's control.</p>
+<p>Device implementations MUST have at least 150MB of non-volatile storage
+available for user data. That is, the <code>/data</code> partition MUST be at
+least 150MB.</p>
+<p>Beyond the requirements above, device implementations SHOULD have at least
+1GB of non-volatile storage available for user data. Note that this higher
+requirement is planned to become a hard minimum in a future version of
+Android. Device implementations are strongly encouraged to meet these
+requirements now, or else they may not be eligible for compatibility for a
+future version of Android.</p>
+<p>The Android APIs include a Download Manager that applications may use to
+download data files. The Download Manager implementation MUST be capable of
+downloading individual files 55MB in size, or larger. The Download Manager
+implementation SHOULD be capable of downloading files 100MB in size, or
+larger.</p>
+<a name="section-7.6.2"></a><h4>7.6.2. Application Shared Storage</h4>
+<p>Device implementations MUST offer shared storage for applications. The
+shared storage provided MUST be at least 1GB in size.</p>
+<p>Device implementations MUST be configured with shared storage mounted by
+default, "out of the box". If the shared storage is not mounted on the Linux
+path <code>/sdcard</code>, then the device MUST include a Linux symbolic link
+from <code>/sdcard</code> to the actual mount point.</p>
+<p>Device implementations MUST enforce as documented the
+<code>android.permission.WRITE_EXTERNAL_STORAGE</code> permission on this
+shared storage. Shared storage MUST otherwise be writable by any application
+that obtains that permission.</p>
+<p>Device implementations MAY have hardware for user-accessible removable
+storage, such as a Secure Digital card. Alternatively, device implementations
+MAY allocate internal (non-removable) storage as shared storage for apps.</p>
+<p>Regardless of the form of shared storage used, device implementations MUST
+provide some mechanism to access the contents of shared storage from a host
+computer, such as USB mass storage or Media Transfer Protocol.</p>
+<p>It is illustrative to consider two common examples. If a device
+implementation includes an SD card slot to satisfy the shared storage
+requirement, a FAT-formatted SD card 1GB in size or larger MUST be included
+with the device as sold to users, and MUST be mounted by default.
+Alternatively, if a device implementation uses internal fixed storage to
+satisfy this requirement, that storage MUST be 1GB in size or larger
+and mounted on <code>/sdcard</code> (or <code>/sdcard</code>
+MUST be a symbolic link to the physical location if it is mounted elsewhere.)</p>
+<p>Device implementations that include multiple shared storage paths (such as
+both an SD card slot and shared internal storage) SHOULD modify the core
+applications such as the media scanner and ContentProvider to transparently
+support files placed in both locations.</p>
+
+<a name="section-7.7"></a><h3>7.7. USB</h3>
+<p>Device implementations:</p>
+<ul>
+<li>MUST implement a USB client, connectable to a USB host with a standard
+USB-A port</li>
+<li>MUST implement the Android Debug Bridge over USB (as described in Section
+7)</li>
+<li>MUST implement the USB mass storage specification, to allow a host
+connected to the device to access the contents of the /sdcard volume </li>
+<li>SHOULD use the micro USB form factor on the device side</li>
+<li>MAY include a non-standard port on the device side, but if so MUST ship
+with a cable capable of connecting the custom pinout to standard USB-A
+port</li>
+</ul>
+
+
+<a name="section-8"></a><h2>8. Performance Compatibility</h2>
+<p>Compatible implementations must ensure not only that applications simply
+run correctly on the device, but that they do so with reasonable performance
+and overall good user experience. Device implementations MUST meet the key
+performance metrics of an Android 2.3 compatible device defined in the table
+below:</p>
+<table><tbody><tr>
+<td><b>Metric</b></td>
+<td><b>Performance Threshold</b></td>
+<td><b>Comments</b></td>
+</tr>
+<tr>
+<td>Application Launch Time</td>
+<td>The following applications should launch within the specified time.<ul>
+<li>Browser: less than 1300ms</li>
+<li>MMS/SMS: less than 700ms</li>
+<li>AlarmClock: less than 650ms</li>
+</ul></td>
+<td>The launch time is measured as the total time to
+complete loading the default activity for the application, including the time
+it takes to start the Linux process, load the Android package into the Dalvik
+VM, and call onCreate.</td>
+</tr>
+<tr>
+<td>Simultaneous Applications</td>
+<td>When multiple applications have been launched, re-launching an
+already-running application after it has been launched must take less than the
+original launch time.</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+
+<a name="section-9"></a><h2>9. Security Model Compatibility</h2>
+<p>Device implementations MUST implement a security model consistent with the
+Android platform security model as defined in Security and Permissions
+reference document in the APIs [<a href="#resources42">Resources, 42</a>] in the
+Android developer documentation. Device implementations MUST support
+installation of self-signed applications without requiring any additional
+permissions/certificates from any third parties/authorities. Specifically,
+compatible devices MUST support the security mechanisms described in the
+follow sub-sections.</p>
+<a name="section-9.1"></a><h3>9.1. Permissions</h3>
+<p>Device implementations MUST support the Android permissions model as
+defined in the Android developer documentation [<a
+href="#resources42">Resources, 42</a>]. Specifically,
+implementations MUST enforce each permission defined as described in the SDK
+documentation; no permissions may be omitted, altered, or ignored.
+Implementations MAY add additional permissions, provided the new permission ID
+strings are not in the android.* namespace.</p>
+<a name="section-9.2"></a><h3>9.2. UID and Process Isolation</h3>
+<p>Device implementations MUST support the Android application sandbox model,
+in which each application runs as a unique Unix-style UID and in a separate
+process. Device implementations MUST support running multiple applications as
+the same Linux user ID, provided that the applications are properly signed and
+constructed, as defined in the Security and Permissions reference [<a
+href="#resources42">Resources, 42</a>].</p>
+<a name="section-9.3"></a><h3>9.3. Filesystem Permissions</h3>
+<p>Device implementations MUST support the Android file access permissions
+model as defined in as defined in the Security and Permissions reference [<a
+href="#resources42">Resources, 42</a>].</p>
+<a name="section-9.4"></a><h3>9.4. Alternate Execution Environments</h3>
+<p>Device implementations MAY include runtime environments that execute
+applications using some other software or technology than the Dalvik virtual
+machine or native code. However, such alternate execution environments MUST
+NOT compromise the Android security model or the security of installed Android
+applications, as described in this section.</p>
+<p>Alternate runtimes MUST themselves be Android applications, and abide by
+ the standard Android security model, as described elsewhere in Section 9.</p>
+<p>Alternate runtimes MUST NOT be granted access to resources protected by
+ permissions not requested in the runtime's AndroidManifest.xml file via the
+ <code><uses-permission></code> mechanism.</p>
+<p>Alternate runtimes MUST NOT permit applications to make use of features
+ protected by Android permissions restricted to system applications.</p>
+<p>Alternate runtimes MUST abide by the Android sandbox model. Specifically:</p>
+<ul>
+<li>Alternate runtimes SHOULD install apps via the PackageManager into
+ separate Android sandboxes (that is, Linux user IDs, etc.)</li>
+<li>Alternate runtimes MAY provide a single Android sandbox shared by all
+ applications using the alternate runtime.</li>
+<li>Alternate runtimes and installed applications using an alternate runtime
+ MUST NOT reuse the sandbox of any other app installed on the device, except
+ through the standard Android mechanisms of shared user ID and signing
+ certificate</li>
+<li>Alternate runtimes MUST NOT launch with, grant, or be granted access to
+ the sandboxes corresponding to other Android applications.</li>
+</ul>
+<p>Alternate runtimes MUST NOT be launched with, be granted, or grant to other
+ applications any privileges of the superuser (root), or of any other user ID.</p>
+<p>The .apk files of alternate runtimes MAY be included in the system image of
+ a device implementation, but MUST be signed with a key distinct
+ from the key used to sign other applications included with the device
+ implementation.</p>
+<p>When installing applications, alternate runtimes MUST obtain user consent
+ for the Android permissions used by the application. That is, if an
+ application needs to make use of a device resource for which there is a
+ corresponding Android permission (such as Camera, GPS, etc.), the alternate
+ runtime MUST inform the user that the application will be able to access
+ that resource. If the runtime environment does not record application
+ capabilities in this manner, the runtime environment MUST list all
+ permissions held by the runtime itself when installing any application
+ using that runtime.</p>
+
+<a name="section-10"></a><h2>10. Software Compatibility Testing</h2>
+<p>The Android Open-Source Project includes various testing tools to verify
+that device implementations are compatible. Device implementations MUST pass
+all tests described in this section.</p>
+<p>However, note that no software test package is fully comprehensive. For
+this reason, device implementers are very strongly encouraged to make the
+minimum number of changes as possible to the reference and preferred
+implementation of Android 2.3 available from the Android Open-Source Project.
+This will minimize the risk of introducing bugs that create incompatibilities
+requiring rework and potential device updates.</p>
+<a name="section-10.1"></a><h3>10.1. Compatibility Test Suite</h3>
+<p>Device implementations MUST pass the Android Compatibility Test Suite (CTS)
+[<a href="#resources02">Resources, 2</a>] available from the Android Open Source
+Project, using the final shipping software on the device. Additionally, device
+implementers SHOULD use the reference implementation in the Android Open
+Source tree as much as possible, and MUST ensure compatibility in cases of
+ambiguity in CTS and for any reimplementations of parts of the reference
+source code.</p>
+<p>The CTS is designed to be run on an actual device. Like any software, the
+CTS may itself contain bugs. The CTS will be versioned independently of this
+Compatibility Definition, and multiple revisions of the CTS may be released
+for Android 2.3. Device implementations MUST pass the latest CTS version
+available at the time the device software is completed.</p>
+<p>MUST pass the most recent version of the Android Compatibility Test Suite
+(CTS) available at the time of the device implementation's software is
+completed. (The CTS is available as part of the Android Open Source Project [<a
+href="#resources02">Resources, 2</a>].) The CTS tests many, but not all, of the
+components outlined in this document.</p>
+<a name="section-10.2"></a><h3>10.2. CTS Verifier</h3>
+<p>Device implementations MUST correctly execute all applicable cases in the
+CTS Verifier. The CTS Verifier is included with the Compatibility Test Suite,
+and is intended to be run by a human operator to test functionality that
+cannot be tested by an automated system, such as correct functioning of a
+camera and sensors.</p>
+<p>The CTS Verifier has tests for many kinds of hardware, including some
+hardware that is optional. Device implementations MUST pass all tests for
+hardware which they possess; for instance, if a device possesses an
+accelerometer, it MUST correctly execute the Accelerometer test case in the
+CTS Verifier. Test cases for features noted as optional by this Compatibility
+Definition Document MAY be skipped or omitted.</p>
+<p>Every device and every build MUST correctly run the CTS Verifier, as noted
+above. However, since many builds are very similar, device implementers are
+not expected to explicitly run the CTS Verifier on builds that differ only in
+trivial ways. Specifically, device implementations that differ from an
+implementation that has passed the CTS Verfier only by the set of included
+locales, branding, etc. MAY omit the CTS Verifier test.</p>
+<a name="section-10.3"></a><h3>10.3. Reference Applications</h3>
+<p>Device implementers MUST test implementation compatibility using the
+following open-source applications:</p>
+<ul>
+<li>The "Apps for Android" applications [<a href="#resources43">Resources, 43</a>].</li>
+<li>Replica Island (available in Android Market; only required for device
+ implementations that support with OpenGL ES 2.0)</li>
+</ul>
+<p>Each app above MUST launch and behave correctly on the implementation, for
+the implementation to be considered compatible.</p>
+
+
+<a name="section-11"></a><h2>11. Updatable Software</h2>
+<p>Device implementations MUST include a mechanism to replace the entirety of
+the system software. The mechanism need not perform "live" upgrades -- that
+is, a device restart MAY be required.</p>
+<p>Any method can be used, provided that it can replace the entirety of the
+software preinstalled on the device. For instance, any of the following
+approaches will satisfy this requirement:</p>
+<ul>
+<li>Over-the-air (OTA) downloads with offline update via reboot</li>
+<li>"Tethered" updates over USB from a host PC</li>
+<li>"Offline" updates via a reboot and update from a file on removable
+storage</li>
+</ul>
+<p>The update mechanism used MUST support updates without wiping user data.
+Note that the upstream Android software includes an update mechanism that
+satisfies this requirement.</p>
+<p>If an error is found in a device implementation after it has been released
+but within its reasonable product lifetime that is determined in consultation
+with the Android Compatibility Team to affect the compatibility of third-party
+applications, the device implementer MUST correct the error via a software
+update available that can be applied per the mechanism just described.</p>
+
+<a name="section-12"></a><h2>12. Contact Us</h2>
+<p>You can contact the document authors at <a
+href="mailto:compatibility@android.com">compatibility@android.com</a> for
+clarifications and to bring up any issues that you think the document does not
+cover.</p>
+
+<div style="page-break-before: always;"></div>
+
+<a name="appendix-A"></a><h2>Appendix A - Bluetooth Test Procedure</h2>
+<p>The Compatibility Test Suite includes cases that cover basic operation of
+the Android RFCOMM Bluetooth API. However, since Bluetooth is a communications
+protocol between devices, it cannot be fully tested by unit tests running on a
+single device. Consequently, device implementations MUST also pass the
+human-operated Bluetooth test procedure described below.</p>
+<p>The test procedure is based on the BluetoothChat sample app included in the
+Android open-source project tree. The procedure requires two devices:</p>
+<ul>
+<li>a candidate device implementation running the software build to be tested</li>
+<li>a separate device implementation already known to be compatible, and of a
+ model from the device implementation being tested -- that is, a "known
+ good" device implementation</li>
+</ul>
+<p>The test procedure below refers to these devices as the "candidate" and "known
+good" devices, respectively.</p>
+<h3>Setup and Installation</h3>
+<ol>
+<li>Build BluetoothChat.apk via 'make samples' from an Android source code tree.</li>
+<li>Install BluetoothChat.apk on the known-good device.</li>
+<li>Install BluetoothChat.apk on the candidate device.</li>
+</ol>
+<h3>Test Bluetooth Control by Apps</h3>
+<ol>
+<li>Launch BluetoothChat on the candidate device, while Bluetooth is disabled.</li>
+<li>Verify that the candidate device either turns on Bluetooth, or prompts the user with a dialog to turn on Bluetooth.</li>
+</ol>
+<h3>Test Pairing and Communication</h3>
+<ol>
+<li>Launch the Bluetooth Chat app on both devices.</li>
+<li>Make the known-good device discoverable from within BluetoothChat (using the Menu).</li>
+<li>On the candidate device, scan for Bluetooth devices from within BluetoothChat (using the Menu) and pair with the known-good device.</li>
+<li>Send 10 or more messages from each device, and verify that the other device receives them correctly.</li>
+<li>Close the BluetoothChat app on both devices by pressing <b>Home</b>.</li>
+<li>Unpair each device from the other, using the device Settings app.</li>
+</ol>
+<h3>Test Pairing and Communication in the Reverse Direction</h3>
+<ol>
+<li>Launch the Bluetooth Chat app on both devices.</li>
+<li>Make the candidate device discoverable from within BluetoothChat (using the Menu).</li>
+<li>On the known-good device, scan for Bluetooth devices from within BluetoothChat (using the Menu) and pair with the candidate device.</li>
+<li>Send 10 or messages from each device, and verify that the other device receives them correctly.</li>
+<li>Close the Bluetooth Chat app on both devices by pressing Back repeatedly to get to the Launcher.</li>
+</ol>
+<h3>Test Re-Launches</h3>
+<ol>
+<li>Re-launch the Bluetooth Chat app on both devices.</li>
+<li>Send 10 or messages from each device, and verify that the other device receives them correctly.</li>
+</ol>
+<p>Note: the above tests have some cases which end a test section by using
+Home, and some using Back. These tests are not redundant and are not optional:
+the objective is to verify that the Bluetooth API and stack works correctly
+both when Activities are explicitly terminated (via the user pressing Back,
+which calls finish()), and implicitly sent to background (via the user
+pressing Home.) Each test sequence MUST be performed as described.</p>
+<div id="footerContent" xmlns:pdf="http://whatever">
+<pdf:pagenumber/>
+</div>
+</body>
+</html>
diff --git a/src/compatibility/4.0/android-4.0-cdd.xhtml b/src/compatibility/4.0/android-4.0-cdd.xhtml
new file mode 100644
index 0000000..e620230
--- /dev/null
+++ b/src/compatibility/4.0/android-4.0-cdd.xhtml
@@ -0,0 +1,2448 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>Android 4.0 Compatibility Definition</title>
+<link rel="stylesheet" type="text/css" href="cdd.css"/>
+</head>
+<body>
+<div><img src="header.jpg" alt="Android logo"/></div>
+<h1>Android 4.0 Compatibility Definition</h1>
+<!--
+<span style="color: red; font-weight: bold;"><h2>DRAFT 3</h2></span><br/>
+<span style="color: red;">Last updated: November 17, 2012</span>
+-->
+<p>Revision 4<br/>
+Last updated: April 21, 2013
+</p>
+<p>Copyright © 2012, Google Inc. All rights reserved.<br/>
+<a href="mailto:compatibility@android.com">compatibility@android.com</a>
+</p>
+
+<h2> Table of Contents</h2>
+<div style="margin-left: 2em;">
+ <a href="#section-1">1. Introduction</a><br/>
+ <a href="#section-2">2. Resources</a><br/>
+ <a href="#section-3">3. Software</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.1">3.1. Managed API Compatibility</a><br/>
+ <a href="#section-3.2">3.2. Soft API Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.2.1">3.2.1. Permissions</a><br/>
+ <a href="#section-3.2.2">3.2.2. Build Parameters</a><br/>
+ <a href="#section-3.2.3">3.2.3. Intent Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.2.3.1">3.2.3.1. Core Application Intents</a><br/>
+ <a href="#section-3.2.3.2">3.2.3.2. Intent Overrides</a><br/>
+ <a href="#section-3.2.3.3">3.2.3.3. Intent Namespaces</a><br/>
+ <a href="#section-3.2.3.4">3.2.3.4. Broadcast Intents</a><br/>
+ </div>
+ </div>
+ <a href="#section-3.3">3.3. Native API Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.3.1">3.3.1 Application Binary Interfaces</a><br/>
+ </div>
+ <a href="#section-3.4">3.4. Web Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.4.1">3.4.1. WebView Compatibility</a><br/>
+ <a href="#section-3.4.2">3.4.2. Browser Compatibility</a><br/>
+ </div>
+ <a href="#section-3.5">3.5. API Behavioral Compatibility</a><br/>
+ <a href="#section-3.6">3.6. API Namespaces</a><br/>
+ <a href="#section-3.7">3.7. Virtual Machine Compatibility</a><br/>
+ <a href="#section-3.8">3.8. User Interface Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.8.1">3.8.1. Widgets</a><br/>
+ <a href="#section-3.8.2">3.8.2. Notifications</a><br/>
+ <a href="#section-3.8.3">3.8.3. Search</a><br/>
+ <a href="#section-3.8.4">3.8.4. Toasts</a><br/>
+ <a href="#section-3.8.5">3.8.5. Themes</a><br/>
+ <a href="#section-3.8.6">3.8.6. Live Wallpapers</a><br/>
+ <a href="#section-3.8.7">3.8.7. Recent Application Display</a><br/>
+ <a href="#section-3.8.8">3.8.8. Input Management Settings</a><br/>
+ </div>
+ <a href="#section-3.9">3.9 Device Administration</a><br/>
+ <a href="#section-3.10">3.10 Accessibility</a><br/>
+ <a href="#section-3.11">3.11 Text-to-Speech</a><br/>
+ </div>
+ <a href="#section-4">4. Application Packaging Compatibility</a><br/>
+ <a href="#section-5">5. Multimedia Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-5.1">5.1. Media Codecs</a><br/>
+ <a href="#section-5.2">5.2. Video Encoding</a><br/>
+ <a href="#section-5.3">5.3. Audio Recording</a><br/>
+ <a href="#section-5.4">5.4. Audio Latency</a><br/>
+ <a href="#section-5.5">5.5. Network Protocols</a><br/>
+ </div>
+ <a href="#section-6">6. Developer Tool Compatibility</a><br/>
+ <a href="#section-7">7. Hardware Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.1">7.1. Display and Graphics</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.1.1">7.1.1. Screen Configuration</a><br/>
+ <a href="#section-7.1.2">7.1.2. Display Metrics</a><br/>
+ <a href="#section-7.1.3">7.1.3. Screen Orientation</a><br/>
+ <a href="#section-7.1.4">7.1.4. 2D and 3D Graphics Accleration</a><br/>
+ <a href="#section-7.1.5">7.1.5. Legacy Application Compatibility Mode</a><br/>
+ <a href="#section-7.1.6">7.1.6. Screen Types</a><br/>
+ <a href="#section-7.1.7">7.1.7. Screen Technology</a><br/>
+ </div>
+ <a href="#section-7.2">7.2. Input Devices</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.2.1">7.2.1. Keyboard</a><br/>
+ <a href="#section-7.2.2">7.2.2. Non-touch Navigation</a><br/>
+ <a href="#section-7.2.3">7.2.3. Navigation keys</a><br/>
+ <a href="#section-7.2.4">7.2.4. Touchscreen input</a><br/>
+ <a href="#section-7.2.5">7.2.5. Fake touch input</a><br/>
+ <a href="#section-7.2.6">7.2.6. Microphone</a><br/>
+ </div>
+ <a href="#section-7.3">7.3. Sensors</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.3.1">7.3.1. Accelerometer</a><br/>
+ <a href="#section-7.3.2">7.3.2. Magnetometer</a><br/>
+ <a href="#section-7.3.3">7.3.3. GPS</a><br/>
+ <a href="#section-7.3.4">7.3.4. Gyroscope</a><br/>
+ <a href="#section-7.3.5">7.3.5. Barometer</a><br/>
+ <a href="#section-7.3.6">7.3.6. Thermometer</a><br/>
+ <a href="#section-7.3.7">7.3.7. Photometer</a><br/>
+ <a href="#section-7.3.8">7.3.8. Proximity Sensor</a><br/>
+ </div>
+ <a href="#section-7.4">7.4. Data Connectivity</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.4.1">7.4.1. Telephony</a><br/>
+ <a href="#section-7.4.2">7.4.2. IEEE 802.11 (WiFi)</a><br/>
+ <a href="#section-7.4.3">7.4.3. Bluetooth</a><br/>
+ <a href="#section-7.4.4">7.4.4. Near-Field Communications</a><br/>
+ <a href="#section-7.4.5">7.4.5. Minimum Network Capability</a><br/>
+ </div>
+ <a href="#section-7.5">7.5. Cameras</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.5.1">7.5.1. Rear-Facing Camera</a><br/>
+ <a href="#section-7.5.2">7.5.2. Front-Facing Camera</a><br/>
+ <a href="#section-7.5.3">7.5.3. Camera API Behavior</a><br/>
+ <a href="#section-7.5.4">7.5.4. Camera Orientation</a><br/>
+ </div>
+ <a href="#section-7.6">7.6. Memory and Storage</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.6.1">7.6.1. Minimum Memory and Storage</a><br/>
+ <a href="#section-7.6.2">7.6.2. Application Shared Storage</a><br/>
+ </div>
+ <a href="#section-7.7">7.7. USB</a><br/>
+ </div>
+ <a href="#section-8">8. Performance Compatibility</a><br/>
+ <a href="#section-9">9. Security Model Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-9.1">9.1. Permissions</a><br/>
+ <a href="#section-9.2">9.2. UID and Process Isolation</a><br/>
+ <a href="#section-9.3">9.3. Filesystem Permissions</a><br/>
+ <a href="#section-9.4">9.4. Alternate Execution Environments</a><br/>
+ </div>
+ <a href="#section-10">10. Software Compatibility Testing</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-10.1">10.1. Compatibility Test Suite</a><br/>
+ <a href="#section-10.2">10.2. CTS Verifier</a><br/>
+ <a href="#section-10.3">10.3. Reference Applications</a><br/>
+ </div>
+ <a href="#section-11">11. Updatable Software</a><br/>
+ <a href="#section-12">12. Contact Us</a><br/>
+ <a href="#appendix-A">Appendix A - Bluetooth Test Procedure</a><br/>
+</div>
+
+<div style="page-break-before: always;"></div>
+
+<a name="section-1"></a><h2>1. Introduction</h2>
+<p>This document enumerates the requirements that must be met in order for
+devices to be compatible with Android 4.0.</p>
+<p>The use of "must", "must not", "required", "shall", "shall not", "should",
+"should not", "recommended", "may" and "optional" is per the IETF standard
+defined in RFC2119 [<a href="#resources01">Resources, 1</a>].</p>
+<p>As used in this document, a "device implementer" or "implementer" is a
+person or organization developing a hardware/software solution running Android
+4.0. A "device implementation" or "implementation" is the hardware/software
+solution so developed.</p>
+<p>To be considered compatible with Android 4.0, device implementations
+MUST meet the requirements presented in this Compatibility Definition,
+including any documents incorporated via reference.</p>
+<p>Where this definition or the software tests described in <a
+href="#section-10">Section 10</a> is silent, ambiguous, or incomplete, it is
+the responsibility of the device implementer to ensure compatibility with
+existing implementations.</p>
+<p>For this reason, the Android Open Source Project [<a
+href="#resources03">Resources, 3</a>] is both the reference and preferred
+implementation of Android. Device implementers are strongly encouraged to base
+their implementations to the greatest extent possible on the "upstream" source
+code available from the Android Open Source Project. While some components can
+hypothetically be replaced with alternate implementations this practice is
+strongly discouraged, as passing the software tests will become substantially
+more difficult. It is the implementer's responsibility to ensure full
+behavioral compatibility with the standard Android implementation, including
+and beyond the Compatibility Test Suite. Finally, note that certain component
+substitutions and modifications are explicitly forbidden by this document.</p>
+<a name="section-2"></a><h2>2. Resources</h2>
+<ol>
+<a name="resources01"></a><li>IETF RFC2119 Requirement Levels: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a></li>
+<a name="resources02"></a><li>Android Compatibility Program Overview: <a href="http://source.android.com/compatibility/index.html">http://source.android.com/compatibility/index.html</a></li>
+<a name="resources03"></a><li>Android Open Source Project: <a href="http://source.android.com/">http://source.android.com/</a></li>
+<a name="resources04"></a><li>API definitions and documentation: <a href="http://developer.android.com/reference/packages.html">http://developer.android.com/reference/packages.html</a></li>
+<a name="resources05"></a><li>Android Permissions reference: <a href="http://developer.android.com/reference/android/Manifest.permission.html">http://developer.android.com/reference/android/Manifest.permission.html</a></li>
+<a name="resources06"></a><li>android.os.Build reference: <a href="http://developer.android.com/reference/android/os/Build.html">http://developer.android.com/reference/android/os/Build.html</a></li>
+<a name="resources07"></a><li>Android 4.0 allowed version strings: <a href="http://source.android.com/compatibility/4.0/versions.html">http://source.android.com/compatibility/4.0/versions.html</a></li>
+<a name="resources08"></a><li>Renderscript: <a href="http://developer.android.com/guide/topics/graphics/renderscript.html">http://developer.android.com/guide/topics/graphics/renderscript.html</a></li>
+<a name="resources09"></a><li>Hardware Acceleration: <a href="http://developer.android.com/guide/topics/graphics/hardware-accel.html">http://developer.android.com/guide/topics/graphics/hardware-accel.html</a></li>
+<a name="resources10"></a><li>android.webkit.WebView class: <a href="http://developer.android.com/reference/android/webkit/WebView.html">http://developer.android.com/reference/android/webkit/WebView.html</a></li>
+<a name="resources11"></a><li>HTML5: <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">http://www.whatwg.org/specs/web-apps/current-work/multipage/</a></li>
+<a name="resources12"></a><li>HTML5 offline capabilities: <a href="http://dev.w3.org/html5/spec/Overview.html#offline">http://dev.w3.org/html5/spec/Overview.html#offline</a></li>
+<a name="resources13"></a><li>HTML5 video tag: <a href="http://dev.w3.org/html5/spec/Overview.html#video">http://dev.w3.org/html5/spec/Overview.html#video</a></li>
+<a name="resources14"></a><li>HTML5/W3C geolocation API: <a href="http://www.w3.org/TR/geolocation-API/">http://www.w3.org/TR/geolocation-API/</a></li>
+<a name="resources15"></a><li>HTML5/W3C webdatabase API: <a href="http://www.w3.org/TR/webdatabase/">http://www.w3.org/TR/webdatabase/</a></li>
+<a name="resources16"></a><li>HTML5/W3C IndexedDB API: <a href="http://www.w3.org/TR/IndexedDB/">http://www.w3.org/TR/IndexedDB/</a></li>
+<a name="resources17"></a><li>Dalvik Virtual Machine specification: available in the Android source code, at dalvik/docs</li>
+<a name="resources18"></a><li>AppWidgets: <a href="http://developer.android.com/guide/practices/ui_guidelines/widget_design.html">http://developer.android.com/guide/practices/ui_guidelines/widget_design.html</a></li>
+<a name="resources19"></a><li>Notifications: <a href="http://developer.android.com/guide/topics/ui/notifiers/notifications.html">http://developer.android.com/guide/topics/ui/notifiers/notifications.html</a></li>
+<a name="resources20"></a><li>Application Resources: <a href="http://code.google.com/android/reference/available-resources.html">http://code.google.com/android/reference/available-resources.html</a></li>
+<a name="resources21"></a><li>Status Bar icon style guide: <a href="http://developer.android.com/guide/practices/ui_guidelines/icon_design.html#statusbarstructure">http://developer.android.com/guide/practices/ui_guideline /icon_design.html#statusbarstructure</a></li>
+<a name="resources22"></a><li>Search Manager: <a href="http://developer.android.com/reference/android/app/SearchManager.html">http://developer.android.com/reference/android/app/SearchManager.html</a></li>
+<a name="resources23"></a><li>Toasts: <a href="http://developer.android.com/reference/android/widget/Toast.html">http://developer.android.com/reference/android/widget/Toast.html</a></li>
+<a name="resources24"></a><li>Themes: <a href="http://developer.android.com/guide/topics/ui/themes.html">http://developer.android.com/guide/topics/ui/themes.html</a></li>
+<a name="resources25"></a><li>R.style class: <a href="http://developer.android.com/reference/android/R.style.html">http://developer.android.com/reference/android/R.style.html</a></li>
+<a name="resources26"></a><li>Live Wallpapers: <a href="http://developer.android.com/resources/articles/live-wallpapers.html">http://developer.android.com/resources/articles/live-wallpapers.html</a></li>
+<a name="resources27"></a><li>Android Device Administration: <a href="http://developer.android.com/guide/topics/admin/device-admin.html">http://developer.android.com/guide/topics/admin/device-admin.html</a></li>
+<a name="resources28"></a><li>android.app.admin.DevicePolicyManager class: <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html">http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html</a></li>
+<a name="resources29"></a><li>Android Accessibility Service APIs: <a href="http://developer.android.com/reference/android/accessibilityservice/package-summary.html">http://developer.android.com/reference/android/accessibilityservice/package-summary.html</a></li>
+<a name="resources30"></a><li>Android Accessibility APIs: <a href="http://developer.android.com/reference/android/view/accessibility/package-summary.html">http://developer.android.com/reference/android/view/accessibility/package-summary.html</a></li>
+<a name="resources31"></a><li>Eyes Free project: <a href="http://http://code.google.com/p/eyes-free">http://code.google.com/p/eyes-free</a></li>
+<a name="resources32"></a><li>Text-To-Speech APIs: <a href="http://developer.android.com/reference/android/speech/tts/package-summary.html">http://developer.android.com/reference/android/speech/tts/package-summary.html</a></li>
+<a name="resources33"></a><li>Reference tool documentation (for adb, aapt, ddms): <a href="http://developer.android.com/guide/developing/tools/index.html">http://developer.android.com/guide/developing/tools/index.html</a></li>
+<a name="resources34"></a><li>Android apk file description: <a href="http://developer.android.com/guide/topics/fundamentals.html">http://developer.android.com/guide/topics/fundamentals.html</a></li>
+<a name="resources35"></a><li>Manifest files: <a href="http://developer.android.com/guide/topics/manifest/manifest-intro.html">http://developer.android.com/guide/topics/manifest/manifest-intro.html</a></li>
+<a name="resources36"></a><li>Monkey testing tool: <a href="http://developer.android.com/guide/developing/tools/monkey.html">http://developer.android.com/guide/developing/tools/monkey.html</a></li>
+<a name="resources37"></a><li>Android android.content.pm.PackageManager class and Hardware Features List: <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html">http://developer.android.com/reference/android/content/pm/PackageManager.html</a></li>
+<a name="resources38"></a><li>Supporting Multiple Screens: <a href="http://developer.android.com/guide/practices/screens_support.html">http://developer.android.com/guide/practices/screens_support.html</a></li>
+<a name="resources39"></a><li>android.util.DisplayMetrics: <a href="http://developer.android.com/reference/android/util/DisplayMetrics.html">http://developer.android.com/reference/android/util/DisplayMetrics.html</a></li>
+<a name="resources40"></a><li>android.content.res.Configuration: <a href="http://developer.android.com/reference/android/content/res/Configuration.html">http://developer.android.com/reference/android/content/res/Configuration.html</a></li>
+<a name="resources41"></a><li>android.hardware.SensorEvent: <a href="http://developer.android.com/reference/android/hardware/SensorEvent.html">http://developer.android.com/reference/android/hardware/SensorEvent.html</a></li>
+<a name="resources42"></a><li>Bluetooth API: <a href="http://developer.android.com/reference/android/bluetooth/package-summary.html">http://developer.android.com/reference/android/bluetooth/package-summary.html</a></li>
+<a name="resources43"></a><li>NDEF Push Protocol: <a href="http://source.android.com/compatibility/ndef-push-protocol.pdf">http://source.android.com/compatibility/ndef-push-protocol.pdf</a></li>
+<a name="resources44"></a><li>MIFARE MF1S503X: <a href="http://www.nxp.com/documents/data_sheet/MF1S503x.pdf">http://www.nxp.com/documents/data_sheet/MF1S503x.pdf</a></li>
+<a name="resources45"></a><li>MIFARE MF1S703X: <a href="http://www.nxp.com/documents/data_sheet/MF1S703x.pdf">http://www.nxp.com/documents/data_sheet/MF1S703x.pdf</a></li>
+<a name="resources46"></a><li>MIFARE MF0ICU1: <a href="http://www.nxp.com/documents/data_sheet/MF0ICU1.pdf">http://www.nxp.com/documents/data_sheet/MF0ICU1.pdf</a></li>
+<a name="resources47"></a><li>MIFARE MF0ICU2: <a href="http://www.nxp.com/documents/short_data_sheet/MF0ICU2_SDS.pdf">http://www.nxp.com/documents/short_data_sheet/MF0ICU2_SDS.pdf</a></li>
+<a name="resources48"></a><li>MIFARE AN130511: <a href="http://www.nxp.com/documents/application_note/AN130511.pdf">http://www.nxp.com/documents/application_note/AN130511.pdf</a></li>
+<a name="resources49"></a><li>MIFARE AN130411: <a href="http://www.nxp.com/documents/application_note/AN130411.pdf">http://www.nxp.com/documents/application_note/AN130411.pdf</a></li>
+<a name="resources50"></a><li>Camera orientation API: <a href="http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)">http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)</a></li>
+<a name="resources51"></a><li>android.hardware.Camera: <a href="http://developer.android.com/reference/android/hardware/Camera.html">http://developer.android.com/reference/android/hardware/Camera.html</a></li>
+<a name="resources52"></a><li>Android Open Accessories: <a href="http://developer.android.com/guide/topics/usb/accessory.html">http://developer.android.com/guide/topics/usb/accessory.html</a></li>
+<a name="resources53"></a><li>USB Host API: <a href="http://developer.android.com/guide/topics/usb/host.html">http://developer.android.com/guide/topics/usb/host.html</a></li>
+<a name="resources54"></a><li>Android Security and Permissions reference: <a href="http://developer.android.com/guide/topics/security/security.html">http://developer.android.com/guide/topics/security/security.html</a></li>
+<a name="resources55"></a><li>Apps for Android: <a href="http://code.google.com/p/apps-for-android">http://code.google.com/p/apps-for-android</a></li>
+<a name="resources56"></a><li>android.app.DownloadManager class: <a href="http://developer.android.com/reference/android/app/DownloadManager.html">http://developer.android.com/reference/android/app/DownloadManager.html</a></li>
+<a name="resources57"></a><li>Android File Transfer: <a href="http://www.android.com/filetransfer">http://www.android.com/filetransfer</a></li>
+<a name="resources58"></a><li>Android Media Formats: <a href="http://developer.android.com/guide/appendix/media-formats.html">http://developer.android.com/guide/appendix/media-formats.html</a></li>
+<a name="resources59"></a><li>HTTP Live Streaming Draft Protocol: <a href="http://tools.ietf.org/html/draft-pantos-http-live-streaming-03">http://tools.ietf.org/html/draft-pantos-http-live-streaming-03</a></li>
+<a name="resources60"></a><li>Motion Event API: <a href="http://developer.android.com/reference/android/view/MotionEvent.html">http://developer.android.com/reference/android/view/MotionEvent.html</a></li>
+<a name="resources61"></a><li>Touch Input Configuration: <a href="http://source.android.com/tech/input/touch-devices.html">http://source.android.com/tech/input/touch-devices.html</a></li>
+</ol>
+
+<p>Many of these resources are derived directly or indirectly from the Android
+4.0 SDK, and will be functionally identical to the information in that SDK's
+documentation. In any cases where this Compatibility Definition or the
+Compatibility Test Suite disagrees with the SDK documentation, the SDK
+documentation is considered authoritative. Any technical details provided in
+the references included above are considered by inclusion to be part of this
+Compatibility Definition.</p>
+
+<a name="section-3"></a><h2>3. Software</h2>
+<a name="section-3.1"></a><h3>3.1. Managed API Compatibility</h3>
+<p>The managed (Dalvik-based) execution environment is the primary vehicle for
+Android applications. The Android application programming interface (API) is
+the set of Android platform interfaces exposed to applications running in the
+managed VM environment. Device implementations MUST provide complete
+implementations, including all documented behaviors, of any documented API
+exposed by the Android 4.0 SDK [<a href="#resources04">Resources, 4</a>].</p>
+<p>Device implementations MUST NOT omit any managed APIs, alter API interfaces
+or signatures, deviate from the documented behavior, or include no-ops, except
+where specifically allowed by this Compatibility Definition.</p>
+<p>This Compatibility Definition permits some types of hardware for which
+Android includes APIs to be omitted by device implementations. In such cases,
+the APIs MUST still be present and behave in a reasonable way. See
+<a href="#section-7">Section 7</a> for specific requirements for this scenario.
+</p>
+
+<a name="section-3.2"></a><h3>3.2. Soft API Compatibility</h3>
+<p>In addition to the managed APIs from Section 3.1, Android also includes a
+significant runtime-only "soft" API, in the form of such things such as
+Intents, permissions, and similar aspects of Android applications that cannot
+be enforced at application compile time.</p>
+<a name="section-3.2.1"></a><h4>3.2.1. Permissions</h4>
+<p>Device implementers MUST support and enforce all permission constants as
+documented by the Permission reference page [<a
+href="#resources05">Resources, 5</a>]. Note that Section 10 lists additional
+requirements related to the Android security model.</p>
+<a name="section-3.2.3"></a><h4>3.2.3. Build Parameters</h4>
+<p>The Android APIs include a number of constants on the <code>android.os.Build</code>
+class [<a href="#resources06">Resources, 6</a>] that are intended to describe
+the current device. To provide consistent, meaningful values across device
+implementations, the table below includes additional restrictions on the
+formats of these values to which device implementations MUST conform.</p>
+<table>
+<tbody>
+<tr>
+<td><b>Parameter</b></td>
+<td><b>Comments</b></td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.RELEASE</td>
+<td>The version of the currently-executing Android system, in human-readable
+format. This field MUST have one of the string values defined in [<a
+href="#resources07">Resources, 7</a>].</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.SDK</td>
+<td>The version of the currently-executing Android system, in a format
+accessible to third-party application code. For Android 4.0.1 - 4.0.2, this
+field MUST have the integer value 14. For Android 4.0.3 or greater, this field
+MUST have the integer value 15.</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.SDK_INT</td>
+<td>The version of the currently-executing Android system, in a format
+accessible to third-party application code. For Android 4.0.1 - 4.0.2, this
+field MUST have the integer value 14. For Android 4.0.3 or greater, this field
+MUST have the integer value 15.</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.INCREMENTAL</td>
+<td>A value chosen by the device implementer designating the specific build of
+the currently-executing Android system, in human-readable format. This value
+MUST NOT be re-used for different builds made available to end users. A typical use
+of this field is to indicate which build number or source-control change
+identifier was used to generate the build. There are no requirements on the
+specific format of this field, except that it MUST NOT be null or the empty
+string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.BOARD</td>
+<td>A value chosen by the device implementer identifying the specific internal
+hardware used by the device, in human-readable format. A possible use of this
+field is to indicate the specific revision of the board powering the device.
+The value of this field MUST be encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.BRAND</td>
+<td>A value chosen by the device implementer identifying the name of the
+company, organization, individual, etc. who produced the device, in
+human-readable format. A possible use of this field is to indicate the OEM
+and/or carrier who sold the device. The value of this field MUST be
+encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.CPU_ABI</td>
+<td>The name of the instruction set (CPU type + ABI convention) of native code.
+See <a href="#section-3.3">Section 3.3: Native API Compatibility</a>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.CPU_ABI2</td>
+<td>The name of the second instruction set (CPU type + ABI convention) of native code.
+See <a href="#section-3.3">Section 3.3: Native API Compatibility</a>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.DEVICE</td>
+<td>A value chosen by the device implementer identifying the specific
+configuration or revision of the body (sometimes called "industrial design")
+of the device. The value of this field MUST be encodable as 7-bit ASCII and
+match the regular expression <code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.FINGERPRINT</td>
+<td>A string that uniquely identifies this build. It SHOULD be reasonably
+human-readable. It MUST follow this template:
+<br/><code>$(BRAND)/$(PRODUCT)/$(DEVICE):$(VERSION.RELEASE)/$(ID)/$(VERSION.INCREMENTAL):$(TYPE)/$(TAGS)</code><br/>
+For example:
+<br/><code>acme/mydevice/generic:4.0/IRK77/3359:userdebug/test-keys</code><br/>
+The fingerprint MUST NOT include whitespace characters. If other fields included in the
+template above have whitespace characters, they MUST be replaced in the build
+fingerprint with another character, such as the underscore ("_") character.
+The value of this field MUST be encodable as 7-bit ASCII.</td>
+</tr>
+<tr>
+<td>android.os.Build.HARDWARE</td>
+<td>The name of the hardware (from the kernel command line or /proc). It SHOULD be
+reasonably human-readable. The value of this field MUST be encodable as 7-bit ASCII and
+match the regular expression <code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.HOST</td>
+<td>A string that uniquely identifies the host the build was built on, in
+human readable format. There are no requirements on the specific format of
+this field, except that it MUST NOT be null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.ID</td>
+<td>An identifier chosen by the device implementer to refer to a specific
+release, in human readable format. This field can be the same as
+android.os.Build.VERSION.INCREMENTAL, but SHOULD be a value sufficiently
+meaningful for end users to distinguish between software builds. The value of
+this field MUST be encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.MANUFACTURER</td>
+<td>The trade name of the Original Equipment Manufacturer (OEM) of the product.
+There are no requirements on the specific format of this field, except that it
+MUST NOT be null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.MODEL</td>
+<td>A value chosen by the device implementer containing the name of the device
+as known to the end user. This SHOULD be the same name under which the device
+is marketed and sold to end users. There are no requirements on the specific
+format of this field, except that it MUST NOT be null or the empty string
+("").</td>
+</tr>
+<tr>
+<td>android.os.Build.PRODUCT</td>
+<td>A value chosen by the device implementer containing the development name
+or code name of the product (SKU). MUST be human-readable, but is not necessarily
+intended for view by end users. The value of this field MUST be encodable as 7-bit
+ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.SERIAL</td>
+<td>A hardware serial number, if available. The value of this field MUST be encodable
+as 7-bit ASCII and match the regular expression
+<code>"^([a-zA-Z0-9]{0,20})$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.TAGS</td>
+<td>A comma-separated list of tags chosen by the device implementer that
+further distinguish the build. For example, "unsigned,debug". The value of
+this field MUST be encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.TIME</td>
+<td>A value representing the timestamp of when the build occurred.</td>
+</tr>
+<tr>
+<td>android.os.Build.TYPE</td>
+<td>A value chosen by the device implementer specifying the runtime
+configuration of the build. This field SHOULD have one of the values
+corresponding to the three typical Android runtime configurations: "user",
+"userdebug", or "eng". The value of this field MUST be
+encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.USER</td>
+<td>A name or user ID of the user (or automated user) that generated the
+build. There are no requirements on the specific format of this field, except
+that it MUST NOT be null or the empty string ("").</td>
+</tr>
+</tbody>
+</table>
+<a name="section-3.2.3"></a><h4>3.2.3. Intent Compatibility</h4>
+<p>
+Device implementations MUST honor Android's loose-coupling Intent system, as
+described in the sections below. By "honored", it is meant that the device
+implementer MUST provide an Android Activity or Service that specifies a
+matching Intent filter and binds to and implements correct behavior for each
+specified Intent pattern.</p>
+<a name="section-3.2.3.1"></a><h4>3.2.3.1. Core Application Intents</h4>
+<p>The Android upstream project defines a number of core applications, such as
+contacts, calendar, photo gallery, music player, and so on. Device implementers
+MAY replace these applications with alternative versions.</p>
+<p>However, any such alternative versions MUST honor the same Intent patterns
+provided by the upstream project. For example, if a device contains an
+alternative music player, it must still honor the Intent pattern issued by
+third-party applications to pick a song.</p>
+<p>The following applications are considered core Android system
+applications:</p>
+<ul>
+<li>Desk Clock</li>
+<li>Browser</li>
+<li>Calendar</li>
+<li>Contacts</li>
+<!--<li>Email</li>-->
+<li>Gallery</li>
+<li>GlobalSearch</li>
+<li>Launcher</li>
+<!-- <li>LivePicker (that is, the Live Wallpaper picker application; MAY be omitted
+if the device does not support Live Wallpapers, per Section 3.8.5.)</li> -->
+<!-- <li>Messaging (AKA "Mms")</li> -->
+<li>Music</li>
+<!-- <li>Phone</li> -->
+<li>Settings</li>
+<!-- <li>SoundRecorder</li> -->
+</ul>
+<p>The core Android system applications include various Activity, or Service
+components that are considered "public". That is, the attribute
+"android:exported" may be absent, or may have the value "true".</p>
+<p>For every Activity or Service defined
+in one of the core Android system apps that is not marked as non-public via an
+android:exported attribute with the value "false", device implementations MUST
+include a compontent of the same type implementing the same Intent filter
+patterns as the core Android system app.</p>
+<p>In other words, a device implementation MAY replace core Android system
+apps; however, if it does, the device implementation MUST support all Intent
+patterns defined by each core Android system app being replaced.</p>
+<a name="section-3.2.3.2"></a><h4>3.2.3.2. Intent Overrides</h4>
+<p>As Android is an extensible platform, device implementations MUST allow each
+Intent pattern referenced in Section 3.2.3.2 to be overridden by third-party
+applications. The upstream Android open source implementation allows this by
+default; device implementers MUST NOT attach special privileges to system
+applications' use of these Intent patterns, or prevent third-party
+applications from binding to and assuming control of these patterns. This
+prohibition specifically includes but is not limited to disabling the
+"Chooser" user interface which allows the user to select between multiple
+applications which all handle the same Intent pattern.</p>
+<a name="section-3.2.3.3"></a><h4>3.2.3.3. Intent Namespaces</h4>
+<p>Device implementations MUST NOT include any Android component that honors any
+new Intent or Broadcast Intent patterns using an ACTION, CATEGORY, or other
+key string in the android.* or com.android.* namespace. Device implementers
+MUST NOT include any Android components that honor any new Intent or Broadcast
+Intent patterns using an ACTION, CATEGORY, or other key string in a package
+space belonging to another organization. Device implementers MUST NOT alter or
+extend any of the Intent patterns used by the core apps listed in Section
+3.2.3.1. Device implementations MAY include Intent patterns using
+namespaces clearly and obviously associated with their own organization.</p>
+<p>This prohibition is analogous to that specified for Java language classes
+in Section 3.6.</p>
+<a name="section-3.2.3.4"></a><h4>3.2.3.4. Broadcast Intents</h4>
+<p>Third-party applications rely on the platform to broadcast certain Intents
+to notify them of changes in the hardware or software environment.
+Android-compatible devices MUST broadcast the public broadcast Intents in
+response to appropriate system events. Broadcast Intents are described in the
+SDK documentation.</p>
+
+<a name="section-3.3"></a><h3>3.3. Native API Compatibility</h3>
+<a name="section-3.3.1"></a><h4>3.3.1 Application Binary Interfaces</h4>
+<p>Managed code running in Dalvik can call into native code provided in the
+application .apk file as an ELF .so file compiled for the appropriate device
+hardware architecture. As native code is highly dependent on the underlying
+processor technology, Android defines a number of Application Binary
+Interfaces (ABIs) in the Android NDK, in the file
+<code>docs/CPU-ARCH-ABIS.txt</code>. If a device implementation is compatible
+with one or more defined ABIs, it SHOULD implement compatibility with the
+Android NDK, as below.</p>
+<p>If a device implementation includes support for an Android ABI, it:</p>
+<ul>
+<li>MUST include support for code running in the managed environment to call
+into native code, using the standard Java Native Interface (JNI)
+semantics.</li>
+<li>MUST be source-compatible (i.e. header compatible) and binary-compatible
+(for the ABI) with each required library in the list below</li>
+<li>MUST accurately report the native Application Binary Interface (ABI)
+supported by the device, via the <code>android.os.Build.CPU_ABI</code>
+API</li>
+<li>MUST report only those ABIs documented in the latest version of the
+Android NDK, in the file <code>docs/CPU-ARCH-ABIS.txt</code></li>
+<li>SHOULD be built using the source code and header files available in the
+upstream Android open source project</li>
+</ul>
+<p>The following native code APIs MUST be available to apps that include
+native code:</p>
+<ul>
+<li>libc (C library)</li>
+<li>libm (math library)</li>
+<li>Minimal support for C++</li>
+<li>JNI interface</li>
+<li>liblog (Android logging)</li>
+<li>libz (Zlib compression)</li>
+<li>libdl (dynamic linker)</li>
+<li>libGLESv1_CM.so (OpenGL ES 1.0)</li>
+<li>libGLESv2.so (OpenGL ES 2.0)</li>
+<li>libEGL.so (native OpenGL surface management)</li>
+<li>libjnigraphics.so</li>
+<li>libOpenSLES.so (OpenSL ES 1.0.1 audio support)</li>
+<li>libOpenMAXAL.so (OpenMAX AL 1.0.1 support)</li>
+<li>libandroid.so (native Android activity support)</li>
+<li>Support for OpenGL, as described below</li>
+</ul>
+<p>Note that future releases of the Android NDK may introduce support for
+additional ABIs. If a device implementation is not compatible with an existing
+predefined ABI, it MUST NOT report support for any ABI at all.</p>
+<p>Native code compatibility is challenging. For this reason, it should be
+repeated that device implementers are VERY strongly encouraged to use the
+upstream implementations of the libraries listed above to help ensure
+compatibility.</p>
+
+<a name="section-3.4"></a><h3>3.4. Web Compatibility</h3>
+<a name="section-3.4.1"></a><h4>3.4.1. WebView Compatibility</h4>
+<p>The Android Open Source implementation uses the WebKit rendering engine to
+implement the <code>android.webkit.WebView</code>. Because it is not feasible
+to develop a comprehensive test suite for a web rendering system, device
+implementers MUST use the specific upstream build of WebKit in the WebView
+implementation. Specifically:</p>
+<ul>
+<li>Device implementations' <code>android.webkit.WebView</code>
+implementations MUST be based on the 534.30 WebKit build from the upstream
+Android Open Source tree for Android 4.0. This build includes a specific set
+of functionality and security fixes for the WebView. Device implementers MAY
+include customizations to the WebKit implementation; however, any such
+customizations MUST NOT alter the behavior of the WebView, including rendering
+behavior.</li>
+<li>The user agent string reported by the WebView MUST be in this format:<br/>
+ <code>Mozilla/5.0 (Linux; U; Android $(VERSION); $(LOCALE); $(MODEL) Build/$(BUILD)) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30</code>
+ <ul>
+ <li>The value of the $(VERSION) string MUST be the same as the value for <code>android.os.Build.VERSION.RELEASE</code></li>
+ <li>The value of the $(LOCALE) string SHOULD follow the ISO conventions for country code and language, and SHOULD refer to the current configured locale of the device</li>
+ <li>The value of the $(MODEL) string MUST be the same as the value for <code>android.os.Build.MODEL</code></li>
+ <li>The value of the $(BUILD) string MUST be the same as the value for <code>android.os.Build.ID</code></li>
+ </ul>
+</li>
+</ul>
+<p>The WebView component SHOULD include support for as much of HTML5 [<a
+href="#resources11">Resources, 11</a>] as possible.
+Minimally, device implementations MUST support each of these APIs associated
+with HTML5 in the WebView:</p>
+<ul>
+<li>application cache/offline operation [<a href="#resources12">Resources, 12</a>]</li>
+<li>the <video> tag [<a href="#resources13">Resources, 13</a>]</li>
+<li>geolocation [<a href="#resources14">Resources, 14</a>]</li>
+</ul>
+<p>Additionally, device implementations MUST support the HTML5/W3C webstorage
+API [<a href="#resources15">Resources, 15</a>], and SHOULD support the
+HTML5/W3C IndexedDB API [<a href="#resources16">Resources, 16</a>]. <i>Note
+that as the web development standards bodies are transitioning to favor
+IndexedDB over webstorage, IndexedDB is expected to become a required
+component in a future version of Android.</i></p>
+<p>HTML5 APIs, like all JavaScript APIs, MUST be disabled by default in a
+WebView, unless the developer explicitly enables them via the usual Android
+APIs.</p>
+
+<a name="section-3.4.2"></a><h4>3.4.2. Browser Compatibility</h4>
+<p>Device implementations MUST include a standalone Browser application for
+general user web browsing. The standalone Browser MAY be based on a
+browser technology other than WebKit. However, even if an alternate Browser
+application is used, the <code>android.webkit.WebView</code> component
+provided to third-party applications MUST be based on WebKit, as described in
+Section 3.4.1.</p>
+<p>Implementations MAY ship a custom user agent string in the standalone
+Browser application.</p>
+<p>The standalone Browser application (whether based on the upstream
+WebKit Browser application or a third-party replacement) SHOULD include support
+for as much of HTML5 [<a href="#resources11">Resources, 11</a>] as possible.
+Minimally, device implementations MUST support each of these APIs associated
+with HTML5:</p>
+<ul>
+<li>application cache/offline operation [<a href="#resources12">Resources, 12</a>]</li>
+<li>the <video> tag [<a href="#resources13">Resources, 13</a>]</li>
+<li>geolocation [<a href="#resources14">Resources, 14</a>]</li>
+</ul>
+<p>Additionally, device implementations MUST support the HTML5/W3C webstorage
+API [<a href="#resources15">Resources, 15</a>], and SHOULD support the
+HTML5/W3C IndexedDB API [<a href="#resources16">Resources, 16</a>]. <i>Note
+that as the web development standards bodies are transitioning to favor
+IndexedDB over webstorage, IndexedDB is expected to become a required
+component in a future version of Android.</i></p>
+
+<a name="section-3.5"></a><h3>3.5. API Behavioral Compatibility</h3>
+<p>The behaviors of each of the API types (managed, soft, native, and web)
+must be consistent with the preferred implementation of the upstream Android
+open source project [<a href="#resources03">Resources, 3</a>]. Some specific areas
+of compatibility are:</p>
+<ul>
+<li>Devices MUST NOT change the behavior or semantics of a standard Intent</li>
+<li>Devices MUST NOT alter the lifecycle or lifecycle semantics of a
+ particular type of system component (such as Service, Activity,
+ ContentProvider, etc.)</li>
+<li>Devices MUST NOT change the semantics of a standard permission</li>
+</ul>
+<p>The above list is not comprehensive. The Compatibility Test Suite (CTS)
+tests significant portions of the platform for behavioral compatibility, but
+not all. It is the responsibility of the implementer to ensure behavioral
+compatibility with the Android Open Source Project. For this reason, device
+implementers SHOULD use the source code available via the Android Open Source
+Project where possible, rather than re-implement significant parts of the
+system.</p>
+
+
+<a name="section-3.6"></a><h3>3.6. API Namespaces</h3>
+<p>Android follows the package and class namespace conventions defined by the
+Java programming language. To ensure compatibility with third-party
+applications, device implementers MUST NOT make any prohibited modifications
+(see below) to these package namespaces:</p>
+<ul>
+<li>java.*</li>
+<li>javax.*</li>
+<li>sun.*</li>
+<li>android.*</li>
+<li>com.android.*</li>
+</ul>
+<p>Prohibited modifications include:</p>
+<ul>
+<li>Device implementations MUST NOT modify the publicly exposed APIs on the
+Android platform by changing any method or class signatures, or by removing
+classes or class fields.</li>
+<li>Device implementers MAY modify the underlying implementation of the APIs,
+but such modifications MUST NOT impact the stated behavior and Java-language
+signature of any publicly exposed APIs.</li>
+<li>Device implementers MUST NOT add any publicly exposed elements (such as
+classes or interfaces, or fields or methods to existing classes or interfaces)
+to the APIs above.</li>
+</ul>
+<p>A "publicly exposed element" is any construct which is not decorated with
+the "@hide" marker as used in the upstream Android source code. In other
+words, device implementers MUST NOT expose new APIs or alter existing APIs in
+the namespaces noted above. Device implementers MAY make internal-only
+modifications, but those modifications MUST NOT be advertised or otherwise
+exposed to developers.</p>
+<p>Device implementers MAY add custom APIs, but any such APIs MUST NOT be in a
+namespace owned by or referring to another organization. For instance, device
+implementers MUST NOT add APIs to the com.google.* or similar namespace; only
+Google may do so. Similarly, Google MUST NOT add APIs to other companies'
+namespaces. Additionally, if a device implementation includes custom APIs
+outside the standard Android namespace, those APIs MUST be packaged in an
+Android shared library so that only apps that explicitly use them (via the
+<code><uses-library></code> mechanism) are affected by the increased
+memory usage of such APIs.</p>
+<p>If a device implementer proposes to improve one of the package namespaces
+above (such as by adding useful new functionality to an existing API, or
+adding a new API), the implementer SHOULD visit source.android.com and begin
+the process for contributing changes and code, according to the information on
+that site.</p>
+<p>Note that the restrictions above correspond to standard conventions for
+naming APIs in the Java programming language; this section simply aims to
+reinforce those conventions and make them binding through inclusion in this
+compatibility definition.</p>
+
+<a name="section-3.7"></a><h3>3.7. Virtual Machine Compatibility</h3>
+<p>Device implementations MUST support the full Dalvik Executable (DEX)
+bytecode specification and Dalvik Virtual Machine semantics [<a
+href="#resources17">Resources, 17</a>].</p>
+<p>Device implementations MUST configure Dalvik to allocate memory in
+accordance with the upstream Android platform, and as specified by the following
+table. (See <a href="#section-7.1.1">Section 7.1.1</a> for screen size and screen
+density definitions.)</p>
+
+<p>Note that memory values specified below are considered minimum values,
+and device implementations MAY allocate more memory per application.</p>
+<table>
+<tbody>
+<tr>
+<td><b>Screen Size</b></td>
+<td><b>Screen Density</b></td>
+<td><b>Application Memory</b></td>
+</tr>
+<tr>
+<td>small / normal / large</td>
+<td>ldpi / mdpi</td>
+<td>16MB</td>
+</tr>
+<tr>
+<td>small / normal / large</td>
+<td>tvdpi / hdpi</td>
+<td>32MB</td>
+</tr>
+<tr>
+<td>small / normal / large</td>
+<td>xhdpi</td>
+<td>64MB</td>
+</tr>
+<tr>
+<td>xlarge</td>
+<td>mdpi</td>
+<td>32MB</td>
+</tr>
+<tr>
+<td>xlarge</td>
+<td>tvdpi / hdpi</td>
+<td>64MB</td>
+</tr>
+<tr>
+<td>xlarge</td>
+<td>xhdpi</td>
+<td>128MB</td>
+</tr>
+</tbody>
+</table>
+
+<a name="section-3.8"></a><h3>3.8. User Interface Compatibility</h3>
+<a name="section-3.8.1"></a><h4>3.8.1. Widgets</h4>
+<p>Android defines a component type and corresponding API and lifecycle that
+allows applications to expose an "AppWidget" to the end user [<a
+href="#resources18">Resources, 18</a>].
+The Android Open Source reference release includes a Launcher application that
+includes user interface affordances allowing the user to add, view, and remove
+AppWidgets from the home screen.</p>
+<p>Device implementations MAY substitute an alternative to the reference Launcher
+(i.e. home screen). Alternative Launchers SHOULD include built-in support for
+AppWidgets, and expose user interface affordances to add, configure, view, and
+remove AppWidgets directly within the Launcher. Alternative Launchers MAY omit
+these user interface elements; however, if they are omitted, the device
+implementation MUST provide a separate application accessible from the Launcher
+that allows users to add, configure, view, and remove AppWidgets.</p>
+<p>Device implementations MUST be capable of rendering widgets that are 4 x 4
+in the standard grid size. (See the App Widget Design Guidelines in the Android
+SDK documentation [<a
+href="#resources18">Resources, 18</a>] for details.</p>
+<a name="section-3.8.2"></a><h4>3.8.2. Notifications</h4>
+<p>Android includes APIs that allow developers to notify users of notable
+events [<a href="#resources19">Resources, 19</a>], using hardware and software
+features of the device.</p>
+<p>Some APIs allow applications to perform notifications or attract attention
+using hardware, specifically sound, vibration, and light. Device implementations
+MUST support notifications that use hardware features, as described in the SDK
+documentation, and to the extent possible with the device implementation
+hardware. For instance, if a device implementation includes a vibrator, it
+MUST correctly implement the vibration APIs. If a device implementation lacks
+hardware, the corresponding APIs MUST be implemented as no-ops. Note that this
+behavior is further detailed in <a href="#section-7">Section 7.</a></p>
+<p>Additionally, the implementation MUST correctly render all resources
+(icons, sound files, etc.) provided for in the APIs [<a
+href="#resources20">Resources, 20</a>], or in the
+Status/System Bar icon style guide [<a href="#resources21">Resources, 21</a>].
+Device implementers MAY provide an alternative user experience for
+notifications than that provided by the reference Android Open Source
+implementation; however, such alternative notification systems MUST support
+existing notification resources, as above.</p>
+<p>Android 4.0 includes support for rich notifications, such as interactive
+Views for ongoing notifications. Device implementations MUST properly display
+and execute rich notifications, as documented in the Android APIs.</p>
+<a name="section-3.8.3"></a><h4>3.8.3. Search</h4>
+<p>Android includes APIs [<a href="#resources22">Resources, 22</a>] that allow
+developers to incorporate search into their applications, and expose their
+application's data into the global system search. Generally speaking, this
+functionality consists of a single, system-wide user interface that allows users
+to enter queries, displays suggestions as users type, and displays results. The
+Android APIs allow developers to reuse this interface to provide search within
+their own apps, and allow developers to supply results to the common global
+search user interface.</p>
+<p>Device implementations MUST include a single, shared, system-wide search
+user interface capable of real-time suggestions in response to user input.
+Device implementations MUST implement the APIs that allow developers to reuse
+this user interface to provide search within their own applications. Device
+implementations MUST implement the APIs that allow third-party applications to
+add suggestions to the search box when it is run in global search mode. If no
+third-party applications are installed that make use of this functionality,
+the default behavior SHOULD be to display web search engine results and
+suggestions.</p>
+<a name="section-3.8.4"></a><h4>3.8.4. Toasts</h4>
+<p>Applications can use the "Toast" API (defined in [<a
+href="#resources23">Resources, 23</a>]) to
+display short non-modal strings to the end user, that disappear after a brief
+period of time. Device implementations MUST display Toasts from applications
+to end users in some high-visibility manner.</p>
+
+<a name="section-3.8.5"></a><h4>3.8.5. Themes</h4>
+<p>Android provides "themes" as a mechanism for applications to apply styles
+across an entire Activity or application. Android 3.0 introduced a new "Holo"
+or "holographic" theme as a set of defined styles for application developers to
+use if they want to match the Holo theme look and feel as defined by the Android
+SDK [<a href="#resources24">Resources, 24</a>]. Device implementations MUST NOT
+alter any of the Holo theme attributes exposed to applications
+[<a href="#resources25">Resources, 25</a>].</p>
+<p>Android 4.0 introduces a new "Device Default" theme as a set of defined
+styles for application developers to use if they want to match the look and feel
+of the device theme as defined by the device implementer. Device implementations
+MAY modify the DeviceDefault theme attributes exposed to applications
+[<a href="#resources25">Resources, 25</a>].</p>
+
+<a name="section-3.8.6"></a><h4>3.8.6. Live Wallpapers</h4>
+<p>Android defines a component type and corresponding API and lifecycle that
+allows applications to expose one or more "Live Wallpapers" to the end user
+[<a href="#resources26">Resources, 26</a>]. Live Wallpapers are animations,
+patterns, or similar images with limited input capabilities that display as a
+wallpaper, behind other applications.</p>
+<p>Hardware is considered capable of reliably running live wallpapers if it
+can run all live wallpapers, with no limitations on functionality, at a
+reasonable framerate with no adverse affects on other applications. If
+limitations in the hardware cause wallpapers and/or applications to crash,
+malfunction, consume excessive CPU or battery power, or run at unacceptably
+low frame rates, the hardware is considered incapable of running live
+wallpaper. As an example, some live wallpapers may use an Open GL 1.0 or 2.0
+context to render their content. Live wallpaper will not run reliably on
+hardware that does not support multiple OpenGL contexts because the live
+wallpaper use of an OpenGL context may conflict with other applications that
+also use an OpenGL context.</p>
+<p>Device implementations capable of running live wallpapers reliably as
+described above SHOULD implement live wallpapers. Device implementations
+determined to not run live wallpapers reliably as described above MUST NOT
+implement live wallpapers.</p>
+<a name="section-3.8.7"></a><h4>3.8.7. Recent Application Display</h4>
+<p>The upstream Android 4.0 source code includes a user interface for
+displaying recent applications using a thumbnail image of the application's
+graphical state at the moment the user last left the application. Device
+implementations MAY alter or eliminate this user interface; however, a future
+version of Android is planned to make more extensive use of this
+functionality. Device implementations are strongly encouraged to use the
+upstream Android 4.0 user interface (or a similar thumbnail-based interface)
+for recent applications, or else they may not be compatible with a future
+version of Android.</p>
+<a name="section-3.8.8"></a><h4>3.8.8. Input Management Settings</h4>
+<p>Android 4.0 includes support for Input Management Engines. The Android 4.0
+APIs allow custom app IMEs to specify user-tunable settings. Device
+implementations MUST include a way for the user to access IME settings at all
+times when an IME that provides such user settings is displayed.</p>
+
+<a name="section-3.9"></a><h3>3.9 Device Administration</h3>
+<p>Android 4.0 includes features that allow security-aware applications
+to perform device administration functions at the system level, such as enforcing
+password policies or performing remote wipe, through the Android Device
+Administration API [<a href="#resources27">Resources, 27</a>]. Device
+implementations MUST provide an implementation of the <code>DevicePolicyManager
+</code> class [<a href="#resources28">Resources, 28</a>], and SHOULD support
+the full range of device administration policies defined in the Android SDK
+documentation [<a href="#resources27">Resources, 27</a>].</p>
+
+<p>If device implementations do not support the full range of device administration
+policies, they MUST NOT allow device administration applications to be enabled.
+Specifically, if a device does not support all device administration policies,
+the device implementation MUST respond to the
+<code>android.app.admin.DevicePolicyManager.ACTION_ADD_DEVICE_ADMIN</code> intent,
+but MUST dislpay a message notifying the user that the device does not support
+device administration.</p>
+
+<a name="section-3.10"></a><h3>3.10 Accessibility</h3>
+<p>Android 4.0 provides an accessibility layer that helps users with disabilities
+to navigate their devices more easily. In addition, Android 4.0 provides
+platform APIs that enable accessibility service implementations to receive
+callbacks for user and system events and generate alternate feedback mechanisms,
+such as text-to-speech, haptic feedback, and trackball/d-pad navigation
+[<a href="#resources29">Resources, 29</a>]. Device implementations MUST provide an
+implementation of the Android accessibility framework consistent with the
+default Android implementation. Specifically, device implementations MUST meet
+the following requirements.</p>
+<ul>
+ <li>Device implementations MUST support third party accessibility service
+ implementations through the <code>android.accessibilityservice</code>
+ APIs [<a href="#resources30">Resources, 30</a>].</li>
+ <li>Device implementations MUST generate <code>AccessibilityEvent</code>s
+ and deliver these events to all registered <code>AccessibilityService
+ </code> implementations in a manner consistent with the default Android
+ implementation.</li>
+ <li>Device implementations MUST provide a user-accessible mechanism to enable
+ and disable accessibility services, and MUST display this interface in
+ response to the
+ <code>android.provider.Settings.ACTION_ACCESSIBILITY_SETTINGS</code>
+ intent.</li>
+</ul>
+<p>Additionally, device implementations SHOULD provide an implementation
+of an accessibility service on the device, and SHOULD provide a mechanism
+for users to enable the accessibility service during device setup. An open
+source implementation of an accessibility service is available from the Eyes
+Free project [<a href="#resources31">Resources, 31</a>].</p>
+
+<a name="section-3.11"></a><h3>3.11 Text-to-Speech</h3>
+<p>Android 4.0 includes APIs that allow applications to make use of
+text-to-speech (TTS) services, and allows service providers to provide
+implementations of TTS services [<a href="#resources32">Resources, 32</a>].
+Device implementations MUST meet these requirements related to the Android TTS
+framework:</p>
+<ul>
+ <li>Device implementations MUST support the Android TTS framework APIs and
+ SHOULD include a TTS engine supporting the languages available on the
+ device. Note that the upstream Android open source software includes a
+ full-featured TTS engine implementation.</li>
+ <li>Device implementations MUST support installation of third-party TTS
+ engines.</li>
+ <li>Device implementations MUST provide a user-accessible interface that allows
+ users to select a TTS engine for use at the system level.</li>
+</ul>
+
+<a name="section-4"></a><h2>4. Application Packaging Compatibility</h2>
+<p>Device implementations MUST install and run Android ".apk" files as
+generated by the "aapt" tool included in the official Android SDK [<a
+href="#resources33">Resources, 33</a>].</p>
+<p>Devices implementations MUST NOT extend either the .apk [<a
+href="#resources34">Resources, 34</a>], Android Manifest [<a
+href="#resources35">Resources, 35</a>],
+Dalvik bytecode [<a href="#resources17">Resources, 17</a>], or renderscript
+bytecode formats in such a way that would prevent those files from installing
+and running correctly on other compatible devices. Device implementers SHOULD
+use the reference upstream implementation of Dalvik, and the reference
+implementation's package management system.</p>
+
+<a name="section-5"></a><h2>5. Multimedia Compatibility</h2>
+<p>Device implementations MUST include at least one form of audio output, such as
+speakers, headphone jack, external speaker connection, etc.</p>
+<a name="section-5.1"></a><h3>5.1. Media Codecs</h3>
+<p>Device implementations MUST support the core media formats specified
+in the Android SDK documentation [<a href="#resources58">Resources, 58</a>] except
+where explicitly permitted in this document. Specifically, device implementations
+MUST support the media formats, encoders, decoders, file types and container
+formats defined in the tables below. All of these codecs are provided as
+software implementations in the preferred Android implementation from the Android
+Open Source Project.</p>
+
+<p><strong>Please note that neither Google nor the Open Handset Alliance make any
+representation that these codecs are unencumbered by third-party patents.
+Those intending to use this source code in hardware or software products are
+advised that implementations of this code, including in open source software
+or shareware, may require patent licenses from the relevant patent
+holders.</strong></p>
+
+<p>Note that these tables do not list specific bitrate requirements for
+most video codecs because current device hardware does not necessarily support
+bitrates that map exactly to the required bitrates specified by the relevant
+standards. Instead, device implementations SHOULD support the highest bitrate
+practical on the hardware, up to the limits defined by the specifications.</p>
+<div style="page-break-before: always;"></div>
+<table>
+<tbody>
+
+<tr>
+<th>Type</th>
+<th>Format / Codec</th>
+<th>Encoder</th>
+<th>Decoder</th>
+<th>Details</th>
+<th>File Type(s) / Container Formats</th>
+</tr>
+
+<tr>
+<td rowspan="10">Audio</td>
+<td>AAC LC/LTP</td>
+<td style="text-align: center;">REQUIRED<br/>
+<small>Required for device implementations that include microphone hardware
+and define <code>android.hardware.microphone</code>.</small></td>
+<td style="text-align: center;">REQUIRED</td>
+<td rowspan="3">Mono/Stereo content in any combination of standard bit
+rates up to 160 kbps and sampling rates from 8 to 48kHz</td>
+<td rowspan="3">
+ <ul>
+ <li>3GPP (.3gp)</li>
+ <li>MPEG-4 (.mp4, .m4a)</li>
+ <li>ADTS raw AAC (.aac, decode in Android 3.1+, encode in Android 4.0+, ADIF not supported)</li>
+ <li>MPEG-TS (.ts, not seekable, Android 3.0+)</li>
+ </ul>
+</td>
+</tr>
+<tr>
+<td>HE-AACv1 (AAC+)</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+</tr>
+
+<tr>
+<td>HE-AACv2 (enhanced AAC+)</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+</tr>
+
+<tr>
+<td>AMR-NB</td>
+<td style="text-align: center;">REQUIRED<br/>
+<small>Required for device implementations that include microphone hardware
+and define <code>android.hardware.microphone</code>.</small></td>
+<td style="text-align: center;">REQUIRED</td>
+<td>4.75 to 12.2 kbps sampled @ 8kHz</td>
+<td>3GPP (.3gp)
+</td>
+</tr>
+
+<tr>
+<td>AMR-WB</td>
+<td style="text-align: center;">REQUIRED<br/>
+<small>Required for device implementations that include microphone hardware
+and define <code>android.hardware.microphone</code>.</small></td>
+<td style="text-align: center;">REQUIRED</td>
+<td>9 rates from 6.60 kbit/s to 23.85 kbit/s sampled @ 16kHz</td>
+<td>3GPP (.3gp)</td>
+</tr>
+
+<tr>
+<td>FLAC</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED<br/><small>(Android 3.1+)</small></td>
+<td>Mono/Stereo (no multichannel). Sample rates up to 48 kHz (but up to 44.1
+kHz is recommended on devices with 44.1 kHz output, as the 48 to 44.1 kHz
+downsampler does not include a low-pass filter). 16-bit recommended;
+no dither applied for 24-bit.
+</td>
+<td>FLAC (.flac) only</td>
+</tr>
+
+<tr>
+<td>MP3</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Mono/Stereo 8-320Kbps constant (CBR) or variable bit-rate (VBR)
+</td>
+<td>MP3 (.mp3)</td>
+</tr>
+
+<tr>
+<td>MIDI</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td>MIDI Type 0 and 1. DLS Version 1 and 2. XMF and Mobile XMF. Support for ringtone formats RTTTL/RTX, OTA, and iMelody </td>
+<td>
+ <ul>
+ <li>Type 0 and 1 (.mid, .xmf, .mxmf)</li>
+ <li>RTTTL/RTX (.rtttl, .rtx)</li>
+ <li>OTA (.ota)</li>
+ <li>iMelody (.imy)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>Vorbis</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>
+ <ul>
+ <li>Ogg (.ogg)</li>
+ <li>Matroska (.mkv)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>PCM/WAVE</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td>8- and 16-bit linear PCM (rates up to limit of hardware)</td>
+<td>WAVE (.wav)</td>
+</tr>
+
+<tr>
+<td rowspan="5">Image</td>
+<td>JPEG</td>
+<td style="text-align: center;">REQUIRED</td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Base+progressive</td>
+<td>JPEG (.jpg)</td>
+</tr>
+
+<tr>
+<td>GIF</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>GIF (.gif)</td>
+</tr>
+
+<tr>
+<td>PNG</td>
+<td style="text-align: center;">REQUIRED</td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>PNG (.png)</td>
+</tr>
+
+<tr>
+<td>BMP</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>BMP (.bmp)</td>
+</tr>
+
+
+<tr>
+<td>WEBP</td>
+<td style="text-align: center;">REQUIRED</td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>WebP (.webp)</td>
+</tr>
+
+<tr>
+<td rowspan="4">Video</td>
+<td>H.263</td>
+<td style="text-align: center;">REQUIRED<br/>
+<small>Required for device implementations that include camera hardware
+and define <code>android.hardware.camera</code> or
+<code>android.hardware.camera.front</code>.</small></td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>
+ <ul>
+ <li>3GPP (.3gp)</li>
+ <li>MPEG-4 (.mp4)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>H.264 AVC</td>
+<td style="text-align: center;">REQUIRED<br/>
+<small>Required for device implementations that include camera hardware
+and define <code>android.hardware.camera</code> or
+<code>android.hardware.camera.front</code>.</small></td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Baseline Profile (BP)</td>
+<td>
+ <ul>
+ <li>3GPP (.3gp)</li>
+ <li>MPEG-4 (.mp4)</li>
+ <li>MPEG-TS (.ts, AAC audio only, not seekable, Android 3.0+)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>MPEG-4 SP</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>3GPP (.3gp)</td>
+</tr>
+
+<tr>
+<td>VP8</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED<br/><small>(Android 2.3.3+)</small></td>
+<td> </td>
+<td><a href="http://www.webmproject.org/">WebM</a> (.webm) and Matroska (.mkv, Android 4.0+)</td>
+</tr>
+
+</tbody></table>
+
+<a name="section-5.2"></a><h3>5.2 Video Encoding</h3>
+<p>Android device implementations that include a rear-facing camera and declare
+<code>android.hardware.camera</code> SHOULD support the following video encoding
+profiles.</p>
+<table>
+ <thead>
+ <tr>
+ <th> </th>
+ <th>SD (Low quality)</th>
+ <th>SD (High quality)</th>
+ <th>HD (When supported by hardware)</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <th>Video codec</th>
+ <td>H.264 Baseline Profile</td>
+ <td>H.264 Baseline Profile</td>
+ <td>H.264 Baseline Profile</td>
+ </tr>
+ <tr>
+ <th>Video resolution</th>
+ <td>176 x 144 px</td>
+ <td>480 x 360 px</td>
+ <td>1280 x 720 px</td>
+ </tr>
+ <tr>
+ <th>Video frame rate</th>
+ <td>12 fps</td>
+ <td>30 fps</td>
+ <td>30 fps</td>
+ </tr>
+ <tr>
+ <th>Video bitrate</th>
+ <td>56 Kbps</td>
+ <td>500 Kbps or higher</td>
+ <td>2 Mbps or higher</td>
+ </tr>
+ <tr>
+ <th>Audio codec</th>
+ <td>AAC-LC</td>
+ <td>AAC-LC</td>
+ <td>AAC-LC</td>
+ </tr>
+ <tr>
+ <th>Audio channels</th>
+ <td>1 (mono)</td>
+ <td>2 (stereo)</td>
+ <td>2 (stereo)</td>
+ </tr>
+ <tr>
+ <th>Audio bitrate</th>
+ <td>24 Kbps</td>
+ <td>128 Kbps</td>
+ <td>192 Kbps</td>
+ </tr>
+ </tbody>
+</table>
+
+<a name="section-5.3"></a><h3>5.3. Audio Recording</h3>
+<p>When an application has used the <code>android.media.AudioRecord</code> API to
+start recording an audio stream, device implementations that include microphone
+hardware and declare <code>android.hardware.microphone</code> MUST sample and
+record audio with each of these behaviors:</p>
+<ul>
+<li>The device SHOULD exhibit approximately flat amplitude versus frequency
+ characteristics; specifically, ±3 dB, from 100 Hz to 4000 Hz</li>
+<li>Audio input sensitivity SHOULD be set such that a 90 dB sound power level
+ (SPL) source at 1000 Hz yields RMS of 2500 for 16-bit samples.</li>
+<li>PCM amplitude levels SHOULD linearly track input SPL changes over at least
+ a 30 dB range from -18 dB to +12 dB re 90 dB SPL at the microphone.</li>
+<li>Total harmonic distortion SHOULD be less than 1% from 100 Hz to 4000 Hz at
+ 90 dB SPL input level.</li>
+</ul>
+<p>In addition to the above recording specifications, when an application has
+started recording an audio stream using the
+<code>android.media.MediaRecorder.AudioSource.VOICE_RECOGNITION</code> audio
+source:</p>
+<ul>
+<li>Noise reduction processing, if present, MUST be disabled.</li>
+<li>Automatic gain control, if present, MUST be disabled.</li>
+</ul>
+<p><b>Note:</b> while some of the requirements outlined above are stated as "SHOULD"
+for Android 4.0, the Compatibility Definition for a future version is planned
+to change these to "MUST". That is, these requirements are optional in Android
+4.0 but <b>will be required</b> by a future version. Existing and new devices
+that run Android 4.0 are <b>very strongly encouraged to meet
+these requirements in Android 4.0</b>, or they will not be able to attain
+Android compatibility when upgraded to the future version.</p>
+
+<a name="section-5.4"></a><h3>5.4. Audio Latency</h3>
+<p>Audio latency is broadly defined as the interval between when an
+application requests an audio playback or record operation, and when the
+device implementation actually begins the operation. Many classes of
+applications rely on short latencies, to achieve real-time effects such sound
+effects or VOIP communication. Device implementations that include microphone
+hardware and declare <code>android.hardware.microphone</code> SHOULD meet all
+audio latency requirements outlined in this section. See <a href="#section-7">
+Section 7</a> for details on the conditions under which microphone hardware may
+be omitted by device implementations.</p>
+<p>For the purposes of this section:</p>
+<ul>
+<li>"cold output latency" is defined to be the interval between when an
+ application requests audio playback and when sound begins playing, when
+ the audio system has been idle and powered down prior to the request</li>
+<li>"warm output latency" is defined to be the interval between when an
+ application requests audio playback and when sound begins playing, when
+ the audio system has been recently used but is currently idle (that is,
+ silent)</li>
+<li>"continuous output latency" is defined to be the interval between when an
+ application issues a sample to be played and when the speaker physically
+ plays the corresponding sound, while the device is currently playing back
+ audio</li>
+<li>"cold input latency" is defined to be the interval between when an
+ application requests audio recording and when the first sample is
+ delivered to the application via its callback, when the audio system and
+ microphone has been idle and powered down prior to the request</li>
+<li>"continuous input latency" is defined to be when an ambient sound occurs
+ and when the sample corresponding to that sound is delivered to a
+ recording application via its callback, while the device is in recording
+ mode</li>
+</ul>
+<p>Using the above definitions, device implementations SHOULD exhibit each of
+these properties:</p>
+<ul>
+<li>cold output latency of 100 milliseconds or less</li>
+<li>warm output latency of 10 milliseconds or less</li>
+<li>continuous output latency of 45 milliseconds or less</li>
+<li>cold input latency of 100 milliseconds or less</li>
+<li>continuous input latency of 50 milliseconds or less</li>
+</ul>
+<p><b>Note:</b> while the requirements outlined above are stated as "SHOULD"
+for Android 4.0, the Compatibility Definition for a future version is planned
+to change these to "MUST". That is, these requirements are optional in Android
+4.0 but <b>will be required</b> by a future version. Existing and new devices
+that run Android 4.0 are <b>very strongly encouraged to meet
+these requirements in Android 4.0</b>, or they will not be able to attain
+Android compatibility when upgraded to the future version.</p>
+<p>If a device implementation meets the requirements of this section, it MAY
+report support for low-latency audio, by reporting the feature
+"android.hardware.audio.low-latency" via the
+<code>android.content.pm.PackageManager</code> class. [<a
+href="#resources37">Resources, 37</a>] Conversely, if the device
+implementation does not meet these requirements it MUST NOT report support for
+low-latency audio.</p>
+
+<a name="section-5.5"></a><h3>5.5. Network Protocols</h3>
+<p>Devices MUST support the media network protocols for audio and video playback
+as specified in the Android SDK documentation
+[<a href="#resources58">Resources, 58</a>]. Specifically, devices MUST support
+the following media network protocols:</p>
+<ul>
+<li>RTSP (RTP, SDP)</li>
+<li>HTTP(S) progressive streaming</li>
+<li>HTTP(S) Live Streaming draft protocol, Version 3 [<a href="#resources59">Resources, 59</a>]</li>
+</ul>
+<a name="section-6"></a><h2>6. Developer Tool Compatibility</h2>
+<p>Device implementations MUST support the Android Developer Tools provided in
+the Android SDK. Specifically, Android-compatible devices MUST be compatible
+with:</p>
+<ul>
+<li><b>Android Debug Bridge (known as adb)</b> [<a href="#resources33">Resources, 33</a>]<br/>
+Device implementations MUST support all <code>adb</code> functions as
+documented in the Android SDK. The device-side <code>adb</code> daemon MUST
+be inactive by default, and there MUST be a user-accessible mechanism to turn
+on the Android Debug Bridge.</li>
+<li><b>Dalvik Debug Monitor Service (known as ddms)</b> [<a href="#resources33">Resources, 33</a>]<br/>
+Device implementations MUST support all <code>ddms</code> features as documented in the
+Android SDK. As <code>ddms</code> uses <code>adb</code>, support for
+<code>ddms</code> SHOULD be inactive by default,
+but MUST be supported whenever the user has activated the Android Debug
+Bridge, as above.</li>
+<li><b>Monkey</b> [<a href="#resources36">Resources, 36</a>]<br/>
+Device implementations MUST include the Monkey framework, and make it
+available for applications to use.</li>
+</ul>
+<p>Most Linux-based systems and Apple Macintosh systems recognize Android
+devices using the standard Android SDK tools, without additional support;
+however Microsoft Windows systems typically require a driver for new Android
+devices. (For instance, new vendor IDs and sometimes new device IDs require
+custom USB drivers for Windows systems.) If a device implementation is
+unrecognized by the <code>adb</code> tool as provided in the standard Android
+SDK, device implementers MUST provide Windows drivers allowing developers to
+connect to the device using the <code>adb</code> protocol. These drivers MUST
+be provided for Windows XP, Windows Vista, and Windows 7, in both 32-bit and
+64-bit versions.</p>
+
+<a name="section-7"></a><h2>7. Hardware Compatibility</h2>
+<p>If a device includes a particular hardware component that has a
+corresponding API for third-party developers, the device implementation MUST
+implement that API as described in the Android SDK documentation. If an API in
+the SDK interacts with a hardware component that is stated to be optional and
+the device implementation does not possess that component:</p>
+<ul>
+<li>complete class definitions (as documented by the SDK) for the component's
+APIs MUST still be present</li>
+<li>the API's behaviors MUST be implemented as no-ops in some reasonable
+fashion</li>
+<li>API methods MUST return null values where permitted by the SDK
+documentation</li>
+<li>API methods MUST return no-op implementations of classes where null
+values are not permitted by the SDK documentation</li>
+<li>API methods MUST NOT throw exceptions not documented by the SDK
+documentation</li>
+</ul>
+<p>A typical example of a scenario where these requirements apply is the
+telephony API: even on non-phone devices, these APIs must be implemented as
+reasonable no-ops.</p>
+<p>Device implementations MUST accurately report accurate hardware configuration
+information via the <code>getSystemAvailableFeatures()</code> and
+<code>hasSystemFeature(String)</code> methods on the
+<code>android.content.pm.PackageManager</code> class. [<a
+href="#resources37">Resources, 37</a>]</p>
+
+<a name="section-7.1"></a><h3>7.1. Display and Graphics</h3>
+<p>Android 4.0 includes facilities that automatically adjust application
+assets and UI layouts appropriately for the device, to ensure that third-party
+applications run well on a variety of hardware configurations [<a
+href="#resources38">Resources, 38</a>]. Devices MUST properly implement these
+APIs and behaviors, as detailed in this section.</p>
+
+<p>The units referenced by the requirements in this section are defined as follows:</p>
+<ul>
+<li>"Physical diagonal size" is the distance in inches between two opposing
+corners of the illuminated portion of the display.</li>
+<li>"dpi" (meaning "dots per inch") is the number of pixels encompassed by a
+linear horizontal or vertical span of 1". Where dpi values are listed, both
+horizontal and vertical dpi must fall within the range.</li>
+<li>"Aspect ratio" is the ratio of the longer dimension of the screen to the
+shorter dimension. For example, a display of 480x854 pixels would be 854 / 480
+= 1.779, or roughly "16:9".</li>
+<li>A "density-independent pixel" or ("dp") is the virtual pixel unit normalized to a
+160 dpi screen, calculated as:
+<code>pixels = dps * (density / 160)</code>.</li>
+</ul>
+
+
+<a name="section-7.1.1"></a><h4>7.1.1. Screen Configuration</h4>
+
+<p style="font-weight:bold;">Screen Size</p>
+<p>The Android UI framework supports a variety of different screen sizes, and
+allows applications to query the device screen size (aka "screen layout") via
+<code>android.content.res.Configuration.screenLayout</code> with the
+<code>SCREENLAYOUT_SIZE_MASK</code>. Device implementations MUST report the
+correct screen size as defined in the Android SDK documentation
+[<a href="#resources38">Resources, 38</a>] and determined by the upstream
+Android platform. Specifically, device implementations must report the correct
+screen size according to the following logical density-independent pixel (dp)
+screen dimensions.</p>
+<ul>
+<li>Devices MUST have screen sizes of at least 426 dp x 320 dp ('small')</li>
+<li>Devices that report screen size 'normal' MUST have screen sizes of at least
+470 dp x 320 dp</li>
+<li>Devices that report screen size 'large' MUST have screen sizes of at least
+640 dp x 480 dp</li>
+<li>Devices that report screen size 'xlarge' MUST have screen sizes of at least
+960 dp x 720 dp</li>
+</ul>
+<p>In addition, devices MUST have screen sizes of at least 2.5 inches in
+physical diagonal size.</p>
+
+<p>Devices MUST NOT change their reported screen size at any time.</p>
+<p>Applications optionally indicate which screen sizes they support via the
+<code><supports-screens></code> attribute in the AndroidManifest.xml
+file. Device implementations MUST correctly honor applications' stated support
+for small, normal, large, and xlarge screens, as described in the Android
+SDK documentation.</p>
+
+<p style="font-weight:bold;">Screen Aspect Ratio</p>
+<p>The aspect ratio MUST be between 1.3333 (4:3) and 1.85 (16:9).</p>
+
+<p style="font-weight:bold;">Screen Density</p>
+<p>The Android UI framework defines a set of standard logical densities to
+help application developers target application resources. Device
+implementations MUST report one of the following logical Android framework
+densities through the <code>android.util.DisplayMetrics</code> APIs, and MUST
+execute applications at this standard density.
+<ul>
+<li>120 dpi, known as 'ldpi'</li>
+<li>160 dpi, known as 'mdpi'</li>
+<li>213 dpi, known as 'tvdpi'</li>
+<li>240 dpi, known as 'hdpi'</li>
+<li>320 dpi, known as 'xhdpi'</li>
+</ul>
+Device implementations SHOULD define the standard Android framework density
+that is numerically closest to the physical density of the screen, unless that
+logical density pushes the reported screen size below the minimum supported.
+If the standard Android framework density that is numerically closest to the
+physical density results in a screen size that is smaller than the smallest
+supported compatible screen size (320 dp width), device implementations SHOULD
+report the next lowest standard Android framework density.</p>
+
+<a name="section-7.1.2"></a><h4>7.1.2. Display Metrics</h4>
+<p>Device implementations MUST report correct values for all display metrics
+defined in <code>android.util.DisplayMetrics</code> [<a
+href="#resources39">Resources, 39</a>].</p>
+
+<a name="section-7.1.3"></a><h4>7.1.3. Screen Orientation</h4>
+<p>Devices MUST support dynamic orientation by applications to
+either portrait or landscape screen orientation. That is, the device must
+respect the application's request for a specific screen orientation. Device
+implementations MAY select either portrait or landscape orientation as the
+default.</p>
+<p>Devices MUST report the correct value for the device's current orientation,
+whenever queried via the android.content.res.Configuration.orientation,
+android.view.Display.getOrientation(), or other APIs.</p>
+<p>Devices MUST NOT change the reported screen size or density when changing
+orientation.</p>
+<p>Devices MUST report which screen orientations they support (
+<code>android.hardware.screen.portrait</code> and/or
+<code>android.hardware.screen.landscape</code>) and MUST report at least one
+supported orientation. For example, a device with a fixed-orientation
+landscape screen, such as a television or laptop, MUST only report
+<code>android.hardware.screen.landscape</code>.</p>
+
+<a name="section-7.1.4"></a><h4>7.1.4. 2D and 3D Graphics Acceleration</h4>
+<p>Device implementations MUST support both OpenGL ES 1.0 and 2.0, as embodied
+and detailed in the Android SDK documentations. Device implementations MUST
+also support Android Renderscript, as detailed in the Android SDK
+documentation [<a href="#resources08">Resources, 8</a>].</p>
+<p>Device implementations MUST also correctly identify themselves as
+supporting OpenGL ES 1.0 and 2.0. That is:</p>
+<ul>
+<li>The managed APIs (such as via the <code>GLES10.getString()</code> method)
+MUST report support for OpenGL ES 1.0 and 2.0</li>
+<li>The native C/C++ OpenGL APIs (that is, those available to apps via
+libGLES_v1CM.so, libGLES_v2.so, or libEGL.so) MUST report support for
+OpenGL ES 1.0 and 2.0.</li>
+</ul>
+<p>Device implementations MAY implement any desired OpenGL ES extensions.
+However, device implementations MUST report via the OpenGL ES managed and
+native APIs all extension strings that they do support, and conversely MUST
+NOT report extension strings that they do not support.</p>
+<p>Note that Android 4.0 includes support for applications to optionally
+specify that they require specific OpenGL texture compression formats. These
+formats are typically vendor-specific. Device implementations are not required
+by Android 4.0 to implement any specific texture compression format. However,
+they SHOULD accurately report any texture compression formats that they do
+support, via the <code>getString()</code> method in the OpenGL API.</p>
+
+<p>Android 3.0 introduced a mechanism for applications to declare that they
+wanted to enable hardware acceleration for 2D graphics at the Application,
+Activity, Window or View level through the use of a manifest tag
+<code>android:hardwareAccelerated</code> or direct API calls
+[<a href="#resources09">Resources, 9</a>].</p>
+<p>In Android 4.0, device implementations MUST enable hardware acceleration by
+default, and MUST disable hardware acceleration if the developer so requests
+by setting <code>android:hardwareAccelerated="false"</code> or disabling
+hardware acceleration directly through the Android View APIs.</p>
+<p>In addition, device implementations MUST exhibit behavior consistent with the
+Android SDK documentation on hardware acceleration
+[<a href="#resources09">Resources, 9</a>].</p>
+<p>Android 4.0 includes a <code>TextureView</code> object that lets developers
+directly integrate hardware-accelerated OpenGL ES textures as rendering targets
+in a UI hierarchy. Device implementations MUST support the <code>TextureView
+</code> API, and MUST exhibit consistent behavior with the upstream Android
+implementation.</p>
+
+<a name="section-7.1.5"></a><h4>7.1.5. Legacy Application Compatibility Mode</h4>
+<p>Android 4.0 specifies a "compatibility mode" in which the framework
+operates in an 'normal' screen size equivalent (320dp width) mode for the benefit
+of legacy applications not developed for old versions of Android that pre-date
+screen-size independence. Device implementations MUST include support for legacy
+application compatibility mode as implemented by the upstream Android open source
+code. That is, device implementations MUST NOT alter the triggers or thresholds at
+which compatibility mode is activated, and MUST NOT alter the behavior of the
+compatibility mode itself.</p>
+
+<a name="section-7.1.6"></a><h4>7.1.6. Screen Types</h4>
+<p>Device implementation screens are classified as one of two types:</p>
+<ul>
+<li>Fixed-pixel display implementations: the screen is a single panel that supports only a
+single pixel width and height. Typically the screen is physically integrated with
+the device. Examples include mobile phones, tablets, and so on.</li>
+<li>Variable-pixel display implementations: the device implementation either has no
+embedded screen and includes a video output port such as VGA or HDMI for
+display, or has an embedded screen that can change pixel dimensions. Examples
+include televisions, set-top boxes, and so on.</li>
+</ul>
+<p style="font-weight: bold;">Fixed-Pixel Device Implementations</p>
+<p>Fixed-pixel device implementations MAY use screens of any pixel dimensions, provided
+that they meet the requirements defined this Compatibility Definition.</p>
+<p>Fixed-pixel implementations MAY include a video output port for use with an
+external display. However, if that display is ever used for running apps, the
+device MUST meet the following requirements:</p>
+<ul>
+<li>The device MUST report the same screen configuration and display metrics, as detailed
+in Sections 7.1.1 and 7.1.2, as the fixed-pixel display.</li>
+<li>The device MUST report the same logical density as the fixed-pixel display.</li>
+<li>The device MUST report screen dimensions that are the same as, or very close to,
+the fixed-pixel display.</li>
+</ul>
+<p>For example, a tablet that is 7" diagonal size with a 1024x600 pixel resolution is
+considered a fixed-pixel large mdpi display implementation. If it contains a video
+output port that displays at 720p or 1080p, the device implementation MUST scale the output so that
+applications are only executed in a large mdpi window, regardless of whether the fixed-pixel display
+or video output port is in use.</p>
+
+<p style="font-weight: bold;">Variable-Pixel Device Implementations</p>
+<p>Variable-pixel device implementations MUST support one or both of 1280x720,
+or 1920x1080 (that is, 720p or 1080p). Device implementations with
+variable-pixel displays MUST NOT support any other screen configuration or
+mode. Device implementations with variable-pixel screens MAY change screen
+configuration or mode at runtime or boot-time. For example, a user of a
+set-top box may replace a 720p display with a 1080p display, and the device
+implementation may adjust accordingly.</p>
+
+<p>Additionally, variable-pixel device implementations MUST report the following
+configuration buckets for these pixel dimensions:</p>
+<ul>
+<li>1280x720 (also known as 720p): 'large' screen size, 'tvdpi' (213 dpi)
+density</li>
+<li>1920x1080 (also known as 1080p): 'large' screen size, 'xhdpi' (320 dpi)
+density</li>
+</ul>
+<p>For clarity, device implementations with variable pixel dimensions are
+restricted to 720p or 1080p in Android 4.0, and MUST be configured to report
+screen size and density buckets as noted above.</p>
+
+<a name="section-7.1.7"></a><h4>7.1.7. Screen Technology</h4>
+<p>The Android platform includes APIs that allow applications to render rich
+graphics to the display. Devices MUST support all of these APIs as defined by
+the Android SDK unless specifically allowed in this document. Specifically:</p>
+<ul>
+<li>Devices MUST support displays capable of rendering 16-bit color graphics and
+SHOULD support displays capable of 24-bit color graphics.</li>
+<li>Devices MUST support displays capable of rendering animations.</li>
+<li>The display technology used MUST have a pixel aspect ratio (PAR) between
+ 0.9 and 1.1. That is, the pixel aspect ratio MUST be near square (1.0) with
+ a 10% tolerance.</li>
+</ul>
+
+<a name="section-7.2"></a><h3>7.2. Input Devices</h3>
+<a name="section-7.2.1"></a><h4>7.2.1. Keyboard</h4>
+<p>Device implementations:</p>
+<ul>
+<li>MUST include support for the Input Management Framework (which allows third
+party developers to create Input Management Engines - i.e. soft keyboard) as
+detailed at <a href="http://developer.android.com">http://developer.android.com</a>
+</li>
+<li>MUST provide at least one soft keyboard implementation (regardless of whether
+a hard keyboard is present)</li>
+<li>MAY include additional soft keyboard implementations</li>
+<li>MAY include a hardware keyboard</li>
+<li>MUST NOT include a hardware keyboard that does not match one of the
+formats specified in <code>android.content.res.Configuration.keyboard</code>
+[<a href="#resources40">Resources, 40</a>] (that is, QWERTY, or 12-key)</li>
+</ul>
+<a name="section-7.2.2"></a><h4>7.2.2. Non-touch Navigation</h4>
+<p>Device implementations:</p>
+<ul>
+<li>MAY omit a non-touch navigation option (that is, may omit a trackball, d-pad,
+or wheel)</li>
+<li>MUST report the correct value for
+<code>android.content.res.Configuration.navigation</code>
+[<a href="#resources40">Resources, 40</a>]</li>
+<li>MUST provide a reasonable alternative user interface mechanism for the
+selection and editing of text, compatible with Input Management Engines. The
+upstream Android open source software includes a selection mechanism suitable
+for use with devices that lack non-touch navigation inputs.</li>
+</ul>
+<a name="section-7.2.3"></a><h4>7.2.3. Navigation keys</h4>
+<p>The Home, Menu and Back functions are essential to the Android navigation
+paradigm. Device implementations MUST make these functions available to the
+user at all times when running applications. These functions MAY be implemented
+via dedicated physical buttons (such as mechanical or capacitive touch buttons),
+or MAY be implemented using dedicated software keys, gestures, touch panel, etc.
+Android 4.0 supports both implementations.</p>
+
+<p>Device implementations MAY use a distinct portion of the screen to display
+the navigation keys, but if so, MUST meet these requirements:</p>
+
+<ul>
+ <li>Device implementation navigation keys MUST use a distinct portion of the
+ screen, not available to applications, and MUST NOT obscure or otherwise
+ interfere with the portion of the screen available to applications.</li>
+ <li>Device implementations MUST make available a portion of the display to
+ applications that meets the requirements defined in
+ <a href="section-7.1.1">Section 7.1.1</a>.</li>
+ <li>Device implementations MUST display the navigation keys when applications
+ do not specify a system UI mode, or specify
+ <code>SYSTEM_UI_FLAG_VISIBLE</code>.</li>
+ <li>Device implementations MUST present the navigation keys in an unobtrusive
+ "low profile" (eg. dimmed) mode when applications specify
+ <code>SYSTEM_UI_FLAG_LOW_PROFILE</code>.</li>
+ <li>Device implementations MUST hide the navigation keys when applications
+ specify <code>SYSTEM_UI_FLAG_HIDE_NAVIGATION</code>.</li>
+ <li>Device implementation MUST present a Menu key to applications when
+ targetSdkVersion <= 10 and SHOULD NOT present a Menu key when the
+ targetSdkVersion > 10.</li>
+</ul>
+
+<a name="section-7.2.4"></a><h4>7.2.4. Touchscreen input</h4>
+<p>Device implementations:</p>
+<ul>
+<li>MUST have a pointer input system of some kind (either mouse-like, or touch)</li>
+<li>MAY have a touchscreen of any modality (such as capacitive or resistive)</li>
+<li>SHOULD support fully independently tracked pointers, if a touchscreen supports multiple pointers</li>
+<li>MUST report the value of <code>android.content.res.Configuration.touchscreen</code> [<a href="#resources40">Resources, 40</a>]
+corresponding to the type of the specific touchscreen on the device</li>
+</ul>
+
+<p>Android 4.0 includes support for a variety of touch screens, touch pads, and fake touch input devices.
+Touch screen based device implementations are associated with a display [<a href="#resources61">Resources, 61</a>]
+such that the user has the impression of directly manipulating items on screen. Since the user is directly touching the screen,
+the system does not require any additional affordances to indicate the objects being manipulated.
+In contrast, a fake touch interface provides a user input system that approximates a subset of touchscreen capabilities.
+For example, a mouse or remote control that drives an on-screen cursor approximates touch, but requires the user to first
+point or focus then click. Numerous input devices like the mouse, trackpad, gyro-based air mouse, gyro-pointer, joystick,
+and multi-touch trackpad can support fake touch interactions. Android 4.0 includes the feature constant <code>android.hardware.faketouch</code>,
+which corresponds to a high-fidelity non-touch (that is, pointer-based) input device such as a mouse or trackpad that can adequately emulate touch-based
+input (including basic gesture support), and indicates that the device supports an emulated subset of touchscreen
+functionality. Device implementations that declare the fake touch feature MUST meet the fake touch requirements in <a href="section 7.2.5">Section 7.2.5</a>.</p>
+
+<p>Device implementations MUST report the correct feature corresponding to the type of input used. Device implementations that
+include a touchscreen (single-touch or better) MUST also report the platform feature constant <code>android.hardware.faketouch</code>.
+Device implementations that do not include a touchscreen (and rely on a pointer device only) MUST NOT report any touchscreen feature, and MUST report only
+<code>android.hardware.faketouch</code> if they meet the fake touch requirements in <a href="section 7.2.5">Section 7.2.5</a>.</p>
+
+<a name="section-7.2.5"></a><h4>7.2.5. Fake touch input</h4>
+<p>Device implementations that declare support for <code>android.hardware.faketouch</code></p>
+<ul>
+<li> MUST report the absolute X and Y screen positions of the pointer location and display a visual pointer on the screen[<a href="#resources60">Resources, 60</a>] </li>
+<li> MUST report touch event with the action code [<a href="#resources60">Resources, 60</a>] that specifies the state change
+that occurs on the pointer going <code>down</code> or <code>up</code> on the screen [<a href="#resources60">Resources, 60</a>] </li>
+<li> MUST support pointer <code>down</code> and <code>up</code> on an object on the screen, which allows users to emulate tap on an object on the screen</li>
+<li> MUST support pointer <code>down</code>, pointer <code>up</code>, pointer <code>down</code> then pointer <code>up</code> in the same place on an object on the screen
+within a time threshold, which allows users to emulate double tap on an object on the screen [<a href="#resources60">Resources, 60</a>]</li>
+<li>MUST support pointer <code>down</code> on an arbitrary point on the screen, pointer move to any other arbitrary point on the screen,
+followed by a pointer <code>up</code>, which allows users to emulate a touch drag</li>
+<li> MUST support pointer <code>down</code> then allow users to quickly move the object to a different position on the screen
+and then pointer <code>up</code> on the screen, which allows users to fling an object on the screen</li>
+</ul>
+
+<p>Devices that declare support for <code>android.hardware.faketouch.multitouch.distinct</code> MUST meet the requirements for
+faketouch above, and MUST also support distinct tracking of two or more independent pointer inputs.</p>
+
+<a name="section-7.2.6"></a><h4>7.2.6. Microphone</h4>
+<p>Device implementations MAY omit a microphone. However, if a device
+implementation omits a microphone, it MUST NOT report the
+<code>android.hardware.microphone</code> feature constant, and must implement
+the audio recording API as no-ops, per <a href="section-7">Section 7</a>.
+Conversely, device implementations that do possess a microphone:</p>
+<ul>
+<li>MUST report the <code>android.hardware.microphone</code> feature
+constant</li>
+<li>SHOULD meet the audio quality requirements in <a
+href="section-5.3">Section 5.3</a></li>
+<li>SHOULD meet the audio latency requirements in <a
+href="section-5.4">Section 5.4</a></li>
+</ul>
+
+<a name="section-7.3"></a><h3>7.3. Sensors</h3>
+<p>Android 4.0 includes APIs for accessing a variety of sensor types. Devices
+implementations generally MAY omit these sensors, as provided for in the
+following subsections. If a device includes a particular sensor type that has a
+corresponding API for third-party developers, the device implementation MUST
+implement that API as described in the Android SDK documentation. For example,
+device implementations:</p>
+<ul>
+<li>MUST accurately report the presence or absence of sensors per the
+<code>android.content.pm.PackageManager</code> class. [<a
+href="#resources37">Resources, 37</a>]</li>
+<li>MUST return an accurate list of supported sensors via the
+<code>SensorManager.getSensorList()</code> and similar methods</li>
+<li>MUST behave reasonably for all other sensor APIs (for example, by
+returning true or false as appropriate when applications attempt to register
+listeners, not calling sensor listeners when the corresponding sensors are not
+present; etc.)</li>
+<li>MUST report all sensor measurements using the relevant International System
+of Units (i.e. metric) values for each sensor type as defined in the Android SDK
+documentation [<a href="#resources41">Resources, 41</a>]</li>
+</ul>
+<p>The list above is not comprehensive; the documented behavior of the Android
+SDK is to be considered authoritative.</p>
+<p>Some sensor types are synthetic, meaning they can be derived from data
+provided by one or more other sensors. (Examples include the orientation
+sensor, and the linear acceleration sensor.) Device implementations SHOULD
+implement these sensor types, when they include the prerequisite physical
+sensors.</p>
+<p>The Android 4.0 APIs introduce a notion of a "streaming" sensor, which is
+one that returns data continuously, rather than only when the data changes.
+Device implementations MUST continuously provide periodic data samples for any
+API indicated by the Android 4.0 SDK documentation to be a streaming
+sensor.</p>
+<a name="section-7.3.1"></a><h4>7.3.1. Accelerometer</h4>
+<p>Device implementations SHOULD include a 3-axis accelerometer. If a device
+implementation does include a 3-axis accelerometer, it:</p>
+<ul>
+<li>MUST be able to deliver events at 50 Hz or greater</li>
+<li>MUST comply with the Android sensor coordinate system as detailed
+in the Android APIs (see [<a href="#resources41">Resources, 41</a>])</li>
+<li>MUST be capable of measuring from freefall up to twice gravity (2g) or
+more on any three-dimensional vector</li>
+<li>MUST have 8-bits of accuracy or more</li>
+<li>MUST have a standard deviation no greater than 0.05 m/s^2</li>
+</ul>
+<a name="section-7.3.2"></a><h4>7.3.2. Magnetometer</h4>
+<p>Device implementations SHOULD include a 3-axis magnetometer (i.e. compass.)
+If a device does include a 3-axis magnetometer, it:</p>
+<ul>
+<li>MUST be able to deliver events at 10 Hz or greater</li>
+<li>MUST comply with the Android sensor coordinate system as detailed
+in the Android APIs (see [<a href="#resources41">Resources, 41</a>]).</li>
+<li>MUST be capable of sampling a range of field strengths adequate to cover the
+geomagnetic field</li>
+<li>MUST have 8-bits of accuracy or more</li>
+<li>MUST have a standard deviation no greater than 0.5 µT</li>
+</ul>
+<a name="section-7.3.3"></a><h4>7.3.3. GPS</h4>
+<p>Device implementations SHOULD include a GPS receiver. If a device
+implementation does include a GPS receiver, it SHOULD include
+some form of "assisted GPS" technique to minimize GPS lock-on time.</p>
+<a name="section-7.3.4"></a><h4>7.3.4. Gyroscope</h4>
+<p>Device implementations SHOULD include a gyroscope (i.e. angular change
+sensor.) Devices SHOULD NOT include a gyroscope sensor unless a 3-axis
+accelerometer is also included. If a device implementation includes a
+gyroscope, it:</p>
+<ul>
+<li>MUST be temperature compensated</li>
+<li>MUST be capable of measuring orientation changes up to 5.5*Pi
+radians/second (that is, approximately 1,000 degrees per second)</li>
+<li>MUST be able to deliver events at 100 Hz or greater</li>
+<li>MUST have 12-bits of accuracy or more</li>
+<li>MUST have a variance no greater than 1e-7 rad^2 / s^2 per Hz (variance per Hz, or rad^2 / s).
+The variance is allowed to vary with the sampling rate, but must be constrained by this value.
+In other words, if you measure the variance of the gyro at 1 Hz sampling rate it should be no
+greater than 1e-7 rad^2/s^2. </li>
+<li>MUST have timestamps as close to when the hardware event happened as possible. The constant latency must be removed.</li>
+</ul>
+<a name="section-7.3.5"></a><h4>7.3.5. Barometer</h4>
+<p>Device implementations MAY include a barometer (i.e. ambient air pressure
+sensor.) If a device implementation includes a barometer, it:</p>
+<ul>
+<li>MUST be able to deliver events at 5 Hz or greater</li>
+<li>MUST have adequate precision to enable estimating altitude</li>
+</ul>
+<a name="section-7.3.6"></a><h4>7.3.7. Thermometer</h4>
+<p>Device implementations MAY but SHOULD NOT include a thermometer (i.e.
+temperature sensor.) If a device implementation does include a thermometer, it
+MUST measure the temperature of the device CPU. It MUST NOT measure any other
+temperature. (Note that this sensor type is deprecated in the Android 4.0
+APIs.)</p>
+<a name="section-7.3.7"></a><h4>7.3.7. Photometer</h4>
+<p>Device implementations MAY include a photometer (i.e. ambient light
+sensor.)</p>
+<a name="section-7.3.8"></a><h4>7.3.8. Proximity Sensor</h4>
+<p>Device implementations MAY include a proximity sensor. If a device
+implementation does include a proximity sensor, it MUST measure the proximity
+of an object in the same direction as the screen. That is, the proximity
+sensor MUST be oriented to detect objects close to the screen, as the
+primary intent of this sensor type is to detect a phone in use by the
+user. If a device implementation includes a proximity sensor with any other
+orientation, it MUST NOT be accessible through this API. If a device
+implementation has a proximity sensor, it MUST be have 1-bit of accuracy or
+more.</p>
+
+<a name="section-7.4"></a><h3>7.4. Data Connectivity</h3>
+<a name="section-7.4.1"></a><h4>7.4.1. Telephony</h4>
+<p>"Telephony" as used by the Android 4.0 APIs and this document refers
+specifically to hardware related to placing voice calls and sending SMS
+messages via a GSM or CDMA network. While these voice calls may or may not be
+packet-switched, they are for the purposes of Android 4.0 considered
+independent of any data connectivity that may be implemented using the same
+network. In other words, the Android "telephony" functionality and APIs refer
+specifically to voice calls and SMS; for instance, device implementations that
+cannot place calls or send/receive SMS messages MUST NOT report the
+"android.hardware.telephony" feature or any sub-features, regardless of
+whether they use a cellular network for data connectivity.</p>
+<p>Android 4.0 MAY be used on devices that do not include telephony hardware.
+That is, Android 4.0 is compatible with devices that are not phones.
+However, if a device implementation does include GSM or CDMA telephony, it
+MUST implement full support for the API for that technology. Device
+implementations that do not include telephony hardware MUST implement the full
+APIs as no-ops.</p>
+<a name="section-7.4.2"></a><h4>7.4.2. IEEE 802.11 (WiFi)</h4>
+<p>Android 4.0 device implementations SHOULD include support for one or more
+forms of 802.11 (b/g/a/n, etc.) If a device implementation does include
+support for 802.11, it MUST implement the corresponding Android API.</p>
+<a name="section-7.4.3"></a><h4>7.4.3. Bluetooth</h4>
+<p>Device implementations SHOULD include a Bluetooth transceiver. Device
+implementations that do include a Bluetooth transceiver MUST enable the
+RFCOMM-based Bluetooth API as described in the SDK documentation [<a
+href="#resources42">Resources, 42</a>]. Device implementations SHOULD
+implement relevant Bluetooth profiles, such as A2DP, AVRCP, OBEX, etc. as
+appropriate for the device.</p>
+<p>The Compatibility Test Suite includes cases that cover basic operation of
+the Android RFCOMM Bluetooth API. However, since Bluetooth is a communications
+protocol between devices, it cannot be fully tested by unit tests running on a
+single device. Consequently, device implementations MUST also pass the
+human-driven Bluetooth test procedure described in Appendix A.</p>
+<a name="section-7.4.4"></a><h4>7.4.4. Near-Field Communications</h4>
+<p>Device implementations SHOULD include a transceiver and related hardware
+for Near-Field Communications (NFC). If a device implementation does include
+NFC hardware, then it:</p>
+<ul>
+ <li>MUST report the android.hardware.nfc feature from the
+ <code>android.content.pm.PackageManager.hasSystemFeature()</code> method.
+ [<a href="#resources37">Resources, 37</a>]</li>
+ <li>MUST be capable of reading and writing NDEF messages via the following NFC
+ standards:
+ <ul>
+ <li>MUST be capable of acting as an NFC Forum reader/writer
+ (as defined by the NFC Forum technical specification
+ NFCForum-TS-DigitalProtocol-1.0) via the following NFC standards:
+ <ul>
+ <li>NfcA (ISO14443-3A)</li>
+ <li>NfcB (ISO14443-3B) </li>
+ <li>NfcF (JIS 6319-4)</li>
+ <li>IsoDep (ISO 14443-4)</li>
+ <li>NFC Forum Tag Types 1, 2, 3, 4 (defined by the NFC Forum)</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>SHOULD be capable of reading and writing NDEF messages via the following
+ NFC standards. Note that while the NFC standards below are stated as
+ "SHOULD" for Android 4.0, the Compatibility Definition for a future
+ version is planned to change these to "MUST". That is, these stanards are
+ optional in Android 4.0 but <b>will be required</b> in future versions.
+ Existing and new devices that run Android 4.0 are <b>very strongly
+ encouraged to meet these requirements in Android 4.0</b> so they will be
+ able to upgrade to the future platform releases.
+ <ul>
+ <li>NfcV (ISO 15693)</li>
+ </ul>
+ </li>
+ <li>MUST be capable of transmitting and receiving data via the following
+ peer-to-peer standards and protocols:
+ <ul>
+ <li>ISO 18092</li>
+ <li>LLCP 1.0 (defined by the NFC Forum)</li>
+ <li>SDP 1.0 (defined by the NFC Forum)</li>
+ <li>NDEF Push Protocol [<a href="#resources43">Resources, 43</a>]</li>
+ <li>SNEP 1.0 (defined by the NFC Forum)</li>
+ </ul>
+ </li>
+ <li>MUST include support for Android Beam:
+ <ul>
+ <li>MUST implement the SNEP default server. Valid NDEF messages received
+ by the default SNEP server MUST be dispatched to applications using
+ the android.nfc.ACTION_NDEF_DISCOVERED intent. Disabling Android Beam
+ in settings MUST NOT disable dispatch of incoming NDEF message.</li>
+ <li>MUST implement the NPP server. Messages received by the NPP server MUST
+ be processed the same way as the SNEP default server.</li>
+ <li>MUST implement a SNEP client and attempt to send outbound P2P NDEF to
+ the default SNEP server when Android Beam is enabled. If no default
+ SNEP server is found then the client MUST attempt to send to an NPP
+ server.</li>
+ <li>MUST allow foreground activities to set the outbound P2P NDEF message
+ using android.nfc.NfcAdapter.setNdefPushMessage, and
+ android.nfc.NfcAdapter.setNdefPushMessageCallback, and
+ android.nfc.NfcAdapter.enableForegroundNdefPush.</li>
+ <li>SHOULD use a gesture or on-screen confirmation, such as 'Touch to Beam',
+ before sending outbound P2P NDEF messages.</li>
+ <li>SHOULD enable Android Beam by default</li>
+ </ul>
+ </li>
+ <li>MUST poll for all supported technologies while in NFC discovery mode.</li>
+ <li>SHOULD be in NFC discovery mode while the device is awake with the screen active
+ and the lock-screen unlocked.</li>
+</ul>
+
+<p>(Note that publicly available links are not available for the JIS, ISO, and
+NFC Forum specifications cited above.)</p>
+<p>Additionally, device implementations MAY include reader/writer support for
+the following MIFARE technologies.</p>
+<ul>
+ <li>MIFARE Classic (NXP MF1S503x [<a href="#resources44">Resources, 44</a>],
+ MF1S703x [<a href="#resources44">Resources, 44</a>])</li>
+ <li>MIFARE Ultralight (NXP MF0ICU1 [<a href="#resources46">Resources, 46</a>],
+ MF0ICU2 [<a href="#resources46">Resources, 46</a>])</li>
+ <li>NDEF on MIFARE Classic (NXP AN130511 [<a href="#resources48">Resources, 48</a>],
+ AN130411 [<a href="#resources49">Resources, 49</a>])</li>
+</ul>
+<p>Note that Android 4.0 includes APIs for these MIFARE types. If a
+device implementation supports MIFARE in the reader/writer role, it:</p>
+<ul>
+ <li>MUST implement the corresponding Android APIs as documented by the
+ Android SDK</li>
+ <li>MUST report the feature com.nxp.mifare from the
+ <code>android.content.pm.PackageManager.hasSystemFeature()</code> method.
+ [<a href="#resources37">Resources, 37</a>] Note that this is not a standard
+ Android feature, and as such does not appear as a constant on the
+ <code>PackageManager</code> class.</li>
+ <li>MUST NOT implement the corresponding Android APIs nor report the
+ com.nxp.mifare feature unless it also implements general NFC support as
+ described in this section</li>
+</ul>
+<p>If a device implementation does not include NFC hardware, it MUST NOT
+declare the android.hardware.nfc feature from the
+<code>android.content.pm.PackageManager.hasSystemFeature()</code> method [<a
+href="#resources37">Resources, 37</a>], and MUST implement the Android 4.0 NFC
+API as a no-op.</p>
+<p>As the classes <code>android.nfc.NdefMessage</code> and
+<code>android.nfc.NdefRecord</code> represent a protocol-independent data
+representation format, device implementations MUST implement these APIs even
+if they do not include support for NFC or declare the android.hardware.nfc
+feature.</p>
+<a name="section-7.4.5"></a><h4>7.4.5. Minimum Network Capability</h4>
+<p>Device implementations MUST include support for one or more forms of data
+networking. Specifically, device implementations MUST include support for at
+least one data standard capable of 200Kbit/sec or greater. Examples of
+technologies that satisfy this requirement include EDGE, HSPA, EV-DO, 802.11g,
+Ethernet, etc.</p>
+<p>Device implementations where a physical networking standard (such as
+Ethernet) is the primary data connection SHOULD also include support for at
+least one common wireless data standard, such as 802.11 (WiFi).</p>
+<p>Devices MAY implement more than one form of data connectivity.</p>
+
+
+<a name="section-7.5"></a><h3>7.5. Cameras</h3>
+<p>Device implementations SHOULD include a rear-facing camera, and MAY include
+a front-facing camera. A rear-facing camera is a camera located on the side of
+the device opposite the display; that is, it images scenes on the far side of
+the device, like a traditional camera. A front-facing camera is a camera
+located on the same side of the device as the display; that is, a camera
+typically used to image the user, such as for video conferencing and similar
+applications.</p>
+<a name="section-7.5.1"></a><h4>7.5.1. Rear-Facing Camera</h4>
+<p>Device implementations SHOULD include a rear-facing camera. If a device
+implementation includes a rear-facing camera, it:</p>
+<ul>
+<li>MUST have a resolution of at least 2 megapixels</li>
+<li>SHOULD have either hardware auto-focus, or software auto-focus implemented
+in the camera driver (transparent to application software)</li>
+<li>MAY have fixed-focus or EDOF (extended depth of field) hardware</li>
+<li>MAY include a flash. If the Camera includes a flash, the flash lamp MUST
+NOT be lit while an android.hardware.Camera.PreviewCallback instance has been
+registered on a Camera preview surface, unless the application has explicitly
+enabled the flash by enabling the <code>FLASH_MODE_AUTO</code> or
+<code>FLASH_MODE_ON</code> attributes of a <code>Camera.Parameters</code>
+object. Note that this constraint does not apply to the device's built-in
+system camera application, but only to third-party applications using
+<code>Camera.PreviewCallback</code>.</li>
+</ul>
+<a name="section-7.5.2"></a><h4>7.5.2. Front-Facing Camera</h4>
+<p>Device implementations MAY include a front-facing camera. If a device
+implementation includes a front-facing camera, it:</p>
+<ul>
+<li>MUST have a resolution of at least VGA (that is, 640x480 pixels)</li>
+<li>MUST NOT use a front-facing camera as the default for the Camera API.
+That is, the camera API in Android 4.0 has specific support for front-facing
+cameras, and device implementations MUST NOT configure the API to to treat a
+front-facing camera as the default rear-facing camera, even if it is the only
+camera on the device.</li>
+<li>MAY include features (such as auto-focus, flash, etc.)
+available to rear-facing cameras as described in Section 7.5.1.</li>
+<li>MUST horizontally reflect (i.e. mirror) the stream displayed by an app in a
+CameraPreview, as follows:</li>
+<ul>
+<li>If the device implementation is capable of being rotated by user (such as
+automatically via an accelerometer or manually via user input), the camera
+preview MUST be mirrored horizontally relative to the device's current
+orientation.</li>
+<li>If the current application has explicitly requested that the Camera
+display be rotated via a call to the
+<code>android.hardware.Camera.setDisplayOrientation()</code> [<a
+href="#resources50">Resources, 50</a>] method, the camera preview MUST be
+mirrored horizontally relative to the orientation specified by the
+application.</li>
+<li>Otherwise, the preview MUST be mirrored along the device's default horizontal axis.</li>
+</ul>
+<li>MUST mirror the image displayed by the postview in the same manner as
+the camera preview image stream. (If the device implementation does not
+support postview, this requirement obviously does not apply.)</li>
+<li>MUST NOT mirror the final captured still image or video streams returned
+to application callbacks or committed to media storage</li>
+</ul>
+<a name="section-7.5.3"></a><h4>7.5.3. Camera API Behavior</h4>
+<p>Device implementations MUST implement the following behaviors for the
+camera-related APIs, for both front- and rear-facing cameras:</p>
+<ol>
+<li>If an application has never called
+<code>android.hardware.Camera.Parameters.setPreviewFormat(int)</code>, then the
+device MUST use <code>android.hardware.PixelFormat.YCbCr_420_SP</code> for
+preview data provided to application callbacks.</li>
+<li>If an application registers an <code>android.hardware.Camera.PreviewCallback
+</code> instance and the system calls the <code>onPreviewFrame()</code> method
+when the preview format is YCbCr_420_SP, the data in the <code>byte[]</code>
+passed into <code>onPreviewFrame()</code> must further be in the NV21 encoding
+format. That is, NV21 MUST be the default.</li>
+<li>Device implementations MUST support the YV12 format (as denoted by the
+<code>android.graphics.ImageFormat.YV12</code> constant) for camera previews
+for both front- and rear-facing cameras. (The hardware video decoder and camera
+may use any native pixel format, but the device implementation MUST support conversion
+to YV12.)</li>
+</ol>
+<p>Device implementations MUST implement the full Camera API included in the
+Android 4.0 SDK documentation [<a href="#resources51">Resources, 51</a>]),
+regardless of whether the device includes hardware autofocus or other
+capabilities. For instance, cameras that lack autofocus MUST still call any
+registered <code>android.hardware.Camera.AutoFocusCallback</code> instances (even though
+this has no relevance to a non-autofocus camera.) Note that this does apply
+to front-facing cameras; for instance, even though most front-facing cameras
+do not support autofocus, the API callbacks must still be "faked" as
+described.</p>
+<p>Device implementations MUST recognize and honor each parameter name defined
+as a constant on the <code>android.hardware.Camera.Parameters</code> class, if the
+underlying hardware supports the feature. If the device hardware does not
+support a feature, the API must behave as documented. Conversely, Device
+implementations MUST NOT honor or recognize string constants passed
+to the <code>android.hardware.Camera.setParameters()</code> method other than
+those documented as constants on the
+<code>android.hardware.Camera.Parameters</code>. That is,
+device implementations MUST support all standard Camera parameters if the
+hardware allows, and MUST NOT support custom Camera parameter types.</p>
+<p>Device implementations MUST broadcast the <code>Camera.ACTION_NEW_PICTURE</code>
+intent whenever a new picture is taken by the camera and the entry of the picture
+has been added to the media store.</p>
+<p>Device implementations MUST broadcast the <code>Camera.ACTION_NEW_VIDEO</code>
+intent whenever a new video is recorded by the camera and the entry of the picture
+has been added to the media store.</p>
+<a name="section-7.5.4"></a><h4>7.5.4. Camera Orientation</h4>
+<p>Both front- and rear-facing cameras, if present, MUST be oriented so that
+the long dimension of the camera aligns with the screen's long dimention. That
+is, when the device is held in the landscape orientation, cameras MUST
+capture images in the landscape orientation. This applies regardless of the
+device's natural orientation; that is, it applies to landscape-primary devices
+as well as portrait-primary devices.</p>
+
+
+<a name="section-7.6"></a><h3>7.6. Memory and Storage</h3>
+<a name="section-7.6.1"></a><h4>7.6.1. Minimum Memory and Storage</h4>
+<p>Device implementations MUST have at least 340MB of memory available to the
+kernel and userspace. The 340MB MUST be in addition to any memory dedicated to
+hardware components such as radio, video, and so on that is not under the
+kernel's control.</p>
+<p>Device implementations MUST have at least 350MB of non-volatile storage
+available for application private data. That is, the <code>/data</code> partition MUST be at
+least 350MB.</p>
+<p>The Android APIs include a Download Manager that applications may use to
+download data files [<a href="#resources56">Resources, 56</a>]. The device
+implementation of the Download Manager MUST be capable of downloading individual
+files of at least 100MB in size to the default "cache" location.</p>
+<a name="section-7.6.2"></a><h4>7.6.2. Application Shared Storage</h4>
+<p>Device implementations MUST offer shared storage for applications. The
+shared storage provided MUST be at least 1GB in size.</p>
+<p>Device implementations MUST be configured with shared storage mounted by
+default, "out of the box". If the shared storage is not mounted on the Linux
+path <code>/sdcard</code>, then the device MUST include a Linux symbolic link
+from <code>/sdcard</code> to the actual mount point.</p>
+<p>Device implementations MUST enforce as documented the
+<code>android.permission.WRITE_EXTERNAL_STORAGE</code> permission on this
+shared storage. Shared storage MUST otherwise be writable by any application
+that obtains that permission.</p>
+<p>Device implementations MAY have hardware for user-accessible removable
+storage, such as a Secure Digital card. Alternatively, device implementations
+MAY allocate internal (non-removable) storage as shared storage for apps.</p>
+<p>Regardless of the form of shared storage used, device implementations MUST
+provide some mechanism to access the contents of shared storage from a host
+computer, such as USB mass storage (UMS) or Media Transfer Protocol (MTP). Device
+implementations MAY use USB mass storage, but SHOULD use Media Transfer
+Protocol. If the device implementation supports Media Transfer Protocol:</p>
+<ul>
+<li>The device implementation SHOULD be compatible with the reference Android
+MTP host, Android File Transfer [<a href="#resources57">Resources, 57</a>].</li>
+<li>The device implementation SHOULD report a USB device class of <code>0x00</code>.</li>
+<li>The device implementation SHOULD report a USB interface name of 'MTP'.</li>
+</ul>
+<p>If the device implementation lacks USB ports, it MUST provide a host
+computer with access to the contents of shared storage by some other means,
+such as a network file system.</p>
+<p>It is illustrative to consider two common examples. If a device
+implementation includes an SD card slot to satisfy the shared storage
+requirement, a FAT-formatted SD card 1GB in size or larger MUST be included
+with the device as sold to users, and MUST be mounted by default.
+Alternatively, if a device implementation uses internal fixed storage to
+satisfy this requirement, that storage MUST be 1GB in size or larger
+and mounted on <code>/sdcard</code> (or <code>/sdcard</code>
+MUST be a symbolic link to the physical location if it is mounted elsewhere.)</p>
+<p>Device implementations that include multiple shared storage paths (such as
+both an SD card slot and shared internal storage) SHOULD modify the core
+applications such as the media scanner and ContentProvider to transparently
+support files placed in both locations.</p>
+
+<a name="section-7.7"></a><h3>7.7. USB</h3>
+<p>Device implementations SHOULD include a USB client port, and SHOULD include
+a USB host port.</p>
+<p>If a device implementation includes a USB client port:</p>
+<ul>
+<li>the port MUST be connectable to a USB host with a standard USB-A port</li>
+<li>the port SHOULD use the micro USB form factor on the device side</li>
+<li>it MUST allow a host connected to the device to access the contents of the
+shared storage volume using either USB mass storage or Media Transfer
+Protocol</li>
+<li>it MUST implement the Android Open Accessory API and specification as documented
+in the Android SDK documentation, and MUST declare support for the hardware
+feature <code>android.hardware.usb.accessory</code> [<a href="#resources52">Resources,
+51</a>]</li>
+</ul>
+
+<p>If a device implementation includes a USB host port:</p>
+<ul>
+<li>it MAY use a non-standard port form factor, but if so MUST ship with a
+cable or cables adapting the port to standard USB-A</li>
+<li>it MUST implement the Android USB host API as documented in the Android
+SDK, and MUST declare support for the hardware feature
+<code>android.hardware.usb.host</code> [<a href="#resources53">Resources,
+52</a>]</li>
+</ul>
+<p>Device implementations MUST implement the Android Debug Bridge. If a device
+implementation omits a USB client port, it MUST implement the Android Debug
+Bridge via local-area network (such as Ethernet or 802.11)</p>
+
+<a name="section-8"></a><h2>8. Performance Compatibility</h2>
+<p>Device implementations MUST meet the key performance metrics of an Android
+4.0 compatible device defined in the table below:</p>
+<table><tbody><tr>
+<td><b>Metric</b></td>
+<td><b>Performance Threshold</b></td>
+<td><b>Comments</b></td>
+</tr>
+<tr>
+<td>Application Launch Time</td>
+<td>The following applications should launch within the specified time.<ul>
+<li>Browser: less than 1300ms</li>
+<li>Contacts: less than 700ms</li>
+<li>Settings: less than 700ms</li>
+</ul></td>
+<td>The launch time is measured as the total time to
+complete loading the default activity for the application, including the time
+it takes to start the Linux process, load the Android package into the Dalvik
+VM, and call onCreate.</td>
+</tr>
+<tr>
+<td>Simultaneous Applications</td>
+<td>When multiple applications have been launched, re-launching an
+already-running application after it has been launched must take less than the
+original launch time.</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+
+<a name="section-9"></a><h2>9. Security Model Compatibility</h2>
+<p>Device implementations MUST implement a security model consistent with the
+Android platform security model as defined in Security and Permissions
+reference document in the APIs [<a href="#resources54">Resources, 54</a>] in the
+Android developer documentation. Device implementations MUST support
+installation of self-signed applications without requiring any additional
+permissions/certificates from any third parties/authorities. Specifically,
+compatible devices MUST support the security mechanisms described in the
+follow sub-sections.</p>
+<a name="section-9.1"></a><h3>9.1. Permissions</h3>
+<p>Device implementations MUST support the Android permissions model as
+defined in the Android developer documentation [<a
+href="#resources54">Resources, 54</a>]. Specifically,
+implementations MUST enforce each permission defined as described in the SDK
+documentation; no permissions may be omitted, altered, or ignored.
+Implementations MAY add additional permissions, provided the new permission ID
+strings are not in the android.* namespace.</p>
+<a name="section-9.2"></a><h3>9.2. UID and Process Isolation</h3>
+<p>Device implementations MUST support the Android application sandbox model,
+in which each application runs as a unique Unix-style UID and in a separate
+process. Device implementations MUST support running multiple applications as
+the same Linux user ID, provided that the applications are properly signed and
+constructed, as defined in the Security and Permissions reference [<a
+href="#resources54">Resources, 54</a>].</p>
+<a name="section-9.3"></a><h3>9.3. Filesystem Permissions</h3>
+<p>Device implementations MUST support the Android file access permissions
+model as defined in as defined in the Security and Permissions reference [<a
+href="#resources54">Resources, 54</a>].</p>
+<a name="section-9.4"></a><h3>9.4. Alternate Execution Environments</h3>
+<p>Device implementations MAY include runtime environments that execute
+applications using some other software or technology than the Dalvik virtual
+machine or native code. However, such alternate execution environments MUST
+NOT compromise the Android security model or the security of installed Android
+applications, as described in this section.</p>
+<p>Alternate runtimes MUST themselves be Android applications, and abide by
+ the standard Android security model, as described elsewhere in Section 9.</p>
+<p>Alternate runtimes MUST NOT be granted access to resources protected by
+ permissions not requested in the runtime's AndroidManifest.xml file via the
+ <code><uses-permission></code> mechanism.</p>
+<p>Alternate runtimes MUST NOT permit applications to make use of features
+ protected by Android permissions restricted to system applications.</p>
+<p>Alternate runtimes MUST abide by the Android sandbox model. Specifically:</p>
+<ul>
+<li>Alternate runtimes SHOULD install apps via the PackageManager into
+ separate Android sandboxes (that is, Linux user IDs, etc.)</li>
+<li>Alternate runtimes MAY provide a single Android sandbox shared by all
+ applications using the alternate runtime.</li>
+<li>Alternate runtimes and installed applications using an alternate runtime
+ MUST NOT reuse the sandbox of any other app installed on the device, except
+ through the standard Android mechanisms of shared user ID and signing
+ certificate</li>
+<li>Alternate runtimes MUST NOT launch with, grant, or be granted access to
+ the sandboxes corresponding to other Android applications.</li>
+</ul>
+<p>Alternate runtimes MUST NOT be launched with, be granted, or grant to other
+ applications any privileges of the superuser (root), or of any other user ID.</p>
+<p>The .apk files of alternate runtimes MAY be included in the system image of
+ a device implementation, but MUST be signed with a key distinct
+ from the key used to sign other applications included with the device
+ implementation.</p>
+<p>When installing applications, alternate runtimes MUST obtain user consent
+ for the Android permissions used by the application. That is, if an
+ application needs to make use of a device resource for which there is a
+ corresponding Android permission (such as Camera, GPS, etc.), the alternate
+ runtime MUST inform the user that the application will be able to access
+ that resource. If the runtime environment does not record application
+ capabilities in this manner, the runtime environment MUST list all
+ permissions held by the runtime itself when installing any application
+ using that runtime.</p>
+
+<a name="section-10"></a><h2>10. Software Compatibility Testing</h2>
+<p>Device implementations MUST pass all tests described in this section.</p>
+<p>However, note that no software test package is fully comprehensive. For
+this reason, device implementers are very strongly encouraged to make the
+minimum number of changes as possible to the reference and preferred
+implementation of Android 4.0 available from the Android Open Source Project.
+This will minimize the risk of introducing bugs that create incompatibilities
+requiring rework and potential device updates.</p>
+<a name="section-10.1"></a><h3>10.1. Compatibility Test Suite</h3>
+<p>Device implementations MUST pass the Android Compatibility Test Suite (CTS)
+[<a href="#resources02">Resources, 2</a>] available from the Android Open Source
+Project, using the final shipping software on the device. Additionally, device
+implementers SHOULD use the reference implementation in the Android Open
+Source tree as much as possible, and MUST ensure compatibility in cases of
+ambiguity in CTS and for any reimplementations of parts of the reference
+source code.</p>
+<p>The CTS is designed to be run on an actual device. Like any software, the
+CTS may itself contain bugs. The CTS will be versioned independently of this
+Compatibility Definition, and multiple revisions of the CTS may be released
+for Android 4.0. Device implementations MUST pass the latest CTS version
+available at the time the device software is completed.</p>
+<a name="section-10.2"></a><h3>10.2. CTS Verifier</h3>
+<p>Device implementations MUST correctly execute all applicable cases in the
+CTS Verifier. The CTS Verifier is included with the Compatibility Test Suite,
+and is intended to be run by a human operator to test functionality that
+cannot be tested by an automated system, such as correct functioning of a
+camera and sensors.</p>
+<p>The CTS Verifier has tests for many kinds of hardware, including some
+hardware that is optional. Device implementations MUST pass all tests for
+hardware which they possess; for instance, if a device possesses an
+accelerometer, it MUST correctly execute the Accelerometer test case in the
+CTS Verifier. Test cases for features noted as optional by this Compatibility
+Definition Document MAY be skipped or omitted.</p>
+<p>Every device and every build MUST correctly run the CTS Verifier, as noted
+above. However, since many builds are very similar, device implementers are
+not expected to explicitly run the CTS Verifier on builds that differ only in
+trivial ways. Specifically, device implementations that differ from an
+implementation that has passed the CTS Verfier only by the set of included
+locales, branding, etc. MAY omit the CTS Verifier test.</p>
+<a name="section-10.3"></a><h3>10.3. Reference Applications</h3>
+<p>Device implementers MUST test implementation compatibility using the
+following open source applications:</p>
+<ul>
+<li>The "Apps for Android" applications [<a href="#resources55">Resources, 55</a>].</li>
+<li>Replica Island (available in Android Market)</li>
+</ul>
+<p>Each app above MUST launch and behave correctly on the implementation, for
+the implementation to be considered compatible.</p>
+
+
+<a name="section-11"></a><h2>11. Updatable Software</h2>
+<p>Device implementations MUST include a mechanism to replace the entirety of
+the system software. The mechanism need not perform "live" upgrades - that
+is, a device restart MAY be required.</p>
+<p>Any method can be used, provided that it can replace the entirety of the
+software preinstalled on the device. For instance, any of the following
+approaches will satisfy this requirement:</p>
+<ul>
+<li>Over-the-air (OTA) downloads with offline update via reboot</li>
+<li>"Tethered" updates over USB from a host PC</li>
+<li>"Offline" updates via a reboot and update from a file on removable
+storage</li>
+</ul>
+<p>The update mechanism used MUST support updates without wiping user data.
+That is, the update mechanism MUST preserve application private data
+and application shared data. Note that the upstream Android software includes
+an update mechanism that satisfies this requirement.</p>
+<p>If an error is found in a device implementation after it has been released
+but within its reasonable product lifetime that is determined in consultation
+with the Android Compatibility Team to affect the compatibility of third-party
+applications, the device implementer MUST correct the error via a software
+update available that can be applied per the mechanism just described.</p>
+
+<a name="section-12"></a><h2>12. Contact Us</h2>
+<p>You can contact the document authors at <a
+href="mailto:compatibility@android.com">compatibility@android.com</a> for
+clarifications and to bring up any issues that you think the document does not
+cover.</p>
+
+<div style="page-break-before: always;"></div>
+
+<a name="appendix-A"></a><h2>Appendix A - Bluetooth Test Procedure</h2>
+<p>The Compatibility Test Suite includes cases that cover basic operation of
+the Android RFCOMM Bluetooth API. However, since Bluetooth is a communications
+protocol between devices, it cannot be fully tested by unit tests running on a
+single device. Consequently, device implementations MUST also pass the
+human-operated Bluetooth test procedure described below.</p>
+<p>The test procedure is based on the BluetoothChat sample app included in the
+Android open source project tree. The procedure requires two devices:</p>
+<ul>
+<li>a candidate device implementation running the software build to be tested</li>
+<li>a separate device implementation already known to be compatible, and of a
+ model from the device implementation being tested - that is, a "known
+ good" device implementation</li>
+</ul>
+<p>The test procedure below refers to these devices as the "candidate" and "known
+good" devices, respectively.</p>
+<h3>Setup and Installation</h3>
+<ol>
+<li>Build BluetoothChat.apk via 'make samples' from an Android source code tree.</li>
+<li>Install BluetoothChat.apk on the known-good device.</li>
+<li>Install BluetoothChat.apk on the candidate device.</li>
+</ol>
+<h3>Test Bluetooth Control by Apps</h3>
+<ol>
+<li>Launch BluetoothChat on the candidate device, while Bluetooth is disabled.</li>
+<li>Verify that the candidate device either turns on Bluetooth, or prompts the user with a dialog to turn on Bluetooth.</li>
+</ol>
+<h3>Test Pairing and Communication</h3>
+<ol>
+<li>Launch the Bluetooth Chat app on both devices.</li>
+<li>Make the known-good device discoverable from within BluetoothChat (using the Menu).</li>
+<li>On the candidate device, scan for Bluetooth devices from within BluetoothChat (using the Menu) and pair with the known-good device.</li>
+<li>Send 10 or more messages from each device, and verify that the other device receives them correctly.</li>
+<li>Close the BluetoothChat app on both devices by pressing <b>Home</b>.</li>
+<li>Unpair each device from the other, using the device Settings app.</li>
+</ol>
+<h3>Test Pairing and Communication in the Reverse Direction</h3>
+<ol>
+<li>Launch the Bluetooth Chat app on both devices.</li>
+<li>Make the candidate device discoverable from within BluetoothChat (using the Menu).</li>
+<li>On the known-good device, scan for Bluetooth devices from within BluetoothChat (using the Menu) and pair with the candidate device.</li>
+<li>Send 10 or messages from each device, and verify that the other device receives them correctly.</li>
+<li>Close the Bluetooth Chat app on both devices by pressing Back repeatedly to get to the Launcher.</li>
+</ol>
+<h3>Test Re-Launches</h3>
+<ol>
+<li>Re-launch the Bluetooth Chat app on both devices.</li>
+<li>Send 10 or messages from each device, and verify that the other device receives them correctly.</li>
+</ol>
+<p>Note: the above tests have some cases which end a test section by using
+Home, and some using Back. These tests are not redundant and are not optional:
+the objective is to verify that the Bluetooth API and stack works correctly
+both when Activities are explicitly terminated (via the user pressing Back,
+which calls finish()), and implicitly sent to background (via the user
+pressing Home.) Each test sequence MUST be performed as described.</p>
+
+<div id="footerContent" xmlns:pdf="http://whatever">
+<pdf:pagenumber/>
+</div>
+</body>
+</html>
diff --git a/src/compatibility/4.2/android-4.2-cdd.xhtml b/src/compatibility/4.2/android-4.2-cdd.xhtml
new file mode 100644
index 0000000..93c492a
--- /dev/null
+++ b/src/compatibility/4.2/android-4.2-cdd.xhtml
@@ -0,0 +1,2646 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>Android 4.2Compatibility Definition</title>
+<link rel="stylesheet" type="text/css" href="cdd.css"/>
+</head>
+<body>
+<div><img src="header.jpg" alt="Android logo"/></div>
+<h1>Android 4.2 Compatibility Definition</h1>
+<!--
+<span style="color: red; font-weight: bold;"><h2>Revision 1</h2></span><br/>
+<span style="color: red;">Last updated: October 17, 2012</span>
+-->
+<p><b><font color="red">Revision 2</font></b><br/>
+Last updated: Feb 17, 2013
+</p>
+<p>Copyright © 2012, Google Inc. All rights reserved.<br/>
+<a href="mailto:compatibility@android.com">compatibility@android.com</a>
+</p>
+
+<h2> Table of Contents</h2>
+<div style="margin-left: 2em;">
+ <a href="#section-1">1. Introduction</a><br/>
+ <a href="#section-2">2. Resources</a><br/>
+ <a href="#section-3">3. Software</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.1">3.1. Managed API Compatibility</a><br/>
+ <a href="#section-3.2">3.2. Soft API Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.2.1">3.2.1. Permissions</a><br/>
+ <a href="#section-3.2.2">3.2.2. Build Parameters</a><br/>
+ <a href="#section-3.2.3">3.2.3. Intent Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.2.3.1">3.2.3.1. Core Application Intents</a><br/>
+ <a href="#section-3.2.3.2">3.2.3.2. Intent Overrides</a><br/>
+ <a href="#section-3.2.3.3">3.2.3.3. Intent Namespaces</a><br/>
+ <a href="#section-3.2.3.4">3.2.3.4. Broadcast Intents</a><br/>
+ </div>
+ </div>
+ <a href="#section-3.3">3.3. Native API Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.3.1">3.3.1 Application Binary Interfaces</a><br/>
+ </div>
+ <a href="#section-3.4">3.4. Web Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.4.1">3.4.1. WebView Compatibility</a><br/>
+ <a href="#section-3.4.2">3.4.2. Browser Compatibility</a><br/>
+ </div>
+ <a href="#section-3.5">3.5. API Behavioral Compatibility</a><br/>
+ <a href="#section-3.6">3.6. API Namespaces</a><br/>
+ <a href="#section-3.7">3.7. Virtual Machine Compatibility</a><br/>
+ <a href="#section-3.8">3.8. User Interface Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.8.1">3.8.1. Widgets</a><br/>
+ <a href="#section-3.8.2">3.8.2. Notifications</a><br/>
+ <a href="#section-3.8.3">3.8.3. Search</a><br/>
+ <a href="#section-3.8.4">3.8.4. Toasts</a><br/>
+ <a href="#section-3.8.5">3.8.5. Themes</a><br/>
+ <a href="#section-3.8.6">3.8.6. Live Wallpapers</a><br/>
+ <a href="#section-3.8.7">3.8.7. Recent Application Display</a><br/>
+ <a href="#section-3.8.8">3.8.8. Input Management Settings</a><br/>
+ <a href="#section-3.8.9">3.8.9. Lock and Home Screen Widgets</a><br/>
+ <a href="#section-3.8.10">3.8.10. Lock Screen Media Remote Control</a><br/>
+ <a href="#section-3.8.11">3.8.11. Dreams</a><br/>
+ </div>
+ <a href="#section-3.9">3.9 Device Administration</a><br/>
+ <a href="#section-3.10">3.10 Accessibility</a><br/>
+ <a href="#section-3.11">3.11 Text-to-Speech</a><br/>
+ </div>
+ <a href="#section-4">4. Application Packaging Compatibility</a><br/>
+ <a href="#section-5">5. Multimedia Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-5.1">5.1. Media Codecs</a><br/>
+ <a href="#section-5.2">5.2. Video Encoding</a><br/>
+ <a href="#section-5.3">5.3. Video Decoding</a><br/>
+ <a href="#section-5.4">5.4. Audio Recording</a><br/>
+ <a href="#section-5.5">5.5. Audio Latency</a><br/>
+ <a href="#section-5.6">5.6. Network Protocols</a><br/>
+ </div>
+ <a href="#section-6">6. Developer Tools and Options Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-6.1">6.1. Developer Tools</a><br/>
+ <a href="#section-6.2">6.2. Developer Options</a><br/>
+ </div>
+ <a href="#section-7">7. Hardware Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.1">7.1. Display and Graphics</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.1.1">7.1.1. Screen Configuration</a><br/>
+ <a href="#section-7.1.2">7.1.2. Display Metrics</a><br/>
+ <a href="#section-7.1.3">7.1.3. Screen Orientation</a><br/>
+ <a href="#section-7.1.4">7.1.4. 2D and 3D Graphics Accleration</a><br/>
+ <a href="#section-7.1.5">7.1.5. Legacy Application Compatibility Mode</a><br/>
+ <a href="#section-7.1.6">7.1.6. Screen Types</a><br/>
+ <a href="#section-7.1.7">7.1.7. Screen Technology</a><br/>
+ <a href="#section-7.1.8">7.1.8. External Displays</a><br/>
+ </div>
+ <a href="#section-7.2">7.2. Input Devices</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.2.1">7.2.1. Keyboard</a><br/>
+ <a href="#section-7.2.2">7.2.2. Non-touch Navigation</a><br/>
+ <a href="#section-7.2.3">7.2.3. Navigation keys</a><br/>
+ <a href="#section-7.2.4">7.2.4. Touchscreen input</a><br/>
+ </div>
+ <a href="#section-7.3">7.3. Sensors</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.3.1">7.3.1. Accelerometer</a><br/>
+ <a href="#section-7.3.2">7.3.2. Magnetometer</a><br/>
+ <a href="#section-7.3.3">7.3.3. GPS</a><br/>
+ <a href="#section-7.3.4">7.3.4. Gyroscope</a><br/>
+ <a href="#section-7.3.5">7.3.5. Barometer</a><br/>
+ <a href="#section-7.3.6">7.3.6. Thermometer</a><br/>
+ <a href="#section-7.3.7">7.3.7. Photometer</a><br/>
+ <a href="#section-7.3.8">7.3.8. Proximity Sensor</a><br/>
+ </div>
+ <a href="#section-7.4">7.4. Data Connectivity</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.4.1">7.4.1. Telephony</a><br/>
+ <a href="#section-7.4.2">7.4.2. IEEE 802.11 (WiFi)</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.4.2.1">7.4.2.1. WiFi Direct</a><br/>
+ </div>
+ <a href="#section-7.4.3">7.4.3. Bluetooth</a><br/>
+ <a href="#section-7.4.4">7.4.4. Near-Field Communications</a><br/>
+ <a href="#section-7.4.5">7.4.5. Minimum Network Capability</a><br/>
+ </div>
+ <a href="#section-7.5">7.5. Cameras</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.5.1">7.5.1. Rear-Facing Camera</a><br/>
+ <a href="#section-7.5.2">7.5.2. Front-Facing Camera</a><br/>
+ <a href="#section-7.5.3">7.5.3. Camera API Behavior</a><br/>
+ <a href="#section-7.5.4">7.5.4. Camera Orientation</a><br/>
+ </div>
+ <a href="#section-7.6">7.6. Memory and Storage</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.6.1">7.6.1. Minimum Memory and Storage</a><br/>
+ <a href="#section-7.6.2">7.6.2. Application Shared Storage</a><br/>
+ </div>
+ <a href="#section-7.7">7.7. USB</a><br/>
+ </div>
+ <a href="#section-8">8. Performance Compatibility</a><br/>
+ <a href="#section-9">9. Security Model Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-9.1">9.1. Permissions</a><br/>
+ <a href="#section-9.2">9.2. UID and Process Isolation</a><br/>
+ <a href="#section-9.3">9.3. Filesystem Permissions</a><br/>
+ <a href="#section-9.4">9.4. Alternate Execution Environments</a><br/>
+ <a href="#section-9.5">9.5. Multi-User Support</a><br/>
+ <a href="#section-9.6">9.6. Premium SMS Warning</a><br/>
+ </div>
+ <a href="#section-10">10. Software Compatibility Testing</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-10.1">10.1. Compatibility Test Suite</a><br/>
+ <a href="#section-10.2">10.2. CTS Verifier</a><br/>
+ <a href="#section-10.3">10.3. Reference Applications</a><br/>
+ </div>
+ <a href="#section-11">11. Updatable Software</a><br/>
+ <a href="#section-12">12. Contact Us</a><br/>
+ <a href="#appendix-A">Appendix A - Bluetooth Test Procedure</a><br/>
+</div>
+
+<div style="page-break-before: always;"></div>
+
+<a name="section-1"></a><h2>1. Introduction</h2>
+<p>This document enumerates the requirements that must be met in order for
+devices to be compatible with Android 4.2.</p>
+<p>The use of "must", "must not", "required", "shall", "shall not", "should",
+"should not", "recommended", "may" and "optional" is per the IETF standard
+defined in RFC2119 [<a href="#resources01">Resources, 1</a>].</p>
+<p>As used in this document, a "device implementer" or "implementer" is a
+person or organization developing a hardware/software solution running Android
+4.2. A "device implementation" or "implementation" is the hardware/software
+solution so developed.</p>
+<p>To be considered compatible with Android 4.2, device implementations
+MUST meet the requirements presented in this Compatibility Definition,
+including any documents incorporated via reference.</p>
+<p>Where this definition or the software tests described in <a
+href="#section-10">Section 10</a> is silent, ambiguous, or incomplete, it is
+the responsibility of the device implementer to ensure compatibility with
+existing implementations.</p>
+<p>For this reason, the Android Open Source Project [<a
+href="#resources03">Resources, 3</a>] is both the reference and preferred
+implementation of Android. Device implementers are strongly encouraged to base
+their implementations to the greatest extent possible on the "upstream" source
+code available from the Android Open Source Project. While some components can
+hypothetically be replaced with alternate implementations this practice is
+strongly discouraged, as passing the software tests will become substantially
+more difficult. It is the implementer's responsibility to ensure full
+behavioral compatibility with the standard Android implementation, including
+and beyond the Compatibility Test Suite. Finally, note that certain component
+substitutions and modifications are explicitly forbidden by this document.</p>
+<a name="section-2"></a><h2>2. Resources</h2>
+<ol>
+<a name="resources01"></a><li>IETF RFC2119 Requirement Levels: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a></li>
+<a name="resources02"></a><li>Android Compatibility Program Overview: <a href="http://source.android.com/compatibility/index.html">http://source.android.com/compatibility/index.html</a></li>
+<a name="resources03"></a><li>Android Open Source Project: <a href="http://source.android.com/">http://source.android.com/</a></li>
+<a name="resources04"></a><li>API definitions and documentation: <a href="http://developer.android.com/reference/packages.html">http://developer.android.com/reference/packages.html</a></li>
+<a name="resources05"></a><li>Android Permissions reference: <a href="http://developer.android.com/reference/android/Manifest.permission.html">http://developer.android.com/reference/android/Manifest.permission.html</a></li>
+<a name="resources06"></a><li>android.os.Build reference: <a href="http://developer.android.com/reference/android/os/Build.html">http://developer.android.com/reference/android/os/Build.html</a></li>
+<a name="resources07"></a><li>Android 4.2 allowed version strings: <a href="http://source.android.com/compatibility/4.2/versions.html">http://source.android.com/compatibility/4.2/versions.html</a></li>
+<a name="resources08"></a><li>Renderscript: <a href="http://developer.android.com/guide/topics/graphics/renderscript.html">http://developer.android.com/guide/topics/graphics/renderscript.html</a></li>
+<a name="resources09"></a><li>Hardware Acceleration: <a href="http://developer.android.com/guide/topics/graphics/hardware-accel.html">http://developer.android.com/guide/topics/graphics/hardware-accel.html</a></li>
+<a name="resources10"></a><li>android.webkit.WebView class: <a href="http://developer.android.com/reference/android/webkit/WebView.html">http://developer.android.com/reference/android/webkit/WebView.html</a></li>
+<a name="resources11"></a><li>HTML5: <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">http://www.whatwg.org/specs/web-apps/current-work/multipage/</a></li>
+<a name="resources12"></a><li>HTML5 offline capabilities: <a href="http://dev.w3.org/html5/spec/Overview.html#offline">http://dev.w3.org/html5/spec/Overview.html#offline</a></li>
+<a name="resources13"></a><li>HTML5 video tag: <a href="http://dev.w3.org/html5/spec/Overview.html#video">http://dev.w3.org/html5/spec/Overview.html#video</a></li>
+<a name="resources14"></a><li>HTML5/W3C geolocation API: <a href="http://www.w3.org/TR/geolocation-API/">http://www.w3.org/TR/geolocation-API/</a></li>
+<a name="resources15"></a><li>HTML5/W3C webdatabase API: <a href="http://www.w3.org/TR/webdatabase/">http://www.w3.org/TR/webdatabase/</a></li>
+<a name="resources16"></a><li>HTML5/W3C IndexedDB API: <a href="http://www.w3.org/TR/IndexedDB/">http://www.w3.org/TR/IndexedDB/</a></li>
+<a name="resources17"></a><li>Dalvik Virtual Machine specification: available in the Android source code, at dalvik/docs</li>
+<a name="resources18"></a><li>AppWidgets: <a href="http://developer.android.com/guide/practices/ui_guidelines/widget_design.html">http://developer.android.com/guide/practices/ui_guidelines/widget_design.html</a></li>
+<a name="resources19"></a><li>Notifications: <a href="http://developer.android.com/guide/topics/ui/notifiers/notifications.html">http://developer.android.com/guide/topics/ui/notifiers/notifications.html</a></li>
+<a name="resources20"></a><li>Application Resources: <a href="http://code.google.com/android/reference/available-resources.html">http://code.google.com/android/reference/available-resources.html</a></li>
+<a name="resources21"></a><li>Status Bar icon style guide: <a href="http://developer.android.com/guide/practices/ui_guidelines/icon_design_status_bar.html">http://developer.android.com/guide/practices/ui_guidelines/icon_design_status_bar.html</a></li>
+<a name="resources22"></a><li>Search Manager: <a href="http://developer.android.com/reference/android/app/SearchManager.html">http://developer.android.com/reference/android/app/SearchManager.html</a></li>
+<a name="resources23"></a><li>Toasts: <a href="http://developer.android.com/reference/android/widget/Toast.html">http://developer.android.com/reference/android/widget/Toast.html</a></li>
+<a name="resources24"></a><li>Themes: <a href="http://developer.android.com/guide/topics/ui/themes.html">http://developer.android.com/guide/topics/ui/themes.html</a></li>
+<a name="resources25"></a><li>R.style class: <a href="http://developer.android.com/reference/android/R.style.html">http://developer.android.com/reference/android/R.style.html</a></li>
+<a name="resources26"></a><li>Live Wallpapers: <a href="http://developer.android.com/resources/articles/live-wallpapers.html">http://developer.android.com/resources/articles/live-wallpapers.html</a></li>
+<a name="resources27"></a><li>Android Device Administration: <a href="http://developer.android.com/guide/topics/admin/device-admin.html">http://developer.android.com/guide/topics/admin/device-admin.html</a></li>
+<a name="resources28"></a><li>DevicePolicyManager reference: <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html">http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html</a></li>
+<a name="resources29"></a><li>Android Accessibility Service APIs: <a href="http://developer.android.com/reference/android/accessibilityservice/package-summary.html">http://developer.android.com/reference/android/accessibilityservice/package-summary.html</a></li>
+<a name="resources30"></a><li>Android Accessibility APIs: <a href="http://developer.android.com/reference/android/view/accessibility/package-summary.html">http://developer.android.com/reference/android/view/accessibility/package-summary.html</a></li>
+<a name="resources31"></a><li>Eyes Free project: <a href="http://http://code.google.com/p/eyes-free">http://code.google.com/p/eyes-free</a></li>
+<a name="resources32"></a><li>Text-To-Speech APIs: <a href="http://developer.android.com/reference/android/speech/tts/package-summary.html">http://developer.android.com/reference/android/speech/tts/package-summary.html</a></li>
+<a name="resources33"></a><li>Reference tool documentation (for adb, aapt, ddms, systrace): <a href="http://developer.android.com/guide/developing/tools/index.html">http://developer.android.com/guide/developing/tools/index.html</a></li>
+<a name="resources34"></a><li>Android apk file description: <a href="http://developer.android.com/guide/topics/fundamentals.html">http://developer.android.com/guide/topics/fundamentals.html</a></li>
+<a name="resources35"></a><li>Manifest files: <a href="http://developer.android.com/guide/topics/manifest/manifest-intro.html">http://developer.android.com/guide/topics/manifest/manifest-intro.html</a></li>
+<a name="resources36"></a><li>Monkey testing tool: <a href="http://developer.android.com/guide/developing/tools/monkey.html">http://developer.android.com/guide/developing/tools/monkey.html</a></li>
+<a name="resources37"></a><li>Android android.content.pm.PackageManager class and Hardware Features List: <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html">http://developer.android.com/reference/android/content/pm/PackageManager.html</a></li>
+<a name="resources38"></a><li>Supporting Multiple Screens: <a href="http://developer.android.com/guide/practices/screens_support.html">http://developer.android.com/guide/practices/screens_support.html</a></li>
+<a name="resources39"></a><li>android.util.DisplayMetrics: <a href="http://developer.android.com/reference/android/util/DisplayMetrics.html">http://developer.android.com/reference/android/util/DisplayMetrics.html</a></li>
+<a name="resources40"></a><li>android.content.res.Configuration: <a href="http://developer.android.com/reference/android/content/res/Configuration.html">http://developer.android.com/reference/android/content/res/Configuration.html</a></li>
+<a name="resources41"></a><li>android.hardware.SensorEvent: <a href="http://developer.android.com/reference/android/hardware/SensorEvent.html">http://developer.android.com/reference/android/hardware/SensorEvent.html</a></li>
+<a name="resources42"></a><li>Bluetooth API: <a href="http://developer.android.com/reference/android/bluetooth/package-summary.html">http://developer.android.com/reference/android/bluetooth/package-summary.html</a></li>
+<a name="resources43"></a><li>NDEF Push Protocol: <a href="http://source.android.com/compatibility/ndef-push-protocol.pdf">http://source.android.com/compatibility/ndef-push-protocol.pdf</a></li>
+<a name="resources44"></a><li>MIFARE MF1S503X: <a href="http://www.nxp.com/documents/data_sheet/MF1S503x.pdf">http://www.nxp.com/documents/data_sheet/MF1S503x.pdf</a></li>
+<a name="resources45"></a><li>MIFARE MF1S703X: <a href="http://www.nxp.com/documents/data_sheet/MF1S703x.pdf">http://www.nxp.com/documents/data_sheet/MF1S703x.pdf</a></li>
+<a name="resources46"></a><li>MIFARE MF0ICU1: <a href="http://www.nxp.com/documents/data_sheet/MF0ICU1.pdf">http://www.nxp.com/documents/data_sheet/MF0ICU1.pdf</a></li>
+<a name="resources47"></a><li>MIFARE MF0ICU2: <a href="http://www.nxp.com/documents/short_data_sheet/MF0ICU2_SDS.pdf">http://www.nxp.com/documents/short_data_sheet/MF0ICU2_SDS.pdf</a></li>
+<a name="resources48"></a><li>MIFARE AN130511: <a href="http://www.nxp.com/documents/application_note/AN130511.pdf">http://www.nxp.com/documents/application_note/AN130511.pdf</a></li>
+<a name="resources49"></a><li>MIFARE AN130411: <a href="http://www.nxp.com/documents/application_note/AN130411.pdf">http://www.nxp.com/documents/application_note/AN130411.pdf</a></li>
+<a name="resources50"></a><li>Camera orientation API: <a href="http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)">http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)</a></li>
+<a name="resources51"></a><li>Camera: <a href="http://developer.android.com/reference/android/hardware/Camera.html">http://developer.android.com/reference/android/hardware/Camera.html</a></li>
+<a name="resources52"></a><li>Android Open Accessories: <a href="http://developer.android.com/guide/topics/usb/accessory.html">http://developer.android.com/guide/topics/usb/accessory.html</a></li>
+<a name="resources53"></a><li>USB Host API: <a href="http://developer.android.com/guide/topics/usb/host.html">http://developer.android.com/guide/topics/usb/host.html</a></li>
+<a name="resources54"></a><li>Android Security and Permissions reference: <a href="http://developer.android.com/guide/topics/security/security.html">http://developer.android.com/guide/topics/security/security.html</a></li>
+<a name="resources55"></a><li>Apps for Android: <a href="http://code.google.com/p/apps-for-android">http://code.google.com/p/apps-for-android</a></li>
+<a name="resources56"></a><li>Android DownloadManager: <a href="http://developer.android.com/reference/android/app/DownloadManager.html">http://developer.android.com/reference/android/app/DownloadManager.html</a></li>
+<a name="resources57"></a><li>Android File Transfer: <a href="http://www.android.com/filetransfer">http://www.android.com/filetransfer</a></li>
+<a name="resources58"></a><li>Android Media Formats: <a href="http://developer.android.com/guide/appendix/media-formats.html">http://developer.android.com/guide/appendix/media-formats.html</a></li>
+<a name="resources59"></a><li>HTTP Live Streaming Draft Protocol: <a href="http://tools.ietf.org/html/draft-pantos-http-live-streaming-03">http://tools.ietf.org/html/draft-pantos-http-live-streaming-03</a></li>
+<a name="resources60"></a><li>NFC Connection Handover: <a href="http://www.nfc-forum.org/specs/spec_list/#conn_handover/">http://www.nfc-forum.org/specs/spec_list/#conn_handover</a></li>
+<a name="resources61"></a><li>Bluetooth Secure Simple Pairing Using NFC: <a href="http://www.nfc-forum.org/resources/AppDocs/NFCForum_AD_BTSSP_1_0.pdf">http://www.nfc-forum.org/resources/AppDocs/NFCForum_AD_BTSSP_1_0.pdf</a></li>
+<a name="resources62"></a><li>Wifi Multicast API: <a href="http://developer.android.com/reference/android/net/wifi/WifiManager.MulticastLock.html">http://developer.android.com/reference/android/net/wifi/WifiManager.MulticastLock.html</a></li>
+<a name="resources63"></a><li>Action Assist: <a href="http://developer.android.com/reference/android/content/Intent.html#ACTION_ASSIST">http://developer.android.com/reference/android/content/Intent.html#ACTION_ASSIST</a></li>
+<a name="resources64"></a><li>USB Charging Specification: <a href="http://www.usb.org/developers/devclass_docs/USB_Battery_Charging_1.2.pdf">http://www.usb.org/developers/devclass_docs/USB_Battery_Charging_1.2.pdf</a></li>
+<a name="resources65"></a><li>Android Beam: <a href="http://developer.android.com/guide/topics/nfc/nfc.html">http://developer.android.com/guide/topics/nfc/nfc.html</a></li>
+<a name="resources66"></a><li>Android USB Audio: <a href="http://developer.android.com/reference/android/hardware/usb/UsbConstants.html#USB_CLASS_AUDIO">http://developer.android.com/reference/android/hardware/usb/UsbConstants.html#USB_CLASS_AUDIO</a></li>
+<a name="resources67"></a><li>Android NFC Sharing Settings: <a href="http://developer.android.com/reference/android/provider/Settings.html#ACTION_NFCSHARING_SETTINGS">http://developer.android.com/reference/android/provider/Settings.html#ACTION_NFCSHARING_SETTINGS</a></li>
+<a name="resources68"></a><li>Wifi Direct (Wifi P2P): <a href="http://developer.android.com/reference/android/net/wifi/p2p/WifiP2pManager.html">http://developer.android.com/reference/android/net/wifi/p2p/WifiP2pManager.html</a></li>
+<a name="resources69"></a><li>Lock and Home Screen Widget: <a href="http://developer.android.com/reference/android/appwidget/AppWidgetProviderInfo.html">http://developer.android.com/reference/android/appwidget/AppWidgetProviderInfo.html</a></li>
+<a name="resources70"></a><li>UserManager reference: <a href="http://developer.android.com/reference/android/os/UserManager.html">http://developer.android.com/reference/android/os/UserManager.html</a></li>
+<a name="resources71"></a><li>External Storage reference: <a href="http://source.android.com/tech/storage">http://source.android.com/tech/storage</a></li>
+<a name="resources72"></a><li>External Storage APIs: <a href="http://developer.android.com/reference/android/os/Environment.html">http://developer.android.com/reference/android/os/Environment.html</a></li>
+<a name="resources73"></a><li>SMS Short Code: <a href="http://en.wikipedia.org/wiki/Short_code">http://en.wikipedia.org/wiki/Short_code</a></li>
+<a name="resources74"></a><li>Media Remote Control Client: <a href="http://developer.android.com/reference/android/media/RemoteControlClient.html">http://developer.android.com/reference/android/media/RemoteControlClient.html</a></li>
+<a name="resources75"></a><li>Display Manager: <a href="http://developer.android.com/reference/android/hardware/display/DisplayManager.html">http://developer.android.com/reference/android/hardware/display/DisplayManager.html</a></li>
+<a name="resources76"></a><li>Dreams: <a href="http://developer.android.com/reference/android/service/dreams/DreamService.html">http://developer.android.com/reference/android/service/dreams/DreamService.html</a></li>
+<a name="resources77"></a><li>Android Application Development-Related Settings: <a href="http://developer.android.com/reference/android/provider/Settings.html#ACTION_APPLICATION_DEVELOPMENT_SETTINGS">http://developer.android.com/reference/android/provider/Settings.html#ACTION_APPLICATION_DEVELOPMENT_SETTINGS</a></li>
+</ol>
+<a name="resources78"></a><li>Camera: <a href="http://developer.android.com/reference/android/hardware/Camera.Parameters.html">http://developer.android.com/reference/android/hardware/Camera.Parameters.html</a></li>
+<p>Many of these resources are derived directly or indirectly from the Android
+4.2 SDK, and will be functionally identical to the information in that SDK's
+documentation. In any cases where this Compatibility Definition or the
+Compatibility Test Suite disagrees with the SDK documentation, the SDK
+documentation is considered authoritative. Any technical details provided in
+the references included above are considered by inclusion to be part of this
+Compatibility Definition.</p>
+
+<a name="section-3"></a><h2>3. Software</h2>
+<a name="section-3.1"></a><h3>3.1. Managed API Compatibility</h3>
+<p>The managed (Dalvik-based) execution environment is the primary vehicle for
+Android applications. The Android application programming interface (API) is
+the set of Android platform interfaces exposed to applications running in the
+managed VM environment. Device implementations MUST provide complete
+implementations, including all documented behaviors, of any documented API
+exposed by the Android 4.2 SDK [<a href="#resources04">Resources, 4</a>].</p>
+<p>Device implementations MUST NOT omit any managed APIs, alter API interfaces
+or signatures, deviate from the documented behavior, or include no-ops, except
+where specifically allowed by this Compatibility Definition.</p>
+<p>This Compatibility Definition permits some types of hardware for which
+Android includes APIs to be omitted by device implementations. In such cases,
+the APIs MUST still be present and behave in a reasonable way. See
+<a href="#section-7">Section 7</a> for specific requirements for this scenario.
+</p>
+
+<a name="section-3.2"></a><h3>3.2. Soft API Compatibility</h3>
+<p>In addition to the managed APIs from Section 3.1, Android also includes a
+significant runtime-only "soft" API, in the form of such things such as
+Intents, permissions, and similar aspects of Android applications that cannot
+be enforced at application compile time.</p>
+<a name="section-3.2.1"></a><h4>3.2.1. Permissions</h4>
+<p>Device implementers MUST support and enforce all permission constants as
+documented by the Permission reference page [<a
+href="#resources05">Resources, 5</a>]. Note that Section 10 lists additional
+requirements related to the Android security model.</p>
+<a name="section-3.2.2"></a><h4>3.2.2. Build Parameters</h4>
+<p>The Android APIs include a number of constants on the <code>android.os.Build</code>
+class [<a href="#resources06">Resources, 6</a>] that are intended to describe
+the current device. To provide consistent, meaningful values across device
+implementations, the table below includes additional restrictions on the
+formats of these values to which device implementations MUST conform.</p>
+<table>
+<tbody>
+<tr>
+<td><b>Parameter</b></td>
+<td><b>Comments</b></td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.RELEASE</td>
+<td>The version of the currently-executing Android system, in human-readable
+format. This field MUST have one of the string values defined in [<a
+href="#resources07">Resources, 7</a>].</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.SDK</td>
+<td>The version of the currently-executing Android system, in a format
+accessible to third-party application code. For Android 4.2, this
+field MUST have the integer value 17.</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.SDK_INT</td>
+<td>The version of the currently-executing Android system, in a format
+accessible to third-party application code. For Android 4.2, this
+field MUST have the integer value 17.</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.INCREMENTAL</td>
+<td>A value chosen by the device implementer designating the specific build of
+the currently-executing Android system, in human-readable format. This value
+MUST NOT be re-used for different builds made available to end users. A typical use
+of this field is to indicate which build number or source-control change
+identifier was used to generate the build. There are no requirements on the
+specific format of this field, except that it MUST NOT be null or the empty
+string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.BOARD</td>
+<td>A value chosen by the device implementer identifying the specific internal
+hardware used by the device, in human-readable format. A possible use of this
+field is to indicate the specific revision of the board powering the device.
+The value of this field MUST be encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.BRAND</td>
+<td>A value chosen by the device implementer identifying the name of the
+company, organization, individual, etc. who produced the device, in
+human-readable format. A possible use of this field is to indicate the OEM
+and/or carrier who sold the device. The value of this field MUST be
+encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.CPU_ABI</td>
+<td>The name of the instruction set (CPU type + ABI convention) of native code.
+See <a href="#section-3.3">Section 3.3: Native API Compatibility</a>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.CPU_ABI2</td>
+<td>The name of the second instruction set (CPU type + ABI convention) of native code.
+See <a href="#section-3.3">Section 3.3: Native API Compatibility</a>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.DEVICE</td>
+<td>A value chosen by the device implementer identifying the specific
+configuration or revision of the body (sometimes called "industrial design")
+of the device. The value of this field MUST be encodable as 7-bit ASCII and
+match the regular expression <code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.FINGERPRINT</td>
+<td>A string that uniquely identifies this build. It SHOULD be reasonably
+human-readable. It MUST follow this template:
+<br/><code>$(BRAND)/$(PRODUCT)/$(DEVICE):$(VERSION.RELEASE)/$(ID)/$(VERSION.INCREMENTAL):$(TYPE)/$(TAGS)</code><br/>
+For example:
+<br/><code>acme/mydevice/generic:4.2/JRN53/3359:userdebug/test-keys</code><br/>
+The fingerprint MUST NOT include whitespace characters. If other fields included in the
+template above have whitespace characters, they MUST be replaced in the build
+fingerprint with another character, such as the underscore ("_") character.
+The value of this field MUST be encodable as 7-bit ASCII.</td>
+</tr>
+<tr>
+<td>android.os.Build.HARDWARE</td>
+<td>The name of the hardware (from the kernel command line or /proc). It SHOULD be
+reasonably human-readable. The value of this field MUST be encodable as 7-bit ASCII and
+match the regular expression <code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.HOST</td>
+<td>A string that uniquely identifies the host the build was built on, in
+human readable format. There are no requirements on the specific format of
+this field, except that it MUST NOT be null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.ID</td>
+<td>An identifier chosen by the device implementer to refer to a specific
+release, in human readable format. This field can be the same as
+android.os.Build.VERSION.INCREMENTAL, but SHOULD be a value sufficiently
+meaningful for end users to distinguish between software builds. The value of
+this field MUST be encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.MANUFACTURER</td>
+<td>The trade name of the Original Equipment Manufacturer (OEM) of the product.
+There are no requirements on the specific format of this field, except that it
+MUST NOT be null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.MODEL</td>
+<td>A value chosen by the device implementer containing the name of the device
+as known to the end user. This SHOULD be the same name under which the device
+is marketed and sold to end users. There are no requirements on the specific
+format of this field, except that it MUST NOT be null or the empty string
+("").</td>
+</tr>
+<tr>
+<td>android.os.Build.PRODUCT</td>
+<td>A value chosen by the device implementer containing the development name
+or code name of the product (SKU). MUST be human-readable, but is not necessarily
+intended for view by end users. The value of this field MUST be encodable as 7-bit
+ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.SERIAL</td>
+<td>A hardware serial number, if available. The value of this field MUST be encodable
+as 7-bit ASCII and match the regular expression
+<code>"^([a-zA-Z0-9]{0,20})$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.TAGS</td>
+<td>A comma-separated list of tags chosen by the device implementer that
+further distinguish the build. For example, "unsigned,debug". The value of
+this field MUST be encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.TIME</td>
+<td>A value representing the timestamp of when the build occurred.</td>
+</tr>
+<tr>
+<td>android.os.Build.TYPE</td>
+<td>A value chosen by the device implementer specifying the runtime
+configuration of the build. This field SHOULD have one of the values
+corresponding to the three typical Android runtime configurations: "user",
+"userdebug", or "eng". The value of this field MUST be
+encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.USER</td>
+<td>A name or user ID of the user (or automated user) that generated the
+build. There are no requirements on the specific format of this field, except
+that it MUST NOT be null or the empty string ("").</td>
+</tr>
+</tbody>
+</table>
+<a name="section-3.2.3"></a><h4>3.2.3. Intent Compatibility</h4>
+<p>
+Device implementations MUST honor Android's loose-coupling Intent system, as
+described in the sections below. By "honored", it is meant that the device
+implementer MUST provide an Android Activity or Service that specifies a
+matching Intent filter and binds to and implements correct behavior for each
+specified Intent pattern.</p>
+<a name="section-3.2.3.1"></a><h4>3.2.3.1. Core Application Intents</h4>
+<p>The Android upstream project defines a number of core applications, such as
+contacts, calendar, photo gallery, music player, and so on. Device implementers
+MAY replace these applications with alternative versions.</p>
+<p>However, any such alternative versions MUST honor the same Intent patterns
+provided by the upstream project. For example, if a device contains an
+alternative music player, it must still honor the Intent pattern issued by
+third-party applications to pick a song.</p>
+<p>The following applications are considered core Android system
+applications:</p>
+<ul>
+<li>Desk Clock</li>
+<li>Browser</li>
+<li>Calendar</li>
+<li>Contacts</li>
+<!--<li>Email</li>-->
+<li>Gallery</li>
+<li>GlobalSearch</li>
+<li>Launcher</li>
+<!-- <li>LivePicker (that is, the Live Wallpaper picker application; MAY be omitted
+if the device does not support Live Wallpapers, per Section 3.8.5.)</li> -->
+<!-- <li>Messaging (AKA "Mms")</li> -->
+<li>Music</li>
+<!-- <li>Phone</li> -->
+<li>Settings</li>
+<!-- <li>SoundRecorder</li> -->
+</ul>
+<p>The core Android system applications include various Activity, or Service
+components that are considered "public". That is, the attribute
+"android:exported" may be absent, or may have the value "true".</p>
+<p>For every Activity or Service defined
+in one of the core Android system apps that is not marked as non-public via an
+android:exported attribute with the value "false", device implementations MUST
+include a compontent of the same type implementing the same Intent filter
+patterns as the core Android system app.</p>
+<p>In other words, a device implementation MAY replace core Android system
+apps; however, if it does, the device implementation MUST support all Intent
+patterns defined by each core Android system app being replaced.</p>
+<a name="section-3.2.3.2"></a><h4>3.2.3.2. Intent Overrides</h4>
+<p>As Android is an extensible platform, device implementations MUST allow each
+Intent pattern referenced in Section 3.2.3.2 to be overridden by third-party
+applications. The upstream Android open source implementation allows this by
+default; device implementers MUST NOT attach special privileges to system
+applications' use of these Intent patterns, or prevent third-party
+applications from binding to and assuming control of these patterns. This
+prohibition specifically includes but is not limited to disabling the
+"Chooser" user interface which allows the user to select between multiple
+applications which all handle the same Intent pattern.</p>
+<p>However, device implementations MAY provide default activities for specific
+URI patterns (eg. http://play.google.com) if the default activity provides a
+more specific filter for the data URI. For example, an intent filter specifying
+the data URI "http://www.android.com" is more specific than the browser filter
+for "http://". Device implementations MUST provide a user interface for users
+to modify the default activity for intents.</p>
+
+<a name="section-3.2.3.3"></a><h4>3.2.3.3. Intent Namespaces</h4>
+<p>Device implementations MUST NOT include any Android component that honors any
+new Intent or Broadcast Intent patterns using an ACTION, CATEGORY, or other
+key string in the android.* or com.android.* namespace. Device implementers
+MUST NOT include any Android components that honor any new Intent or Broadcast
+Intent patterns using an ACTION, CATEGORY, or other key string in a package
+space belonging to another organization. Device implementers MUST NOT alter or
+extend any of the Intent patterns used by the core apps listed in Section
+3.2.3.1. Device implementations MAY include Intent patterns using
+namespaces clearly and obviously associated with their own organization.</p>
+<p>This prohibition is analogous to that specified for Java language classes
+in Section 3.6.</p>
+<a name="section-3.2.3.4"></a><h4>3.2.3.4. Broadcast Intents</h4>
+<p>Third-party applications rely on the platform to broadcast certain Intents
+to notify them of changes in the hardware or software environment.
+Android-compatible devices MUST broadcast the public broadcast Intents in
+response to appropriate system events. Broadcast Intents are described in the
+SDK documentation.</p>
+
+<a name="section-3.3"></a><h3>3.3. Native API Compatibility</h3>
+<a name="section-3.3.1"></a><h4>3.3.1 Application Binary Interfaces</h4>
+<p>Managed code running in Dalvik can call into native code provided in the
+application .apk file as an ELF .so file compiled for the appropriate device
+hardware architecture. As native code is highly dependent on the underlying
+processor technology, Android defines a number of Application Binary
+Interfaces (ABIs) in the Android NDK, in the file
+<code>docs/CPU-ARCH-ABIS.html</code>. If a device implementation is compatible
+with one or more defined ABIs, it SHOULD implement compatibility with the
+Android NDK, as below.</p>
+<p>If a device implementation includes support for an Android ABI, it:</p>
+<ul>
+<li>MUST include support for code running in the managed environment to call
+into native code, using the standard Java Native Interface (JNI)
+semantics.</li>
+<li>MUST be source-compatible (i.e. header compatible) and binary-compatible
+(for the ABI) with each required library in the list below</li>
+<li>MUST accurately report the native Application Binary Interface (ABI)
+supported by the device, via the <code>android.os.Build.CPU_ABI</code>
+API</li>
+<li>MUST report only those ABIs documented in the latest version of the
+Android NDK, in the file <code>docs/CPU-ARCH-ABIS.txt</code></li>
+<li>SHOULD be built using the source code and header files available in the
+upstream Android open source project</li>
+</ul>
+<p>The following native code APIs MUST be available to apps that include
+native code:</p>
+<ul>
+<li>libc (C library)</li>
+<li>libm (math library)</li>
+<li>Minimal support for C++</li>
+<li>JNI interface</li>
+<li>liblog (Android logging)</li>
+<li>libz (Zlib compression)</li>
+<li>libdl (dynamic linker)</li>
+<li>libGLESv1_CM.so (OpenGL ES 1.0)</li>
+<li>libGLESv2.so (OpenGL ES 2.0)</li>
+<li>libEGL.so (native OpenGL surface management)</li>
+<li>libjnigraphics.so</li>
+<li>libOpenSLES.so (OpenSL ES 1.0.1 audio support)</li>
+<li>libOpenMAXAL.so (OpenMAX AL 1.0.1 support)</li>
+<li>libandroid.so (native Android activity support)</li>
+<li>Support for OpenGL, as described below</li>
+</ul>
+<p>Note that future releases of the Android NDK may introduce support for
+additional ABIs. If a device implementation is not compatible with an existing
+predefined ABI, it MUST NOT report support for any ABI at all.</p>
+<p>Native code compatibility is challenging. For this reason, it should be
+repeated that device implementers are VERY strongly encouraged to use the
+upstream implementations of the libraries listed above to help ensure
+compatibility.</p>
+
+<a name="section-3.4"></a><h3>3.4. Web Compatibility</h3>
+<a name="section-3.4.1"></a><h4>3.4.1. WebView Compatibility</h4>
+<p>The Android Open Source implementation uses the WebKit rendering engine to
+implement the <code>android.webkit.WebView</code>. Because it is not feasible
+to develop a comprehensive test suite for a web rendering system, device
+implementers MUST use the specific upstream build of WebKit in the WebView
+implementation. Specifically:</p>
+<ul>
+<li>Device implementations' <code>android.webkit.WebView</code>
+implementations MUST be based on the 534.30 WebKit build from the upstream
+Android Open Source tree for Android 4.2. This build includes a specific set
+of functionality and security fixes for the WebView. Device implementers MAY
+include customizations to the WebKit implementation; however, any such
+customizations MUST NOT alter the behavior of the WebView, including rendering
+behavior.</li>
+<li>The user agent string reported by the WebView MUST be in this format:<br/>
+ <code>Mozilla/5.0 (Linux; U; Android $(VERSION); $(LOCALE); $(MODEL) Build/$(BUILD)) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.2 Mobile Safari/534.30</code>
+ <ul>
+ <li>The value of the $(VERSION) string MUST be the same as the value for <code>android.os.Build.VERSION.RELEASE</code></li>
+ <li>The value of the $(LOCALE) string SHOULD follow the ISO conventions for country code and language, and SHOULD refer to the current configured locale of the device</li>
+ <li>The value of the $(MODEL) string MUST be the same as the value for <code>android.os.Build.MODEL</code></li>
+ <li>The value of the $(BUILD) string MUST be the same as the value for <code>android.os.Build.ID</code></li>
+ <li>Device implementations MAY omit <code>Mobile</code> in the user agent string</li>
+ </ul>
+</li>
+</ul>
+<p>The WebView component SHOULD include support for as much of HTML5 [<a
+href="#resources11">Resources, 11</a>] as possible.
+Minimally, device implementations MUST support each of these APIs associated
+with HTML5 in the WebView:</p>
+<ul>
+<li>application cache/offline operation [<a href="#resources12">Resources, 12</a>]</li>
+<li>the <video> tag [<a href="#resources13">Resources, 13</a>]</li>
+<li>geolocation [<a href="#resources14">Resources, 14</a>]</li>
+</ul>
+<p>Additionally, device implementations MUST support the HTML5/W3C webstorage
+API [<a href="#resources15">Resources, 15</a>], and SHOULD support the
+HTML5/W3C IndexedDB API [<a href="#resources16">Resources, 16</a>]. <i>Note
+that as the web development standards bodies are transitioning to favor
+IndexedDB over webstorage, IndexedDB is expected to become a required
+component in a future version of Android.</i></p>
+<p>HTML5 APIs, like all JavaScript APIs, MUST be disabled by default in a
+WebView, unless the developer explicitly enables them via the usual Android
+APIs.</p>
+
+<a name="section-3.4.2"></a><h4>3.4.2. Browser Compatibility</h4>
+<p>Device implementations MUST include a standalone Browser application for
+general user web browsing. The standalone Browser MAY be based on a
+browser technology other than WebKit. However, even if an alternate Browser
+application is used, the <code>android.webkit.WebView</code> component
+provided to third-party applications MUST be based on WebKit, as described in
+Section 3.4.1.</p>
+<p>Implementations MAY ship a custom user agent string in the standalone
+Browser application.</p>
+<p>The standalone Browser application (whether based on the upstream
+WebKit Browser application or a third-party replacement) SHOULD include support
+for as much of HTML5 [<a href="#resources11">Resources, 11</a>] as possible.
+Minimally, device implementations MUST support each of these APIs associated
+with HTML5:</p>
+<ul>
+<li>application cache/offline operation [<a href="#resources12">Resources, 12</a>]</li>
+<li>the <video> tag [<a href="#resources13">Resources, 13</a>]</li>
+<li>geolocation [<a href="#resources14">Resources, 14</a>]</li>
+</ul>
+<p>Additionally, device implementations MUST support the HTML5/W3C webstorage
+API [<a href="#resources15">Resources, 15</a>], and SHOULD support the
+HTML5/W3C IndexedDB API [<a href="#resources16">Resources, 16</a>]. <i>Note
+that as the web development standards bodies are transitioning to favor
+IndexedDB over webstorage, IndexedDB is expected to become a required
+component in a future version of Android.</i></p>
+
+<a name="section-3.5"></a><h3>3.5. API Behavioral Compatibility</h3>
+<p>The behaviors of each of the API types (managed, soft, native, and web)
+must be consistent with the preferred implementation of the upstream Android
+open source project [<a href="#resources03">Resources, 3</a>]. Some specific areas
+of compatibility are:</p>
+<ul>
+<li>Devices MUST NOT change the behavior or semantics of a standard Intent</li>
+<li>Devices MUST NOT alter the lifecycle or lifecycle semantics of a
+ particular type of system component (such as Service, Activity,
+ ContentProvider, etc.)</li>
+<li>Devices MUST NOT change the semantics of a standard permission</li>
+</ul>
+<p>The above list is not comprehensive. The Compatibility Test Suite (CTS)
+tests significant portions of the platform for behavioral compatibility, but
+not all. It is the responsibility of the implementer to ensure behavioral
+compatibility with the Android Open Source Project. For this reason, device
+implementers SHOULD use the source code available via the Android Open Source
+Project where possible, rather than re-implement significant parts of the
+system.</p>
+
+
+<a name="section-3.6"></a><h3>3.6. API Namespaces</h3>
+<p>Android follows the package and class namespace conventions defined by the
+Java programming language. To ensure compatibility with third-party
+applications, device implementers MUST NOT make any prohibited modifications
+(see below) to these package namespaces:</p>
+<ul>
+<li>java.*</li>
+<li>javax.*</li>
+<li>sun.*</li>
+<li>android.*</li>
+<li>com.android.*</li>
+</ul>
+<p>Prohibited modifications include:</p>
+<ul>
+<li>Device implementations MUST NOT modify the publicly exposed APIs on the
+Android platform by changing any method or class signatures, or by removing
+classes or class fields.</li>
+<li>Device implementers MAY modify the underlying implementation of the APIs,
+but such modifications MUST NOT impact the stated behavior and Java-language
+signature of any publicly exposed APIs.</li>
+<li>Device implementers MUST NOT add any publicly exposed elements (such as
+classes or interfaces, or fields or methods to existing classes or interfaces)
+to the APIs above.</li>
+</ul>
+<p>A "publicly exposed element" is any construct which is not decorated with
+the "@hide" marker as used in the upstream Android source code. In other
+words, device implementers MUST NOT expose new APIs or alter existing APIs in
+the namespaces noted above. Device implementers MAY make internal-only
+modifications, but those modifications MUST NOT be advertised or otherwise
+exposed to developers.</p>
+<p>Device implementers MAY add custom APIs, but any such APIs MUST NOT be in a
+namespace owned by or referring to another organization. For instance, device
+implementers MUST NOT add APIs to the com.google.* or similar namespace; only
+Google may do so. Similarly, Google MUST NOT add APIs to other companies'
+namespaces. Additionally, if a device implementation includes custom APIs
+outside the standard Android namespace, those APIs MUST be packaged in an
+Android shared library so that only apps that explicitly use them (via the
+<code><uses-library></code> mechanism) are affected by the increased
+memory usage of such APIs.</p>
+<p>If a device implementer proposes to improve one of the package namespaces
+above (such as by adding useful new functionality to an existing API, or
+adding a new API), the implementer SHOULD visit source.android.com and begin
+the process for contributing changes and code, according to the information on
+that site.</p>
+<p>Note that the restrictions above correspond to standard conventions for
+naming APIs in the Java programming language; this section simply aims to
+reinforce those conventions and make them binding through inclusion in this
+compatibility definition.</p>
+
+<a name="section-3.7"></a><h3>3.7. Virtual Machine Compatibility</h3>
+<p>Device implementations MUST support the full Dalvik Executable (DEX)
+bytecode specification and Dalvik Virtual Machine semantics [<a
+href="#resources17">Resources, 17</a>].</p>
+<p>Device implementations MUST configure Dalvik to allocate memory in
+accordance with the upstream Android platform, and as specified by the following
+table. (See <a href="#section-7.1.1">Section 7.1.1</a> for screen size and screen
+density definitions.)</p>
+
+<p>Note that memory values specified below are considered minimum values,
+and device implementations MAY allocate more memory per application.</p>
+<table>
+<tbody>
+<tr>
+<td><b>Screen Size</b></td>
+<td><b>Screen Density</b></td>
+<td><b>Application Memory</b></td>
+</tr>
+<tr>
+<td>small / normal / large</td>
+<td>ldpi / mdpi</td>
+<td>16MB</td>
+</tr>
+<tr>
+<td>small / normal / large</td>
+<td>tvdpi / hdpi</td>
+<td>32MB</td>
+</tr>
+<tr>
+<td>small / normal / large</td>
+<td>xhdpi</td>
+<td>64MB</td>
+</tr>
+<tr>
+<td>xlarge</td>
+<td>mdpi</td>
+<td>32MB</td>
+</tr>
+<tr>
+<td>xlarge</td>
+<td>tvdpi / hdpi</td>
+<td>64MB</td>
+</tr>
+<tr>
+<td>xlarge</td>
+<td>xhdpi</td>
+<td>128MB</td>
+</tr>
+</tbody>
+</table>
+
+<a name="section-3.8"></a><h3>3.8. User Interface Compatibility</h3>
+<a name="section-3.8.1"></a><h4>3.8.1. Widgets</h4>
+<p>Android defines a component type and corresponding API and lifecycle that
+allows applications to expose an "AppWidget" to the end user [<a
+href="#resources18">Resources, 18</a>].
+The Android Open Source reference release includes a Launcher application that
+includes user interface affordances allowing the user to add, view, and remove
+AppWidgets from the home screen.</p>
+<p>Device implementations MAY substitute an alternative to the reference Launcher
+(i.e. home screen). Alternative Launchers SHOULD include built-in support for
+AppWidgets, and expose user interface affordances to add, configure, view, and
+remove AppWidgets directly within the Launcher. Alternative Launchers MAY omit
+these user interface elements; however, if they are omitted, the device
+implementation MUST provide a separate application accessible from the Launcher
+that allows users to add, configure, view, and remove AppWidgets.</p>
+<p>Device implementations MUST be capable of rendering widgets that are 4 x 4
+in the standard grid size. (See the App Widget Design Guidelines in the Android
+SDK documentation [<a href="#resources18">Resources, 18</a>] for details.</p>
+<p>
+<a name="section-3.8.2"></a><h4>3.8.2. Notifications</h4>
+<p>Android includes APIs that allow developers to notify users of notable
+events [<a href="#resources19">Resources, 19</a>], using hardware and software
+features of the device.</p>
+<p>Some APIs allow applications to perform notifications or attract attention
+using hardware, specifically sound, vibration, and light. Device implementations
+MUST support notifications that use hardware features, as described in the SDK
+documentation, and to the extent possible with the device implementation
+hardware. For instance, if a device implementation includes a vibrator, it
+MUST correctly implement the vibration APIs. If a device implementation lacks
+hardware, the corresponding APIs MUST be implemented as no-ops. Note that this
+behavior is further detailed in <a href="#section-7">Section 7.</a></p>
+<p>Additionally, the implementation MUST correctly render all resources
+(icons, sound files, etc.) provided for in the APIs [<a
+href="#resources20">Resources, 20</a>], or in the
+Status/System Bar icon style guide [<a href="#resources21">Resources, 21</a>].
+Device implementers MAY provide an alternative user experience for
+notifications than that provided by the reference Android Open Source
+implementation; however, such alternative notification systems MUST support
+existing notification resources, as above.</p>
+<p>Android 4.2 includes support for rich notifications, such as interactive
+Views for ongoing notifications. Device implementations MUST properly display
+and execute rich notifications, as documented in the Android APIs.</p>
+<a name="section-3.8.3"></a><h4>3.8.3. Search</h4>
+<p>Android includes APIs [<a href="#resources22">Resources, 22</a>] that allow
+developers to incorporate search into their applications, and expose their
+application's data into the global system search. Generally speaking, this
+functionality consists of a single, system-wide user interface that allows users
+to enter queries, displays suggestions as users type, and displays results. The
+Android APIs allow developers to reuse this interface to provide search within
+their own apps, and allow developers to supply results to the common global
+search user interface.</p>
+<p>Device implementations MUST include a single, shared, system-wide search
+user interface capable of real-time suggestions in response to user input.
+Device implementations MUST implement the APIs that allow developers to reuse
+this user interface to provide search within their own applications. Device
+implementations MUST implement the APIs that allow third-party applications to
+add suggestions to the search box when it is run in global search mode. If no
+third-party applications are installed that make use of this functionality,
+the default behavior SHOULD be to display web search engine results and
+suggestions.</p>
+<a name="section-3.8.4"></a><h4>3.8.4. Toasts</h4>
+<p>Applications can use the "Toast" API (defined in [<a
+href="#resources23">Resources, 23</a>]) to
+display short non-modal strings to the end user, that disappear after a brief
+period of time. Device implementations MUST display Toasts from applications
+to end users in some high-visibility manner.</p>
+
+<a name="section-3.8.5"></a><h4>3.8.5. Themes</h4>
+<p>Android provides "themes" as a mechanism for applications to apply styles
+across an entire Activity or application. Android 4.2 includes a "Holo"
+or "holographic" theme as a set of defined styles for application developers to
+use if they want to match the Holo theme look and feel as defined by the Android
+SDK [<a href="#resources24">Resources, 24</a>]. Device implementations MUST NOT
+alter any of the Holo theme attributes exposed to applications
+[<a href="#resources25">Resources, 25</a>].</p>
+<p>Android 4.2 includes a new "Device Default" theme as a set of defined
+styles for application developers to use if they want to match the look and feel
+of the device theme as defined by the device implementer. Device implementations
+MAY modify the DeviceDefault theme attributes exposed to applications
+[<a href="#resources25">Resources, 25</a>].</p>
+
+<a name="section-3.8.6"></a><h4>3.8.6. Live Wallpapers</h4>
+<p>Android defines a component type and corresponding API and lifecycle that
+allows applications to expose one or more "Live Wallpapers" to the end user
+[<a href="#resources26">Resources, 26</a>]. Live Wallpapers are animations,
+patterns, or similar images with limited input capabilities that display as a
+wallpaper, behind other applications.</p>
+<p>Hardware is considered capable of reliably running live wallpapers if it
+can run all live wallpapers, with no limitations on functionality, at a
+reasonable framerate with no adverse affects on other applications. If
+limitations in the hardware cause wallpapers and/or applications to crash,
+malfunction, consume excessive CPU or battery power, or run at unacceptably
+low frame rates, the hardware is considered incapable of running live
+wallpaper. As an example, some live wallpapers may use an Open GL 1.0 or 2.0
+context to render their content. Live wallpaper will not run reliably on
+hardware that does not support multiple OpenGL contexts because the live
+wallpaper use of an OpenGL context may conflict with other applications that
+also use an OpenGL context.</p>
+<p>Device implementations capable of running live wallpapers reliably as
+described above SHOULD implement live wallpapers. Device implementations
+determined to not run live wallpapers reliably as described above MUST NOT
+implement live wallpapers.</p>
+<a name="section-3.8.7"></a><h4>3.8.7. Recent Application Display</h4>
+<p>The upstream Android 4.2 source code includes a user interface for
+displaying recent applications using a thumbnail image of the application's
+graphical state at the moment the user last left the application. Device
+implementations MAY alter or eliminate this user interface; however, a future
+version of Android is planned to make more extensive use of this
+functionality. Device implementations are strongly encouraged to use the
+upstream Android 4.2 user interface (or a similar thumbnail-based interface)
+for recent applications, or else they may not be compatible with a future
+version of Android.</p>
+<a name="section-3.8.8"></a><h4>3.8.8. Input Management Settings</h4>
+<p>Android 4.2 includes support for Input Management Engines. The Android 4.2
+APIs allow custom app IMEs to specify user-tunable settings. Device
+implementations MUST include a way for the user to access IME settings at all
+times when an IME that provides such user settings is displayed.</p>
+
+<a name="section-3.8.9"></a><h4>3.8.9. Lock and Home Screen Widgets</h4>
+<p>Android 4.2 includes support for application widgets that users can embed in the home screen or the lock screen
+(See the App Widget Design Guidelines in the Android SDK documentation [<a href="#resources69">Resources, 69</a>] for details).
+Application widgets allow quick access to application data and services without launching a new activity. Widgets declare support
+for usage on the home screen or the lock screen by declaring the <code>android:widgetCategory</code> manifest tag that tells the system
+where the widget can be placed. Specifically, device implementations MUST meet the following requirements.</p>
+<ul>
+ <li>Device implementations MUST support application widgets on the home screen.</li>
+ <li>Device implementations SHOULD support lock screen. If device implementations include support for lock screen
+ then device implementations MUST support application widgets on the lock screen.</li>
+</ul>
+
+<a name="section-3.8.10"></a><h4>3.8.10. Lock Screen Media Remote Control</h4>
+<p>Android 4.2 includes support for Remote Control API that lets media applications integrate with playback controls
+that are displayed in a remote view like the device lock screen[<a href="#resources74">Resources, 74</a>]. Device implementations MUST
+include support for embedding remote controls in the device lock screen.
+</p>
+<a name="section-3.8.11"></a><h4>3.8.11. Dreams</h4>
+<p>Android 4.2 includes support for interactive screensavers called Dreams [<a href="#resources76">Resources, 76</a>].
+Dreams allows users to interact with applications when a charging device is idle, or docked in a desk dock. Device implementations
+MUST include support for Dreams and provide a settings option for users to configure Dreams.</p>
+
+<a name="section-3.9"></a><h3>3.9 Device Administration</h3>
+<p>Android 4.2 includes features that allow security-aware applications
+to perform device administration functions at the system level, such as enforcing
+password policies or performing remote wipe, through the Android Device
+Administration API [<a href="#resources27">Resources, 27</a>]. Device
+implementations MUST provide an implementation of the <code>DevicePolicyManager
+</code> class [<a href="#resources28">Resources, 28</a>], and SHOULD support
+the full range of device administration policies defined in the Android SDK
+documentation [<a href="#resources27">Resources, 27</a>].
+</p>
+<p><b>Note:</b> while some of the requirements outlined above are stated as "SHOULD"
+for Android 4.2, device implementations that support lock screen MUST support device policies to manage widgets
+on the lock screen as defined in the Android SDK documentation [<a href="#resources27">Resources, 27</a>].
+</p>
+<p><b>Note:</b> while some of the requirements outlined above are stated as "SHOULD"
+for Android 4.2, the Compatibility Definition for a future version is planned
+to change these to "MUST". That is, these requirements are optional in Android
+4.2 but <b>will be required</b> by a future version. Existing and new devices
+that run Android 4.2 are <b>very strongly encouraged to meet
+these requirements in Android 4.2</b>, or they will not be able to attain
+Android compatibility when upgraded to the future version.</p>
+
+<a name="section-3.10"></a><h3>3.10 Accessibility</h3>
+<p>Android 4.2 provides an accessibility layer that helps users with disabilities
+to navigate their devices more easily. In addition, Android 4.2 provides
+platform APIs that enable accessibility service implementations to receive
+callbacks for user and system events and generate alternate feedback mechanisms,
+such as text-to-speech, haptic feedback, and trackball/d-pad navigation
+[<a href="#resources29">Resources, 29</a>]. Device implementations MUST provide an
+implementation of the Android accessibility framework consistent with the
+default Android implementation. Specifically, device implementations MUST meet
+the following requirements.</p>
+<ul>
+ <li>Device implementations MUST support third party accessibility service
+ implementations through the <code>android.accessibilityservice</code>
+ APIs [<a href="#resources30">Resources, 30</a>].</li>
+ <li>Device implementations MUST generate <code>AccessibilityEvents</code>
+ and deliver these events to all registered <code>AccessibilityService
+ </code> implementations in a manner consistent with the default Android
+ implementation.</li>
+ <li>Device implementations MUST provide a user-accessible mechanism to enable
+ and disable accessibility services, and MUST display this interface in
+ response to the
+ <code>android.provider.Settings.ACTION_ACCESSIBILITY_SETTINGS</code>
+ intent.</li>
+</ul>
+<p>Additionally, device implementations SHOULD provide an implementation
+of an accessibility service on the device, and SHOULD provide a mechanism
+for users to enable the accessibility service during device setup. An open
+source implementation of an accessibility service is available from the Eyes
+Free project [<a href="#resources31">Resources, 31</a>].</p>
+
+<a name="section-3.11"></a><h3>3.11 Text-to-Speech</h3>
+<p>Android 4.2 includes APIs that allow applications to make use of
+text-to-speech (TTS) services, and allows service providers to provide
+implementations of TTS services [<a href="#resources32">Resources, 32</a>].
+Device implementations MUST meet these requirements related to the Android TTS
+framework:</p>
+<ul>
+ <li>Device implementations MUST support the Android TTS framework APIs and
+ SHOULD include a TTS engine supporting the languages available on the
+ device. Note that the upstream Android open source software includes a
+ full-featured TTS engine implementation.</li>
+ <li>Device implementations MUST support installation of third-party TTS
+ engines.</li>
+ <li>Device implementations MUST provide a user-accessible interface that allows
+ users to select a TTS engine for use at the system level.</li>
+</ul>
+
+<a name="section-4"></a><h2>4. Application Packaging Compatibility</h2>
+<p>Device implementations MUST install and run Android ".apk" files as
+generated by the "aapt" tool included in the official Android SDK [<a
+href="#resources33">Resources, 33</a>].</p>
+<p>Devices implementations MUST NOT extend either the .apk [<a
+href="#resources34">Resources, 34</a>], Android Manifest [<a
+href="#resources35">Resources, 35</a>],
+Dalvik bytecode [<a href="#resources17">Resources, 17</a>], or renderscript
+bytecode formats in such a way that would prevent those files from installing
+and running correctly on other compatible devices. Device implementers SHOULD
+use the reference upstream implementation of Dalvik, and the reference
+implementation's package management system.</p>
+
+<a name="section-5"></a><h2>5. Multimedia Compatibility</h2>
+<p>Device implementations MUST include at least one form of audio output, such as
+speakers, headphone jack, external speaker connection, etc.</p>
+<a name="section-5.1"></a><h3>5.1. Media Codecs</h3>
+<p>Device implementations MUST support the core media formats specified
+in the Android SDK documentation [<a href="#resources58">Resources, 58</a>] except
+where explicitly permitted in this document. Specifically, device implementations
+MUST support the media formats, encoders, decoders, file types and container
+formats defined in the tables below. All of these codecs are provided as
+software implementations in the preferred Android implementation from the Android
+Open Source Project.</p>
+
+<p><strong>Please note that neither Google nor the Open Handset Alliance make any
+representation that these codecs are unencumbered by third-party patents.
+Those intending to use this source code in hardware or software products are
+advised that implementations of this code, including in open source software
+or shareware, may require patent licenses from the relevant patent
+holders.</strong></p>
+
+<p>Note that these tables do not list specific bitrate requirements for
+most video codecs because current device hardware does not necessarily support
+bitrates that map exactly to the required bitrates specified by the relevant
+standards. Instead, device implementations SHOULD support the highest bitrate
+practical on the hardware, up to the limits defined by the specifications.</p>
+<div style="page-break-before: always;"></div>
+<table>
+<tbody>
+
+<tr>
+<th>Type</th>
+<th>Format / Codec</th>
+<th>Encoder</th>
+<th>Decoder</th>
+<th>Details</th>
+<th>File Type(s) / Container Formats</th>
+</tr>
+
+<tr>
+<td rowspan="11">Audio</td>
+<td>MPEG-4 AAC Profile (AAC LC)</td>
+<td style="text-align: center;">REQUIRED<br/>
+<small>Required for device implementations that include microphone hardware
+and define <code>android.hardware.microphone</code>.</small></td>
+<td style="text-align: center;">REQUIRED</td>
+<td rowspan="1"> Support for mono/stereo/5.0/5.1* content with standard sampling rates from 8 to 48 kHz.</td>
+<td rowspan="4">
+ <ul>
+ <li>3GPP (.3gp)</li>
+ <li>MPEG-4 (.mp4, .m4a)</li>
+ <li>ADTS raw AAC (.aac, decode in Android 3.1+, encode in Android 4.0+, ADIF not supported)</li>
+ <li>MPEG-TS (.ts, not seekable, Android 3.0+)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>MPEG-4 HE AAC Profile (AAC+)</td>
+<td>REQUIRED for device implementations that include microphone hardware and define android.hardware.microphone</td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Support for mono/stereo/5.0/5.1* content with standard sampling rates from 16 to 48 kHz.</td>
+</tr>
+
+<tr>
+<td>MPEG-4 HE AAC v2 Profile (enhanced AAC+)</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Support for mono/stereo/5.0/5.1* content with standard sampling rates from 16 to 48 kHz.</td>
+</tr>
+
+<tr>
+<td>MPEG-4 Audio Object Type ER AAC ELD (Enhanced Low Delay AAC)</td>
+<td>REQUIRED for device implementations that include microphone hardware and define android.hardware.microphone</td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Support for mono/stereo content with standard
+sampling rates from 16 to 48 kHz.</td>
+</tr>
+
+<tr>
+<td>AMR-NB</td>
+<td style="text-align: center;">REQUIRED<br/>
+<small>Required for device implementations that include microphone hardware
+and define <code>android.hardware.microphone</code>.</small></td>
+<td style="text-align: center;">REQUIRED</td>
+<td>4.75 to 12.2 kbps sampled @ 8kHz</td>
+<td>3GPP (.3gp)
+</td>
+</tr>
+
+<tr>
+<td>AMR-WB</td>
+<td style="text-align: center;">REQUIRED<br/>
+<small>Required for device implementations that include microphone hardware
+and define <code>android.hardware.microphone</code>.</small></td>
+<td style="text-align: center;">REQUIRED</td>
+<td>9 rates from 6.60 kbit/s to 23.85 kbit/s sampled @ 16kHz</td>
+<td>3GPP (.3gp)</td>
+</tr>
+
+<tr>
+<td>FLAC</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED<br/><small>(Android 3.1+)</small></td>
+<td>Mono/Stereo (no multichannel). Sample rates up to 48 kHz (but up to 44.1
+kHz is recommended on devices with 44.1 kHz output, as the 48 to 44.1 kHz
+downsampler does not include a low-pass filter). 16-bit recommended;
+no dither applied for 24-bit.
+</td>
+<td>FLAC (.flac) only</td>
+</tr>
+
+<tr>
+<td>MP3</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Mono/Stereo 8-320Kbps constant (CBR) or variable bit-rate (VBR)
+</td>
+<td>MP3 (.mp3)</td>
+</tr>
+
+<tr>
+<td>MIDI</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td>MIDI Type 0 and 1. DLS Version 1 and 2. XMF and Mobile XMF. Support for ringtone formats RTTTL/RTX, OTA, and iMelody </td>
+<td>
+ <ul>
+ <li>Type 0 and 1 (.mid, .xmf, .mxmf)</li>
+ <li>RTTTL/RTX (.rtttl, .rtx)</li>
+ <li>OTA (.ota)</li>
+ <li>iMelody (.imy)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>Vorbis</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>
+ <ul>
+ <li>Ogg (.ogg)</li>
+ <li>Matroska (.mkv)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>PCM/WAVE</td>
+<td style="text-align: center;">REQUIRED</td>
+<td style="text-align: center;">REQUIRED</td>
+<td>8-bit and 16-bit linear PCM** (rates up to limit of hardware).Devices MUST support sampling rates
+for raw PCM recording at 8000,16000 and 44100 Hz frequencies</td>
+<td>WAVE (.wav)</td>
+</tr>
+
+<tr>
+<td rowspan="5">Image</td>
+<td>JPEG</td>
+<td style="text-align: center;">REQUIRED</td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Base+progressive</td>
+<td>JPEG (.jpg)</td>
+</tr>
+
+<tr>
+<td>GIF</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>GIF (.gif)</td>
+</tr>
+
+<tr>
+<td>PNG</td>
+<td style="text-align: center;">REQUIRED</td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>PNG (.png)</td>
+</tr>
+
+<tr>
+<td>BMP</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>BMP (.bmp)</td>
+</tr>
+
+
+<tr>
+<td>WEBP</td>
+<td style="text-align: center;">REQUIRED</td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>WebP (.webp)</td>
+</tr>
+
+<tr>
+<td rowspan="4">Video</td>
+<td>H.263</td>
+<td style="text-align: center;">REQUIRED<br/>
+<small>Required for device implementations that include camera hardware
+and define <code>android.hardware.camera</code> or
+<code>android.hardware.camera.front</code>.</small></td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>
+ <ul>
+ <li>3GPP (.3gp)</li>
+ <li>MPEG-4 (.mp4)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>H.264 AVC</td>
+<td style="text-align: center;">REQUIRED<br/>
+<small>Required for device implementations that include camera hardware
+and define <code>android.hardware.camera</code> or
+<code>android.hardware.camera.front</code>.</small></td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Baseline Profile (BP)</td>
+<td>
+ <ul>
+ <li>3GPP (.3gp)</li>
+ <li>MPEG-4 (.mp4)</li>
+ <li>MPEG-TS (.ts, AAC audio only, not seekable, Android 3.0+)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>MPEG-4 SP</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>3GPP (.3gp)</td>
+</tr>
+
+<tr>
+<td>VP8</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED<br/><small>(Android 2.3.3+)</small></td>
+<td> </td>
+<td><a href="http://www.webmproject.org/">WebM</a> (.webm) and Matroska (.mkv, Android 4.0+)</td>
+</tr>
+
+</tbody></table>
+*Note: Only downmix of 5.0/5.1 content is required; recording or rendering more than 2 channels is optional.
+**Note: 16-bit linear PCM capture is mandatory. 8-bit linear PCM capture is not mandatory.
+
+<a name="section-5.2"></a><h3>5.2 Video Encoding</h3>
+<p>Android device implementations that include a rear-facing camera and declare
+<code>android.hardware.camera</code> SHOULD support the following video encoding
+profiles.</p>
+<table>
+ <thead>
+ <tr>
+ <th> </th>
+ <th>SD (Low quality)</th>
+ <th>SD (High quality)</th>
+ <th>HD (When supported by hardware)</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <th>Video codec</th>
+ <td>H.264 Baseline Profile</td>
+ <td>H.264 Baseline Profile</td>
+ <td>H.264 Baseline Profile</td>
+ </tr>
+ <tr>
+ <th>Video resolution</th>
+ <td>176 x 144 px</td>
+ <td>480 x 360 px</td>
+ <td>1280 x 720 px</td>
+ </tr>
+ <tr>
+ <th>Video frame rate</th>
+ <td>12 fps</td>
+ <td>30 fps</td>
+ <td>30 fps</td>
+ </tr>
+ <tr>
+ <th>Video bitrate</th>
+ <td>56 Kbps</td>
+ <td>500 Kbps or higher</td>
+ <td>2 Mbps or higher</td>
+ </tr>
+ <tr>
+ <th>Audio codec</th>
+ <td>AAC-LC</td>
+ <td>AAC-LC</td>
+ <td>AAC-LC</td>
+ </tr>
+ <tr>
+ <th>Audio channels</th>
+ <td>1 (mono)</td>
+ <td>2 (stereo)</td>
+ <td>2 (stereo)</td>
+ </tr>
+ <tr>
+ <th>Audio bitrate</th>
+ <td>24 Kbps</td>
+ <td>128 Kbps</td>
+ <td>192 Kbps</td>
+ </tr>
+ </tbody>
+</table>
+
+<a name="section-5.3"></a><h3>5.3 Video Decoding</h3>
+<p>Android device implementations SHOULD support the following VP8 video decoding profiles.</p>
+<div style="page-break-before: always;"></div>
+<table>
+ <thead>
+ <tr>
+ <th> </th>
+ <th>SD (Low quality)</th>
+ <th>SD (High quality)</th>
+ <th>HD 720p <br/> (When supported by hardware)</th>
+ <th>HD 1080p <br/>(When supported by hardware)</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <th>Video resolution</th>
+ <td>320 x 180 px</td>
+ <td>640 x 360 px</td>
+ <td>1280 x 720 px</td>
+ <td>1920 x 1080 px</td>
+ </tr>
+ <tr>
+ <th>Video frame rate</th>
+ <td>30 fps</td>
+ <td>30 fps</td>
+ <td>30 fps</td>
+ <td>30 fps</td>
+ </tr>
+ <tr>
+ <th>Video bitrate</th>
+ <td>800 Kbps</td>
+ <td>2 Mbps</td>
+ <td>8 Mbps</td>
+ <td>20 Mbps</td>
+ </tr>
+ </tbody>
+</table>
+<a name="section-5.4"></a><h3>5.4. Audio Recording</h3>
+<p>When an application has used the <code>android.media.AudioRecord</code> API to
+start recording an audio stream, device implementations that include microphone
+hardware and declare <code>android.hardware.microphone</code> MUST sample and
+record audio with each of these behaviors:</p>
+<ul>
+<li>The device SHOULD exhibit approximately flat amplitude versus frequency
+ characteristics; specifically, ±3 dB, from 100 Hz to 4000 Hz</li>
+<li>Audio input sensitivity SHOULD be set such that a 90 dB sound power level
+ (SPL) source at 1000 Hz yields RMS of 2500 for 16-bit samples.</li>
+<li>PCM amplitude levels SHOULD linearly track input SPL changes over at least
+ a 30 dB range from -18 dB to +12 dB re 90 dB SPL at the microphone.</li>
+<li>Total harmonic distortion SHOULD be less than 1% for 1Khz at 90 dB SPL input level.</li>
+</ul>
+<p>In addition to the above recording specifications, when an application has
+started recording an audio stream using the
+<code>android.media.MediaRecorder.AudioSource.VOICE_RECOGNITION</code> audio
+source:</p>
+<ul>
+<li>Noise reduction processing, if present, MUST be disabled.</li>
+<li>Automatic gain control, if present, MUST be disabled.</li>
+</ul>
+<p><b>Note:</b> while some of the requirements outlined above are stated as "SHOULD"
+for Android 4.2, the Compatibility Definition for a future version is planned
+to change these to "MUST". That is, these requirements are optional in Android
+4.2 but <b>will be required</b> by a future version. Existing and new devices
+that run Android 4.2 are <b>very strongly encouraged to meet
+these requirements in Android 4.2</b>, or they will not be able to attain
+Android compatibility when upgraded to the future version.</p>
+
+<a name="section-5.5"></a><h3>5.5. Audio Latency</h3>
+<p>Audio latency is the time delay as an audio signal passes through a system.
+Many classes of
+applications rely on short latencies, to achieve real-time effects such sound
+effects or VOIP communication.</p>
+<p>For the purposes of this section:</p>
+<ul>
+<li>"output latency" is defined as the interval between when an application
+writes a frame of PCM-coded data and when the corresponding sound can be heard
+by an external listener or observed by a transducer</li>
+<li>"cold output latency" is defined as the output latency for the first frame, when
+ the audio output system has been idle and powered down prior to the request</li>
+<li>"continuous output latency" is defined as the output latency for subsequent frames,
+ after the device is already playing audio</li>
+<li>"input latency" is the interval between when an external sound is presented
+to the device and when an application reads the corresponding frame of PCM-coded data</li>
+<li>"cold input latency" is defined as the sum of lost input time
+ and the input latency for the first frame, when
+ the audio input system has been idle and powered down prior to the request</li>
+<li>"continuous input latency" is defined as the input latency for subsequent frames,
+ while the device is already capturing audio</li>
+<li>"OpenSL ES PCM buffer queue API" is the set of PCM-related OpenSL ES APIs within Android NDK;
+see <i>NDK_root</i><code>/docs/opensles/index.html</code></li>
+</ul>
+<p>Per <a href="#section-5">Section 5</a>,
+all compatible device implementations MUST include at least one form of audio output.
+Device implementations SHOULD meet or exceed these output latency requirements:</p>
+<ul>
+<li>cold output latency of 100 milliseconds or less</li>
+<li>continuous output latency of 45 milliseconds or less</li>
+</ul>
+<p>If a device implementation meets the requirements of this section
+after any initial calibration
+when using the OpenSL ES PCM buffer queue API,
+for continuous output latency and cold output latency
+over at least one supported audio output device, it MAY
+report support for low-latency audio, by reporting the feature
+"android.hardware.audio.low-latency" via the
+<code>android.content.pm.PackageManager</code> class. [<a
+href="#resources37">Resources, 37</a>] Conversely, if the device
+implementation does not meet these requirements it MUST NOT report support for
+low-latency audio.</p>
+<p>
+Per <a href="#section-7.2.5">Section 7.2.5</a>,
+microphone hardware may be omitted by device implementations.</p>
+<p>
+Device implementations that include microphone
+hardware and declare <code>android.hardware.microphone</code> SHOULD
+meet these input audio latency requirements:</p>
+<ul>
+<li>cold input latency of 100 milliseconds or less</li>
+<li>continuous input latency of 50 milliseconds or less</li>
+</ul>
+
+<a name="section-5.6"></a><h3>5.6. Network Protocols</h3>
+<p>Devices MUST support the media network protocols for audio and video playback
+as specified in the Android SDK documentation
+[<a href="#resources58">Resources, 58</a>]. Specifically, devices MUST support
+the following media network protocols:</p>
+<ul>
+<li>RTSP (RTP, SDP)</li>
+<li>HTTP(S) progressive streaming</li>
+<li>HTTP(S) Live Streaming draft protocol, Version 3 [<a href="#resources59">Resources, 59</a>]</li>
+</ul>
+<a name="section-6"></a><h2>6. Developer Tools and Options Compatibility</h2>
+
+<a name="section-6.1"></a><h3>6.1 Developer Tools</h3>
+<p>Device implementations MUST support the Android Developer Tools provided in the Android SDK.
+Specifically, Android-compatible devices MUST be compatible with:</p>
+<ul>
+<li><b>Android Debug Bridge (known as adb)</b> [<a href="#resources33">Resources, 33</a>]<br/>
+Device implementations MUST support all <code>adb</code> functions as
+documented in the Android SDK. The device-side <code>adb</code> daemon MUST
+be inactive by default, and there MUST be a user-accessible mechanism to turn
+on the Android Debug Bridge.</li>
+<p>Android 4.2.2 includes support for secure adb. Secure adb enables adb on known authenticated hosts.
+Existing and new devices that run Android 4.2.2 are <b>very strongly encouraged to meet
+this requirement in Android 4.2</b>, or they will not be able to attain
+Android compatibility when upgraded to the future version.</p>
+<li><b>Dalvik Debug Monitor Service (known as ddms)</b> [<a href="#resources33">Resources, 33</a>]<br/>
+Device implementations MUST support all <code>ddms</code> features as documented in the
+Android SDK. As <code>ddms</code> uses <code>adb</code>, support for
+<code>ddms</code> SHOULD be inactive by default,
+but MUST be supported whenever the user has activated the Android Debug
+Bridge, as above.</li>
+<li><b>Monkey</b> [<a href="#resources36">Resources, 36</a>]<br/>
+Device implementations MUST include the Monkey framework, and make it
+available for applications to use.</li>
+<li><b>SysTrace</b> [<a href="#resources33">Resources, 33</a>]<br/>
+Device implementations MUST support systrace tool as documented in the Android SDK.
+Systrace must be inactive by default, and there MUST be a user-accessible mechanism to turn
+on Systrace.</li>
+</ul>
+<p>Most Linux-based systems and Apple Macintosh systems recognize Android
+devices using the standard Android SDK tools, without additional support;
+however Microsoft Windows systems typically require a driver for new Android
+devices. (For instance, new vendor IDs and sometimes new device IDs require
+custom USB drivers for Windows systems.) If a device implementation is
+unrecognized by the <code>adb</code> tool as provided in the standard Android
+SDK, device implementers MUST provide Windows drivers allowing developers to
+connect to the device using the <code>adb</code> protocol. These drivers MUST
+be provided for Windows XP, Windows Vista, Windows 7, and Windows 8, in both 32-bit and
+64-bit versions.</p>
+
+<a name="section-6.2"></a><h3>6.2 Developer Options</h3>
+<p>Android 4.2 includes support for developers to configure application development-related settings.
+Device implementations MUST honor the android.settings.APPLICATION_DEVELOPMENT_SETTINGS intent to show
+application development-related settings [<a href="#resources77">Resources, 77</a>]. The upstream Android
+implementation hides the Developer Options menu by default, and enables users to launch Developer Options
+after pressing seven (7) times on the Settings > About Device > Build Number menu item. Device implementations
+MUST provide a consistent experience for Developer Options. Specifically, device implementations MUST hide
+Developer Options by default and MUST provide a mechanism to enable Developer Options that is consistent with
+the upstream Android implementation.</p>
+
+<a name="section-7"></a><h2>7. Hardware Compatibility</h2>
+<p>If a device includes a particular hardware component that has a
+corresponding API for third-party developers, the device implementation MUST
+implement that API as described in the Android SDK documentation. If an API in
+the SDK interacts with a hardware component that is stated to be optional and
+the device implementation does not possess that component:</p>
+<ul>
+<li>complete class definitions (as documented by the SDK) for the component's
+APIs MUST still be present</li>
+<li>the API's behaviors MUST be implemented as no-ops in some reasonable
+fashion</li>
+<li>API methods MUST return null values where permitted by the SDK
+documentation</li>
+<li>API methods MUST return no-op implementations of classes where null
+values are not permitted by the SDK documentation</li>
+<li>API methods MUST NOT throw exceptions not documented by the SDK
+documentation</li>
+</ul>
+<p>A typical example of a scenario where these requirements apply is the
+telephony API: even on non-phone devices, these APIs must be implemented as
+reasonable no-ops.</p>
+<p>Device implementations MUST accurately report accurate hardware configuration
+information via the <code>getSystemAvailableFeatures()</code> and
+<code>hasSystemFeature(String)</code> methods on the
+<code>android.content.pm.PackageManager</code> class. [<a
+href="#resources37">Resources, 37</a>]</p>
+
+<a name="section-7.1"></a><h3>7.1. Display and Graphics</h3>
+<p>Android 4.2 includes facilities that automatically adjust application
+assets and UI layouts appropriately for the device, to ensure that third-party
+applications run well on a variety of hardware configurations [<a
+href="#resources38">Resources, 38</a>]. Devices MUST properly implement these
+APIs and behaviors, as detailed in this section.</p>
+
+<p>The units referenced by the requirements in this section are defined as follows:</p>
+<ul>
+<li>"Physical diagonal size" is the distance in inches between two opposing
+corners of the illuminated portion of the display.</li>
+<li>"dpi" (meaning "dots per inch") is the number of pixels encompassed by a
+linear horizontal or vertical span of 1". Where dpi values are listed, both
+horizontal and vertical dpi must fall within the range.</li>
+<li>"Aspect ratio" is the ratio of the longer dimension of the screen to the
+shorter dimension. For example, a display of 480x854 pixels would be 854 / 480
+= 1.779, or roughly "16:9".</li>
+<li>A "density-independent pixel" or ("dp") is the virtual pixel unit normalized to a
+160 dpi screen, calculated as:
+<code>pixels = dps * (density / 160)</code>.</li>
+</ul>
+
+
+<a name="section-7.1.1"></a><h4>7.1.1. Screen Configuration</h4>
+
+<p style="font-weight:bold;">Screen Size</p>
+<p>The Android UI framework supports a variety of different screen sizes, and
+allows applications to query the device screen size (aka "screen layout") via
+<code>android.content.res.Configuration.screenLayout</code> with the
+<code>SCREENLAYOUT_SIZE_MASK</code>. Device implementations MUST report the
+correct screen size as defined in the Android SDK documentation
+[<a href="#resources38">Resources, 38</a>] and determined by the upstream
+Android platform. Specifically, device implementations must report the correct
+screen size according to the following logical density-independent pixel (dp)
+screen dimensions.</p>
+<ul>
+<li>Devices MUST have screen sizes of at least 426 dp x 320 dp ('small')</li>
+<li>Devices that report screen size 'normal' MUST have screen sizes of at least
+480 dp x 320 dp</li>
+<li>Devices that report screen size 'large' MUST have screen sizes of at least
+640 dp x 480 dp</li>
+<li>Devices that report screen size 'xlarge' MUST have screen sizes of at least
+960 dp x 720 dp</li>
+</ul>
+<p>In addition, devices MUST have screen sizes of at least 2.5 inches in
+physical diagonal size.</p>
+
+<p>Devices MUST NOT change their reported screen size at any time.</p>
+<p>Applications optionally indicate which screen sizes they support via the
+<code><supports-screens></code> attribute in the AndroidManifest.xml
+file. Device implementations MUST correctly honor applications' stated support
+for small, normal, large, and xlarge screens, as described in the Android
+SDK documentation.</p>
+
+<p style="font-weight:bold;">Screen Aspect Ratio</p>
+<p>The aspect ratio MUST be between 1.3333 (4:3) and 1.85 (16:9).</p>
+
+<p style="font-weight:bold;">Screen Density</p>
+<p>The Android UI framework defines a set of standard logical densities to
+help application developers target application resources. Device
+implementations MUST report one of the following logical Android framework
+densities through the <code>android.util.DisplayMetrics</code> APIs, and MUST
+execute applications at this standard density.
+<ul>
+<li>120 dpi, known as 'ldpi'</li>
+<li>160 dpi, known as 'mdpi'</li>
+<li>213 dpi, known as 'tvdpi'</li>
+<li>240 dpi, known as 'hdpi'</li>
+<li>320 dpi, known as 'xhdpi'</li>
+<li>480 dpi, known as 'xxhdpi'</li>
+</ul>
+Device implementations SHOULD define the standard Android framework density
+that is numerically closest to the physical density of the screen, unless that
+logical density pushes the reported screen size below the minimum supported.
+If the standard Android framework density that is numerically closest to the
+physical density results in a screen size that is smaller than the smallest
+supported compatible screen size (320 dp width), device implementations SHOULD
+report the next lowest standard Android framework density.</p>
+
+<a name="section-7.1.2"></a><h4>7.1.2. Display Metrics</h4>
+<p>Device implementations MUST report correct values for all display metrics
+defined in <code>android.util.DisplayMetrics</code> [<a
+href="#resources39">Resources, 39</a>].</p>
+
+<a name="section-7.1.3"></a><h4>7.1.3. Screen Orientation</h4>
+<p>Devices MUST support dynamic orientation by applications to
+either portrait or landscape screen orientation. That is, the device must
+respect the application's request for a specific screen orientation. Device
+implementations MAY select either portrait or landscape orientation as the
+default.</p>
+<p>Devices MUST report the correct value for the device's current orientation,
+whenever queried via the android.content.res.Configuration.orientation,
+android.view.Display.getOrientation(), or other APIs.</p>
+<p>Devices MUST NOT change the reported screen size or density when changing
+orientation.</p>
+<p>Devices MUST report which screen orientations they support (
+<code>android.hardware.screen.portrait</code> and/or
+<code>android.hardware.screen.landscape</code>) and MUST report at least one
+supported orientation. For example, a device with a fixed-orientation
+landscape screen, such as a television or laptop, MUST only report
+<code>android.hardware.screen.landscape</code>.</p>
+
+<a name="section-7.1.4"></a><h4>7.1.4. 2D and 3D Graphics Acceleration</h4>
+<p>Device implementations MUST support both OpenGL ES 1.0 and 2.0, as embodied
+and detailed in the Android SDK documentations. Device implementations MUST
+also support Android Renderscript, as detailed in the Android SDK
+documentation [<a href="#resources08">Resources, 8</a>].</p>
+<p>Device implementations MUST also correctly identify themselves as
+supporting OpenGL ES 1.0 and 2.0. That is:</p>
+<ul>
+<li>The managed APIs (such as via the <code>GLES10.getString()</code> method)
+MUST report support for OpenGL ES 1.0 and 2.0</li>
+<li>The native C/C++ OpenGL APIs (that is, those available to apps via
+libGLES_v1CM.so, libGLES_v2.so, or libEGL.so) MUST report support for
+OpenGL ES 1.0 and 2.0.</li>
+</ul>
+<p>Device implementations MAY implement any desired OpenGL ES extensions.
+However, device implementations MUST report via the OpenGL ES managed and
+native APIs all extension strings that they do support, and conversely MUST
+NOT report extension strings that they do not support.</p>
+<p>Note that Android 4.2 includes support for applications to optionally
+specify that they require specific OpenGL texture compression formats. These
+formats are typically vendor-specific. Device implementations are not required
+by Android 4.2 to implement any specific texture compression format. However,
+they SHOULD accurately report any texture compression formats that they do
+support, via the <code>getString()</code> method in the OpenGL API.</p>
+
+<p>Android 4.2 includes a mechanism for applications to declare that they
+wanted to enable hardware acceleration for 2D graphics at the Application,
+Activity, Window or View level through the use of a manifest tag
+<code>android:hardwareAccelerated</code> or direct API calls
+[<a href="#resources09">Resources, 9</a>].</p>
+<p>In Android 4.2, device implementations MUST enable hardware acceleration by
+default, and MUST disable hardware acceleration if the developer so requests
+by setting <code>android:hardwareAccelerated="false"</code> or disabling
+hardware acceleration directly through the Android View APIs.</p>
+<p>In addition, device implementations MUST exhibit behavior consistent with the
+Android SDK documentation on hardware acceleration
+[<a href="#resources09">Resources, 9</a>].</p>
+<p>Android 4.2 includes a <code>TextureView</code> object that lets developers
+directly integrate hardware-accelerated OpenGL ES textures as rendering targets
+in a UI hierarchy. Device implementations MUST support the <code>TextureView
+</code> API, and MUST exhibit consistent behavior with the upstream Android
+implementation.</p>
+
+<a name="section-7.1.5"></a><h4>7.1.5. Legacy Application Compatibility Mode</h4>
+<p>Android 4.2 specifies a "compatibility mode" in which the framework
+operates in an 'normal' screen size equivalent (320dp width) mode for the benefit
+of legacy applications not developed for old versions of Android that pre-date
+screen-size independence. Device implementations MUST include support for legacy
+application compatibility mode as implemented by the upstream Android open source
+code. That is, device implementations MUST NOT alter the triggers or thresholds at
+which compatibility mode is activated, and MUST NOT alter the behavior of the
+compatibility mode itself.</p>
+
+<a name="section-7.1.6"></a><h4>7.1.6. Screen Types</h4>
+<p>Device implementation screens are classified as one of two types:</p>
+<ul>
+<li>Fixed-pixel display implementations: the screen is a single panel that supports only a
+single pixel width and height. Typically the screen is physically integrated with
+the device. Examples include mobile phones, tablets, and so on.</li>
+<li>Variable-pixel display implementations: the device implementation either has no
+embedded screen and includes a video output port such as VGA, HDMI or a wireless port
+for display, or has an embedded screen that can change pixel dimensions. Examples
+include televisions, set-top boxes, and so on.</li>
+</ul>
+<p style="font-weight: bold;">Fixed-Pixel Device Implementations</p>
+<p>Fixed-pixel device implementations MAY use screens of any pixel dimensions, provided
+that they meet the requirements defined this Compatibility Definition.</p>
+<p>Fixed-pixel implementations MAY include a video output port for use with an
+external display. However, if that display is ever used for running apps, the
+device MUST meet the following requirements:</p>
+<ul>
+<li>The device MUST report the same screen configuration and display metrics, as detailed
+in Sections 7.1.1 and 7.1.2, as the fixed-pixel display.</li>
+<li>The device MUST report the same logical density as the fixed-pixel display.</li>
+<li>The device MUST report screen dimensions that are the same as, or very close to,
+the fixed-pixel display.</li>
+</ul>
+<p>For example, a tablet that is 7" diagonal size with a 1024x600 pixel resolution is
+considered a fixed-pixel large mdpi display implementation. If it contains a video
+output port that displays at 720p or 1080p, the device implementation MUST scale the output so that
+applications are only executed in a large mdpi window, regardless of whether the fixed-pixel display
+or video output port is in use.</p>
+
+<p style="font-weight: bold;">Variable-Pixel Device Implementations</p>
+<p>Variable-pixel device implementations MUST support one or both of 1280x720,
+or 1920x1080 (that is, 720p or 1080p). Device implementations with
+variable-pixel displays MUST NOT support any other screen configuration or
+mode. Device implementations with variable-pixel screens MAY change screen
+configuration or mode at runtime or boot-time. For example, a user of a
+set-top box may replace a 720p display with a 1080p display, and the device
+implementation may adjust accordingly.</p>
+
+<p>Additionally, variable-pixel device implementations MUST report the following
+configuration buckets for these pixel dimensions:</p>
+<ul>
+<li>1280x720 (also known as 720p): 'large' screen size, 'tvdpi' (213 dpi)
+density</li>
+<li>1920x1080 (also known as 1080p): 'large' screen size, 'xhdpi' (320 dpi)
+density</li>
+</ul>
+<p>For clarity, device implementations with variable pixel dimensions are
+restricted to 720p or 1080p in Android 4.2, and MUST be configured to report
+screen size and density buckets as noted above.</p>
+
+<a name="section-7.1.7"></a><h4>7.1.7. Screen Technology</h4>
+<p>The Android platform includes APIs that allow applications to render rich
+graphics to the display. Devices MUST support all of these APIs as defined by
+the Android SDK unless specifically allowed in this document. Specifically:</p>
+<ul>
+<li>Devices MUST support displays capable of rendering 16-bit color graphics and
+SHOULD support displays capable of 24-bit color graphics.</li>
+<li>Devices MUST support displays capable of rendering animations.</li>
+<li>The display technology used MUST have a pixel aspect ratio (PAR) between
+ 0.9 and 1.1. That is, the pixel aspect ratio MUST be near square (1.0) with
+ a 10% tolerance.</li>
+</ul>
+<a name="section-7.1.8"></a><h4>7.1.8. External Displays</h4>
+<p>Android 4.2 includes support for secondary display to enable media sharing capabilities and
+developer APIs for accessing external displays. If a device supports an external display either via
+a wired, wireless or an embedded additional display connection then the device implementation MUST
+implement the display manager API as described in the Android SDK documentation [<a href="#resources75">Resources, 75</a>].
+Device implementations that support secure video output and are capable of supporting secure surfaces MUST declare support
+for <code>Display.SECURE_FLAG</code>. Specifically, device implementations that declare support for <code>Display.SECURE_FLAG</code>,
+MUST support <b>HDCP 2.x or higher</b> for Miracast wireless displays or <b>HDCP 1.2 or higher</b> for wired displays. The upstream
+Android open source implementation includes support for wireless (Miracast) and wired (HDMI) displays that satisfies this requirement.</p>
+
+<a name="section-7.2"></a><h3>7.2. Input Devices</h3>
+<a name="section-7.2.1"></a><h4>7.2.1. Keyboard</h4>
+<p>Device implementations:</p>
+<ul>
+<li>MUST include support for the Input Management Framework (which allows third
+party developers to create Input Management Engines - i.e. soft keyboard) as
+detailed at <a href="http://developer.android.com">http://developer.android.com</a>
+</li>
+<li>MUST provide at least one soft keyboard implementation (regardless of whether
+a hard keyboard is present)</li>
+<li>MAY include additional soft keyboard implementations</li>
+<li>MAY include a hardware keyboard</li>
+<li>MUST NOT include a hardware keyboard that does not match one of the
+formats specified in <code>android.content.res.Configuration.keyboard</code>
+[<a href="#resources40">Resources, 40</a>] (that is, QWERTY, or 12-key)</li>
+</ul>
+<a name="section-7.2.2"></a><h4>7.2.2. Non-touch Navigation</h4>
+<p>Device implementations:</p>
+<ul>
+<li>MAY omit a non-touch navigation option (that is, may omit a trackball, d-pad,
+or wheel)</li>
+<li>MUST report the correct value for
+<code>android.content.res.Configuration.navigation</code>
+[<a href="#resources40">Resources, 40</a>]</li>
+<li>MUST provide a reasonable alternative user interface mechanism for the
+selection and editing of text, compatible with Input Management Engines. The
+upstream Android open source implementation includes a selection mechanism suitable
+for use with devices that lack non-touch navigation inputs.</li>
+</ul>
+<a name="section-7.2.3"></a><h4>7.2.3. Navigation keys</h4>
+<p>The Home, Menu and Back functions are essential to the Android navigation
+paradigm. Device implementations MUST make these functions available to the
+user at all times when running applications. These functions MAY be implemented
+via dedicated physical buttons (such as mechanical or capacitive touch buttons),
+or MAY be implemented using dedicated software keys, gestures, touch panel, etc.
+Android 4.2 supports both implementations.</p>
+
+<p>Android 4.2 includes support for assist action [<a href="#resources63">Resources, 63</a>].
+Device implementations MUST make the assist action available to the user at all times when running applications.
+This function MAY be implemented via hardware or software keys.</p>
+
+<p>Device implementations MAY use a distinct portion of the screen to display
+the navigation keys, but if so, MUST meet these requirements:</p>
+
+<ul>
+ <li>Device implementation navigation keys MUST use a distinct portion of the
+ screen, not available to applications, and MUST NOT obscure or otherwise
+ interfere with the portion of the screen available to applications.</li>
+ <li>Device implementations MUST make available a portion of the display to
+ applications that meets the requirements defined in
+ <a href="section-7.1.1">Section 7.1.1</a>.</li>
+ <li>Device implementations MUST display the navigation keys when applications
+ do not specify a system UI mode, or specify
+ <code>SYSTEM_UI_FLAG_VISIBLE</code>.</li>
+ <li>Device implementations MUST present the navigation keys in an unobtrusive
+ "low profile" (eg. dimmed) mode when applications specify
+ <code>SYSTEM_UI_FLAG_LOW_PROFILE</code>.</li>
+ <li>Device implementations MUST hide the navigation keys when applications
+ specify <code>SYSTEM_UI_FLAG_HIDE_NAVIGATION</code>.</li>
+ <li>Device implementation MUST present a Menu key to applications when
+ targetSdkVersion <= 10 and SHOULD NOT present a Menu key when the
+ targetSdkVersion > 10.</li>
+</ul>
+
+<a name="section-7.2.4"></a><h4>7.2.4. Touchscreen input</h4>
+<p>Device implementations:</p>
+<ul>
+<li>MUST have a pointer input system of some kind (either mouse-like, or
+touch)</li>
+<li>MAY have a touchscreen of any modality (such as capacitive or resistive)</li>
+<li>SHOULD support fully independently tracked pointers, if a touchscreen
+supports multiple pointers</li>
+<li>MUST report the value of <code>android.content.res.Configuration</code>
+[<a href="#resources40">Resources, 39</a>]
+reflecting corresponding to the type of the specific touchscreen on the
+device</li>
+</ul>
+<p>Device implementations MUST report the correct feature corresponding to the
+type of input used. Note that Android 4.2 includes the feature
+<code>android.hardware.faketouch</code>, which corresponds to a high-fidelity
+non-touch (that is, pointer-based) input device such as a mouse or trackpad that
+can adequately emulate touch-based input (including basic gesture support),
+and indicates that the device supports an emulated subset of touchscreen
+functionality.
+Device implementations that include a touchscreen (single-touch or better)
+MUST also report android.hardware.faketouch. Device implementations that do
+not include a touchscreen (and rely on a pointer device only) MUST NOT report
+any touchscreen feature, and MUST report only
+<code>android.hardware.faketouch</code>.</p>
+<a name="section-7.2.5"></a><h4>7.2.5. Microphone</h4>
+<p>Device implementations MAY omit a microphone. However, if a device
+implementation omits a microphone, it MUST NOT report the
+<code>android.hardware.microphone</code> feature constant, and must implement
+the audio recording API as no-ops, per <a href="section-7">Section 7</a>.
+Conversely, device implementations that do possess a microphone:</p>
+<ul>
+<li>MUST report the <code>android.hardware.microphone</code> feature constant</li>
+<li>SHOULD meet the audio quality requirements in <a href="section-5.4">Section 5.4</a></li>
+<li>SHOULD meet the audio latency requirements in <a href="section-5.5">Section 5.5</a></li>
+</ul>
+
+<a name="section-7.3"></a><h3>7.3. Sensors</h3>
+<p>Android 4.2 includes APIs for accessing a variety of sensor types. Devices
+implementations generally MAY omit these sensors, as provided for in the
+following subsections. If a device includes a particular sensor type that has a
+corresponding API for third-party developers, the device implementation MUST
+implement that API as described in the Android SDK documentation. For example,
+device implementations:</p>
+<ul>
+<li>MUST accurately report the presence or absence of sensors per the
+<code>android.content.pm.PackageManager</code> class. [<a
+href="#resources37">Resources, 37</a>]</li>
+<li>MUST return an accurate list of supported sensors via the
+<code>SensorManager.getSensorList()</code> and similar methods</li>
+<li>MUST behave reasonably for all other sensor APIs (for example, by
+returning true or false as appropriate when applications attempt to register
+listeners, not calling sensor listeners when the corresponding sensors are not
+present; etc.)</li>
+<li>MUST report all sensor measurements using the relevant International System
+of Units (i.e. metric) values for each sensor type as defined in the Android SDK
+documentation [<a href="#resources41">Resources, 41</a>]</li>
+</ul>
+<p>The list above is not comprehensive; the documented behavior of the Android
+SDK is to be considered authoritative.</p>
+<p>Some sensor types are synthetic, meaning they can be derived from data
+provided by one or more other sensors. (Examples include the orientation
+sensor, and the linear acceleration sensor.) Device implementations SHOULD
+implement these sensor types, when they include the prerequisite physical
+sensors.</p>
+<p>The Android 4.2 includes a notion of a "streaming" sensor, which is
+one that returns data continuously, rather than only when the data changes.
+Device implementations MUST continuously provide periodic data samples for any
+API indicated by the Android 4.2 SDK documentation to be a streaming
+sensor. Note that the device implementations MUST ensure that the sensor stream must not
+prevent the device CPU from entering a suspend state or waking up from a suspend state.</p>
+
+<a name="section-7.3.1"></a><h4>7.3.1. Accelerometer</h4>
+<p>Device implementations SHOULD include a 3-axis accelerometer. If a device
+implementation does include a 3-axis accelerometer, it:</p>
+<ul>
+<li>SHOULD be able to deliver events at 120 Hz or greater. Note that while the
+accelerometer frequency above is stated as "SHOULD" for Android 4.2, the Compatibility Definition
+for a future version is planned to change these to "MUST". That is, these standards are
+optional in Android 4.2 but <b>will be required</b> in future versions. Existing and
+new devices that run Android 4.2 are <b>very strongly encouraged to meet these requirements
+in Android 4.2</b> so they will be able to upgrade to the future platform releases
+</li>
+<li>MUST comply with the Android sensor coordinate system as detailed
+in the Android APIs (see [<a href="#resources41">Resources, 41</a>])</li>
+<li>MUST be capable of measuring from freefall up to twice gravity (2g) or
+more on any three-dimensional vector</li>
+<li>MUST have 8-bits of accuracy or more</li>
+<li>MUST have a standard deviation no greater than 0.05 m/s^2</li>
+</ul>
+<a name="section-7.3.2"></a><h4>7.3.2. Magnetometer</h4>
+<p>Device implementations SHOULD include a 3-axis magnetometer (i.e. compass.)
+If a device does include a 3-axis magnetometer, it:</p>
+<ul>
+<li>MUST be able to deliver events at 10 Hz or greater</li>
+<li>MUST comply with the Android sensor coordinate system as detailed
+in the Android APIs (see [<a href="#resources41">Resources, 41</a>]).</li>
+<li>MUST be capable of sampling a range of field strengths adequate to cover the
+geomagnetic field</li>
+<li>MUST have 8-bits of accuracy or more</li>
+<li>MUST have a standard deviation no greater than 0.5 µT</li>
+</ul>
+<a name="section-7.3.3"></a><h4>7.3.3. GPS</h4>
+<p>Device implementations SHOULD include a GPS receiver. If a device
+implementation does include a GPS receiver, it SHOULD include
+some form of "assisted GPS" technique to minimize GPS lock-on time.</p>
+<a name="section-7.3.4"></a><h4>7.3.4. Gyroscope</h4>
+<p>Device implementations SHOULD include a gyroscope (i.e. angular change
+sensor.) Devices SHOULD NOT include a gyroscope sensor unless a 3-axis
+accelerometer is also included. If a device implementation includes a
+gyroscope, it:</p>
+<ul>
+<li>MUST be temperature compensated</li>
+<li>MUST be capable of measuring orientation changes up to 5.5*Pi
+radians/second (that is, approximately 1,000 degrees per second)</li>
+<li>SHOULD be able to deliver events at 200 Hz or greater. Note that while the
+gyroscope frequency above is stated as "SHOULD" for Android 4.2, the Compatibility Definition
+for a future version is planned to change these to "MUST". That is, these standards are
+optional in Android 4.2 but <b>will be required</b> in future versions. Existing and
+new devices that run Android 4.2 are <b>very strongly encouraged to meet these requirements
+in Android 4.2</b> so they will be able to upgrade to the future platform releases
+</li>
+<li>MUST have 12-bits of accuracy or more</li>
+<li>MUST have a variance no greater than 1e-7 rad^2 / s^2 per Hz (variance per Hz, or rad^2 / s).
+The variance is allowed to vary with the sampling rate, but must be constrained by this value.
+In other words, if you measure the variance of the gyro at 1 Hz sampling rate it should be no
+greater than 1e-7 rad^2/s^2. </li>
+<li>MUST have timestamps as close to when the hardware event happened as possible. The constant latency must be removed.</li>
+</ul>
+<a name="section-7.3.5"></a><h4>7.3.5. Barometer</h4>
+<p>Device implementations MAY include a barometer (i.e. ambient air pressure
+sensor.) If a device implementation includes a barometer, it:</p>
+<ul>
+<li>MUST be able to deliver events at 5 Hz or greater</li>
+<li>MUST have adequate precision to enable estimating altitude</li>
+<li>MUST be temperature compensated</li>
+</ul>
+<a name="section-7.3.6"></a><h4>7.3.7. Thermometer</h4>
+<p>Device implementations MAY but SHOULD NOT include a thermometer (i.e.
+temperature sensor.) If a device implementation does include a thermometer, it
+MUST measure the temperature of the device CPU. It MUST NOT measure any other
+temperature. (Note that this sensor type is deprecated in the Android 4.2
+APIs.)</p>
+<a name="section-7.3.7"></a><h4>7.3.7. Photometer</h4>
+<p>Device implementations MAY include a photometer (i.e. ambient light
+sensor.)</p>
+<a name="section-7.3.8"></a><h4>7.3.8. Proximity Sensor</h4>
+<p>Device implementations MAY include a proximity sensor. If a device
+implementation does include a proximity sensor, it MUST measure the proximity
+of an object in the same direction as the screen. That is, the proximity
+sensor MUST be oriented to detect objects close to the screen, as the
+primary intent of this sensor type is to detect a phone in use by the
+user. If a device implementation includes a proximity sensor with any other
+orientation, it MUST NOT be accessible through this API. If a device
+implementation has a proximity sensor, it MUST be have 1-bit of accuracy or
+more.</p>
+
+<a name="section-7.4"></a><h3>7.4. Data Connectivity</h3>
+<a name="section-7.4.1"></a><h4>7.4.1. Telephony</h4>
+<p>"Telephony" as used by the Android 4.2 APIs and this document refers
+specifically to hardware related to placing voice calls and sending SMS
+messages via a GSM or CDMA network. While these voice calls may or may not be
+packet-switched, they are for the purposes of Android 4.2 considered
+independent of any data connectivity that may be implemented using the same
+network. In other words, the Android "telephony" functionality and APIs refer
+specifically to voice calls and SMS; for instance, device implementations that
+cannot place calls or send/receive SMS messages MUST NOT report the
+"android.hardware.telephony" feature or any sub-features, regardless of
+whether they use a cellular network for data connectivity.</p>
+<p>Android 4.2 MAY be used on devices that do not include telephony hardware.
+That is, Android 4.2 is compatible with devices that are not phones.
+However, if a device implementation does include GSM or CDMA telephony, it
+MUST implement full support for the API for that technology. Device
+implementations that do not include telephony hardware MUST implement the full
+APIs as no-ops.</p>
+<a name="section-7.4.2"></a><h4>7.4.2. IEEE 802.11 (WiFi)</h4>
+<p>Android 4.2 device implementations SHOULD include support for one or more
+forms of 802.11 (b/g/a/n, etc.) If a device implementation does include
+support for 802.11, it MUST implement the corresponding Android API.</p>
+<p>Device implementations MUST implement the multicast API as described in
+the SDK documentation [<a href="#resources62">Resources, 62</a>]. Device
+implementations that do include Wifi support MUST support multicast DNS (mDNS).
+Device implementations MUST not filter mDNS packets (224.0.0.251) at any time
+of operation including when the screen is not in an active state.</p>
+
+<a name="section-7.4.2.1"></a><h4>7.4.2.1. WiFi Direct</h4>
+<p>Device implementations SHOULD include support for Wifi direct (Wifi peer-to-peer).
+If a device implementation does include support for Wifi direct, it MUST implement the corresponding
+Android API as described in the SDK documentation [<a href="#resources68">Resources, 68</a>].
+If a device implementation includes support for Wifi direct, then it:</p>
+<ul>
+ <li>MUST support regular Wifi operation</li>
+ <li>SHOULD support concurrent wifi and wifi Direct operation</li>
+</ul>
+
+<a name="section-7.4.3"></a><h4>7.4.3. Bluetooth</h4>
+<p>Device implementations SHOULD include a Bluetooth transceiver. Device
+implementations that do include a Bluetooth transceiver MUST enable the
+RFCOMM-based Bluetooth API as described in the SDK documentation [<a
+href="#resources42">Resources, 42</a>]. Device implementations SHOULD
+implement relevant Bluetooth profiles, such as A2DP, AVRCP, OBEX, etc. as
+appropriate for the device.</p>
+<p>The Compatibility Test Suite includes cases that cover basic operation of
+the Android RFCOMM Bluetooth API. However, since Bluetooth is a communications
+protocol between devices, it cannot be fully tested by unit tests running on a
+single device. Consequently, device implementations MUST also pass the
+human-driven Bluetooth test procedure described in Appendix A.</p>
+
+<a name="section-7.4.4"></a><h4>7.4.4. Near-Field Communications</h4>
+<p>Device implementations SHOULD include a transceiver and related hardware
+for Near-Field Communications (NFC). If a device implementation does include
+NFC hardware, then it:</p>
+<ul>
+ <li>MUST report the android.hardware.nfc feature from the
+ <code>android.content.pm.PackageManager.hasSystemFeature()</code> method.
+ [<a href="#resources37">Resources, 37</a>]</li>
+ <li>MUST be capable of reading and writing NDEF messages via the following NFC
+ standards:
+ <ul>
+ <li>MUST be capable of acting as an NFC Forum reader/writer
+ (as defined by the NFC Forum technical specification
+ NFCForum-TS-DigitalProtocol-1.0) via the following NFC standards:
+ <ul>
+ <li>NfcA (ISO14443-3A)</li>
+ <li>NfcB (ISO14443-3B) </li>
+ <li>NfcF (JIS 6319-4)</li>
+ <li>IsoDep (ISO 14443-4)</li>
+ <li>NFC Forum Tag Types 1, 2, 3, 4 (defined by the NFC Forum)</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>SHOULD be capable of reading and writing NDEF messages via the following
+ NFC standards. Note that while the NFC standards below are stated as
+ "SHOULD" for Android 4.2, the Compatibility Definition for a future
+ version is planned to change these to "MUST". That is, these standards are
+ optional in Android 4.2 but <b>will be required</b> in future versions.
+ Existing and new devices that run Android 4.2 are <b>very strongly
+ encouraged to meet these requirements in Android 4.2</b> so they will be
+ able to upgrade to the future platform releases.
+ <ul>
+ <li>NfcV (ISO 15693)</li>
+ </ul>
+ </li>
+ <li>MUST be capable of transmitting and receiving data via the following
+ peer-to-peer standards and protocols:
+ <ul>
+ <li>ISO 18092</li>
+ <li>LLCP 1.0 (defined by the NFC Forum)</li>
+ <li>SDP 1.0 (defined by the NFC Forum)</li>
+ <li>NDEF Push Protocol [<a href="#resources43">Resources, 43</a>]</li>
+ <li>SNEP 1.0 (defined by the NFC Forum)</li>
+ </ul>
+ </li>
+ <li>MUST include support for Android Beam [<a href="#resources65">Resources, 65</a>]:
+ <ul>
+ <li>MUST implement the SNEP default server. Valid NDEF messages received
+ by the default SNEP server MUST be dispatched to applications using
+ the android.nfc.ACTION_NDEF_DISCOVERED intent. Disabling Android Beam
+ in settings MUST NOT disable dispatch of incoming NDEF message.</li>
+ <li>Device implementations MUST honor the android.settings.NFCSHARING_SETTINGS intent
+ to show NFC sharing settings [<a href="#resources67">Resources, 67</a>].</li>
+ <li>MUST implement the NPP server. Messages received by the NPP server MUST
+ be processed the same way as the SNEP default server.</li>
+ <li>MUST implement a SNEP client and attempt to send outbound P2P NDEF to
+ the default SNEP server when Android Beam is enabled. If no default
+ SNEP server is found then the client MUST attempt to send to an NPP
+ server.</li>
+ <li>MUST allow foreground activities to set the outbound P2P NDEF message
+ using android.nfc.NfcAdapter.setNdefPushMessage, and
+ android.nfc.NfcAdapter.setNdefPushMessageCallback, and
+ android.nfc.NfcAdapter.enableForegroundNdefPush.</li>
+ <li>SHOULD use a gesture or on-screen confirmation, such as 'Touch to Beam',
+ before sending outbound P2P NDEF messages.</li>
+ <li>SHOULD enable Android Beam by default</li>
+ <li>MUST support NFC Connection handover to Bluetooth when the device supports Bluetooth Object Push Profile.
+ Device implementations must support connection handover to Bluetooth when using android.nfc.NfcAdapter.setBeamPushUris,
+ by implementing the "Connection Handover version 1.2" [<a href="#resources60">Resources, 60</a>]
+ and "Bluetooth Secure Simple Pairing Using NFC version 1.0" [<a href="#resources61">Resources, 61</a>]
+ specs from the NFC Forum. Such an implementation SHOULD use SNEP GET
+ requests for exchanging the handover request / select records over NFC, and it MUST
+ use the Bluetooth Object Push Profile for the actual Bluetooth data transfer.</li>
+ </ul>
+ </li>
+ <li>MUST poll for all supported technologies while in NFC discovery mode.</li>
+ <li>SHOULD be in NFC discovery mode while the device is awake with the screen active
+ and the lock-screen unlocked.</li>
+</ul>
+
+<p>(Note that publicly available links are not available for the JIS, ISO, and
+NFC Forum specifications cited above.)</p>
+<p>Additionally, device implementations MAY include reader/writer support for
+the following MIFARE technologies.</p>
+<ul>
+ <li>MIFARE Classic (NXP MF1S503x [<a href="#resources44">Resources, 44</a>],
+ MF1S703x [<a href="#resources44">Resources, 44</a>])</li>
+ <li>MIFARE Ultralight (NXP MF0ICU1 [<a href="#resources46">Resources, 46</a>],
+ MF0ICU2 [<a href="#resources46">Resources, 46</a>])</li>
+ <li>NDEF on MIFARE Classic (NXP AN130511 [<a href="#resources48">Resources, 48</a>],
+ AN130411 [<a href="#resources49">Resources, 49</a>])</li>
+</ul>
+<p>Note that Android 4.2 includes APIs for these MIFARE types. If a
+device implementation supports MIFARE in the reader/writer role, it:</p>
+<ul>
+ <li>MUST implement the corresponding Android APIs as documented by the
+ Android SDK</li>
+ <li>MUST report the feature com.nxp.mifare from the
+ <code>android.content.pm.PackageManager.hasSystemFeature()</code> method.
+ [<a href="#resources37">Resources, 37</a>] Note that this is not a standard
+ Android feature, and as such does not appear as a constant on the
+ <code>PackageManager</code> class.</li>
+ <li>MUST NOT implement the corresponding Android APIs nor report the
+ com.nxp.mifare feature unless it also implements general NFC support as
+ described in this section</li>
+</ul>
+<p>If a device implementation does not include NFC hardware, it MUST NOT
+declare the android.hardware.nfc feature from the
+<code>android.content.pm.PackageManager.hasSystemFeature()</code> method [<a
+href="#resources37">Resources, 37</a>], and MUST implement the Android 4.2 NFC
+API as a no-op.</p>
+<p>As the classes <code>android.nfc.NdefMessage</code> and
+<code>android.nfc.NdefRecord</code> represent a protocol-independent data
+representation format, device implementations MUST implement these APIs even
+if they do not include support for NFC or declare the android.hardware.nfc
+feature.</p>
+<a name="section-7.4.5"></a><h4>7.4.5. Minimum Network Capability</h4>
+<p>Device implementations MUST include support for one or more forms of data
+networking. Specifically, device implementations MUST include support for at
+least one data standard capable of 200Kbit/sec or greater. Examples of
+technologies that satisfy this requirement include EDGE, HSPA, EV-DO, 802.11g,
+Ethernet, etc.</p>
+<p>Device implementations where a physical networking standard (such as
+Ethernet) is the primary data connection SHOULD also include support for at
+least one common wireless data standard, such as 802.11 (WiFi).</p>
+<p>Devices MAY implement more than one form of data connectivity.</p>
+
+
+<a name="section-7.5"></a><h3>7.5. Cameras</h3>
+<p>Device implementations SHOULD include a rear-facing camera, and MAY include
+a front-facing camera. A rear-facing camera is a camera located on the side of
+the device opposite the display; that is, it images scenes on the far side of
+the device, like a traditional camera. A front-facing camera is a camera
+located on the same side of the device as the display; that is, a camera
+typically used to image the user, such as for video conferencing and similar
+applications.</p>
+<a name="section-7.5.1"></a><h4>7.5.1. Rear-Facing Camera</h4>
+<p>Device implementations SHOULD include a rear-facing camera. If a device
+implementation includes a rear-facing camera, it:</p>
+<ul>
+<li>MUST have a resolution of at least 2 megapixels</li>
+<li>SHOULD have either hardware auto-focus, or software auto-focus implemented
+in the camera driver (transparent to application software)</li>
+<li>MAY have fixed-focus or EDOF (extended depth of field) hardware</li>
+<li>MAY include a flash. If the Camera includes a flash, the flash lamp MUST
+NOT be lit while an android.hardware.Camera.PreviewCallback instance has been
+registered on a Camera preview surface, unless the application has explicitly
+enabled the flash by enabling the <code>FLASH_MODE_AUTO</code> or
+<code>FLASH_MODE_ON</code> attributes of a <code>Camera.Parameters</code>
+object. Note that this constraint does not apply to the device's built-in
+system camera application, but only to third-party applications using
+<code>Camera.PreviewCallback</code>.</li>
+</ul>
+<a name="section-7.5.2"></a><h4>7.5.2. Front-Facing Camera</h4>
+<p>Device implementations MAY include a front-facing camera. If a device
+implementation includes a front-facing camera, it:</p>
+<ul>
+<li>MUST have a resolution of at least VGA (that is, 640x480 pixels)</li>
+<li>MUST NOT use a front-facing camera as the default for the Camera API.
+That is, the camera API in Android 4.2 has specific support for front-facing
+cameras, and device implementations MUST NOT configure the API to to treat a
+front-facing camera as the default rear-facing camera, even if it is the only
+camera on the device.</li>
+<li>MAY include features (such as auto-focus, flash, etc.)
+available to rear-facing cameras as described in Section 7.5.1.</li>
+<li>MUST horizontally reflect (i.e. mirror) the stream displayed by an app in a
+CameraPreview, as follows:</li>
+<ul>
+<li>If the device implementation is capable of being rotated by user (such as
+automatically via an accelerometer or manually via user input), the camera
+preview MUST be mirrored horizontally relative to the device's current
+orientation.</li>
+<li>If the current application has explicitly requested that the Camera
+display be rotated via a call to the
+<code>android.hardware.Camera.setDisplayOrientation()</code> [<a
+href="#resources50">Resources, 50</a>] method, the camera preview MUST be
+mirrored horizontally relative to the orientation specified by the
+application.</li>
+<li>Otherwise, the preview MUST be mirrored along the device's default horizontal axis.</li>
+</ul>
+<li>MUST mirror the image displayed by the postview in the same manner as
+the camera preview image stream. (If the device implementation does not
+support postview, this requirement obviously does not apply.)</li>
+<li>MUST NOT mirror the final captured still image or video streams returned
+to application callbacks or committed to media storage</li>
+</ul>
+<a name="section-7.5.3"></a><h4>7.5.3. Camera API Behavior</h4>
+<p>Device implementations MUST implement the following behaviors for the
+camera-related APIs, for both front- and rear-facing cameras:</p>
+<ol>
+<li>If an application has never called
+<code>android.hardware.Camera.Parameters.setPreviewFormat(int)</code>, then the
+device MUST use <code>android.hardware.PixelFormat.YCbCr_420_SP</code> for
+preview data provided to application callbacks.</li>
+<li>If an application registers an <code>android.hardware.Camera.PreviewCallback
+</code> instance and the system calls the <code>onPreviewFrame()</code> method
+when the preview format is YCbCr_420_SP, the data in the <code>byte[]</code>
+passed into <code>onPreviewFrame()</code> must further be in the NV21 encoding
+format. That is, NV21 MUST be the default.</li>
+<li>Device implementations MUST support the YV12 format (as denoted by the
+<code>android.graphics.ImageFormat.YV12</code> constant) for camera previews
+for both front- and rear-facing cameras. (The hardware video encoder and camera
+may use any native pixel format, but the device implementation MUST support conversion
+to YV12.)</li>
+</ol>
+<p>Device implementations MUST implement the full Camera API included in the
+Android 4.2 SDK documentation [<a href="#resources51">Resources, 51</a>]),
+regardless of whether the device includes hardware autofocus or other
+capabilities. For instance, cameras that lack autofocus MUST still call any
+registered <code>android.hardware.Camera.AutoFocusCallback</code> instances (even though
+this has no relevance to a non-autofocus camera.) Note that this does apply
+to front-facing cameras; for instance, even though most front-facing cameras
+do not support autofocus, the API callbacks must still be "faked" as
+described.</p>
+<p>Device implementations MUST recognize and honor each parameter name defined
+as a constant on the <code>android.hardware.Camera.Parameters</code> class, if the
+underlying hardware supports the feature. If the device hardware does not
+support a feature, the API must behave as documented. Conversely, Device
+implementations MUST NOT honor or recognize string constants passed
+to the <code>android.hardware.Camera.setParameters()</code> method other than
+those documented as constants on the
+<code>android.hardware.Camera.Parameters</code>. That is,
+device implementations MUST support all standard Camera parameters if the
+hardware allows, and MUST NOT support custom Camera parameter types.
+For instance, device implementations that support image capture using high dynamic range (HDR)
+imaging techniques MUST support camera parameter <code>Camera.SCENE_MODE_HDR</code>
+[<a href="#resources78">Resources, 78</a>]).</p>
+<p>Device implementations MUST broadcast the <code>Camera.ACTION_NEW_PICTURE</code>
+intent whenever a new picture is taken by the camera and the entry of the picture
+has been added to the media store.</p>
+<p>Device implementations MUST broadcast the <code>Camera.ACTION_NEW_VIDEO</code>
+intent whenever a new video is recorded by the camera and the entry of the picture
+has been added to the media store.</p>
+<a name="section-7.5.4"></a><h4>7.5.4. Camera Orientation</h4>
+<p>Both front- and rear-facing cameras, if present, MUST be oriented so that
+the long dimension of the camera aligns with the screen's long dimention. That
+is, when the device is held in the landscape orientation, cameras MUST
+capture images in the landscape orientation. This applies regardless of the
+device's natural orientation; that is, it applies to landscape-primary devices
+as well as portrait-primary devices.</p>
+
+<a name="section-7.6"></a><h3>7.6. Memory and Storage</h3>
+<a name="section-7.6.1"></a><h4>7.6.1. Minimum Memory and Storage</h4>
+<p>Device implementations MUST have at least 340MB of memory available to the
+kernel and userspace. The 340MB MUST be in addition to any memory dedicated to
+hardware components such as radio, video, and so on that is not under the
+kernel's control.</p>
+<p>Device implementations MUST have at least 350MB of non-volatile storage
+available for application private data. That is, the <code>/data</code> partition MUST be at
+least 350MB.</p>
+<p>The Android APIs include a Download Manager that applications may use to
+download data files [<a href="#resources56">Resources, 56</a>]. The device
+implementation of the Download Manager MUST be capable of downloading individual
+files of at least 100MB in size to the default "cache" location.</p>
+<a name="section-7.6.2"></a><h4>7.6.2. Application Shared Storage</h4>
+<p>Device implementations MUST offer shared storage for applications. The
+shared storage provided MUST be at least 1GB in size.</p>
+<p>Device implementations MUST be configured with shared storage mounted by
+default, "out of the box". If the shared storage is not mounted on the Linux
+path <code>/sdcard</code>, then the device MUST include a Linux symbolic link
+from <code>/sdcard</code> to the actual mount point.</p>
+<p>Device implementations MUST enforce as documented the
+<code>android.permission.WRITE_EXTERNAL_STORAGE</code> permission on this
+shared storage. Shared storage MUST otherwise be writable by any application
+that obtains that permission.</p>
+<p>Device implementations MAY have hardware for user-accessible removable
+storage, such as a Secure Digital card. Alternatively, device implementations
+MAY allocate internal (non-removable) storage as shared storage for apps.</p>
+<p>Regardless of the form of shared storage used, device implementations MUST
+provide some mechanism to access the contents of shared storage from a host
+computer, such as USB mass storage (UMS) or Media Transfer Protocol (MTP). Device
+implementations MAY use USB mass storage, but SHOULD use Media Transfer
+Protocol. If the device implementation supports Media Transfer Protocol:</p>
+<ul>
+<li>The device implementation SHOULD be compatible with the reference Android
+MTP host, Android File Transfer [<a href="#resources57">Resources, 57</a>].</li>
+<li>The device implementation SHOULD report a USB device class of <code>0x00</code>.</li>
+<li>The device implementation SHOULD report a USB interface name of 'MTP'.</li>
+</ul>
+<p>If the device implementation lacks USB ports, it MUST provide a host
+computer with access to the contents of shared storage by some other means,
+such as a network file system.</p>
+<p>It is illustrative to consider two common examples. If a device
+implementation includes an SD card slot to satisfy the shared storage
+requirement, a FAT-formatted SD card 1GB in size or larger MUST be included
+with the device as sold to users, and MUST be mounted by default.
+Alternatively, if a device implementation uses internal fixed storage to
+satisfy this requirement, that storage MUST be 1GB in size or larger
+and mounted on <code>/sdcard</code> (or <code>/sdcard</code>
+MUST be a symbolic link to the physical location if it is mounted elsewhere.)</p>
+<p>Device implementations that include multiple shared storage paths (such as
+both an SD card slot and shared internal storage) SHOULD modify the core
+applications such as the media scanner and ContentProvider to transparently
+support files placed in both locations.</p>
+
+<a name="section-7.7"></a><h3>7.7. USB</h3>
+<p>Device implementations SHOULD include a USB client port, and SHOULD include
+a USB host port.</p>
+<p>If a device implementation includes a USB client port:</p>
+<ul>
+<li>the port MUST be connectable to a USB host with a standard USB-A port</li>
+<li>the port SHOULD use the micro USB form factor on the device side. Existing and
+new devices that run Android 4.2 are <b>very strongly encouraged to meet these requirements
+in Android 4.2</b> so they will be able to upgrade to the future platform releases</li>
+<li>the port SHOULD be centered in the middle of an edge. Device implementations SHOULD either
+locate the port on the bottom of the device (according to natural orientation) or enable software
+screen rotation for all apps (including home screen), so that the display draws correctly when the device
+is oriented with the port at bottom. Existing and new devices that run Android 4.2 are <b>very strongly
+encouraged to meet these requirements in Android 4.2</b> so they will be able to upgrade to future platform releases.</li>
+<li>if the device has other ports (such as a non-USB charging port) it SHOULD be on the same edge as the
+micro-USB port</li>
+<li>it MUST allow a host connected to the device to access the contents of the
+shared storage volume using either USB mass storage or Media Transfer
+Protocol</li>
+<li>it MUST implement the Android Open Accessory API and specification as documented
+in the Android SDK documentation, and MUST declare support for the hardware
+feature <code>android.hardware.usb.accessory</code> [<a href="#resources52">Resources,
+52</a>]</li>
+<li>it MUST implement the USB audio class as documented in the Android SDK documentation [<a href="#resources66">Resources, 66</a>]</li>
+<li>it SHOULD implement support for USB battery charging specification [<a href="#resources64">Resources, 64</a>]
+Existing and new devices that run Android 4.2 are <b>very strongly encouraged to meet these requirements in Android 4.2</b>
+so they will be able to upgrade to the future platform releases</li>
+
+</ul>
+<p>If a device implementation includes a USB host port:</p>
+<ul>
+<li>it MAY use a non-standard port form factor, but if so MUST ship with a
+cable or cables adapting the port to standard USB-A</li>
+<li>it MUST implement the Android USB host API as documented in the Android
+SDK, and MUST declare support for the hardware feature
+<code>android.hardware.usb.host</code> [<a href="#resources53">Resources, 53</a>]</li>
+</ul>
+<p>Device implementations MUST implement the Android Debug Bridge. If a device
+implementation omits a USB client port, it MUST implement the Android Debug
+Bridge via local-area network (such as Ethernet or 802.11)</p>
+
+<a name="section-8"></a><h2>8. Performance Compatibility</h2>
+<p>Device implementations MUST meet the key performance metrics of an Android
+4.2 compatible device defined in the table below:</p>
+<table><tbody><tr>
+<td><b>Metric</b></td>
+<td><b>Performance Threshold</b></td>
+<td><b>Comments</b></td>
+</tr>
+<tr>
+<td>Application Launch Time</td>
+<td>The following applications should launch within the specified time.<ul>
+<li>Browser: less than 1300ms</li>
+<li>Contacts: less than 700ms</li>
+<li>Settings: less than 700ms</li>
+</ul></td>
+<td>The launch time is measured as the total time to
+complete loading the default activity for the application, including the time
+it takes to start the Linux process, load the Android package into the Dalvik
+VM, and call onCreate.</td>
+</tr>
+<tr>
+<td>Simultaneous Applications</td>
+<td>When multiple applications have been launched, re-launching an
+already-running application after it has been launched must take less than the
+original launch time.</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+
+<a name="section-9"></a><h2>9. Security Model Compatibility</h2>
+<p>Device implementations MUST implement a security model consistent with the
+Android platform security model as defined in Security and Permissions
+reference document in the APIs [<a href="#resources54">Resources, 54</a>] in the
+Android developer documentation. Device implementations MUST support
+installation of self-signed applications without requiring any additional
+permissions/certificates from any third parties/authorities. Specifically,
+compatible devices MUST support the security mechanisms described in the
+follow sub-sections.</p>
+<a name="section-9.1"></a><h3>9.1. Permissions</h3>
+<p>Device implementations MUST support the Android permissions model as
+defined in the Android developer documentation [<a
+href="#resources54">Resources, 54</a>]. Specifically,
+implementations MUST enforce each permission defined as described in the SDK
+documentation; no permissions may be omitted, altered, or ignored.
+Implementations MAY add additional permissions, provided the new permission ID
+strings are not in the android.* namespace.</p>
+<a name="section-9.2"></a><h3>9.2. UID and Process Isolation</h3>
+<p>Device implementations MUST support the Android application sandbox model,
+in which each application runs as a unique Unix-style UID and in a separate
+process. Device implementations MUST support running multiple applications as
+the same Linux user ID, provided that the applications are properly signed and
+constructed, as defined in the Security and Permissions reference [<a
+href="#resources54">Resources, 54</a>].</p>
+<a name="section-9.3"></a><h3>9.3. Filesystem Permissions</h3>
+<p>Device implementations MUST support the Android file access permissions
+model as defined in as defined in the Security and Permissions reference [<a
+href="#resources54">Resources, 54</a>].</p>
+<a name="section-9.4"></a><h3>9.4. Alternate Execution Environments</h3>
+<p>Device implementations MAY include runtime environments that execute
+applications using some other software or technology than the Dalvik virtual
+machine or native code. However, such alternate execution environments MUST
+NOT compromise the Android security model or the security of installed Android
+applications, as described in this section.</p>
+<p>Alternate runtimes MUST themselves be Android applications, and abide by
+ the standard Android security model, as described elsewhere in Section 9.</p>
+<p>Alternate runtimes MUST NOT be granted access to resources protected by
+ permissions not requested in the runtime's AndroidManifest.xml file via the
+ <code><uses-permission></code> mechanism.</p>
+<p>Alternate runtimes MUST NOT permit applications to make use of features
+ protected by Android permissions restricted to system applications.</p>
+<p>Alternate runtimes MUST abide by the Android sandbox model. Specifically:</p>
+<ul>
+<li>Alternate runtimes SHOULD install apps via the PackageManager into
+ separate Android sandboxes (that is, Linux user IDs, etc.)</li>
+<li>Alternate runtimes MAY provide a single Android sandbox shared by all
+ applications using the alternate runtime</li>
+<li>Alternate runtimes and installed applications using an alternate runtime
+ MUST NOT reuse the sandbox of any other app installed on the device, except
+ through the standard Android mechanisms of shared user ID and signing
+ certificate</li>
+<li>Alternate runtimes MUST NOT launch with, grant, or be granted access to
+ the sandboxes corresponding to other Android applications</li>
+</ul>
+<p>Alternate runtimes MUST NOT be launched with, be granted, or grant to other
+ applications any privileges of the superuser (root), or of any other user ID.</p>
+<p>The .apk files of alternate runtimes MAY be included in the system image of
+ a device implementation, but MUST be signed with a key distinct
+ from the key used to sign other applications included with the device
+ implementation.</p>
+<p>When installing applications, alternate runtimes MUST obtain user consent
+ for the Android permissions used by the application. That is, if an
+ application needs to make use of a device resource for which there is a
+ corresponding Android permission (such as Camera, GPS, etc.), the alternate
+ runtime MUST inform the user that the application will be able to access
+ that resource. If the runtime environment does not record application
+ capabilities in this manner, the runtime environment MUST list all
+ permissions held by the runtime itself when installing any application
+ using that runtime.</p>
+
+<a name="section-9.5"></a><h3>9.5. Multi-User Support </h3>
+<p>Android 4.2 includes support for multiple users and provides support for full user isolation
+[<a href="#resources70">Resources, 70</a>].</p>
+<p>Device implementations MUST meet these requirements related to multi-user support[<a href="#resources71">Resources, 71</a>]:</p>
+<ul>
+<li>As the behavior of the telephony APIs on devices with multiple users is currently undefined, device implementations that
+declare android.hardware.telephony MUST NOT enable multi-user support. </li>
+<li>Device implementations MUST, for each user, implement a security model consistent with the Android platform security model
+as defined in Security and Permissions reference document in the APIs [Resources, 54]</li>
+</ul>
+</p>
+
+<p>Each user instance on an Android device MUST have separate and isolated external storage directories. Device implementations MAY store multiple users' data on the same volume or filesystem.
+However, the device implementation MUST ensure that applications owned by and running on behalf a given user cannot list, read, or write to data owned by any other user.
+Note that removable media, such as SD card slots, can allow one user to access another's data by means of a host PC. For this reason, device implementations that use removable media for the
+external storage APIs MUST encrypt the contents of the SD card if multi-user is enabled using a key stored only on non-removable media accessible only to the system. As this will make the
+media unreadable by a host PC, device implementations will be required to switch to MTP or a similar system to provide host PCs with access to the current user's data. Accordingly, device
+implementations MAY but SHOULD NOT enable multi-user if they use removable media [<a href="#resources72">Resources, 72</a>] for primary external storage. The upstream Android open-source
+project includes an implementation that uses internal device storage for application external storage APIs; device implementations SHOULD use this configuration and software implementation.
+Device implementations that include multiple external storage paths MUST NOT allow Android applications to write to the secondary external storage</p>
+
+<a name="section-9.6"></a><h3>9.6. Premium SMS Warning</h3>
+<p>Android 4.2 includes support for warning users for any outgoing premium SMS message. Premium SMS messages are text messages sent to a service registered with a carrier that may incur a charge to the user.
+Device implementations that declare support for <code>android.hardware.telephony</code> MUST warn users before sending a SMS message to numbers identified by regular expressions defined in <code>/data/misc/sms/codes.xml</code> file in the device.
+The upstream Android open-source project provides an implementation that satisfies this requirement.
+</p>
+
+<a name="section-10"></a><h2>10. Software Compatibility Testing</h2>
+<p>Device implementations MUST pass all tests described in this section.</p>
+<p>However, note that no software test package is fully comprehensive. For
+this reason, device implementers are very strongly encouraged to make the
+minimum number of changes as possible to the reference and preferred
+implementation of Android 4.2 available from the Android Open Source Project.
+This will minimize the risk of introducing bugs that create incompatibilities
+requiring rework and potential device updates.</p>
+<a name="section-10.1"></a><h3>10.1. Compatibility Test Suite</h3>
+<p>Device implementations MUST pass the Android Compatibility Test Suite (CTS)
+[<a href="#resources02">Resources, 2</a>] available from the Android Open Source
+Project, using the final shipping software on the device. Additionally, device
+implementers SHOULD use the reference implementation in the Android Open
+Source tree as much as possible, and MUST ensure compatibility in cases of
+ambiguity in CTS and for any reimplementations of parts of the reference
+source code.</p>
+<p>The CTS is designed to be run on an actual device. Like any software, the
+CTS may itself contain bugs. The CTS will be versioned independently of this
+Compatibility Definition, and multiple revisions of the CTS may be released
+for Android 4.2. Device implementations MUST pass the latest CTS version
+available at the time the device software is completed.</p>
+<a name="section-10.2"></a><h3>10.2. CTS Verifier</h3>
+<p>Device implementations MUST correctly execute all applicable cases in the
+CTS Verifier. The CTS Verifier is included with the Compatibility Test Suite,
+and is intended to be run by a human operator to test functionality that
+cannot be tested by an automated system, such as correct functioning of a
+camera and sensors.</p>
+<p>The CTS Verifier has tests for many kinds of hardware, including some
+hardware that is optional. Device implementations MUST pass all tests for
+hardware which they possess; for instance, if a device possesses an
+accelerometer, it MUST correctly execute the Accelerometer test case in the
+CTS Verifier. Test cases for features noted as optional by this Compatibility
+Definition Document MAY be skipped or omitted.</p>
+<p>Every device and every build MUST correctly run the CTS Verifier, as noted
+above. However, since many builds are very similar, device implementers are
+not expected to explicitly run the CTS Verifier on builds that differ only in
+trivial ways. Specifically, device implementations that differ from an
+implementation that has passed the CTS Verfier only by the set of included
+locales, branding, etc. MAY omit the CTS Verifier test.</p>
+<a name="section-10.3"></a><h3>10.3. Reference Applications</h3>
+<p>Device implementers MUST test implementation compatibility using the
+following open source applications:</p>
+<ul>
+<li>The "Apps for Android" applications [<a href="#resources55">Resources, 55</a>]</li>
+<li>Replica Island (available in Android Market)</li>
+</ul>
+<p>Each app above MUST launch and behave correctly on the implementation, for
+the implementation to be considered compatible.</p>
+
+
+<a name="section-11"></a><h2>11. Updatable Software</h2>
+<p>Device implementations MUST include a mechanism to replace the entirety of
+the system software. The mechanism need not perform "live" upgrades - that
+is, a device restart MAY be required.</p>
+<p>Any method can be used, provided that it can replace the entirety of the
+software preinstalled on the device. For instance, any of the following
+approaches will satisfy this requirement:</p>
+<ul>
+<li>Over-the-air (OTA) downloads with offline update via reboot</li>
+<li>"Tethered" updates over USB from a host PC</li>
+<li>"Offline" updates via a reboot and update from a file on removable
+storage</li>
+</ul>
+<p>The update mechanism used MUST support updates without wiping user data.
+That is, the update mechanism MUST preserve application private data
+and application shared data. Note that the upstream Android software includes
+an update mechanism that satisfies this requirement.</p>
+<p>If an error is found in a device implementation after it has been released
+but within its reasonable product lifetime that is determined in consultation
+with the Android Compatibility Team to affect the compatibility of third-party
+applications, the device implementer MUST correct the error via a software
+update available that can be applied per the mechanism just described.</p>
+
+<a name="section-12"></a><h2>12. Contact Us</h2>
+<p>You can contact the document authors at <a
+href="mailto:compatibility@android.com">compatibility@android.com</a> for
+clarifications and to bring up any issues that you think the document does not
+cover.</p>
+
+<div style="page-break-before: always;"></div>
+
+<a name="appendix-A"></a><h2>Appendix A - Bluetooth Test Procedure</h2>
+<p>The Compatibility Test Suite includes cases that cover basic operation of
+the Android RFCOMM Bluetooth API. However, since Bluetooth is a communications
+protocol between devices, it cannot be fully tested by unit tests running on a
+single device. Consequently, device implementations MUST also pass the
+human-operated Bluetooth test procedure described below.</p>
+<p>The test procedure is based on the BluetoothChat sample app included in the
+Android open source project tree. The procedure requires two devices:</p>
+<ul>
+<li>a candidate device implementation running the software build to be tested</li>
+<li>a separate device implementation already known to be compatible, and of a
+ model from the device implementation being tested - that is, a "known
+ good" device implementation</li>
+</ul>
+<p>The test procedure below refers to these devices as the "candidate" and "known
+good" devices, respectively.</p>
+<h3>Setup and Installation</h3>
+<ol>
+<li>Build BluetoothChat.apk via 'make samples' from an Android source code tree</li>
+<li>Install BluetoothChat.apk on the known-good device</li>
+<li>Install BluetoothChat.apk on the candidate device</li>
+</ol>
+<h3>Test Bluetooth Control by Apps</h3>
+<ol>
+<li>Launch BluetoothChat on the candidate device, while Bluetooth is disabled</li>
+<li>Verify that the candidate device either turns on Bluetooth, or prompts the user with a dialog to turn on Bluetooth</li>
+</ol>
+<h3>Test Pairing and Communication</h3>
+<ol>
+<li>Launch the Bluetooth Chat app on both devices</li>
+<li>Make the known-good device discoverable from within BluetoothChat (using the Menu)</li>
+<li>On the candidate device, scan for Bluetooth devices from within BluetoothChat (using the Menu) and pair with the known-good device</li>
+<li>Send 10 or more messages from each device, and verify that the other device receives them correctly</li>
+<li>Close the BluetoothChat app on both devices by pressing <b>Home</b></li>
+<li>Unpair each device from the other, using the device Settings app</li>
+</ol>
+<h3>Test Pairing and Communication in the Reverse Direction</h3>
+<ol>
+<li>Launch the Bluetooth Chat app on both devices.</li>
+<li>Make the candidate device discoverable from within BluetoothChat (using the Menu).</li>
+<li>On the known-good device, scan for Bluetooth devices from within BluetoothChat (using the Menu) and pair with the candidate device.</li>
+<li>Send 10 or messages from each device, and verify that the other device receives them correctly.</li>
+<li>Close the Bluetooth Chat app on both devices by pressing Back repeatedly to get to the Launcher.</li>
+</ol>
+<h3>Test Re-Launches</h3>
+<ol>
+<li>Re-launch the Bluetooth Chat app on both devices.</li>
+<li>Send 10 or messages from each device, and verify that the other device receives them correctly.</li>
+</ol>
+<p>Note: the above tests have some cases which end a test section by using
+Home, and some using Back. These tests are not redundant and are not optional:
+the objective is to verify that the Bluetooth API and stack works correctly
+both when Activities are explicitly terminated (via the user pressing Back,
+which calls finish()), and implicitly sent to background (via the user
+pressing Home.) Each test sequence MUST be performed as described.</p>
+<div id="footerContent" xmlns:pdf="http://whatever">
+<pdf:pagenumber/>
+</div>
+</body>
+</html>
diff --git a/src/compatibility/4.3/android-4.3-cdd.xhtml b/src/compatibility/4.3/android-4.3-cdd.xhtml
new file mode 100644
index 0000000..65ffc5c
--- /dev/null
+++ b/src/compatibility/4.3/android-4.3-cdd.xhtml
@@ -0,0 +1,2661 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>Android 4.3Compatibility Definition</title>
+<link rel="stylesheet" type="text/css" href="cdd.css"/>
+</head>
+<body>
+<div><img src="header.jpg" alt="Android logo"/></div>
+<h1>Android 4.3 Compatibility Definition</h1>
+<!--
+<span style="color: red; font-weight: bold;"><h2>Revision 1</h2></span><br/>
+<span style="color: red;">Last updated: July 23, 2013</span>
+-->
+<p><b><font color="red">Revision 1</font></b><br/>
+Last updated: July 23, 2013
+</p>
+<p>Copyright © 2013, Google Inc. All rights reserved.<br/>
+<a href="mailto:compatibility@android.com">compatibility@android.com</a>
+</p>
+
+<h2> Table of Contents</h2>
+<div style="margin-left: 2em;">
+ <a href="#section-1">1. Introduction</a><br/>
+ <a href="#section-2">2. Resources</a><br/>
+ <a href="#section-3">3. Software</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.1">3.1. Managed API Compatibility</a><br/>
+ <a href="#section-3.2">3.2. Soft API Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.2.1">3.2.1. Permissions</a><br/>
+ <a href="#section-3.2.2">3.2.2. Build Parameters</a><br/>
+ <a href="#section-3.2.3">3.2.3. Intent Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.2.3.1">3.2.3.1. Core Application Intents</a><br/>
+ <a href="#section-3.2.3.2">3.2.3.2. Intent Overrides</a><br/>
+ <a href="#section-3.2.3.3">3.2.3.3. Intent Namespaces</a><br/>
+ <a href="#section-3.2.3.4">3.2.3.4. Broadcast Intents</a><br/>
+ </div>
+ </div>
+ <a href="#section-3.3">3.3. Native API Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.3.1">3.3.1 Application Binary Interfaces</a><br/>
+ </div>
+ <a href="#section-3.4">3.4. Web Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.4.1">3.4.1. WebView Compatibility</a><br/>
+ <a href="#section-3.4.2">3.4.2. Browser Compatibility</a><br/>
+ </div>
+ <a href="#section-3.5">3.5. API Behavioral Compatibility</a><br/>
+ <a href="#section-3.6">3.6. API Namespaces</a><br/>
+ <a href="#section-3.7">3.7. Virtual Machine Compatibility</a><br/>
+ <a href="#section-3.8">3.8. User Interface Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-3.8.1">3.8.1. Launcher (Home Screen)</a><br/>
+ <a href="#section-3.8.2">3.8.2. Widgets</a><br/>
+ <a href="#section-3.8.3">3.8.3. Notifications</a><br/>
+ <a href="#section-3.8.4">3.8.4. Search</a><br/>
+ <a href="#section-3.8.5">3.8.5. Toasts</a><br/>
+ <a href="#section-3.8.6">3.8.6. Themes</a><br/>
+ <a href="#section-3.8.7">3.8.7. Live Wallpapers</a><br/>
+ <a href="#section-3.8.8">3.8.8. Recent Application Display</a><br/>
+ <a href="#section-3.8.9">3.8.9. Input Management</a><br/>
+ <a href="#section-3.8.10">3.8.10. Lock Screen Media Remote Control</a><br/>
+ <a href="#section-3.8.11">3.8.11. Dreams</a><br/>
+ </div>
+ <a href="#section-3.9">3.9 Device Administration</a><br/>
+ <a href="#section-3.10">3.10 Accessibility</a><br/>
+ <a href="#section-3.11">3.11 Text-to-Speech</a><br/>
+ </div>
+ <a href="#section-4">4. Application Packaging Compatibility</a><br/>
+ <a href="#section-5">5. Multimedia Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-5.1">5.1. Media Codecs</a><br/>
+ <a href="#section-5.2">5.2. Video Encoding</a><br/>
+ <a href="#section-5.3">5.3. Video Decoding</a><br/>
+ <a href="#section-5.4">5.4. Audio Recording</a><br/>
+ <a href="#section-5.5">5.5. Audio Latency</a><br/>
+ <a href="#section-5.6">5.6. Network Protocols</a><br/>
+ </div>
+ <a href="#section-6">6. Developer Tools and Options Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-6.1">6.1. Developer Tools</a><br/>
+ <a href="#section-6.2">6.2. Developer Options</a><br/>
+ </div>
+ <a href="#section-7">7. Hardware Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.1">7.1. Display and Graphics</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.1.1">7.1.1. Screen Configuration</a><br/>
+ <a href="#section-7.1.2">7.1.2. Display Metrics</a><br/>
+ <a href="#section-7.1.3">7.1.3. Screen Orientation</a><br/>
+ <a href="#section-7.1.4">7.1.4. 2D and 3D Graphics Acceleration</a><br/>
+ <a href="#section-7.1.5">7.1.5. Legacy Application Compatibility Mode</a><br/>
+ <a href="#section-7.1.6">7.1.6. Screen Types</a><br/>
+ <a href="#section-7.1.7">7.1.7. Screen Technology</a><br/>
+ <a href="#section-7.1.8">7.1.8. External Displays</a><br/>
+ </div>
+ <a href="#section-7.2">7.2. Input Devices</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.2.1">7.2.1. Keyboard</a><br/>
+ <a href="#section-7.2.2">7.2.2. Non-touch Navigation</a><br/>
+ <a href="#section-7.2.3">7.2.3. Navigation keys</a><br/>
+ <a href="#section-7.2.4">7.2.4. Touchscreen input</a><br/>
+ <a href="#section-7.2.5">7.2.5. Fake touch input</a><br/>
+ <a href="#section-7.2.6">7.2.6. Microphone</a><br/>
+ </div>
+ <a href="#section-7.3">7.3. Sensors</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.3.1">7.3.1. Accelerometer</a><br/>
+ <a href="#section-7.3.2">7.3.2. Magnetometer</a><br/>
+ <a href="#section-7.3.3">7.3.3. GPS</a><br/>
+ <a href="#section-7.3.4">7.3.4. Gyroscope</a><br/>
+ <a href="#section-7.3.5">7.3.5. Barometer</a><br/>
+ <a href="#section-7.3.6">7.3.6. Thermometer</a><br/>
+ <a href="#section-7.3.7">7.3.7. Photometer</a><br/>
+ <a href="#section-7.3.8">7.3.8. Proximity Sensor</a><br/>
+ </div>
+ <a href="#section-7.4">7.4. Data Connectivity</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.4.1">7.4.1. Telephony</a><br/>
+ <a href="#section-7.4.2">7.4.2. IEEE 802.11 (WiFi)</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.4.2.1">7.4.2.1. WiFi Direct</a><br/>
+ </div>
+ <a href="#section-7.4.3">7.4.3. Bluetooth</a><br/>
+ <a href="#section-7.4.4">7.4.4. Near-Field Communications</a><br/>
+ <a href="#section-7.4.5">7.4.5. Minimum Network Capability</a><br/>
+ </div>
+ <a href="#section-7.5">7.5. Cameras</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.5.1">7.5.1. Rear-Facing Camera</a><br/>
+ <a href="#section-7.5.2">7.5.2. Front-Facing Camera</a><br/>
+ <a href="#section-7.5.3">7.5.3. Camera API Behavior</a><br/>
+ <a href="#section-7.5.4">7.5.4. Camera Orientation</a><br/>
+ </div>
+ <a href="#section-7.6">7.6. Memory and Storage</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-7.6.1">7.6.1. Minimum Memory and Storage</a><br/>
+ <a href="#section-7.6.2">7.6.2. Application Shared Storage</a><br/>
+ </div>
+ <a href="#section-7.7">7.7. USB</a><br/>
+ </div>
+ <a href="#section-8">8. Performance Compatibility</a><br/>
+ <a href="#section-9">9. Security Model Compatibility</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-9.1">9.1. Permissions</a><br/>
+ <a href="#section-9.2">9.2. UID and Process Isolation</a><br/>
+ <a href="#section-9.3">9.3. Filesystem Permissions</a><br/>
+ <a href="#section-9.4">9.4. Alternate Execution Environments</a><br/>
+ <a href="#section-9.5">9.5. Multi-User Support</a><br/>
+ <a href="#section-9.6">9.6. Premium SMS Warning</a><br/>
+ <a href="section-9.7">9.7. Kernel Security Features</a><br/>
+ </div>
+ <a href="#section-10">10. Software Compatibility Testing</a><br/>
+ <div style="margin-left: 2em;">
+ <a href="#section-10.1">10.1. Compatibility Test Suite</a><br/>
+ <a href="#section-10.2">10.2. CTS Verifier</a><br/>
+ <a href="#section-10.3">10.3. Reference Applications</a><br/>
+ </div>
+ <a href="#section-11">11. Updatable Software</a><br/>
+ <a href="#section-12">12. Contact Us</a><br/>
+</div>
+
+<div style="page-break-before: always;"></div>
+
+<a name="section-1"></a><h2>1. Introduction</h2>
+<p>This document enumerates the requirements that must be met in order for
+devices to be compatible with Android 4.3.</p>
+<p>The use of "must", "must not", "required", "shall", "shall not", "should",
+"should not", "recommended", "may" and "optional" is per the IETF standard
+defined in RFC2119 [<a href="#resources01">Resources, 1</a>].</p>
+<p>As used in this document, a "device implementer" or "implementer" is a
+person or organization developing a hardware/software solution running Android
+4.3. A "device implementation" or "implementation" is the hardware/software
+solution so developed.</p>
+<p>To be considered compatible with Android 4.3, device implementations
+MUST meet the requirements presented in this Compatibility Definition,
+including any documents incorporated via reference.</p>
+<p>Where this definition or the software tests described in <a
+href="#section-10">Section 10</a> is silent, ambiguous, or incomplete, it is
+the responsibility of the device implementer to ensure compatibility with
+existing implementations.</p>
+<p>For this reason, the Android Open Source Project [<a
+href="#resources03">Resources, 3</a>] is both the reference and preferred
+implementation of Android. Device implementers are strongly encouraged to base
+their implementations to the greatest extent possible on the "upstream" source
+code available from the Android Open Source Project. While some components can
+hypothetically be replaced with alternate implementations this practice is
+strongly discouraged, as passing the software tests will become substantially
+more difficult. It is the implementer's responsibility to ensure full
+behavioral compatibility with the standard Android implementation, including
+and beyond the Compatibility Test Suite. Finally, note that certain component
+substitutions and modifications are explicitly forbidden by this document.</p>
+<a name="section-2"></a><h2>2. Resources</h2>
+<ol>
+<a name="resources01"></a><li>IETF RFC2119 Requirement Levels: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a></li>
+<a name="resources02"></a><li>Android Compatibility Program Overview: <a href="http://source.android.com/compatibility/index.html">http://source.android.com/compatibility/index.html</a></li>
+<a name="resources03"></a><li>Android Open Source Project: <a href="http://source.android.com/">http://source.android.com/</a></li>
+<a name="resources04"></a><li>API definitions and documentation: <a href="http://developer.android.com/reference/packages.html">http://developer.android.com/reference/packages.html</a></li>
+<a name="resources05"></a><li>Android Permissions reference: <a href="http://developer.android.com/reference/android/Manifest.permission.html">http://developer.android.com/reference/android/Manifest.permission.html</a></li>
+<a name="resources06"></a><li>android.os.Build reference: <a href="http://developer.android.com/reference/android/os/Build.html">http://developer.android.com/reference/android/os/Build.html</a></li>
+<a name="resources07"></a><li>Android 4.3 allowed version strings: <a href="http://source.android.com/compatibility/4.3/versions.html">http://source.android.com/compatibility/4.3/versions.html</a></li>
+<a name="resources08"></a><li>Renderscript: <a href="http://developer.android.com/guide/topics/graphics/renderscript.html">http://developer.android.com/guide/topics/graphics/renderscript.html</a></li>
+<a name="resources09"></a><li>Hardware Acceleration: <a href="http://developer.android.com/guide/topics/graphics/hardware-accel.html">http://developer.android.com/guide/topics/graphics/hardware-accel.html</a></li>
+<a name="resources10"></a><li>android.webkit.WebView class: <a href="http://developer.android.com/reference/android/webkit/WebView.html">http://developer.android.com/reference/android/webkit/WebView.html</a></li>
+<a name="resources11"></a><li>HTML5: <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">http://www.whatwg.org/specs/web-apps/current-work/multipage/</a></li>
+<a name="resources12"></a><li>HTML5 offline capabilities: <a href="http://dev.w3.org/html5/spec/Overview.html#offline">http://dev.w3.org/html5/spec/Overview.html#offline</a></li>
+<a name="resources13"></a><li>HTML5 video tag: <a href="http://dev.w3.org/html5/spec/Overview.html#video">http://dev.w3.org/html5/spec/Overview.html#video</a></li>
+<a name="resources14"></a><li>HTML5/W3C geolocation API: <a href="http://www.w3.org/TR/geolocation-API/">http://www.w3.org/TR/geolocation-API/</a></li>
+<a name="resources15"></a><li>HTML5/W3C webdatabase API: <a href="http://www.w3.org/TR/webdatabase/">http://www.w3.org/TR/webdatabase/</a></li>
+<a name="resources16"></a><li>HTML5/W3C IndexedDB API: <a href="http://www.w3.org/TR/IndexedDB/">http://www.w3.org/TR/IndexedDB/</a></li>
+<a name="resources17"></a><li>Dalvik Virtual Machine specification: available in the Android source code, at dalvik/docs</li>
+<a name="resources18"></a><li>AppWidgets: <a href="http://developer.android.com/guide/practices/ui_guidelines/widget_design.html">http://developer.android.com/guide/practices/ui_guidelines/widget_design.html</a></li>
+<a name="resources19"></a><li>Notifications: <a href="http://developer.android.com/guide/topics/ui/notifiers/notifications.html">http://developer.android.com/guide/topics/ui/notifiers/notifications.html</a></li>
+<a name="resources20"></a><li>Application Resources: <a href="http://code.google.com/android/reference/available-resources.html">http://code.google.com/android/reference/available-resources.html</a></li>
+<a name="resources21"></a><li>Status Bar icon style guide: <a href="http://developer.android.com/guide/practices/ui_guidelines/icon_design_status_bar.html">http://developer.android.com/guide/practices/ui_guidelines/icon_design_status_bar.html</a></li>
+<a name="resources22"></a><li>Search Manager: <a href="http://developer.android.com/reference/android/app/SearchManager.html">http://developer.android.com/reference/android/app/SearchManager.html</a></li>
+<a name="resources23"></a><li>Toasts: <a href="http://developer.android.com/reference/android/widget/Toast.html">http://developer.android.com/reference/android/widget/Toast.html</a></li>
+<a name="resources24"></a><li>Themes: <a href="http://developer.android.com/guide/topics/ui/themes.html">http://developer.android.com/guide/topics/ui/themes.html</a></li>
+<a name="resources25"></a><li>R.style class: <a href="http://developer.android.com/reference/android/R.style.html">http://developer.android.com/reference/android/R.style.html</a></li>
+<a name="resources26"></a><li>Live Wallpapers: <a href="http://developer.android.com/resources/articles/live-wallpapers.html">http://developer.android.com/resources/articles/live-wallpapers.html</a></li>
+<a name="resources27"></a><li>Android Device Administration: <a href="http://developer.android.com/guide/topics/admin/device-admin.html">http://developer.android.com/guide/topics/admin/device-admin.html</a></li>
+<a name="resources28"></a><li>DevicePolicyManager reference: <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html">http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html</a></li>
+<a name="resources29"></a><li>Android Accessibility Service APIs: <a href="http://developer.android.com/reference/android/accessibilityservice/package-summary.html">http://developer.android.com/reference/android/accessibilityservice/package-summary.html</a></li>
+<a name="resources30"></a><li>Android Accessibility APIs: <a href="http://developer.android.com/reference/android/view/accessibility/package-summary.html">http://developer.android.com/reference/android/view/accessibility/package-summary.html</a></li>
+<a name="resources31"></a><li>Eyes Free project: <a href="http://http://code.google.com/p/eyes-free">http://code.google.com/p/eyes-free</a></li>
+<a name="resources32"></a><li>Text-To-Speech APIs: <a href="http://developer.android.com/reference/android/speech/tts/package-summary.html">http://developer.android.com/reference/android/speech/tts/package-summary.html</a></li>
+<a name="resources33"></a><li>Reference tool documentation (for adb, aapt, ddms, systrace): <a href="http://developer.android.com/guide/developing/tools/index.html">http://developer.android.com/guide/developing/tools/index.html</a></li>
+<a name="resources34"></a><li>Android apk file description: <a href="http://developer.android.com/guide/topics/fundamentals.html">http://developer.android.com/guide/topics/fundamentals.html</a></li>
+<a name="resources35"></a><li>Manifest files: <a href="http://developer.android.com/guide/topics/manifest/manifest-intro.html">http://developer.android.com/guide/topics/manifest/manifest-intro.html</a></li>
+<a name="resources36"></a><li>Monkey testing tool: <a href="http://developer.android.com/guide/developing/tools/monkey.html">http://developer.android.com/guide/developing/tools/monkey.html</a></li>
+<a name="resources37"></a><li>Android android.content.pm.PackageManager class and Hardware Features List: <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html">http://developer.android.com/reference/android/content/pm/PackageManager.html</a></li>
+<a name="resources38"></a><li>Supporting Multiple Screens: <a href="http://developer.android.com/guide/practices/screens_support.html">http://developer.android.com/guide/practices/screens_support.html</a></li>
+<a name="resources39"></a><li>android.util.DisplayMetrics: <a href="http://developer.android.com/reference/android/util/DisplayMetrics.html">http://developer.android.com/reference/android/util/DisplayMetrics.html</a></li>
+<a name="resources40"></a><li>android.content.res.Configuration: <a href="http://developer.android.com/reference/android/content/res/Configuration.html">http://developer.android.com/reference/android/content/res/Configuration.html</a></li>
+<a name="resources41"></a><li>android.hardware.SensorEvent: <a href="http://developer.android.com/reference/android/hardware/SensorEvent.html">http://developer.android.com/reference/android/hardware/SensorEvent.html</a></li>
+<a name="resources42"></a><li>Bluetooth API: <a href="http://developer.android.com/reference/android/bluetooth/package-summary.html">http://developer.android.com/reference/android/bluetooth/package-summary.html</a></li>
+<a name="resources43"></a><li>NDEF Push Protocol: <a href="http://source.android.com/compatibility/ndef-push-protocol.pdf">http://source.android.com/compatibility/ndef-push-protocol.pdf</a></li>
+<a name="resources44"></a><li>MIFARE MF1S503X: <a href="http://www.nxp.com/documents/data_sheet/MF1S503x.pdf">http://www.nxp.com/documents/data_sheet/MF1S503x.pdf</a></li>
+<a name="resources45"></a><li>MIFARE MF1S703X: <a href="http://www.nxp.com/documents/data_sheet/MF1S703x.pdf">http://www.nxp.com/documents/data_sheet/MF1S703x.pdf</a></li>
+<a name="resources46"></a><li>MIFARE MF0ICU1: <a href="http://www.nxp.com/documents/data_sheet/MF0ICU1.pdf">http://www.nxp.com/documents/data_sheet/MF0ICU1.pdf</a></li>
+<a name="resources47"></a><li>MIFARE MF0ICU2: <a href="http://www.nxp.com/documents/short_data_sheet/MF0ICU2_SDS.pdf">http://www.nxp.com/documents/short_data_sheet/MF0ICU2_SDS.pdf</a></li>
+<a name="resources48"></a><li>MIFARE AN130511: <a href="http://www.nxp.com/documents/application_note/AN130511.pdf">http://www.nxp.com/documents/application_note/AN130511.pdf</a></li>
+<a name="resources49"></a><li>MIFARE AN130411: <a href="http://www.nxp.com/documents/application_note/AN130411.pdf">http://www.nxp.com/documents/application_note/AN130411.pdf</a></li>
+<a name="resources50"></a><li>Camera orientation API: <a href="http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)">http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)</a></li>
+<a name="resources51"></a><li>Camera: <a href="http://developer.android.com/reference/android/hardware/Camera.html">http://developer.android.com/reference/android/hardware/Camera.html</a></li>
+<a name="resources52"></a><li>Android Open Accessories: <a href="http://developer.android.com/guide/topics/usb/accessory.html">http://developer.android.com/guide/topics/usb/accessory.html</a></li>
+<a name="resources53"></a><li>USB Host API: <a href="http://developer.android.com/guide/topics/usb/host.html">http://developer.android.com/guide/topics/usb/host.html</a></li>
+<a name="resources54"></a><li>Android Security and Permissions reference: <a href="http://developer.android.com/guide/topics/security/security.html">http://developer.android.com/guide/topics/security/security.html</a></li>
+<a name="resources55"></a><li>Apps for Android: <a href="http://code.google.com/p/apps-for-android">http://code.google.com/p/apps-for-android</a></li>
+<a name="resources56"></a><li>Android DownloadManager: <a href="http://developer.android.com/reference/android/app/DownloadManager.html">http://developer.android.com/reference/android/app/DownloadManager.html</a></li>
+<a name="resources57"></a><li>Android File Transfer: <a href="http://www.android.com/filetransfer">http://www.android.com/filetransfer</a></li>
+<a name="resources58"></a><li>Android Media Formats: <a href="http://developer.android.com/guide/appendix/media-formats.html">http://developer.android.com/guide/appendix/media-formats.html</a></li>
+<a name="resources59"></a><li>HTTP Live Streaming Draft Protocol: <a href="http://tools.ietf.org/html/draft-pantos-http-live-streaming-03">http://tools.ietf.org/html/draft-pantos-http-live-streaming-03</a></li>
+<a name="resources60"></a><li>NFC Connection Handover: <a href="http://www.nfc-forum.org/specs/spec_list/#conn_handover/">http://www.nfc-forum.org/specs/spec_list/#conn_handover</a></li>
+<a name="resources61"></a><li>Bluetooth Secure Simple Pairing Using NFC: <a href="http://www.nfc-forum.org/resources/AppDocs/NFCForum_AD_BTSSP_1_0.pdf">http://www.nfc-forum.org/resources/AppDocs/NFCForum_AD_BTSSP_1_0.pdf</a></li>
+<a name="resources62"></a><li>Wifi Multicast API: <a href="http://developer.android.com/reference/android/net/wifi/WifiManager.MulticastLock.html">http://developer.android.com/reference/android/net/wifi/WifiManager.MulticastLock.html</a></li>
+<a name="resources63"></a><li>Action Assist: <a href="http://developer.android.com/reference/android/content/Intent.html#ACTION_ASSIST">http://developer.android.com/reference/android/content/Intent.html#ACTION_ASSIST</a></li>
+<a name="resources64"></a><li>USB Charging Specification: <a href="http://www.usb.org/developers/devclass_docs/USB_Battery_Charging_1.2.pdf">http://www.usb.org/developers/devclass_docs/USB_Battery_Charging_1.2.pdf</a></li>
+<a name="resources65"></a><li>Android Beam: <a href="http://developer.android.com/guide/topics/nfc/nfc.html">http://developer.android.com/guide/topics/nfc/nfc.html</a></li>
+<a name="resources66"></a><li>Android USB Audio: <a href="http://developer.android.com/reference/android/hardware/usb/UsbConstants.html#USB_CLASS_AUDIO">http://developer.android.com/reference/android/hardware/usb/UsbConstants.html#USB_CLASS_AUDIO</a></li>
+<a name="resources67"></a><li>Android NFC Sharing Settings: <a href="http://developer.android.com/reference/android/provider/Settings.html#ACTION_NFCSHARING_SETTINGS">http://developer.android.com/reference/android/provider/Settings.html#ACTION_NFCSHARING_SETTINGS</a></li>
+<a name="resources68"></a><li>Wifi Direct (Wifi P2P): <a href="http://developer.android.com/reference/android/net/wifi/p2p/WifiP2pManager.html">http://developer.android.com/reference/android/net/wifi/p2p/WifiP2pManager.html</a></li>
+<a name="resources69"></a><li>Lock and Home Screen Widget: <a href="http://developer.android.com/reference/android/appwidget/AppWidgetProviderInfo.html">http://developer.android.com/reference/android/appwidget/AppWidgetProviderInfo.html</a></li>
+<a name="resources70"></a><li>UserManager reference: <a href="http://developer.android.com/reference/android/os/UserManager.html">http://developer.android.com/reference/android/os/UserManager.html</a></li>
+<a name="resources71"></a><li>External Storage reference: <a href="http://source.android.com/tech/storage">http://source.android.com/tech/storage</a></li>
+<a name="resources72"></a><li>External Storage APIs: <a href="http://developer.android.com/reference/android/os/Environment.html">http://developer.android.com/reference/android/os/Environment.html</a></li>
+<a name="resources73"></a><li>SMS Short Code: <a href="http://en.wikipedia.org/wiki/Short_code">http://en.wikipedia.org/wiki/Short_code</a></li>
+<a name="resources74"></a><li>Media Remote Control Client: <a href="http://developer.android.com/reference/android/media/RemoteControlClient.html">http://developer.android.com/reference/android/media/RemoteControlClient.html</a></li>
+<a name="resources75"></a><li>Display Manager: <a href="http://developer.android.com/reference/android/hardware/display/DisplayManager.html">http://developer.android.com/reference/android/hardware/display/DisplayManager.html</a></li>
+<a name="resources76"></a><li>Dreams: <a href="http://developer.android.com/reference/android/service/dreams/DreamService.html">http://developer.android.com/reference/android/service/dreams/DreamService.html</a></li>
+<a name="resources77"></a><li>Android Application Development-Related Settings: <a href="http://developer.android.com/reference/android/provider/Settings.html#ACTION_APPLICATION_DEVELOPMENT_SETTINGS">http://developer.android.com/reference/android/provider/Settings.html#ACTION_APPLICATION_DEVELOPMENT_SETTINGS</a></li>
+<a name="resources78"></a><li>Camera: <a href="http://developer.android.com/reference/android/hardware/Camera.Parameters.html">http://developer.android.com/reference/android/hardware/Camera.Parameters.html</a></li>
+<a name="resources79"></a><li>EGL Extension-EGL_ANDROID_RECORDABLE: <a href="http://www.khronos.org/registry/egl/extensions/ANDROID/EGL_ANDROID_recordable.txt">http://www.khronos.org/registry/egl/extensions/ANDROID/EGL_ANDROID_recordable.txt</a></li>
+<a name="resources80"></a><li>Motion Event API: <a href="http://developer.android.com/reference/android/view/MotionEvent.html">http://developer.android.com/reference/android/view/MotionEvent.html</a></li>
+<a name="resources81"></a><li>Touch Input Configuration: <a href="http://source.android.com/devices/tech/input/touch-devices.html">http://source.android.com/devices/tech/input/touch-devices.html</a></li>
+</ol>
+<p>Many of these resources are derived directly or indirectly from the Android
+4.3 SDK, and will be functionally identical to the information in that SDK's
+documentation. In any cases where this Compatibility Definition or the
+Compatibility Test Suite disagrees with the SDK documentation, the SDK
+documentation is considered authoritative. Any technical details provided in
+the references included above are considered by inclusion to be part of this
+Compatibility Definition.</p>
+
+<a name="section-3"></a><h2>3. Software</h2>
+<a name="section-3.1"></a><h3>3.1. Managed API Compatibility</h3>
+<p>The managed (Dalvik-based) execution environment is the primary vehicle for
+Android applications. The Android application programming interface (API) is
+the set of Android platform interfaces exposed to applications running in the
+managed VM environment. Device implementations MUST provide complete
+implementations, including all documented behaviors, of any documented API
+exposed by the Android 4.3 SDK [<a href="#resources04">Resources, 4</a>].</p>
+<p>Device implementations MUST NOT omit any managed APIs, alter API interfaces
+or signatures, deviate from the documented behavior, or include no-ops, except
+where specifically allowed by this Compatibility Definition.</p>
+<p>This Compatibility Definition permits some types of hardware for which
+Android includes APIs to be omitted by device implementations. In such cases,
+the APIs MUST still be present and behave in a reasonable way. See
+<a href="#section-7">Section 7</a> for specific requirements for this scenario.
+</p>
+
+<a name="section-3.2"></a><h3>3.2. Soft API Compatibility</h3>
+<p>In addition to the managed APIs from Section 3.1, Android also includes a
+significant runtime-only "soft" API, in the form of such things such as
+Intents, permissions, and similar aspects of Android applications that cannot
+be enforced at application compile time.</p>
+<a name="section-3.2.1"></a><h4>3.2.1. Permissions</h4>
+<p>Device implementers MUST support and enforce all permission constants as
+documented by the Permission reference page [<a
+href="#resources05">Resources, 5</a>]. Note that Section 9 lists additional
+requirements related to the Android security model.</p>
+<a name="section-3.2.2"></a><h4>3.2.2. Build Parameters</h4>
+<p>The Android APIs include a number of constants on the <code>android.os.Build</code>
+class [<a href="#resources06">Resources, 6</a>] that are intended to describe
+the current device. To provide consistent, meaningful values across device
+implementations, the table below includes additional restrictions on the
+formats of these values to which device implementations MUST conform.</p>
+<table>
+<tbody>
+<tr>
+<td><b>Parameter</b></td>
+<td><b>Comments</b></td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.RELEASE</td>
+<td>The version of the currently-executing Android system, in human-readable
+format. This field MUST have one of the string values defined in [<a
+href="#resources07">Resources, 7</a>].</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.SDK</td>
+<td>The version of the currently-executing Android system, in a format
+accessible to third-party application code. For Android 4.3, this
+field MUST have the integer value 18.</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.SDK_INT</td>
+<td>The version of the currently-executing Android system, in a format
+accessible to third-party application code. For Android 4.3, this
+field MUST have the integer value 18.</td>
+</tr>
+<tr>
+<td>android.os.Build.VERSION.INCREMENTAL</td>
+<td>A value chosen by the device implementer designating the specific build of
+the currently-executing Android system, in human-readable format. This value
+MUST NOT be re-used for different builds made available to end users. A typical use
+of this field is to indicate which build number or source-control change
+identifier was used to generate the build. There are no requirements on the
+specific format of this field, except that it MUST NOT be null or the empty
+string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.BOARD</td>
+<td>A value chosen by the device implementer identifying the specific internal
+hardware used by the device, in human-readable format. A possible use of this
+field is to indicate the specific revision of the board powering the device.
+The value of this field MUST be encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.BRAND</td>
+<td>A value chosen by the device implementer identifying the name of the
+company, organization, individual, etc. who produced the device, in
+human-readable format. A possible use of this field is to indicate the OEM
+and/or carrier who sold the device. The value of this field MUST be
+encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.CPU_ABI</td>
+<td>The name of the instruction set (CPU type + ABI convention) of native code.
+See <a href="#section-3.3">Section 3.3: Native API Compatibility</a>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.CPU_ABI2</td>
+<td>The name of the second instruction set (CPU type + ABI convention) of native code.
+See <a href="#section-3.3">Section 3.3: Native API Compatibility</a>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.DEVICE</td>
+<td>A value chosen by the device implementer identifying the specific
+configuration or revision of the body (sometimes called "industrial design")
+of the device. The value of this field MUST be encodable as 7-bit ASCII and
+match the regular expression <code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.FINGERPRINT</td>
+<td>A string that uniquely identifies this build. It SHOULD be reasonably
+human-readable. It MUST follow this template:
+<br/><code>$(BRAND)/$(PRODUCT)/$(DEVICE):$(VERSION.RELEASE)/$(ID)/$(VERSION.INCREMENTAL):$(TYPE)/$(TAGS)</code><br/>
+For example:
+<br/><code>acme/mydevice/generic:4.3/JRN53/3359:userdebug/test-keys</code><br/>
+The fingerprint MUST NOT include whitespace characters. If other fields included in the
+template above have whitespace characters, they MUST be replaced in the build
+fingerprint with another character, such as the underscore ("_") character.
+The value of this field MUST be encodable as 7-bit ASCII.</td>
+</tr>
+<tr>
+<td>android.os.Build.HARDWARE</td>
+<td>The name of the hardware (from the kernel command line or /proc). It SHOULD be
+reasonably human-readable. The value of this field MUST be encodable as 7-bit ASCII and
+match the regular expression <code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.HOST</td>
+<td>A string that uniquely identifies the host the build was built on, in
+human readable format. There are no requirements on the specific format of
+this field, except that it MUST NOT be null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.ID</td>
+<td>An identifier chosen by the device implementer to refer to a specific
+release, in human readable format. This field can be the same as
+android.os.Build.VERSION.INCREMENTAL, but SHOULD be a value sufficiently
+meaningful for end users to distinguish between software builds. The value of
+this field MUST be encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.
+</td>
+</tr>
+<tr>
+<td>android.os.Build.MANUFACTURER</td>
+<td>The trade name of the Original Equipment Manufacturer (OEM) of the product.
+There are no requirements on the specific format of this field, except that it
+MUST NOT be null or the empty string ("").</td>
+</tr>
+<tr>
+<td>android.os.Build.MODEL</td>
+<td>A value chosen by the device implementer containing the name of the device
+as known to the end user. This SHOULD be the same name under which the device
+is marketed and sold to end users. There are no requirements on the specific
+format of this field, except that it MUST NOT be null or the empty string
+("").</td>
+</tr>
+<tr>
+<td>android.os.Build.PRODUCT</td>
+<td>A value chosen by the device implementer containing the development name
+or code name of the product (SKU). MUST be human-readable, but is not necessarily
+intended for view by end users. The value of this field MUST be encodable as 7-bit
+ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.SERIAL</td>
+<td>A hardware serial number, if available. The value of this field MUST be encodable
+as 7-bit ASCII and match the regular expression
+<code>"^([a-zA-Z0-9]{0,20})$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.TAGS</td>
+<td>A comma-separated list of tags chosen by the device implementer that
+further distinguishes the build. For example, "unsigned,debug". The value of
+this field MUST be encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.TIME</td>
+<td>A value representing the timestamp of when the build occurred.</td>
+</tr>
+<tr>
+<td>android.os.Build.TYPE</td>
+<td>A value chosen by the device implementer specifying the runtime
+configuration of the build. This field SHOULD have one of the values
+corresponding to the three typical Android runtime configurations: "user",
+"userdebug", or "eng". The value of this field MUST be
+encodable as 7-bit ASCII and match the regular expression
+<code>"^[a-zA-Z0-9.,_-]+$"</code>.</td>
+</tr>
+<tr>
+<td>android.os.Build.USER</td>
+<td>A name or user ID of the user (or automated user) that generated the
+build. There are no requirements on the specific format of this field, except
+that it MUST NOT be null or the empty string ("").</td>
+</tr>
+</tbody>
+</table>
+<a name="section-3.2.3"></a><h4>3.2.3. Intent Compatibility</h4>
+<p>
+Device implementations MUST honor Android's loose-coupling Intent system, as
+described in the sections below. By "honored", it is meant that the device
+implementer MUST provide an Android Activity or Service that specifies a
+matching Intent filter and binds to and implements correct behavior for each
+specified Intent pattern.</p>
+<a name="section-3.2.3.1"></a><h4>3.2.3.1. Core Application Intents</h4>
+<p>The Android upstream project defines a number of core applications, such as
+contacts, calendar, photo gallery, music player, and so on. Device implementers
+MAY replace these applications with alternative versions.</p>
+<p>However, any such alternative versions MUST honor the same Intent patterns
+provided by the upstream project. For example, if a device contains an
+alternative music player, it must still honor the Intent pattern issued by
+third-party applications to pick a song.</p>
+<p>The following applications are considered core Android system
+applications:</p>
+<ul>
+<li>Desk Clock</li>
+<li>Browser</li>
+<li>Calendar</li>
+<li>Contacts</li>
+<!--<li>Email</li>-->
+<li>Gallery</li>
+<li>GlobalSearch</li>
+<li>Launcher</li>
+<!-- <li>LivePicker (that is, the Live Wallpaper picker application; MAY be omitted
+if the device does not support Live Wallpapers, per Section 3.8.5.)</li> -->
+<!-- <li>Messaging (AKA "Mms")</li> -->
+<li>Music</li>
+<!-- <li>Phone</li> -->
+<li>Settings</li>
+<!-- <li>SoundRecorder</li> -->
+</ul>
+<p>The core Android system applications include various Activity, or Service
+components that are considered "public". That is, the attribute
+"android:exported" may be absent, or may have the value "true".</p>
+<p>For every Activity or Service defined
+in one of the core Android system apps that is not marked as non-public via an
+android:exported attribute with the value "false", device implementations MUST
+include a component of the same type implementing the same Intent filter
+patterns as the core Android system app.</p>
+<p>In other words, a device implementation MAY replace core Android system
+apps; however, if it does, the device implementation MUST support all Intent
+patterns defined by each core Android system app being replaced.</p>
+<a name="section-3.2.3.2"></a><h4>3.2.3.2. Intent Overrides</h4>
+<p>As Android is an extensible platform, device implementations MUST allow each
+Intent pattern referenced in Section 3.2.3.2 to be overridden by third-party
+applications. The upstream Android open source implementation allows this by
+default; device implementers MUST NOT attach special privileges to system
+applications' use of these Intent patterns, or prevent third-party
+applications from binding to and assuming control of these patterns. This
+prohibition specifically includes but is not limited to disabling the
+"Chooser" user interface that allows the user to select between multiple
+applications which all handle the same Intent pattern.</p>
+<p>However, device implementations MAY provide default activities for specific
+URI patterns (eg. http://play.google.com) if the default activity provides a
+more specific filter for the data URI. For example, an intent filter specifying
+the data URI "http://www.android.com" is more specific than the browser filter
+for "http://". Device implementations MUST provide a user interface for users
+to modify the default activity for intents.</p>
+
+<a name="section-3.2.3.3"></a><h4>3.2.3.3. Intent Namespaces</h4>
+<p>Device implementations MUST NOT include any Android component that honors any
+new Intent or Broadcast Intent patterns using an ACTION, CATEGORY, or other
+key string in the android.* or com.android.* namespace. Device implementers
+MUST NOT include any Android components that honor any new Intent or Broadcast
+Intent patterns using an ACTION, CATEGORY, or other key string in a package
+space belonging to another organization. Device implementers MUST NOT alter or
+extend any of the Intent patterns used by the core apps listed in Section
+3.2.3.1. Device implementations MAY include Intent patterns using
+namespaces clearly and obviously associated with their own organization.</p>
+<p>This prohibition is analogous to that specified for Java language classes
+in Section 3.6.</p>
+<a name="section-3.2.3.4"></a><h4>3.2.3.4. Broadcast Intents</h4>
+<p>Third-party applications rely on the platform to broadcast certain Intents
+to notify them of changes in the hardware or software environment.
+Android-compatible devices MUST broadcast the public broadcast Intents in
+response to appropriate system events. Broadcast Intents are described in the
+SDK documentation.</p>
+
+<a name="section-3.3"></a><h3>3.3. Native API Compatibility</h3>
+<a name="section-3.3.1"></a><h4>3.3.1 Application Binary Interfaces</h4>
+<p>Managed code running in Dalvik can call into native code provided in the
+application .apk file as an ELF .so file compiled for the appropriate device
+hardware architecture. As native code is highly dependent on the underlying
+processor technology, Android defines a number of Application Binary
+Interfaces (ABIs) in the Android NDK, in the file
+<code>docs/CPU-ARCH-ABIS.html</code>. If a device implementation is compatible
+with one or more defined ABIs, it SHOULD implement compatibility with the
+Android NDK, as below.</p>
+<p>If a device implementation includes support for an Android ABI, it:</p>
+<ul>
+<li>MUST include support for code running in the managed environment to call
+into native code, using the standard Java Native Interface (JNI)
+semantics</li>
+<li>MUST be source-compatible (i.e. header compatible) and binary-compatible
+(for the ABI) with each required library in the list below</li>
+<li>MUST accurately report the native Application Binary Interface (ABI)
+supported by the device, via the <code>android.os.Build.CPU_ABI</code>
+API</li>
+<li>MUST report only those ABIs documented in the latest version of the
+Android NDK, in the file <code>docs/CPU-ARCH-ABIS.txt</code></li>
+<li>SHOULD be built using the source code and header files available in the
+upstream Android Open Source Project</li>
+</ul>
+<p>The following native code APIs MUST be available to apps that include
+native code:</p>
+<ul>
+<li>libc (C library)</li>
+<li>libm (math library)</li>
+<li>Minimal support for C++</li>
+<li>JNI interface</li>
+<li>liblog (Android logging)</li>
+<li>libz (Zlib compression)</li>
+<li>libdl (dynamic linker)</li>
+<li>libGLESv1_CM.so (OpenGL ES 1.0)</li>
+<li>libGLESv2.so (OpenGL ES 2.0)</li>
+<li>libGLESv3.so (OpenGL ES 3.0)</li>
+<li>libEGL.so (native OpenGL surface management)</li>
+<li>libjnigraphics.so</li>
+<li>libOpenSLES.so (OpenSL ES 1.0.1 audio support)</li>
+<li>libOpenMAXAL.so (OpenMAX AL 1.0.1 support)</li>
+<li>libandroid.so (native Android activity support)</li>
+<li>Support for OpenGL, as described below</li>
+</ul>
+<p>Note that future releases of the Android NDK may introduce support for
+additional ABIs. If a device implementation is not compatible with an existing
+predefined ABI, it MUST NOT report support for any ABI at all.</p>
+<p>Note that device implementations MUST include libGLESv3.so and it MUST symlink (symbolic)
+link to libGLESv2.so. On device implementations that declare support for OpenGL ES 3.0, libGLESv2.so
+MUST export the OpenGL ES 3.0 function symbols in addition to the OpenGL ES 2.0 function symbols.</p>
+<p>Native code compatibility is challenging. For this reason, it should be
+repeated that device implementers are VERY strongly encouraged to use the
+upstream implementations of the libraries listed above to help ensure
+compatibility.</p>
+
+<a name="section-3.4"></a><h3>3.4. Web Compatibility</h3>
+<a name="section-3.4.1"></a><h4>3.4.1. WebView Compatibility</h4>
+<p>The Android Open Source implementation uses the WebKit rendering engine to
+implement the <code>android.webkit.WebView</code> [<a href="#resources10">Resources, 10</a>] . Because it is not feasible
+to develop a comprehensive test suite for a web rendering system, device
+implementers MUST use the specific upstream build of WebKit in the WebView
+implementation. Specifically:</p>
+<ul>
+<li>Device implementations' <code>android.webkit.WebView</code>
+implementations MUST be based on the 534.30 WebKit build from the upstream
+Android Open Source tree for Android 4.3. This build includes a specific set
+of functionality and security fixes for the WebView. Device implementers MAY
+include customizations to the WebKit implementation; however, any such
+customizations MUST NOT alter the behavior of the WebView, including rendering
+behavior.</li>
+<li>The user agent string reported by the WebView MUST be in this format:<br/>
+ <code>Mozilla/5.0 (Linux; U; Android $(VERSION); $(LOCALE); $(MODEL) Build/$(BUILD)) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30</code>
+ <ul>
+ <li>The value of the $(VERSION) string MUST be the same as the value for <code>android.os.Build.VERSION.RELEASE</code></li>
+ <li>The value of the $(LOCALE) string SHOULD follow the ISO conventions for country code and language, and SHOULD refer to the current configured locale of the device</li>
+ <li>The value of the $(MODEL) string MUST be the same as the value for <code>android.os.Build.MODEL</code></li>
+ <li>The value of the $(BUILD) string MUST be the same as the value for <code>android.os.Build.ID</code></li>
+ <li>Device implementations MAY omit <code>Mobile</code> in the user agent string</li>
+ </ul>
+</li>
+</ul>
+<p>The WebView component SHOULD include support for as much of HTML5 [<a
+href="#resources11">Resources, 11</a>] as possible.
+Minimally, device implementations MUST support each of these APIs associated
+with HTML5 in the WebView:</p>
+<ul>
+<li>application cache/offline operation [<a href="#resources12">Resources, 12</a>]</li>
+<li>the <video> tag [<a href="#resources13">Resources, 13</a>]</li>
+<li>geolocation [<a href="#resources14">Resources, 14</a>]</li>
+</ul>
+<p>Additionally, device implementations MUST support the HTML5/W3C webstorage
+API [<a href="#resources15">Resources, 15</a>], and SHOULD support the
+HTML5/W3C IndexedDB API [<a href="#resources16">Resources, 16</a>]. <i>Note
+that as the web development standards bodies are transitioning to favor
+IndexedDB over webstorage, IndexedDB is expected to become a required
+component in a future version of Android.</i></p>
+<p>HTML5 APIs, like all JavaScript APIs, MUST be disabled by default in a
+WebView, unless the developer explicitly enables them via the usual Android
+APIs.</p>
+
+<a name="section-3.4.2"></a><h4>3.4.2. Browser Compatibility</h4>
+<p>Device implementations MUST include a standalone Browser application for
+general user web browsing. The standalone Browser MAY be based on a
+browser technology other than WebKit. However, even if an alternate Browser
+application is used, the <code>android.webkit.WebView</code> component
+provided to third-party applications MUST be based on WebKit, as described in
+Section 3.4.1.</p>
+<p>Implementations MAY ship a custom user agent string in the standalone
+Browser application.</p>
+<p>The standalone Browser application (whether based on the upstream
+WebKit Browser application or a third-party replacement) SHOULD include support
+for as much of HTML5 [<a href="#resources11">Resources, 11</a>] as possible.
+Minimally, device implementations MUST support each of these APIs associated
+with HTML5:</p>
+<ul>
+<li>application cache/offline operation [<a href="#resources12">Resources, 12</a>]</li>
+<li>the <video> tag [<a href="#resources13">Resources, 13</a>]</li>
+<li>geolocation [<a href="#resources14">Resources, 14</a>]</li>
+</ul>
+<p>Additionally, device implementations MUST support the HTML5/W3C webstorage
+API [<a href="#resources15">Resources, 15</a>], and SHOULD support the
+HTML5/W3C IndexedDB API [<a href="#resources16">Resources, 16</a>]. <i>Note
+that as the web development standards bodies are transitioning to favor
+IndexedDB over webstorage, IndexedDB is expected to become a required
+component in a future version of Android.</i></p>
+
+<a name="section-3.5"></a><h3>3.5. API Behavioral Compatibility</h3>
+<p>The behaviors of each of the API types (managed, soft, native, and web)
+must be consistent with the preferred implementation of the upstream Android
+Open Source Project [<a href="#resources03">Resources, 3</a>]. Some specific areas
+of compatibility are:</p>
+<ul>
+<li>Devices MUST NOT change the behavior or semantics of a standard Intent</li>
+<li>Devices MUST NOT alter the lifecycle or lifecycle semantics of a
+ particular type of system component (such as Service, Activity,
+ ContentProvider, etc.)</li>
+<li>Devices MUST NOT change the semantics of a standard permission</li>
+</ul>
+<p>The above list is not comprehensive. The Compatibility Test Suite (CTS)
+tests significant portions of the platform for behavioral compatibility, but
+not all. It is the responsibility of the implementer to ensure behavioral
+compatibility with the Android Open Source Project. For this reason, device
+implementers SHOULD use the source code available via the Android Open Source
+Project where possible, rather than re-implement significant parts of the
+system.</p>
+
+
+<a name="section-3.6"></a><h3>3.6. API Namespaces</h3>
+<p>Android follows the package and class namespace conventions defined by the
+Java programming language. To ensure compatibility with third-party
+applications, device implementers MUST NOT make any prohibited modifications
+(see below) to these package namespaces:</p>
+<ul>
+<li>java.*</li>
+<li>javax.*</li>
+<li>sun.*</li>
+<li>android.*</li>
+<li>com.android.*</li>
+</ul>
+<p>Prohibited modifications include:</p>
+<ul>
+<li>Device implementations MUST NOT modify the publicly exposed APIs on the
+Android platform by changing any method or class signatures, or by removing
+classes or class fields.</li>
+<li>Device implementers MAY modify the underlying implementation of the APIs,
+but such modifications MUST NOT impact the stated behavior and Java-language
+signature of any publicly exposed APIs.</li>
+<li>Device implementers MUST NOT add any publicly exposed elements (such as
+classes or interfaces, or fields or methods to existing classes or interfaces)
+to the APIs above.</li>
+</ul>
+<p>A "publicly exposed element" is any construct which is not decorated with
+the "@hide" marker as used in the upstream Android source code. In other
+words, device implementers MUST NOT expose new APIs or alter existing APIs in
+the namespaces noted above. Device implementers MAY make internal-only
+modifications, but those modifications MUST NOT be advertised or otherwise
+exposed to developers.</p>
+<p>Device implementers MAY add custom APIs, but any such APIs MUST NOT be in a
+namespace owned by or referring to another organization. For instance, device
+implementers MUST NOT add APIs to the com.google.* or similar namespace; only
+Google may do so. Similarly, Google MUST NOT add APIs to other companies'
+namespaces. Additionally, if a device implementation includes custom APIs
+outside the standard Android namespace, those APIs MUST be packaged in an
+Android shared library so that only apps that explicitly use them (via the
+<code><uses-library></code> mechanism) are affected by the increased
+memory usage of such APIs.</p>
+<p>If a device implementer proposes to improve one of the package namespaces
+above (such as by adding useful new functionality to an existing API, or
+adding a new API), the implementer SHOULD visit source.android.com and begin
+the process for contributing changes and code, according to the information on
+that site.</p>
+<p>Note that the restrictions above correspond to standard conventions for
+naming APIs in the Java programming language; this section simply aims to
+reinforce those conventions and make them binding through inclusion in this
+compatibility definition.</p>
+
+<a name="section-3.7"></a><h3>3.7. Virtual Machine Compatibility</h3>
+<p>Device implementations MUST support the full Dalvik Executable (DEX)
+bytecode specification and Dalvik Virtual Machine semantics [<a
+href="#resources17">Resources, 17</a>].</p>
+<p>Device implementations MUST configure Dalvik to allocate memory in
+accordance with the upstream Android platform, and as specified by the following
+table. (See <a href="#section-7.1.1">Section 7.1.1</a> for screen size and screen
+density definitions.)</p>
+
+<p>Note that memory values specified below are considered minimum values,
+and device implementations MAY allocate more memory per application.</p>
+<table>
+<tbody>
+<tr>
+<td><b>Screen Size</b></td>
+<td><b>Screen Density</b></td>
+<td><b>Application Memory</b></td>
+</tr>
+<tr>
+<td>small / normal / large</td>
+<td>ldpi / mdpi</td>
+<td>16MB</td>
+</tr>
+<tr>
+<td>small / normal / large</td>
+<td>tvdpi / hdpi</td>
+<td>32MB</td>
+</tr>
+<tr>
+<td>small / normal / large</td>
+<td>xhdpi</td>
+<td>64MB</td>
+</tr>
+<tr>
+<td>xlarge</td>
+<td>mdpi</td>
+<td>32MB</td>
+</tr>
+<tr>
+<td>xlarge</td>
+<td>tvdpi / hdpi</td>
+<td>64MB</td>
+</tr>
+<tr>
+<td>xlarge</td>
+<td>xhdpi</td>
+<td>128MB</td>
+</tr>
+</tbody>
+</table>
+
+<a name="section-3.8"></a><h3>3.8. User Interface Compatibility</h3>
+
+<a name="section-3.8.1"></a><h4>3.8.1. Launcher (Home Screen)</h4>
+<p>Android 4.3 includes a launcher application (home screen) and support for third party applications to replace the device
+launcher (home screen). Device implementations that allow third party applications to replace the device home screen
+MUST declare the platform feature <code>android.software.home_screen</code>.</p>
+
+<a name="section-3.8.2"></a><h4>3.8.2. Widgets</h4>
+<p>Android defines a component type and corresponding API and lifecycle that allows applications to expose an "AppWidget"
+to the end user [<a href="#resources18">Resources, 18</a>]. Device implementations that support embedding widgets on the
+home screen MUST meet the following requirements and declare support for platform feature <code>android.software.app_widgets</code>.</p>
+<ul>
+ <li>Device launchers MUST include built-in support for AppWidgets, and expose user
+ interface affordances to add, configure, view, and remove AppWidgets directly within the Launcher.</li>
+ <li>Device implementations MUST be capable of rendering widgets that are 4 x 4 in the standard grid size.
+ (See the App Widget Design Guidelines in the Android SDK documentation [<a href="#resources18">Resources, 18</a>] for details.</li>
+ <li>Device implementations that include support for lock screen MUST support application widgets on the lock screen.</li>
+</ul>
+
+<a name="section-3.8.3"></a><h4>3.8.3. Notifications</h4>
+<p>Android includes APIs that allow developers to notify users of notable
+events [<a href="#resources19">Resources, 19</a>], using hardware and software
+features of the device.</p>
+<p>Some APIs allow applications to perform notifications or attract attention
+using hardware, specifically sound, vibration, and light. Device implementations
+MUST support notifications that use hardware features, as described in the SDK
+documentation, and to the extent possible with the device implementation
+hardware. For instance, if a device implementation includes a vibrator, it
+MUST correctly implement the vibration APIs. If a device implementation lacks
+hardware, the corresponding APIs MUST be implemented as no-ops. Note that this
+behavior is further detailed in <a href="#section-7">Section 7.</a></p>
+<p>Additionally, the implementation MUST correctly render all resources
+(icons, sound files, etc.) provided for in the APIs [<a
+href="#resources20">Resources, 20</a>], or in the
+Status/System Bar icon style guide [<a href="#resources21">Resources, 21</a>].
+Device implementers MAY provide an alternative user experience for
+notifications than that provided by the reference Android Open Source
+implementation; however, such alternative notification systems MUST support
+existing notification resources, as above.</p>
+<p>Android 4.3 includes support for rich notifications, such as interactive
+Views for ongoing notifications. Device implementations MUST properly display
+and execute rich notifications, as documented in the Android APIs.</p>
+<a name="section-3.8.4"></a><h4>3.8.4. Search</h4>
+<p>Android includes APIs [<a href="#resources22">Resources, 22</a>] that allow
+developers to incorporate search into their applications, and expose their
+application's data into the global system search. Generally speaking, this
+functionality consists of a single, system-wide user interface that allows users
+to enter queries, displays suggestions as users type, and displays results. The
+Android APIs allow developers to reuse this interface to provide search within
+their own apps, and allow developers to supply results to the common global
+search user interface.</p>
+<p>Device implementations MUST include a single, shared, system-wide search
+user interface capable of real-time suggestions in response to user input.
+Device implementations MUST implement the APIs that allow developers to reuse
+this user interface to provide search within their own applications. Device
+implementations MUST implement the APIs that allow third-party applications to
+add suggestions to the search box when it is run in global search mode. If no
+third-party applications are installed that make use of this functionality,
+the default behavior SHOULD be to display web search engine results and
+suggestions.</p>
+<a name="section-3.8.5"></a><h4>3.8.5. Toasts</h4>
+<p>Applications can use the "Toast" API (defined in [<a
+href="#resources23">Resources, 23</a>]) to
+display short non-modal strings to the end user, that disappear after a brief
+period of time. Device implementations MUST display Toasts from applications
+to end users in some high-visibility manner.</p>
+
+<a name="section-3.8.6"></a><h4>3.8.6. Themes</h4>
+<p>Android provides "themes" as a mechanism for applications to apply styles
+across an entire Activity or application. Android 4.3 includes a "Holo"
+or "holographic" theme as a set of defined styles for application developers to
+use if they want to match the Holo theme look and feel as defined by the Android
+SDK [<a href="#resources24">Resources, 24</a>]. Device implementations MUST NOT
+alter any of the Holo theme attributes exposed to applications
+[<a href="#resources25">Resources, 25</a>].</p>
+<p>Android 4.3 includes a new "Device Default" theme as a set of defined
+styles for application developers to use if they want to match the look and feel
+of the device theme as defined by the device implementer. Device implementations
+MAY modify the DeviceDefault theme attributes exposed to applications
+[<a href="#resources25">Resources, 25</a>].</p>
+
+<a name="section-3.8.7"></a><h4>3.8.7. Live Wallpapers</h4>
+<p>Android defines a component type and corresponding API and lifecycle that
+allows applications to expose one or more "Live Wallpapers" to the end user
+[<a href="#resources26">Resources, 26</a>]. Live Wallpapers are animations,
+patterns, or similar images with limited input capabilities that display as a
+wallpaper, behind other applications.</p>
+<p>Hardware is considered capable of reliably running live wallpapers if it
+can run all live wallpapers, with no limitations on functionality, at a
+reasonable framerate with no adverse affects on other applications. If
+limitations in the hardware cause wallpapers and/or applications to crash,
+malfunction, consume excessive CPU or battery power, or run at unacceptably
+low frame rates, the hardware is considered incapable of running live
+wallpaper. As an example, some live wallpapers may use an Open GL 1.0 or 2.0
+context to render their content. Live wallpaper will not run reliably on
+hardware that does not support multiple OpenGL contexts because the live
+wallpaper use of an OpenGL context may conflict with other applications that
+also use an OpenGL context.</p>
+<p>Device implementations capable of running live wallpapers reliably as
+described above SHOULD implement live wallpapers. Device implementations
+determined to not run live wallpapers reliably as described above MUST NOT
+implement live wallpapers.</p>
+<a name="section-3.8.8"></a><h4>3.8.8. Recent Application Display</h4>
+<p>The upstream Android 4.3 source code includes a user interface for
+displaying recent applications using a thumbnail image of the application's
+graphical state at the moment the user last left the application. Device
+implementations MAY alter or eliminate this user interface; however, a future
+version of Android is planned to make more extensive use of this
+functionality. Device implementations are strongly encouraged to use the
+upstream Android 4.3 user interface (or a similar thumbnail-based interface)
+for recent applications, or else they may not be compatible with a future
+version of Android.</p>
+<a name="section-3.8.9"></a><h4>3.8.9. Input Management </h4>
+<p>Android 4.3 includes support for Input Management and support for third party input method editors.
+Device implementations that allow users to use third party input methods on the device MUST declare the platform feature
+<code>android.software.input_methods</code> and support IME APIs as defined in the Android SDK documentation.</p>
+<p>Device implementations that declare the <code>android.software.input_methods</code> feature MUST provide a user-accessible mechanism
+to add and configure third party input methods. Device implementations MUST display the settings interface in response to the
+<code>android.settings.INPUT_METHOD_SETTINGS</code> intent.</p>
+
+<a name="section-3.8.10"></a><h4>3.8.10. Lock Screen Media Remote Control</h4>
+<p>Android 4.3 includes support for Remote Control API that lets media applications integrate with playback controls
+that are displayed in a remote view like the device lock screen [<a href="#resources74">Resources, 74</a>]. Device implementations
+that support lock screen in the device and allow users to add widgets on the home screen MUST
+include support for embedding remote controls in the device lock screen [<a href="#resources69">Resources, 69</a>].</p>
+
+<a name="section-3.8.11"></a><h4>3.8.11. Dreams</h4>
+<p>Android 4.3 includes support for interactive screensavers called Dreams [<a href="#resources76">Resources, 76</a>].
+Dreams allows users to interact with applications when a charging device is idle, or docked in a desk dock. Device implementations
+MUST include support for Dreams and provide a settings option for users to configure Dreams.</p>
+
+<a name="section-3.9"></a><h3>3.9 Device Administration</h3>
+<p>Android 4.3 includes features that allow security-aware applications
+to perform device administration functions at the system level, such as enforcing
+password policies or performing remote wipe, through the Android Device
+Administration API [<a href="#resources27">Resources, 27</a>]. Device
+implementations MUST provide an implementation of the <code>DevicePolicyManager</code>
+class [<a href="#resources28">Resources, 28</a>]. Device implementations that include support for lock screen
+MUST support the full range of device administration policies defined in the Android SDK
+documentation [<a href="#resources27">Resources, 27</a>].</p>
+
+<a name="section-3.10"></a><h3>3.10 Accessibility</h3>
+<p>Android 4.3 provides an accessibility layer that helps users with disabilities
+to navigate their devices more easily. In addition, Android 4.3 provides
+platform APIs that enable accessibility service implementations to receive
+callbacks for user and system events and generate alternate feedback mechanisms,
+such as text-to-speech, haptic feedback, and trackball/d-pad navigation
+[<a href="#resources29">Resources, 29</a>]. Device implementations MUST provide an
+implementation of the Android accessibility framework consistent with the
+default Android implementation. Specifically, device implementations MUST meet
+the following requirements.</p>
+<ul>
+ <li>Device implementations MUST support third party accessibility service
+ implementations through the <code>android.accessibilityservice</code>
+ APIs [<a href="#resources30">Resources, 30</a>].</li>
+ <li>Device implementations MUST generate <code>AccessibilityEvents</code>
+ and deliver these events to all registered <code>AccessibilityService
+ </code> implementations in a manner consistent with the default Android
+ implementation.</li>
+ <li>Device implementations MUST provide a user-accessible mechanism to enable
+ and disable accessibility services, and MUST display this interface in
+ response to the
+ <code>android.provider.Settings.ACTION_ACCESSIBILITY_SETTINGS</code>
+ intent.</li>
+</ul>
+<p>Additionally, device implementations SHOULD provide an implementation
+of an accessibility service on the device, and SHOULD provide a mechanism
+for users to enable the accessibility service during device setup. An open
+source implementation of an accessibility service is available from the Eyes
+Free project [<a href="#resources31">Resources, 31</a>].</p>
+
+<a name="section-3.11"></a><h3>3.11 Text-to-Speech</h3>
+<p>Android 4.3 includes APIs that allow applications to make use of
+text-to-speech (TTS) services, and allows service providers to provide
+implementations of TTS services [<a href="#resources32">Resources, 32</a>].
+Device implementations MUST meet these requirements related to the Android TTS
+framework:</p>
+<ul>
+ <li>Device implementations MUST support the Android TTS framework APIs and
+ SHOULD include a TTS engine supporting the languages available on the
+ device. Note that the upstream Android open source software includes a
+ full-featured TTS engine implementation.</li>
+ <li>Device implementations MUST support installation of third-party TTS
+ engines.</li>
+ <li>Device implementations MUST provide a user-accessible interface that allows
+ users to select a TTS engine for use at the system level.</li>
+</ul>
+
+<a name="section-4"></a><h2>4. Application Packaging Compatibility</h2>
+<p>Device implementations MUST install and run Android ".apk" files as
+generated by the "aapt" tool included in the official Android SDK [<a
+href="#resources33">Resources, 33</a>].</p>
+<p>Devices implementations MUST NOT extend either the .apk [<a
+href="#resources34">Resources, 34</a>], Android Manifest [<a
+href="#resources35">Resources, 35</a>],
+Dalvik bytecode [<a href="#resources17">Resources, 17</a>], or renderscript
+bytecode formats in such a way that would prevent those files from installing
+and running correctly on other compatible devices. Device implementers SHOULD
+use the reference upstream implementation of Dalvik, and the reference
+implementation's package management system.</p>
+
+<a name="section-5"></a><h2>5. Multimedia Compatibility</h2>
+<p>Device implementations MUST include at least one form of audio output, such as
+speakers, headphone jack, external speaker connection, etc.</p>
+<a name="section-5.1"></a><h3>5.1. Media Codecs</h3>
+<p>Device implementations MUST support the core media formats specified
+in the Android SDK documentation [<a href="#resources58">Resources, 58</a>] except
+where explicitly permitted in this document. Specifically, device implementations
+MUST support the media formats, encoders, decoders, file types and container
+formats defined in the tables below. All of these codecs are provided as
+software implementations in the preferred Android implementation from the Android
+Open Source Project.</p>
+
+<p><strong>Please note that neither Google nor the Open Handset Alliance make any
+representation that these codecs are unencumbered by third-party patents.
+Those intending to use this source code in hardware or software products are
+advised that implementations of this code, including in open source software
+or shareware, may require patent licenses from the relevant patent
+holders.</strong></p>
+
+<p>Note that these tables do not list specific bitrate requirements for
+most video codecs because current device hardware does not necessarily support
+bitrates that map exactly to the required bitrates specified by the relevant
+standards. Instead, device implementations SHOULD support the highest bitrate
+practical on the hardware, up to the limits defined by the specifications.</p>
+<div style="page-break-before: always;"></div>
+<table>
+<tbody>
+
+<tr>
+<th>Type</th>
+<th>Format / Codec</th>
+<th>Encoder</th>
+<th>Decoder</th>
+<th>Details</th>
+<th>File Type(s) / Container Formats</th>
+</tr>
+
+<tr>
+<td rowspan="11">Audio</td>
+<td>MPEG-4 AAC Profile (AAC LC)</td>
+<td>REQUIRED for device implementations that include microphone hardware
+and define <code>android.hardware.microphone</code>.</td>
+<td style="text-align: center;">REQUIRED</td>
+<td rowspan="1"> Support for mono/stereo/5.0/5.1* content with standard sampling rates from 8 to 48 kHz.</td>
+<td rowspan="4">
+ <ul>
+ <li>3GPP (.3gp)</li>
+ <li>MPEG-4 (.mp4, .m4a)</li>
+ <li>ADTS raw AAC (.aac, decode in Android 3.1+, encode in Android 4.0+, ADIF not supported)</li>
+ <li>MPEG-TS (.ts, not seekable, Android 3.0+)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>MPEG-4 HE AAC Profile (AAC+)</td>
+<td>REQUIRED for device implementations that include microphone hardware and define android.hardware.microphone</td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Support for mono/stereo/5.0/5.1* content with standard sampling rates from 16 to 48 kHz.</td>
+</tr>
+
+<tr>
+<td>MPEG-4 HE AAC v2 Profile (enhanced AAC+)</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Support for mono/stereo/5.0/5.1* content with standard sampling rates from 16 to 48 kHz.</td>
+</tr>
+
+<tr>
+<td>MPEG-4 Audio Object Type ER AAC ELD (Enhanced Low Delay AAC)</td>
+<td>REQUIRED for device implementations that include microphone hardware and define android.hardware.microphone</td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Support for mono/stereo content with standard
+sampling rates from 16 to 48 kHz.</td>
+</tr>
+
+<tr>
+<td>AMR-NB</td>
+<td>REQUIRED for device implementations that include microphone hardware
+and define <code>android.hardware.microphone</code>.</td>
+<td style="text-align: center;">REQUIRED</td>
+<td>4.75 to 12.2 kbps sampled @ 8kHz</td>
+<td>3GPP (.3gp)
+</td>
+</tr>
+
+<tr>
+<td>AMR-WB</td>
+<td>REQUIRED for device implementations that include microphone hardware
+and define <code>android.hardware.microphone</code>.</td>
+<td style="text-align: center;">REQUIRED</td>
+<td>9 rates from 6.60 kbit/s to 23.85 kbit/s sampled @ 16kHz</td>
+<td>3GPP (.3gp)</td>
+</tr>
+
+<tr>
+<td>FLAC</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED<br/><small>(Android 3.1+)</small></td>
+<td>Mono/Stereo (no multichannel). Sample rates up to 48 kHz (but up to 44.1
+kHz is recommended on devices with 44.1 kHz output, as the 48 to 44.1 kHz
+downsampler does not include a low-pass filter). 16-bit recommended;
+no dither applied for 24-bit.
+</td>
+<td>FLAC (.flac) only</td>
+</tr>
+
+<tr>
+<td>MP3</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Mono/Stereo 8-320Kbps constant (CBR) or variable bit-rate (VBR)
+</td>
+<td>MP3 (.mp3)</td>
+</tr>
+
+<tr>
+<td>MIDI</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td>MIDI Type 0 and 1. DLS Version 1 and 2. XMF and Mobile XMF. Support for ringtone formats RTTTL/RTX, OTA, and iMelody </td>
+<td>
+ <ul>
+ <li>Type 0 and 1 (.mid, .xmf, .mxmf)</li>
+ <li>RTTTL/RTX (.rtttl, .rtx)</li>
+ <li>OTA (.ota)</li>
+ <li>iMelody (.imy)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>Vorbis</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>
+ <ul>
+ <li>Ogg (.ogg)</li>
+ <li>Matroska (.mkv)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>PCM/WAVE</td>
+<td style="text-align: center;">REQUIRED</td>
+<td style="text-align: center;">REQUIRED</td>
+<td>8-bit and 16-bit linear PCM** (rates up to limit of hardware).Devices MUST support sampling rates
+for raw PCM recording at 8000,16000 and 44100 Hz frequencies</td>
+<td>WAVE (.wav)</td>
+</tr>
+
+<tr>
+<td rowspan="5">Image</td>
+<td>JPEG</td>
+<td style="text-align: center;">REQUIRED</td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Base+progressive</td>
+<td>JPEG (.jpg)</td>
+</tr>
+
+<tr>
+<td>GIF</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>GIF (.gif)</td>
+</tr>
+
+<tr>
+<td>PNG</td>
+<td style="text-align: center;">REQUIRED</td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>PNG (.png)</td>
+</tr>
+
+<tr>
+<td>BMP</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>BMP (.bmp)</td>
+</tr>
+
+
+<tr>
+<td>WEBP</td>
+<td style="text-align: center;">REQUIRED</td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>WebP (.webp)</td>
+</tr>
+
+<tr>
+<td rowspan="4">Video</td>
+<td>H.263</td>
+<td>REQUIRED for device implementations that include camera hardware
+and define <code>android.hardware.camera</code> or
+<code>android.hardware.camera.front</code>.</td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>
+ <ul>
+ <li>3GPP (.3gp)</li>
+ <li>MPEG-4 (.mp4)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>H.264 AVC</td>
+<td>REQUIRED for device implementations that include camera hardware
+and define <code>android.hardware.camera</code> or
+<code>android.hardware.camera.front</code>.</td>
+<td style="text-align: center;">REQUIRED</td>
+<td>Baseline Profile (BP)</td>
+<td>
+ <ul>
+ <li>3GPP (.3gp)</li>
+ <li>MPEG-4 (.mp4)</li>
+ <li>MPEG-TS (.ts, AAC audio only, not seekable, Android 3.0+)</li>
+ </ul>
+</td>
+</tr>
+
+<tr>
+<td>MPEG-4 SP</td>
+<td> </td>
+<td style="text-align: center;">REQUIRED</td>
+<td> </td>
+<td>3GPP (.3gp)</td>
+</tr>
+
+<tr>
+<td>VP8</td>
+<td style="text-align: center;">REQUIRED<br/><small>(Android 4.3+)</small></td>
+<td style="text-align: center;">REQUIRED<br/><small>(Android 2.3.3+)</small></td>
+<td> </td>
+<td><a href="http://www.webmproject.org/">WebM</a> (.webm) and Matroska (.mkv, Android 4.0+)***</td>
+</tr>
+
+</tbody></table>
+<ul>
+<li>*Note: Only downmix of 5.0/5.1 content is required; recording or rendering more than 2 channels is optional.</li>
+<li>**Note: 16-bit linear PCM capture is mandatory. 8-bit linear PCM capture is not mandatory.</li>
+<li>***Note: Device implementations SHOULD support writing Matroska WebM files.</li>
+</ul>
+
+<a name="section-5.2"></a><h3>5.2 Video Encoding</h3>
+<p>Android device implementations that include a rear-facing camera and declare
+<code>android.hardware.camera</code> SHOULD support the following H.264 video encoding
+profiles.</p>
+<table>
+ <thead>
+ <tr>
+ <th> </th>
+ <th>SD (Low quality)</th>
+ <th>SD (High quality)</th>
+ <th>HD (When supported by hardware)</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <th>Video resolution</th>
+ <td>176 x 144 px</td>
+ <td>480 x 360 px</td>
+ <td>1280 x 720 px</td>
+ </tr>
+ <tr>
+ <th>Video frame rate</th>
+ <td>12 fps</td>
+ <td>30 fps</td>
+ <td>30 fps</td>
+ </tr>
+ <tr>
+ <th>Video bitrate</th>
+ <td>56 Kbps</td>
+ <td>500 Kbps or higher</td>
+ <td>2 Mbps or higher</td>
+ </tr>
+ <tr>
+ <th>Audio codec</th>
+ <td>AAC-LC</td>
+ <td>AAC-LC</td>
+ <td>AAC-LC</td>
+ </tr>
+ <tr>
+ <th>Audio channels</th>
+ <td>1 (mono)</td>
+ <td>2 (stereo)</td>
+ <td>2 (stereo)</td>
+ </tr>
+ <tr>
+ <th>Audio bitrate</th>
+ <td>24 Kbps</td>
+ <td>128 Kbps</td>
+ <td>192 Kbps</td>
+ </tr>
+ </tbody>
+</table>
+
+<p>Android device implementations that include a rear-facing camera and declare
+<code>android.hardware.camera</code> SHOULD support the following VP8 video encoding profiles</p>
+<table>
+ <thead>
+ <tr>
+ <th> </th>
+ <th>SD (Low quality)</th>
+ <th>SD (High quality)</th>
+ <th>HD 720p <br/> (When supported by hardware)</th>
+ <th>HD 1080p <br/>(When supported by hardware)</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <th>Video resolution</th>
+ <td>320 x 180 px</td>
+ <td>640 x 360 px</td>
+ <td>1280 x 720 px</td>
+ <td>1920 x 1080 px</td>
+ </tr>
+ <tr>
+ <th>Video frame rate</th>
+ <td>30 fps</td>
+ <td>30 fps</td>
+ <td>30 fps</td>
+ <td>30 fps</td>
+ </tr>
+ <tr>
+ <th>Video bitrate</th>
+ <td>800 Kbps</td>
+ <td>2 Mbps</td>
+ <td>4 Mbps</td>
+ <td>10 Mbps</td>
+ </tr>
+ </tbody>
+</table>
+
+<a name="section-5.3"></a><h3>5.3 Video Decoding</h3>
+<p>Android device implementations SHOULD support the following VP8 and H.264 video decoding profiles.</p>
+<table>
+ <thead>
+ <tr>
+ <th> </th>
+ <th>SD (Low quality)</th>
+ <th>SD (High quality)</th>
+ <th>HD 720p <br/> (When supported by hardware)</th>
+ <th>HD 1080p <br/>(When supported by hardware)</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <th>Video resolution</th>
+ <td>320 x 180 px</td>
+ <td>640 x 360 px</td>
+ <td>1280 x 720 px</td>
+ <td>1920 x 1080 px</td>
+ </tr>
+ <tr>
+ <th>Video frame rate</th>
+ <td>30 fps</td>
+ <td>30 fps</td>
+ <td>30 fps</td>
+ <td>30 fps</td>
+ </tr>
+ <tr>
+ <th>Video bitrate</th>
+ <td>800 Kbps</td>
+ <td>2 Mbps</td>
+ <td>8 Mbps</td>
+ <td>20 Mbps</td>
+ </tr>
+ </tbody>
+</table>
+
+<a name="section-5.4"></a><h3>5.4. Audio Recording</h3>
+<p>When an application has used the <code>android.media.AudioRecord</code> API to
+start recording an audio stream, device implementations that include microphone
+hardware and declare <code>android.hardware.microphone</code> MUST sample and
+record audio with each of these behaviors:</p>
+<ul>
+<li>The device SHOULD exhibit approximately flat amplitude versus frequency
+ characteristics; specifically, ±3 dB, from 100 Hz to 4000 Hz</li>
+<li>Audio input sensitivity SHOULD be set such that a 90 dB sound power level
+ (SPL) source at 1000 Hz yields RMS of 2500 for 16-bit samples.</li>
+<li>PCM amplitude levels SHOULD linearly track input SPL changes over at least
+ a 30 dB range from -18 dB to +12 dB re 90 dB SPL at the microphone.</li>
+<li>Total harmonic distortion SHOULD be less than 1% for 1Khz at 90 dB SPL input level.</li>
+</ul>
+<p>In addition to the above recording specifications, when an application has
+started recording an audio stream using the
+<code>android.media.MediaRecorder.AudioSource.VOICE_RECOGNITION</code> audio
+source:</p>
+<ul>
+<li>Noise reduction processing, if present, MUST be disabled.</li>
+<li>Automatic gain control, if present, MUST be disabled.</li>
+</ul>
+<p><b>Note:</b> while some of the requirements outlined above are stated as "SHOULD"
+for Android 4.3, the Compatibility Definition for a future version is planned
+to change these to "MUST". That is, these requirements are optional in Android
+4.3 but <b>will be required</b> by a future version. Existing and new devices
+that run Android 4.3 are <b>very strongly encouraged to meet
+these requirements in Android 4.3</b>, or they will not be able to attain
+Android compatibility when upgraded to the future version.</p>
+
+<a name="section-5.5"></a><h3>5.5. Audio Latency</h3>
+<p>Audio latency is the time delay as an audio signal passes through a system.
+Many classes of
+applications rely on short latencies, to achieve real-time sound effects.</p>
+<p>For the purposes of this section:</p>
+<ul>
+<li>"output latency" is defined as the interval between when an application
+writes a frame of PCM-coded data and when the corresponding sound can be heard
+by an external listener or observed by a transducer</li>
+<li>"cold output latency" is defined as the output latency for the first frame, when
+ the audio output system has been idle and powered down prior to the request</li>
+<li>"continuous output latency" is defined as the output latency for subsequent frames,
+ after the device is already playing audio</li>
+<li>"input latency" is the interval between when an external sound is presented
+to the device and when an application reads the corresponding frame of PCM-coded data</li>
+<li>"cold input latency" is defined as the sum of lost input time
+ and the input latency for the first frame, when
+ the audio input system has been idle and powered down prior to the request</li>
+<li>"continuous input latency" is defined as the input latency for subsequent frames,
+ while the device is already capturing audio</li>
+<li>"OpenSL ES PCM buffer queue API" is the set of PCM-related OpenSL ES APIs within Android NDK;
+see <i>NDK_root</i><code>/docs/opensles/index.html</code></li>
+</ul>
+<p>Per <a href="#section-5">Section 5</a>,
+all compatible device implementations MUST include at least one form of audio output.
+Device implementations SHOULD meet or exceed these output latency requirements:</p>
+<ul>
+<li>cold output latency of 100 milliseconds or less</li>
+<li>continuous output latency of 45 milliseconds or less</li>
+</ul>
+<p>If a device implementation meets the requirements of this section
+after any initial calibration
+when using the OpenSL ES PCM buffer queue API,
+for continuous output latency and cold output latency
+over at least one supported audio output device, it MAY
+report support for low-latency audio, by reporting the feature
+"android.hardware.audio.low-latency" via the
+<code>android.content.pm.PackageManager</code> class. [<a
+href="#resources37">Resources, 37</a>] Conversely, if the device
+implementation does not meet these requirements it MUST NOT report support for
+low-latency audio.</p>
+<p>
+Per <a href="#section-7.2.5">Section 7.2.5</a>,
+microphone hardware may be omitted by device implementations.</p>
+<p>
+Device implementations that include microphone
+hardware and declare <code>android.hardware.microphone</code> SHOULD
+meet these input audio latency requirements:</p>
+<ul>
+<li>cold input latency of 100 milliseconds or less</li>
+<li>continuous input latency of 50 milliseconds or less</li>
+</ul>
+
+<a name="section-5.6"></a><h3>5.6. Network Protocols</h3>
+<p>Devices MUST support the media network protocols for audio and video playback
+as specified in the Android SDK documentation
+[<a href="#resources58">Resources, 58</a>]. Specifically, devices MUST support
+the following media network protocols:</p>
+<ul>
+<li>RTSP (RTP, SDP)</li>
+<li>HTTP(S) progressive streaming</li>
+<li>HTTP(S) Live Streaming draft protocol, Version 3 [<a href="#resources59">Resources, 59</a>]</li>
+</ul>
+<a name="section-6"></a><h2>6. Developer Tools and Options Compatibility</h2>
+
+<a name="section-6.1"></a><h3>6.1 Developer Tools</h3>
+<p>Device implementations MUST support the Android Developer Tools provided in the Android SDK.
+Specifically, Android-compatible devices MUST be compatible with:</p>
+<ul>
+<li><b>Android Debug Bridge (known as adb)</b> [<a href="#resources33">Resources, 33</a>]<br/>
+Device implementations MUST support all <code>adb</code> functions as
+documented in the Android SDK. The device-side <code>adb</code> daemon MUST
+be inactive by default, and there MUST be a user-accessible mechanism to turn
+on the Android Debug Bridge.</li>
+<li>Android 4.3 includes support for secure adb. Secure adb enables adb on known authenticated hosts.
+Device implementations MUST support secure adb.</li>
+<li><b>Dalvik Debug Monitor Service (known as ddms)</b> [<a href="#resources33">Resources, 33</a>]<br/>
+Device implementations MUST support all <code>ddms</code> features as documented in the
+Android SDK. As <code>ddms</code> uses <code>adb</code>, support for
+<code>ddms</code> SHOULD be inactive by default,
+but MUST be supported whenever the user has activated the Android Debug
+Bridge, as above.</li>
+<li><b>Monkey</b> [<a href="#resources36">Resources, 36</a>]<br/>
+Device implementations MUST include the Monkey framework, and make it
+available for applications to use.</li>
+<li><b>SysTrace</b> [<a href="#resources33">Resources, 33</a>]<br/>
+Device implementations MUST support systrace tool as documented in the Android SDK.
+Systrace must be inactive by default, and there MUST be a user-accessible mechanism to turn
+on Systrace.</li>
+</ul>
+<p>Most Linux-based systems and Apple Macintosh systems recognize Android
+devices using the standard Android SDK tools, without additional support;
+however Microsoft Windows systems typically require a driver for new Android
+devices. (For instance, new vendor IDs and sometimes new device IDs require
+custom USB drivers for Windows systems.) If a device implementation is
+unrecognized by the <code>adb</code> tool as provided in the standard Android
+SDK, device implementers MUST provide Windows drivers allowing developers to
+connect to the device using the <code>adb</code> protocol. These drivers MUST
+be provided for Windows XP, Windows Vista, Windows 7, and Windows 8, in both 32-bit and
+64-bit versions.</p>
+
+<a name="section-6.2"></a><h3>6.2 Developer Options</h3>
+<p>Android 4.3 includes support for developers to configure application development-related settings.
+Device implementations MUST honor the android.settings.APPLICATION_DEVELOPMENT_SETTINGS intent to show
+application development-related settings [<a href="#resources77">Resources, 77</a>]. The upstream Android
+implementation hides the Developer Options menu by default, and enables users to launch Developer Options
+after pressing seven (7) times on the Settings > About Device > Build Number menu item. Device implementations
+MUST provide a consistent experience for Developer Options. Specifically, device implementations MUST hide
+Developer Options by default and MUST provide a mechanism to enable Developer Options that is consistent with
+the upstream Android implementation.</p>
+
+<a name="section-7"></a><h2>7. Hardware Compatibility</h2>
+<p>If a device includes a particular hardware component that has a
+corresponding API for third-party developers, the device implementation MUST
+implement that API as described in the Android SDK documentation. If an API in
+the SDK interacts with a hardware component that is stated to be optional and
+the device implementation does not possess that component:</p>
+<ul>
+<li>complete class definitions (as documented by the SDK) for the component's
+APIs MUST still be present</li>
+<li>the API's behaviors MUST be implemented as no-ops in some reasonable
+fashion</li>
+<li>API methods MUST return null values where permitted by the SDK
+documentation</li>
+<li>API methods MUST return no-op implementations of classes where null
+values are not permitted by the SDK documentation</li>
+<li>API methods MUST NOT throw exceptions not documented by the SDK
+documentation</li>
+</ul>
+<p>A typical example of a scenario where these requirements apply is the
+telephony API: even on non-phone devices, these APIs must be implemented as
+reasonable no-ops.</p>
+<p>Device implementations MUST accurately report accurate hardware configuration
+information via the <code>getSystemAvailableFeatures()</code> and
+<code>hasSystemFeature(String)</code> methods on the
+<code>android.content.pm.PackageManager</code> class. [<a
+href="#resources37">Resources, 37</a>]</p>
+
+<a name="section-7.1"></a><h3>7.1. Display and Graphics</h3>
+<p>Android 4.3 includes facilities that automatically adjust application
+assets and UI layouts appropriately for the device, to ensure that third-party
+applications run well on a variety of hardware configurations [<a
+href="#resources38">Resources, 38</a>]. Devices MUST properly implement these
+APIs and behaviors, as detailed in this section.</p>
+
+<p>The units referenced by the requirements in this section are defined as follows:</p>
+<ul>
+<li>"Physical diagonal size" is the distance in inches between two opposing
+corners of the illuminated portion of the display.</li>
+<li>"dpi" (meaning "dots per inch") is the number of pixels encompassed by a
+linear horizontal or vertical span of 1". Where dpi values are listed, both
+horizontal and vertical dpi must fall within the range.</li>
+<li>"Aspect ratio" is the ratio of the longer dimension of the screen to the
+shorter dimension. For example, a display of 480x854 pixels would be 854 / 480
+= 1.779, or roughly "16:9".</li>
+<li>A "density-independent pixel" or ("dp") is the virtual pixel unit normalized to a
+160 dpi screen, calculated as:
+<code>pixels = dps * (density / 160)</code>.</li>
+</ul>
+
+
+<a name="section-7.1.1"></a><h4>7.1.1. Screen Configuration</h4>
+
+<p style="font-weight:bold;">Screen Size</p>
+<p>The Android UI framework supports a variety of different screen sizes, and
+allows applications to query the device screen size (aka "screen layout") via
+<code>android.content.res.Configuration.screenLayout</code> with the
+<code>SCREENLAYOUT_SIZE_MASK</code>. Device implementations MUST report the
+correct screen size as defined in the Android SDK documentation
+[<a href="#resources38">Resources, 38</a>] and determined by the upstream
+Android platform. Specifically, device implementations must report the correct
+screen size according to the following logical density-independent pixel (dp)
+screen dimensions.</p>
+<ul>
+<li>Devices MUST have screen sizes of at least 426 dp x 320 dp ('small')</li>
+<li>Devices that report screen size 'normal' MUST have screen sizes of at least
+480 dp x 320 dp</li>
+<li>Devices that report screen size 'large' MUST have screen sizes of at least
+640 dp x 480 dp</li>
+<li>Devices that report screen size 'xlarge' MUST have screen sizes of at least
+960 dp x 720 dp</li>
+</ul>
+<p>In addition, devices MUST have screen sizes of at least 2.5 inches in
+physical diagonal size.</p>
+
+<p>Devices MUST NOT change their reported screen size at any time.</p>
+<p>Applications optionally indicate which screen sizes they support via the
+<code><supports-screens></code> attribute in the AndroidManifest.xml
+file. Device implementations MUST correctly honor applications' stated support
+for small, normal, large, and xlarge screens, as described in the Android
+SDK documentation.</p>
+
+<p style="font-weight:bold;">Screen Aspect Ratio</p>
+<p>The aspect ratio MUST be between 1.3333 (4:3) and 1.85 (16:9).</p>
+
+<p style="font-weight:bold;">Screen Density</p>
+<p>The Android UI framework defines a set of standard logical densities to
+help application developers target application resources. Device
+implementations MUST report one of the following logical Android framework
+densities through the <code>android.util.DisplayMetrics</code> APIs, and MUST
+execute applications at this standard density.
+<ul>
+<li>120 dpi, known as 'ldpi'</li>
+<li>160 dpi, known as 'mdpi'</li>
+<li>213 dpi, known as 'tvdpi'</li>
+<li>240 dpi, known as 'hdpi'</li>
+<li>320 dpi, known as 'xhdpi'</li>
+<li>480 dpi, known as 'xxhdpi'</li>
+<li>640 dpi, known as 'xxxhdpi'</li>
+</ul>
+Device implementations SHOULD define the standard Android framework density
+that is numerically closest to the physical density of the screen, unless that
+logical density pushes the reported screen size below the minimum supported.
+If the standard Android framework density that is numerically closest to the
+physical density results in a screen size that is smaller than the smallest
+supported compatible screen size (320 dp width), device implementations SHOULD
+report the next lowest standard Android framework density.</p>
+
+<a name="section-7.1.2"></a><h4>7.1.2. Display Metrics</h4>
+<p>Device implementations MUST report correct values for all display metrics
+defined in <code>android.util.DisplayMetrics</code> [<a
+href="#resources39">Resources, 39</a>].</p>
+
+<a name="section-7.1.3"></a><h4>7.1.3. Screen Orientation</h4>
+<p>Devices MUST support dynamic orientation by applications to
+either portrait or landscape screen orientation. That is, the device must
+respect the application's request for a specific screen orientation. Device
+implementations MAY select either portrait or landscape orientation as the
+default.</p>
+<p>Devices MUST report the correct value for the device's current orientation,
+whenever queried via the android.content.res.Configuration.orientation,
+android.view.Display.getOrientation(), or other APIs.</p>
+<p>Devices MUST NOT change the reported screen size or density when changing
+orientation.</p>
+<p>Devices MUST report which screen orientations they support (
+<code>android.hardware.screen.portrait</code> and/or
+<code>android.hardware.screen.landscape</code>) and MUST report at least one
+supported orientation. For example, a device with a fixed-orientation
+landscape screen, such as a television or laptop, MUST only report
+<code>android.hardware.screen.landscape</code>.</p>
+
+<a name="section-7.1.4"></a><h4>7.1.4. 2D and 3D Graphics Acceleration</h4>
+<p>Device implementations MUST support both OpenGL ES 1.0 and 2.0, as embodied
+and detailed in the Android SDK documentations. Device implementations SHOULD support
+OpenGL ES 3.0 on devices capable of supporting OpenGL ES 3.0.
+Device implementations MUST also support Android Renderscript, as detailed in the Android SDK
+documentation [<a href="#resources08">Resources, 8</a>].</p>
+<p>Device implementations MUST also correctly identify themselves as
+supporting OpenGL ES 1.0, OpenGL ES 2.0, or OpenGL ES 3.0. That is:</p>
+<ul>
+<li>The managed APIs (such as via the <code>GLES10.getString()</code> method)
+MUST report support for OpenGL ES 1.0 and OpenGL ES 2.0 </li>
+<li>The native C/C++ OpenGL APIs (that is, those available to apps via
+libGLES_v1CM.so, libGLES_v2.so, or libEGL.so) MUST report support for
+OpenGL ES 1.0 and OpenGL ES 2.0.</li>
+<li>Device implementations that declare support for OpenGL ES 3.0 MUST support
+OpenGL ES 3.0 managed APIs and include support for native C/C++ APIs. On device
+implementations that declare support for OpenGL ES 3.0, libGLESv2.so MUST export the OpenGL ES 3.0
+function symbols in addition to the OpenGL ES 2.0 function symbols.
+</li>
+</ul>
+
+<p>Device implementations MAY implement any desired OpenGL ES extensions.
+However, device implementations MUST report via the OpenGL ES managed and
+native APIs all extension strings that they do support, and conversely MUST
+NOT report extension strings that they do not support.</p>
+<p>Note that Android 4.3 includes support for applications to optionally
+specify that they require specific OpenGL texture compression formats. These
+formats are typically vendor-specific. Device implementations are not required
+by Android 4.3 to implement any specific texture compression format. However,
+they SHOULD accurately report any texture compression formats that they do
+support, via the <code>getString()</code> method in the OpenGL API.</p>
+
+<p>Android 4.3 includes a mechanism for applications to declare that they
+wanted to enable hardware acceleration for 2D graphics at the Application,
+Activity, Window or View level through the use of a manifest tag
+<code>android:hardwareAccelerated</code> or direct API calls
+[<a href="#resources09">Resources, 9</a>].</p>
+<p>In Android 4.3, device implementations MUST enable hardware acceleration by
+default, and MUST disable hardware acceleration if the developer so requests
+by setting <code>android:hardwareAccelerated="false"</code> or disabling
+hardware acceleration directly through the Android View APIs.</p>
+<p>In addition, device implementations MUST exhibit behavior consistent with the
+Android SDK documentation on hardware acceleration
+[<a href="#resources09">Resources, 9</a>].</p>
+<p>Android 4.3 includes a <code>TextureView</code> object that lets developers
+directly integrate hardware-accelerated OpenGL ES textures as rendering targets
+in a UI hierarchy. Device implementations MUST support the <code>TextureView
+</code> API, and MUST exhibit consistent behavior with the upstream Android
+implementation.</p>
+<p>Android 4.3 includes support for <code>EGL_ANDROID_RECORDABLE</code>, a EGLConfig attribute
+that indicates whether the EGLConfig supports rendering to an ANativeWindow that records images to a video.
+Device implementations MUST support <code>EGL_ANDROID_RECORDABLE</code> extension [<a href="#resources79">Resources, 79</a>].</p>
+
+<a name="section-7.1.5"></a><h4>7.1.5. Legacy Application Compatibility Mode</h4>
+<p>Android 4.3 specifies a "compatibility mode" in which the framework
+operates in an 'normal' screen size equivalent (320dp width) mode for the benefit
+of legacy applications not developed for old versions of Android that pre-date
+screen-size independence. Device implementations MUST include support for legacy
+application compatibility mode as implemented by the upstream Android open source
+code. That is, device implementations MUST NOT alter the triggers or thresholds at
+which compatibility mode is activated, and MUST NOT alter the behavior of the
+compatibility mode itself.</p>
+
+<a name="section-7.1.6"></a><h4>7.1.6. Screen Types</h4>
+<p>Device implementation screens are classified as one of two types:</p>
+<ul>
+<li>Fixed-pixel display implementations: the screen is a single panel that supports only a
+single pixel width and height. Typically the screen is physically integrated with
+the device. Examples include mobile phones, tablets, and so on.</li>
+<li>Variable-pixel display implementations: the device implementation either has no
+embedded screen and includes a video output port such as VGA, HDMI or a wireless port
+for display, or has an embedded screen that can change pixel dimensions. Examples
+include televisions, set-top boxes, and so on.</li>
+</ul>
+<p style="font-weight: bold;">Fixed-Pixel Device Implementations</p>
+<p>Fixed-pixel device implementations MAY use screens of any pixel dimensions, provided
+that they meet the requirements defined this Compatibility Definition.</p>
+<p>Fixed-pixel implementations MAY include a video output port for use with an
+external display. However, if that display is ever used for running apps, the
+device MUST meet the following requirements:</p>
+<ul>
+<li>The device MUST report the same screen configuration and display metrics, as detailed
+in Sections 7.1.1 and 7.1.2, as the fixed-pixel display.</li>
+<li>The device MUST report the same logical density as the fixed-pixel display.</li>
+<li>The device MUST report screen dimensions that are the same as, or very close to,
+the fixed-pixel display.</li>
+</ul>
+<p>For example, a tablet that is 7" diagonal size with a 1024x600 pixel resolution is
+considered a fixed-pixel large mdpi display implementation. If it contains a video
+output port that displays at 720p or 1080p, the device implementation MUST scale the output so that
+applications are only executed in a large mdpi window, regardless of whether the fixed-pixel display
+or video output port is in use.</p>
+
+<p style="font-weight: bold;">Variable-Pixel Device Implementations</p>
+<p>Variable-pixel device implementations MUST support one or both of 1280x720,
+or 1920x1080 (that is, 720p or 1080p). Device implementations with
+variable-pixel displays MUST NOT support any other screen configuration or
+mode. Device implementations with variable-pixel screens MAY change screen
+configuration or mode at runtime or boot-time. For example, a user of a
+set-top box may replace a 720p display with a 1080p display, and the device
+implementation may adjust accordingly.</p>
+
+<p>Additionally, variable-pixel device implementations MUST report the following
+configuration buckets for these pixel dimensions:</p>
+<ul>
+<li>1280x720 (also known as 720p): 'large' screen size, 'tvdpi' (213 dpi)
+density</li>
+<li>1920x1080 (also known as 1080p): 'large' screen size, 'xhdpi' (320 dpi)
+density</li>
+</ul>
+<p>For clarity, device implementations with variable pixel dimensions are
+restricted to 720p or 1080p in Android 4.3, and MUST be configured to report
+screen size and density buckets as noted above.</p>
+
+<a name="section-7.1.7"></a><h4>7.1.7. Screen Technology</h4>
+<p>The Android platform includes APIs that allow applications to render rich
+graphics to the display. Devices MUST support all of these APIs as defined by
+the Android SDK unless specifically allowed in this document. Specifically:</p>
+<ul>
+<li>Devices MUST support displays capable of rendering 16-bit color graphics and
+SHOULD support displays capable of 24-bit color graphics.</li>
+<li>Devices MUST support displays capable of rendering animations.</li>
+<li>The display technology used MUST have a pixel aspect ratio (PAR) between
+ 0.9 and 1.1. That is, the pixel aspect ratio MUST be near square (1.0) with
+ a 10% tolerance.</li>
+</ul>
+<a name="section-7.1.8"></a><h4>7.1.8. External Displays</h4>
+<p>Android 4.3 includes support for secondary display to enable media sharing capabilities and
+developer APIs for accessing external displays. If a device supports an external display either via
+a wired, wireless or an embedded additional display connection then the device implementation MUST
+implement the display manager API as described in the Android SDK documentation [<a href="#resources75">Resources, 75</a>].
+Device implementations that support secure video output and are capable of supporting secure surfaces MUST declare support
+for <code>Display.FLAG_SECURE</code>. Specifically, device implementations that declare support for <code>Display.FLAG_SECURE</code>,
+MUST support <b>HDCP 2.x or higher</b> for Miracast wireless displays or <b>HDCP 1.2 or higher</b> for wired displays. The upstream
+Android open source implementation includes support for wireless (Miracast) and wired (HDMI) displays that satisfies this requirement.</p>
+
+<a name="section-7.2"></a><h3>7.2. Input Devices</h3>
+<a name="section-7.2.1"></a><h4>7.2.1. Keyboard</h4>
+<p>Device implementations:</p>
+<ul>
+<li>MUST include support for the Input Management Framework (which allows third
+party developers to create Input Management Engines - i.e. soft keyboard) as
+detailed at <a href="http://developer.android.com">http://developer.android.com</a>
+</li>
+<li>MUST provide at least one soft keyboard implementation (regardless of whether
+a hard keyboard is present)</li>
+<li>MAY include additional soft keyboard implementations</li>
+<li>MAY include a hardware keyboard</li>
+<li>MUST NOT include a hardware keyboard that does not match one of the
+formats specified in <code>android.content.res.Configuration.keyboard</code>
+[<a href="#resources40">Resources, 40</a>] (that is, QWERTY, or 12-key)</li>
+</ul>
+<a name="section-7.2.2"></a><h4>7.2.2. Non-touch Navigation</h4>
+<p>Device implementations:</p>
+<ul>
+<li>MAY omit a non-touch navigation option (that is, may omit a trackball, d-pad,
+or wheel)</li>
+<li>MUST report the correct value for
+<code>android.content.res.Configuration.navigation</code>
+[<a href="#resources40">Resources, 40</a>]</li>
+<li>MUST provide a reasonable alternative user interface mechanism for the
+selection and editing of text, compatible with Input Management Engines. The
+upstream Android open source implementation includes a selection mechanism suitable
+for use with devices that lack non-touch navigation inputs.</li>
+</ul>
+<a name="section-7.2.3"></a><h4>7.2.3. Navigation keys</h4>
+<p>The Home, Menu and Back functions are essential to the Android navigation
+paradigm. Device implementations MUST make these functions available to the
+user at all times when running applications. These functions MAY be implemented
+via dedicated physical buttons (such as mechanical or capacitive touch buttons),
+or MAY be implemented using dedicated software keys, gestures, touch panel, etc.
+Android 4.3 supports both implementations.</p>
+
+<p>Android 4.3 includes support for assist action [<a href="#resources63">Resources, 63</a>].
+Device implementations MUST make the assist action available to the user at all times when running applications.
+This function MAY be implemented via hardware or software keys.</p>
+
+<p>Device implementations MAY use a distinct portion of the screen to display
+the navigation keys, but if so, MUST meet these requirements:</p>
+
+<ul>
+ <li>Device implementation navigation keys MUST use a distinct portion of the
+ screen, not available to applications, and MUST NOT obscure or otherwise
+ interfere with the portion of the screen available to applications.</li>
+ <li>Device implementations MUST make available a portion of the display to
+ applications that meets the requirements defined in
+ <a href="section-7.1.1">Section 7.1.1</a>.</li>
+ <li>Device implementations MUST display the navigation keys when applications
+ do not specify a system UI mode, or specify
+ <code>SYSTEM_UI_FLAG_VISIBLE</code>.</li>
+ <li>Device implementations MUST present the navigation keys in an unobtrusive
+ "low profile" (eg. dimmed) mode when applications specify
+ <code>SYSTEM_UI_FLAG_LOW_PROFILE</code>.</li>
+ <li>Device implementations MUST hide the navigation keys when applications
+ specify <code>SYSTEM_UI_FLAG_HIDE_NAVIGATION</code>.</li>
+ <li>Device implementation MUST present a Menu key to applications when
+ targetSdkVersion <= 10 and SHOULD NOT present a Menu key when the
+ targetSdkVersion > 10.</li>
+</ul>
+<a name="section-7.2.4"></a><h4>7.2.4. Touchscreen input</h4>
+<p>Device implementations SHOULD have a pointer input system of some kind (either mouse-like, or touch). However, if a device
+implementation does not support a pointer input system, it MUST NOT report the <code>android.hardware.touchscreen</code> or
+<code>android.hardware.faketouch</code> feature constant. Device implementations that do include a pointer input system:</p>
+<ul>
+<li>SHOULD support fully independently tracked pointers, if the device input system supports multiple pointers</li>
+<li>MUST report the value of <code>android.content.res.Configuration.touchscreen</code> [<a href="#resources40">Resources, 40</a>]
+corresponding to the type of the specific touchscreen on the device</li>
+</ul>
+
+<p>Android 4.3 includes support for a variety of touch screens, touch pads, and fake touch input devices.
+Touch screen based device implementations are associated with a display [<a href="#resources81">Resources, 81</a>]
+such that the user has the impression of directly manipulating items on screen. Since the user is directly touching the screen,
+the system does not require any additional affordances to indicate the objects being manipulated.
+In contrast, a fake touch interface provides a user input system that approximates a subset of touchscreen capabilities.
+For example, a mouse or remote control that drives an on-screen cursor approximates touch, but requires the user to first
+point or focus then click. Numerous input devices like the mouse, trackpad, gyro-based air mouse, gyro-pointer, joystick,
+and multi-touch trackpad can support fake touch interactions. Android 4.0 includes the feature constant <code>android.hardware.faketouch</code>,
+which corresponds to a high-fidelity non-touch (that is, pointer-based) input device such as a mouse or trackpad that can adequately emulate touch-based
+input (including basic gesture support), and indicates that the device supports an emulated subset of touchscreen
+functionality. Device implementations that declare the fake touch feature MUST meet the fake touch requirements in <a href="section 7.2.5">Section 7.2.5</a>.</p>
+
+<p>Device implementations MUST report the correct feature corresponding to the type of input used. Device implementations that
+include a touchscreen (single-touch or better) MUST report the platform feature constant <code>android.hardware.touchscreen</code>.
+Device implementations that report the platform feature constant <code>android.hardware.touchscreen</code> MUST also report the platform feature constant
+<code>android.hardware.faketouch</code>. Device implementations that do not include a touchscreen (and rely on a pointer device only) MUST NOT report any
+touchscreen feature, and MUST report only <code>android.hardware.faketouch</code> if they meet the fake touch requirements in <a href="section 7.2.5">Section 7.2.5</a>.</p>
+
+<a name="section-7.2.5"></a><h4>7.2.5. Fake touch input</h4>
+<p>Device implementations that declare support for <code>android.hardware.faketouch</code></p>
+<ul>
+<li> MUST report the absolute X and Y screen positions of the pointer location and display a visual pointer on the screen [<a href="#resources80">Resources, 80</a>] </li>
+<li> MUST report touch event with the action code [<a href="#resources80">Resources, 80</a>] that specifies the state change
+that occurs on the pointer going <code>down</code> or <code>up</code> on the screen [<a href="#resources80">Resources, 80</a>] </li>
+<li> MUST support pointer <code>down</code> and <code>up</code> on an object on the screen, which allows users to emulate tap on an object on the screen</li>
+<li> MUST support pointer <code>down</code>, pointer <code>up</code>, pointer <code>down</code> then pointer <code>up</code> in the same place on an object on the screen
+within a time threshold, which allows users to emulate double tap on an object on the screen [<a href="#resources80">Resources, 80</a>]</li>
+<li>MUST support pointer <code>down</code> on an arbitrary point on the screen, pointer move to any other arbitrary point on the screen,
+followed by a pointer <code>up</code>, which allows users to emulate a touch drag</li>
+<li> MUST support pointer <code>down</code> then allow users to quickly move the object to a different position on the screen
+and then pointer <code>up</code> on the screen, which allows users to fling an object on the screen</li>
+</ul>
+
+<p>Devices that declare support for <code>android.hardware.faketouch.multitouch.distinct</code> MUST meet the requirements for
+faketouch above, and MUST also support distinct tracking of two or more independent pointer inputs.</p>
+
+<a name="section-7.2.6"></a><h4>7.2.6. Microphone</h4>
+<p>Device implementations MAY omit a microphone. However, if a device
+implementation omits a microphone, it MUST NOT report the
+<code>android.hardware.microphone</code> feature constant, and must implement
+the audio recording API as no-ops, per <a href="section-7">Section 7</a>.
+Conversely, device implementations that do possess a microphone:</p>
+<ul>
+<li>MUST report the <code>android.hardware.microphone</code> feature constant</li>
+<li>SHOULD meet the audio quality requirements in <a href="section-5.4">Section 5.4</a></li>
+<li>SHOULD meet the audio latency requirements in <a href="section-5.5">Section 5.5</a></li>
+</ul>
+
+<a name="section-7.3"></a><h3>7.3. Sensors</h3>
+<p>Android 4.3 includes APIs for accessing a variety of sensor types. Devices
+implementations generally MAY omit these sensors, as provided for in the
+following subsections. If a device includes a particular sensor type that has a
+corresponding API for third-party developers, the device implementation MUST
+implement that API as described in the Android SDK documentation. For example,
+device implementations:</p>
+<ul>
+<li>MUST accurately report the presence or absence of sensors per the
+<code>android.content.pm.PackageManager</code> class. [<a
+href="#resources37">Resources, 37</a>]</li>
+<li>MUST return an accurate list of supported sensors via the
+<code>SensorManager.getSensorList()</code> and similar methods</li>
+<li>MUST behave reasonably for all other sensor APIs (for example, by
+returning true or false as appropriate when applications attempt to register
+listeners, not calling sensor listeners when the corresponding sensors are not
+present; etc.)</li>
+<li>MUST report all sensor measurements using the relevant International System
+of Units (i.e. metric) values for each sensor type as defined in the Android SDK
+documentation [<a href="#resources41">Resources, 41</a>]</li>
+</ul>
+<p>The list above is not comprehensive; the documented behavior of the Android
+SDK is to be considered authoritative.</p>
+<p>Some sensor types are synthetic, meaning they can be derived from data
+provided by one or more other sensors. (Examples include the orientation
+sensor, and the linear acceleration sensor.) Device implementations SHOULD
+implement these sensor types, when they include the prerequisite physical
+sensors.</p>
+<p>The Android 4.3 includes a notion of a "streaming" sensor, which is
+one that returns data continuously, rather than only when the data changes.
+Device implementations MUST continuously provide periodic data samples for any
+API indicated by the Android 4.3 SDK documentation to be a streaming
+sensor. Note that the device implementations MUST ensure that the sensor stream must not
+prevent the device CPU from entering a suspend state or waking up from a suspend state.</p>
+
+<a name="section-7.3.1"></a><h4>7.3.1. Accelerometer</h4>
+<p>Device implementations SHOULD include a 3-axis accelerometer. If a device
+implementation does include a 3-axis accelerometer, it:</p>
+<ul>
+<li>SHOULD be able to deliver events at 120 Hz or greater. Note that while the
+accelerometer frequency above is stated as "SHOULD" for Android 4.3, the Compatibility Definition
+for a future version is planned to change these to "MUST". That is, these standards are
+optional in Android 4.3 but <b>will be required</b> in future versions. Existing and
+new devices that run Android 4.3 are <b>very strongly encouraged to meet these requirements
+in Android 4.3</b> so they will be able to upgrade to the future platform releases
+</li>
+<li>MUST comply with the Android sensor coordinate system as detailed
+in the Android APIs (see [<a href="#resources41">Resources, 41</a>])</li>
+<li>MUST be capable of measuring from freefall up to twice gravity (2g) or
+more on any three-dimensional vector</li>
+<li>MUST have 8-bits of accuracy or more</li>
+<li>MUST have a standard deviation no greater than 0.05 m/s^2</li>
+</ul>
+<a name="section-7.3.2"></a><h4>7.3.2. Magnetometer</h4>
+<p>Device implementations SHOULD include a 3-axis magnetometer (i.e. compass.)
+If a device does include a 3-axis magnetometer, it:</p>
+<ul>
+<li>MUST be able to deliver events at 10 Hz or greater</li>
+<li>MUST comply with the Android sensor coordinate system as detailed
+in the Android APIs (see [<a href="#resources41">Resources, 41</a>]).</li>
+<li>MUST be capable of sampling a range of field strengths adequate to cover the
+geomagnetic field</li>
+<li>MUST have 8-bits of accuracy or more</li>
+<li>MUST have a standard deviation no greater than 0.5 µT</li>
+</ul>
+<a name="section-7.3.3"></a><h4>7.3.3. GPS</h4>
+<p>Device implementations SHOULD include a GPS receiver. If a device
+implementation does include a GPS receiver, it SHOULD include
+some form of "assisted GPS" technique to minimize GPS lock-on time.</p>
+<a name="section-7.3.4"></a><h4>7.3.4. Gyroscope</h4>
+<p>Device implementations SHOULD include a gyroscope (i.e. angular change
+sensor.) Devices SHOULD NOT include a gyroscope sensor unless a 3-axis
+accelerometer is also included. If a device implementation includes a
+gyroscope, it:</p>
+<ul>
+<li>MUST be temperature compensated</li>
+<li>MUST be capable of measuring orientation changes up to 5.5*Pi
+radians/second (that is, approximately 1,000 degrees per second)</li>
+<li>SHOULD be able to deliver events at 200 Hz or greater. Note that while the
+gyroscope frequency above is stated as "SHOULD" for Android 4.3, the Compatibility Definition
+for a future version is planned to change these to "MUST". That is, these standards are
+optional in Android 4.3 but <b>will be required</b> in future versions. Existing and
+new devices that run Android 4.3 are <b>very strongly encouraged to meet these requirements
+in Android 4.3</b> so they will be able to upgrade to the future platform releases
+</li>
+<li>MUST have 12-bits of accuracy or more</li>
+<li>MUST have a variance no greater than 1e-7 rad^2 / s^2 per Hz (variance per Hz, or rad^2 / s).
+The variance is allowed to vary with the sampling rate, but must be constrained by this value.
+In other words, if you measure the variance of the gyro at 1 Hz sampling rate it should be no
+greater than 1e-7 rad^2/s^2. </li>
+<li>MUST have timestamps as close to when the hardware event happened as possible. The constant latency must be removed.</li>
+</ul>
+<a name="section-7.3.5"></a><h4>7.3.5. Barometer</h4>
+<p>Device implementations MAY include a barometer (i.e. ambient air pressure
+sensor.) If a device implementation includes a barometer, it:</p>
+<ul>
+<li>MUST be able to deliver events at 5 Hz or greater</li>
+<li>MUST have adequate precision to enable estimating altitude</li>
+<li>MUST be temperature compensated</li>
+</ul>
+<a name="section-7.3.6"></a><h4>7.3.6. Thermometer</h4>
+<p>Device implementations MAY but SHOULD NOT include a thermometer (i.e.
+temperature sensor.) If a device implementation does include a thermometer, it
+MUST measure the temperature of the device CPU. It MUST NOT measure any other
+temperature. (Note that this sensor type is deprecated in the Android 4.3
+APIs.)</p>
+<a name="section-7.3.7"></a><h4>7.3.7. Photometer</h4>
+<p>Device implementations MAY include a photometer (i.e. ambient light
+sensor.)</p>
+<a name="section-7.3.8"></a><h4>7.3.8. Proximity Sensor</h4>
+<p>Device implementations MAY include a proximity sensor. If a device
+implementation does include a proximity sensor, it MUST measure the proximity
+of an object in the same direction as the screen. That is, the proximity
+sensor MUST be oriented to detect objects close to the screen, as the
+primary intent of this sensor type is to detect a phone in use by the
+user. If a device implementation includes a proximity sensor with any other
+orientation, it MUST NOT be accessible through this API. If a device
+implementation has a proximity sensor, it MUST be have 1-bit of accuracy or
+more.</p>
+
+<a name="section-7.4"></a><h3>7.4. Data Connectivity</h3>
+<a name="section-7.4.1"></a><h4>7.4.1. Telephony</h4>
+<p>"Telephony" as used by the Android 4.3 APIs and this document refers
+specifically to hardware related to placing voice calls and sending SMS
+messages via a GSM or CDMA network. While these voice calls may or may not be
+packet-switched, they are for the purposes of Android 4.3 considered
+independent of any data connectivity that may be implemented using the same
+network. In other words, the Android "telephony" functionality and APIs refer
+specifically to voice calls and SMS; for instance, device implementations that
+cannot place calls or send/receive SMS messages MUST NOT report the
+"android.hardware.telephony" feature or any sub-features, regardless of
+whether they use a cellular network for data connectivity.</p>
+<p>Android 4.3 MAY be used on devices that do not include telephony hardware.
+That is, Android 4.3 is compatible with devices that are not phones.
+However, if a device implementation does include GSM or CDMA telephony, it
+MUST implement full support for the API for that technology. Device
+implementations that do not include telephony hardware MUST implement the full
+APIs as no-ops.</p>
+<a name="section-7.4.2"></a><h4>7.4.2. IEEE 802.11 (WiFi)</h4>
+<p>Android 4.3 device implementations SHOULD include support for one or more
+forms of 802.11 (b/g/a/n, etc.) If a device implementation does include
+support for 802.11, it MUST implement the corresponding Android API.</p>
+<p>Device implementations MUST implement the multicast API as described in
+the SDK documentation [<a href="#resources62">Resources, 62</a>]. Device
+implementations that do include Wifi support MUST support multicast DNS (mDNS).
+Device implementations MUST NOT filter mDNS packets (224.0.0.251) at any time
+of operation including when the screen is not in an active state.</p>
+
+<a name="section-7.4.2.1"></a><h4>7.4.2.1. WiFi Direct</h4>
+<p>Device implementations SHOULD include support for Wifi direct (Wifi peer-to-peer).
+If a device implementation does include support for Wifi direct, it MUST implement the corresponding
+Android API as described in the SDK documentation [<a href="#resources68">Resources, 68</a>].
+If a device implementation includes support for Wifi direct, then it:</p>
+<ul>
+ <li>MUST support regular Wifi operation</li>
+ <li>SHOULD support concurrent wifi and wifi Direct operation</li>
+</ul>
+
+<a name="section-7.4.3"></a><h4>7.4.3. Bluetooth</h4>
+<p>Device implementations SHOULD include a Bluetooth transceiver. Device
+implementations that do include a Bluetooth transceiver MUST enable the
+RFCOMM-based Bluetooth API as described in the SDK documentation and declare
+hardware feature android.hardware.bluetooth [<a href="#resources42">Resources, 42</a>].
+Device implementations SHOULD implement relevant Bluetooth profiles, such as A2DP, AVRCP, OBEX, etc. as
+appropriate for the device.</p>
+
+<p>Device implementations that do include support for Bluetooth GATT (generic attribute profile)
+to enable communication with Bluetooth Smart or Smart Ready devices MUST enable the
+GATT-based Bluetooth API as described in the SDK documentation and declare hardware feature
+android.hardware.bluetooth_le [<a href="#resources42">Resources, 42</a>].</p>
+
+<a name="section-7.4.4"></a><h4>7.4.4. Near-Field Communications</h4>
+<p>Device implementations SHOULD include a transceiver and related hardware
+for Near-Field Communications (NFC). If a device implementation does include
+NFC hardware, then it:</p>
+<ul>
+ <li>MUST report the android.hardware.nfc feature from the
+ <code>android.content.pm.PackageManager.hasSystemFeature()</code> method.
+ [<a href="#resources37">Resources, 37</a>]</li>
+ <li>MUST be capable of reading and writing NDEF messages via the following NFC
+ standards:
+ <ul>
+ <li>MUST be capable of acting as an NFC Forum reader/writer
+ (as defined by the NFC Forum technical specification
+ NFCForum-TS-DigitalProtocol-1.0) via the following NFC standards:
+ <ul>
+ <li>NfcA (ISO14443-3A)</li>
+ <li>NfcB (ISO14443-3B) </li>
+ <li>NfcF (JIS 6319-4)</li>
+ <li>IsoDep (ISO 14443-4)</li>
+ <li>NFC Forum Tag Types 1, 2, 3, 4 (defined by the NFC Forum)</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>SHOULD be capable of reading and writing NDEF messages via the following
+ NFC standards. Note that while the NFC standards below are stated as
+ "SHOULD" for Android 4.3, the Compatibility Definition for a future
+ version is planned to change these to "MUST". That is, these standards are
+ optional in Android 4.3 but <b>will be required</b> in future versions.
+ Existing and new devices that run Android 4.3 are <b>very strongly
+ encouraged to meet these requirements in Android 4.3</b> so they will be
+ able to upgrade to the future platform releases.
+ <ul>
+ <li>NfcV (ISO 15693)</li>
+ </ul>
+ </li>
+ <li>MUST be capable of transmitting and receiving data via the following
+ peer-to-peer standards and protocols:
+ <ul>
+ <li>ISO 18092</li>
+ <li>LLCP 1.0 (defined by the NFC Forum)</li>
+ <li>SDP 1.0 (defined by the NFC Forum)</li>
+ <li>NDEF Push Protocol [<a href="#resources43">Resources, 43</a>]</li>
+ <li>SNEP 1.0 (defined by the NFC Forum)</li>
+ </ul>
+ </li>
+ <li>MUST include support for Android Beam [<a href="#resources65">Resources, 65</a>]:
+ <ul>
+ <li>MUST implement the SNEP default server. Valid NDEF messages received
+ by the default SNEP server MUST be dispatched to applications using
+ the android.nfc.ACTION_NDEF_DISCOVERED intent. Disabling Android Beam
+ in settings MUST NOT disable dispatch of incoming NDEF message.</li>
+ <li>Device implementations MUST honor the android.settings.NFCSHARING_SETTINGS intent
+ to show NFC sharing settings [<a href="#resources67">Resources, 67</a>].</li>
+ <li>MUST implement the NPP server. Messages received by the NPP server MUST
+ be processed the same way as the SNEP default server.</li>
+ <li>MUST implement a SNEP client and attempt to send outbound P2P NDEF to
+ the default SNEP server when Android Beam is enabled. If no default
+ SNEP server is found then the client MUST attempt to send to an NPP
+ server.</li>
+ <li>MUST allow foreground activities to set the outbound P2P NDEF message
+ using android.nfc.NfcAdapter.setNdefPushMessage, and
+ android.nfc.NfcAdapter.setNdefPushMessageCallback, and
+ android.nfc.NfcAdapter.enableForegroundNdefPush.</li>
+ <li>SHOULD use a gesture or on-screen confirmation, such as 'Touch to Beam',
+ before sending outbound P2P NDEF messages.</li>
+ <li>SHOULD enable Android Beam by default</li>
+ <li>MUST support NFC Connection handover to Bluetooth when the device supports Bluetooth Object Push Profile.
+ Device implementations must support connection handover to Bluetooth when using android.nfc.NfcAdapter.setBeamPushUris,
+ by implementing the "Connection Handover version 1.2" [<a href="#resources60">Resources, 60</a>]
+ and "Bluetooth Secure Simple Pairing Using NFC version 1.0" [<a href="#resources61">Resources, 61</a>]
+ specs from the NFC Forum. Such an implementation SHOULD use SNEP GET
+ requests for exchanging the handover request / select records over NFC, and it MUST
+ use the Bluetooth Object Push Profile for the actual Bluetooth data transfer.</li>
+ </ul>
+ </li>
+ <li>MUST poll for all supported technologies while in NFC discovery mode.</li>
+ <li>SHOULD be in NFC discovery mode while the device is awake with the screen active
+ and the lock-screen unlocked.</li>
+</ul>
+
+<p>(Note that publicly available links are not available for the JIS, ISO, and
+NFC Forum specifications cited above.)</p>
+<p>Additionally, device implementations MAY include reader/writer support for
+the following MIFARE technologies.</p>
+<ul>
+ <li>MIFARE Classic (NXP MF1S503x [<a href="#resources44">Resources, 44</a>],
+ MF1S703x [<a href="#resources45">Resources, 45</a>])</li>
+ <li>MIFARE Ultralight (NXP MF0ICU1 [<a href="#resources46">Resources, 46</a>],
+ MF0ICU2 [<a href="#resources47">Resources, 47</a>])</li>
+ <li>NDEF on MIFARE Classic (NXP AN130511 [<a href="#resources48">Resources, 48</a>],
+ AN130411 [<a href="#resources49">Resources, 49</a>])</li>
+</ul>
+<p>Note that Android 4.3 includes APIs for these MIFARE types. If a
+device implementation supports MIFARE in the reader/writer role, it:</p>
+<ul>
+ <li>MUST implement the corresponding Android APIs as documented by the
+ Android SDK</li>
+ <li>MUST report the feature com.nxp.mifare from the
+ <code>android.content.pm.PackageManager.hasSystemFeature()</code> method.
+ [<a href="#resources37">Resources, 37</a>] Note that this is not a standard
+ Android feature, and as such does not appear as a constant on the
+ <code>PackageManager</code> class.</li>
+ <li>MUST NOT implement the corresponding Android APIs nor report the
+ com.nxp.mifare feature unless it also implements general NFC support as
+ described in this section</li>
+</ul>
+<p>If a device implementation does not include NFC hardware, it MUST NOT
+declare the android.hardware.nfc feature from the
+<code>android.content.pm.PackageManager.hasSystemFeature()</code> method [<a
+href="#resources37">Resources, 37</a>], and MUST implement the Android 4.3 NFC
+API as a no-op.</p>
+<p>As the classes <code>android.nfc.NdefMessage</code> and
+<code>android.nfc.NdefRecord</code> represent a protocol-independent data
+representation format, device implementations MUST implement these APIs even
+if they do not include support for NFC or declare the android.hardware.nfc
+feature.</p>
+<a name="section-7.4.5"></a><h4>7.4.5. Minimum Network Capability</h4>
+<p>Device implementations MUST include support for one or more forms of data
+networking. Specifically, device implementations MUST include support for at
+least one data standard capable of 200Kbit/sec or greater. Examples of
+technologies that satisfy this requirement include EDGE, HSPA, EV-DO, 802.11g,
+Ethernet, etc.</p>
+<p>Device implementations where a physical networking standard (such as
+Ethernet) is the primary data connection SHOULD also include support for at
+least one common wireless data standard, such as 802.11 (WiFi).</p>
+<p>Devices MAY implement more than one form of data connectivity.</p>
+
+
+<a name="section-7.5"></a><h3>7.5. Cameras</h3>
+<p>Device implementations SHOULD include a rear-facing camera, and MAY include
+a front-facing camera. A rear-facing camera is a camera located on the side of
+the device opposite the display; that is, it images scenes on the far side of
+the device, like a traditional camera. A front-facing camera is a camera
+located on the same side of the device as the display; that is, a camera
+typically used to image the user, such as for video conferencing and similar
+applications.</p>
+<a name="section-7.5.1"></a><h4>7.5.1. Rear-Facing Camera</h4>
+<p>Device implementations SHOULD include a rear-facing camera. If a device
+implementation includes a rear-facing camera, it:</p>
+<ul>
+<li>MUST have a resolution of at least 2 megapixels</li>
+<li>SHOULD have either hardware auto-focus, or software auto-focus implemented
+in the camera driver (transparent to application software)</li>
+<li>MAY have fixed-focus or EDOF (extended depth of field) hardware</li>
+<li>MAY include a flash. If the Camera includes a flash, the flash lamp MUST
+NOT be lit while an android.hardware.Camera.PreviewCallback instance has been
+registered on a Camera preview surface, unless the application has explicitly
+enabled the flash by enabling the <code>FLASH_MODE_AUTO</code> or
+<code>FLASH_MODE_ON</code> attributes of a <code>Camera.Parameters</code>
+object. Note that this constraint does not apply to the device's built-in
+system camera application, but only to third-party applications using
+<code>Camera.PreviewCallback</code>.</li>
+</ul>
+<a name="section-7.5.2"></a><h4>7.5.2. Front-Facing Camera</h4>
+<p>Device implementations MAY include a front-facing camera. If a device
+implementation includes a front-facing camera, it:</p>
+<ul>
+<li>MUST have a resolution of at least VGA (that is, 640x480 pixels)</li>
+<li>MUST NOT use a front-facing camera as the default for the Camera API.
+That is, the camera API in Android 4.3 has specific support for front-facing
+cameras, and device implementations MUST NOT configure the API to to treat a
+front-facing camera as the default rear-facing camera, even if it is the only
+camera on the device.</li>
+<li>MAY include features (such as auto-focus, flash, etc.)
+available to rear-facing cameras as described in Section 7.5.1.</li>
+<li>MUST horizontally reflect (i.e. mirror) the stream displayed by an app in a
+CameraPreview, as follows:</li>
+<ul>
+<li>If the device implementation is capable of being rotated by user (such as
+automatically via an accelerometer or manually via user input), the camera
+preview MUST be mirrored horizontally relative to the device's current
+orientation.</li>
+<li>If the current application has explicitly requested that the Camera
+display be rotated via a call to the
+<code>android.hardware.Camera.setDisplayOrientation()</code> [<a
+href="#resources50">Resources, 50</a>] method, the camera preview MUST be
+mirrored horizontally relative to the orientation specified by the
+application.</li>
+<li>Otherwise, the preview MUST be mirrored along the device's default horizontal axis.</li>
+</ul>
+<li>MUST mirror the image displayed by the postview in the same manner as
+the camera preview image stream. (If the device implementation does not
+support postview, this requirement obviously does not apply.)</li>
+<li>MUST NOT mirror the final captured still image or video streams returned
+to application callbacks or committed to media storage</li>
+</ul>
+<a name="section-7.5.3"></a><h4>7.5.3. Camera API Behavior</h4>
+<p>Device implementations MUST implement the following behaviors for the
+camera-related APIs, for both front- and rear-facing cameras:</p>
+<ol>
+<li>If an application has never called
+<code>android.hardware.Camera.Parameters.setPreviewFormat(int)</code>, then the
+device MUST use <code>android.hardware.PixelFormat.YCbCr_420_SP</code> for
+preview data provided to application callbacks.</li>
+<li>If an application registers an <code>android.hardware.Camera.PreviewCallback
+</code> instance and the system calls the <code>onPreviewFrame()</code> method
+when the preview format is YCbCr_420_SP, the data in the <code>byte[]</code>
+passed into <code>onPreviewFrame()</code> must further be in the NV21 encoding
+format. That is, NV21 MUST be the default.</li>
+<li>Device implementations MUST support the YV12 format (as denoted by the
+<code>android.graphics.ImageFormat.YV12</code> constant) for camera previews
+for both front- and rear-facing cameras. (The hardware video encoder and camera
+may use any native pixel format, but the device implementation MUST support conversion
+to YV12.)</li>
+</ol>
+<p>Device implementations MUST implement the full Camera API included in the
+Android 4.3 SDK documentation [<a href="#resources51">Resources, 51</a>]),
+regardless of whether the device includes hardware autofocus or other
+capabilities. For instance, cameras that lack autofocus MUST still call any
+registered <code>android.hardware.Camera.AutoFocusCallback</code> instances (even though
+this has no relevance to a non-autofocus camera.) Note that this does apply
+to front-facing cameras; for instance, even though most front-facing cameras
+do not support autofocus, the API callbacks must still be "faked" as
+described.</p>
+<p>Device implementations MUST recognize and honor each parameter name defined
+as a constant on the <code>android.hardware.Camera.Parameters</code> class, if the
+underlying hardware supports the feature. If the device hardware does not
+support a feature, the API must behave as documented. Conversely, Device
+implementations MUST NOT honor or recognize string constants passed
+to the <code>android.hardware.Camera.setParameters()</code> method other than
+those documented as constants on the
+<code>android.hardware.Camera.Parameters</code>. That is,
+device implementations MUST support all standard Camera parameters if the
+hardware allows, and MUST NOT support custom Camera parameter types.
+For instance, device implementations that support image capture using high dynamic range (HDR)
+imaging techniques MUST support camera parameter <code>Camera.SCENE_MODE_HDR</code>
+[<a href="#resources78">Resources, 78</a>]).</p>
+<p>Device implementations MUST broadcast the <code>Camera.ACTION_NEW_PICTURE</code>
+intent whenever a new picture is taken by the camera and the entry of the picture
+has been added to the media store.</p>
+<p>Device implementations MUST broadcast the <code>Camera.ACTION_NEW_VIDEO</code>
+intent whenever a new video is recorded by the camera and the entry of the picture
+has been added to the media store.</p>
+<a name="section-7.5.4"></a><h4>7.5.4. Camera Orientation</h4>
+<p>Both front- and rear-facing cameras, if present, MUST be oriented so that
+the long dimension of the camera aligns with the screen's long dimension. That
+is, when the device is held in the landscape orientation, cameras MUST
+capture images in the landscape orientation. This applies regardless of the
+device's natural orientation; that is, it applies to landscape-primary devices
+as well as portrait-primary devices.</p>
+
+<a name="section-7.6"></a><h3>7.6. Memory and Storage</h3>
+<a name="section-7.6.1"></a><h4>7.6.1. Minimum Memory and Storage</h4>
+<p>Device implementations MUST have at least 340MB of memory available to the
+kernel and userspace. The 340MB MUST be in addition to any memory dedicated to
+hardware components such as radio, video, and so on that is not under the
+kernel's control.</p>
+<p>Device implementations MUST have at least 512MB of non-volatile storage available
+for application private data. That is, the <code>/data</code> partition MUST be at
+least 512MB. Device implementations that run Android 4.3 are <b>very strongly encouraged to
+have at least 1GB of non-volatile storage for application private data</b> so they will be
+able to upgrade to the future platform releases.</p>
+
+<p>The Android APIs include a Download Manager that applications may use to
+download data files [<a href="#resources56">Resources, 56</a>]. The device
+implementation of the Download Manager MUST be capable of downloading individual
+files of at least 100MB in size to the default "cache" location.</p>
+<a name="section-7.6.2"></a><h4>7.6.2. Application Shared Storage</h4>
+<p>Device implementations MUST offer shared storage for applications. The
+shared storage provided MUST be at least 1GB in size.</p>
+<p>Device implementations MUST be configured with shared storage mounted by
+default, "out of the box". If the shared storage is not mounted on the Linux
+path <code>/sdcard</code>, then the device MUST include a Linux symbolic link
+from <code>/sdcard</code> to the actual mount point.</p>
+<p>Device implementations MUST enforce as documented the
+<code>android.permission.WRITE_EXTERNAL_STORAGE</code> permission on this
+shared storage. Shared storage MUST otherwise be writable by any application
+that obtains that permission.</p>
+<p>Device implementations MAY have hardware for user-accessible removable
+storage, such as a Secure Digital card. Alternatively, device implementations
+MAY allocate internal (non-removable) storage as shared storage for apps.</p>
+<p>Regardless of the form of shared storage used, device implementations MUST
+provide some mechanism to access the contents of shared storage from a host
+computer, such as USB mass storage (UMS) or Media Transfer Protocol (MTP). Device
+implementations MAY use USB mass storage, but SHOULD use Media Transfer
+Protocol. If the device implementation supports Media Transfer Protocol:</p>
+<ul>
+<li>The device implementation SHOULD be compatible with the reference Android
+MTP host, Android File Transfer [<a href="#resources57">Resources, 57</a>].</li>
+<li>The device implementation SHOULD report a USB device class of <code>0x00</code>.</li>
+<li>The device implementation SHOULD report a USB interface name of 'MTP'.</li>
+</ul>
+<p>If the device implementation lacks USB ports, it MUST provide a host
+computer with access to the contents of shared storage by some other means,
+such as a network file system.</p>
+<p>It is illustrative to consider two common examples. If a device
+implementation includes an SD card slot to satisfy the shared storage
+requirement, a FAT-formatted SD card 1GB in size or larger MUST be included
+with the device as sold to users, and MUST be mounted by default.
+Alternatively, if a device implementation uses internal fixed storage to
+satisfy this requirement, that storage MUST be 1GB in size or larger
+and mounted on <code>/sdcard</code> (or <code>/sdcard</code>
+MUST be a symbolic link to the physical location if it is mounted elsewhere.)</p>
+<p>Device implementations that include multiple shared storage paths (such as
+both an SD card slot and shared internal storage) SHOULD modify the core
+applications such as the media scanner and ContentProvider to transparently
+support files placed in both locations.</p>
+
+<a name="section-7.7"></a><h3>7.7. USB</h3>
+<p>Device implementations SHOULD include a USB client port, and SHOULD include
+a USB host port.</p>
+<p>If a device implementation includes a USB client port:</p>
+<ul>
+<li>the port MUST be connectable to a USB host with a standard USB-A port</li>
+<li>the port SHOULD use the micro USB form factor on the device side. Existing and
+new devices that run Android 4.3 are <b>very strongly encouraged to meet these requirements
+in Android 4.3</b> so they will be able to upgrade to the future platform releases</li>
+<li>the port SHOULD be centered in the middle of an edge. Device implementations SHOULD either
+locate the port on the bottom of the device (according to natural orientation) or enable software
+screen rotation for all apps (including home screen), so that the display draws correctly when the device
+is oriented with the port at bottom. Existing and new devices that run Android 4.3 are <b>very strongly
+encouraged to meet these requirements in Android 4.3</b> so they will be able to upgrade to future platform releases.</li>
+<li>if the device has other ports (such as a non-USB charging port) it SHOULD be on the same edge as the
+micro-USB port</li>
+<li>it MUST allow a host connected to the device to access the contents of the
+shared storage volume using either USB mass storage or Media Transfer
+Protocol</li>
+<li>it MUST implement the Android Open Accessory API and specification as documented
+in the Android SDK documentation, and MUST declare support for the hardware
+feature <code>android.hardware.usb.accessory</code> [<a href="#resources52">Resources,
+52</a>]</li>
+<li>it MUST implement the USB audio class as documented in the Android SDK documentation [<a href="#resources66">Resources, 66</a>]</li>
+<li>it SHOULD implement support for USB battery charging specification [<a href="#resources64">Resources, 64</a>]
+Existing and new devices that run Android 4.3 are <b>very strongly encouraged to meet these requirements in Android 4.3</b>
+so they will be able to upgrade to the future platform releases</li>
+
+</ul>
+<p>If a device implementation includes a USB host port:</p>
+<ul>
+<li>it MAY use a non-standard port form factor, but if so MUST ship with a
+cable or cables adapting the port to standard USB-A</li>
+<li>it MUST implement the Android USB host API as documented in the Android
+SDK, and MUST declare support for the hardware feature
+<code>android.hardware.usb.host</code> [<a href="#resources53">Resources, 53</a>]</li>
+</ul>
+<p>Device implementations MUST implement the Android Debug Bridge. If a device
+implementation omits a USB client port, it MUST implement the Android Debug
+Bridge via local-area network (such as Ethernet or 802.11)</p>
+
+<a name="section-8"></a><h2>8. Performance Compatibility</h2>
+<p>Device implementations MUST meet the key performance metrics of an Android
+4.3 compatible device defined in the table below:</p>
+<table><tbody><tr>
+<td><b>Metric</b></td>
+<td><b>Performance Threshold</b></td>
+<td><b>Comments</b></td>
+</tr>
+<tr>
+<td>Application Launch Time</td>
+<td>The following applications should launch within the specified time.<ul>
+<li>Browser: less than 1300ms</li>
+<li>Contacts: less than 700ms</li>
+<li>Settings: less than 700ms</li>
+</ul></td>
+<td>The launch time is measured as the total time to
+complete loading the default activity for the application, including the time
+it takes to start the Linux process, load the Android package into the Dalvik
+VM, and call onCreate.</td>
+</tr>
+<tr>
+<td>Simultaneous Applications</td>
+<td>When multiple applications have been launched, re-launching an
+already-running application after it has been launched must take less than the
+original launch time.</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+
+<a name="section-9"></a><h2>9. Security Model Compatibility</h2>
+<p>Device implementations MUST implement a security model consistent with the
+Android platform security model as defined in Security and Permissions
+reference document in the APIs [<a href="#resources54">Resources, 54</a>] in the
+Android developer documentation. Device implementations MUST support
+installation of self-signed applications without requiring any additional
+permissions/certificates from any third parties/authorities. Specifically,
+compatible devices MUST support the security mechanisms described in the
+follow sub-sections.</p>
+<a name="section-9.1"></a><h3>9.1. Permissions</h3>
+<p>Device implementations MUST support the Android permissions model as
+defined in the Android developer documentation [<a
+href="#resources54">Resources, 54</a>]. Specifically,
+implementations MUST enforce each permission defined as described in the SDK
+documentation; no permissions may be omitted, altered, or ignored.
+Implementations MAY add additional permissions, provided the new permission ID
+strings are not in the android.* namespace.</p>
+<a name="section-9.2"></a><h3>9.2. UID and Process Isolation</h3>
+<p>Device implementations MUST support the Android application sandbox model,
+in which each application runs as a unique Unix-style UID and in a separate
+process. Device implementations MUST support running multiple applications as
+the same Linux user ID, provided that the applications are properly signed and
+constructed, as defined in the Security and Permissions reference [<a
+href="#resources54">Resources, 54</a>].</p>
+<a name="section-9.3"></a><h3>9.3. Filesystem Permissions</h3>
+<p>Device implementations MUST support the Android file access permissions
+model as defined in the Security and Permissions reference [<a
+href="#resources54">Resources, 54</a>].</p>
+<a name="section-9.4"></a><h3>9.4. Alternate Execution Environments</h3>
+<p>Device implementations MAY include runtime environments that execute
+applications using some other software or technology than the Dalvik virtual
+machine or native code. However, such alternate execution environments MUST
+NOT compromise the Android security model or the security of installed Android
+applications, as described in this section.</p>
+<p>Alternate runtimes MUST themselves be Android applications, and abide by
+ the standard Android security model, as described elsewhere in Section 9.</p>
+<p>Alternate runtimes MUST NOT be granted access to resources protected by
+ permissions not requested in the runtime's AndroidManifest.xml file via the
+ <code><uses-permission></code> mechanism.</p>
+<p>Alternate runtimes MUST NOT permit applications to make use of features
+ protected by Android permissions restricted to system applications.</p>
+<p>Alternate runtimes MUST abide by the Android sandbox model. Specifically:</p>
+<ul>
+<li>Alternate runtimes SHOULD install apps via the PackageManager into
+ separate Android sandboxes (that is, Linux user IDs, etc.)</li>
+<li>Alternate runtimes MAY provide a single Android sandbox shared by all
+ applications using the alternate runtime</li>
+<li>Alternate runtimes and installed applications using an alternate runtime
+ MUST NOT reuse the sandbox of any other app installed on the device, except
+ through the standard Android mechanisms of shared user ID and signing
+ certificate</li>
+<li>Alternate runtimes MUST NOT launch with, grant, or be granted access to
+ the sandboxes corresponding to other Android applications</li>
+</ul>
+<p>Alternate runtimes MUST NOT be launched with, be granted, or grant to other
+ applications any privileges of the superuser (root), or of any other user ID.</p>
+<p>The .apk files of alternate runtimes MAY be included in the system image of
+ a device implementation, but MUST be signed with a key distinct
+ from the key used to sign other applications included with the device
+ implementation.</p>
+<p>When installing applications, alternate runtimes MUST obtain user consent
+ for the Android permissions used by the application. That is, if an
+ application needs to make use of a device resource for which there is a
+ corresponding Android permission (such as Camera, GPS, etc.), the alternate
+ runtime MUST inform the user that the application will be able to access
+ that resource. If the runtime environment does not record application
+ capabilities in this manner, the runtime environment MUST list all
+ permissions held by the runtime itself when installing any application
+ using that runtime.</p>
+
+<a name="section-9.5"></a><h3>9.5. Multi-User Support </h3>
+<p>Android 4.3 includes support for multiple users and provides support for full user isolation
+[<a href="#resources70">Resources, 70</a>].</p>
+<p>Device implementations MUST meet these requirements related to multi-user support [<a href="#resources71">Resources, 71</a>]:</p>
+<ul>
+<li>As the behavior of the telephony APIs on devices with multiple users is currently undefined, device implementations that
+declare android.hardware.telephony MUST NOT enable multi-user support. </li>
+<li>Device implementations MUST, for each user, implement a security model consistent with the Android platform security model
+as defined in Security and Permissions reference document in the APIs [Resources, 54]</li>
+<li>Android 4.3 includes support for restricted profiles, a feature that allows device owners to manage additional users and their capabilities
+on the device. With restricted profiles, device owners can quickly set up separate environments for additional users to work in, with the ability to
+manage finer-grained restrictions in the apps that are available in those environments. Device implementations that include support for multiple users
+MUST include support for restricted profiles. The upstream Android Open Source Project includes an implementation that satisfies this requirement.</li>
+</ul>
+
+<p>Each user instance on an Android device MUST have separate and isolated external storage directories. Device implementations MAY store multiple users' data on the same volume or filesystem.
+However, the device implementation MUST ensure that applications owned by and running on behalf a given user cannot list, read, or write to data owned by any other user.
+Note that removable media, such as SD card slots, can allow one user to access another's data by means of a host PC. For this reason, device implementations that use removable media for the
+external storage APIs MUST encrypt the contents of the SD card if multi-user is enabled using a key stored only on non-removable media accessible only to the system. As this will make the
+media unreadable by a host PC, device implementations will be required to switch to MTP or a similar system to provide host PCs with access to the current user's data. Accordingly, device
+implementations MAY but SHOULD NOT enable multi-user if they use removable media [<a href="#resources72">Resources, 72</a>] for primary external storage. The upstream Android Open Source
+Project includes an implementation that uses internal device storage for application external storage APIs; device implementations SHOULD use this configuration and software implementation.
+Device implementations that include multiple external storage paths MUST NOT allow Android applications to write to the secondary external storage.</p>
+
+<a name="section-9.6"></a><h3>9.6. Premium SMS Warning</h3>
+<p>Android 4.3 includes support for warning users for any outgoing premium SMS message [<a href="#resources73">Resources, 73</a>] . Premium SMS messages are text messages sent to a service registered with a carrier that may incur a charge to the user.
+Device implementations that declare support for <code>android.hardware.telephony</code> MUST warn users before sending a SMS message to numbers identified by regular expressions defined in <code>/data/misc/sms/codes.xml</code> file in the device.
+The upstream Android Open Source Project provides an implementation that satisfies this requirement.
+</p>
+
+<a name="section-9.7"></a><h3>9.7. Kernel Security Features</h3>
+<p>The Android Sandbox in Android 4.3 includes features that can use the SELinux
+mandatory access control system (MAC) and other security features in the Linux kernel.
+Device implementations MUST support SELinux MAC. Note that the upstream Android Open Source
+Project provides an implementation that satisfies this requirement.</p>
+
+<p>SELinux or any security features implemented below the Android framework MUST maintain
+compatibility with existing applications. These features SHOULD be invisible to users and developers.
+These features SHOULD NOT be user or developer configurable. If any API for configuration of policy is
+exposed to an application that can affect another application (such as a Device Administration API),
+the API MUST NOT allow configurations that break compatibility. To ensure continued compatibility the
+reference implementation allows the use of SELinux in a permissive mode and supports dynamic policy updates
+without requiring a system image update. Device implementations using SELinux MUST support this permissive
+mode, support dynamic policy updates and log any policy violations without breaking applications or affecting
+system behavior. Implementations using SELinux SHOULD load policy from <code>/sepolicy</code> file on the device.
+The upstream Android Open Source Project provides an implementation that satisfies this requirement.
+Device implementations SHOULD use the reference implementation in the Android Open Source Project, and
+device implementations MUST be compatible with the upstream Android Open Source Project.</p>
+
+<a name="section-10"></a><h2>10. Software Compatibility Testing</h2>
+<p>Device implementations MUST pass all tests described in this section.</p>
+<p>However, note that no software test package is fully comprehensive. For
+this reason, device implementers are very strongly encouraged to make the
+minimum number of changes as possible to the reference and preferred
+implementation of Android 4.3 available from the Android Open Source Project.
+This will minimize the risk of introducing bugs that create incompatibilities
+requiring rework and potential device updates.</p>
+<a name="section-10.1"></a><h3>10.1. Compatibility Test Suite</h3>
+<p>Device implementations MUST pass the Android Compatibility Test Suite (CTS)
+[<a href="#resources02">Resources, 2</a>] available from the Android Open Source
+Project, using the final shipping software on the device. Additionally, device
+implementers SHOULD use the reference implementation in the Android Open
+Source tree as much as possible, and MUST ensure compatibility in cases of
+ambiguity in CTS and for any reimplementations of parts of the reference
+source code.</p>
+<p>The CTS is designed to be run on an actual device. Like any software, the
+CTS may itself contain bugs. The CTS will be versioned independently of this
+Compatibility Definition, and multiple revisions of the CTS may be released
+for Android 4.3. Device implementations MUST pass the latest CTS version
+available at the time the device software is completed.</p>
+<a name="section-10.2"></a><h3>10.2. CTS Verifier</h3>
+<p>Device implementations MUST correctly execute all applicable cases in the
+CTS Verifier. The CTS Verifier is included with the Compatibility Test Suite,
+and is intended to be run by a human operator to test functionality that
+cannot be tested by an automated system, such as correct functioning of a
+camera and sensors.</p>
+<p>The CTS Verifier has tests for many kinds of hardware, including some
+hardware that is optional. Device implementations MUST pass all tests for
+hardware which they possess; for instance, if a device possesses an
+accelerometer, it MUST correctly execute the Accelerometer test case in the
+CTS Verifier. Test cases for features noted as optional by this Compatibility
+Definition Document MAY be skipped or omitted.</p>
+<p>Every device and every build MUST correctly run the CTS Verifier, as noted
+above. However, since many builds are very similar, device implementers are
+not expected to explicitly run the CTS Verifier on builds that differ only in
+trivial ways. Specifically, device implementations that differ from an
+implementation that has passed the CTS Verifier only by the set of included
+locales, branding, etc. MAY omit the CTS Verifier test.</p>
+<a name="section-10.3"></a><h3>10.3. Reference Applications</h3>
+<p>Device implementers MUST test implementation compatibility using the
+following open source applications:</p>
+<ul>
+<li>The "Apps for Android" applications [<a href="#resources55">Resources, 55</a>]</li>
+<li>Replica Island (available in Google Play Store)</li>
+</ul>
+<p>Each app above MUST launch and behave correctly on the implementation, for
+the implementation to be considered compatible.</p>
+
+
+<a name="section-11"></a><h2>11. Updatable Software</h2>
+<p>Device implementations MUST include a mechanism to replace the entirety of
+the system software. The mechanism need not perform "live" upgrades - that
+is, a device restart MAY be required.</p>
+<p>Any method can be used, provided that it can replace the entirety of the
+software preinstalled on the device. For instance, any of the following
+approaches will satisfy this requirement:</p>
+<ul>
+<li>Over-the-air (OTA) downloads with offline update via reboot</li>
+<li>"Tethered" updates over USB from a host PC</li>
+<li>"Offline" updates via a reboot and update from a file on removable
+storage</li>
+</ul>
+<p>The update mechanism used MUST support updates without wiping user data.
+That is, the update mechanism MUST preserve application private data
+and application shared data. Note that the upstream Android software includes
+an update mechanism that satisfies this requirement.</p>
+<p>If an error is found in a device implementation after it has been released
+but within its reasonable product lifetime that is determined in consultation
+with the Android Compatibility Team to affect the compatibility of third-party
+applications, the device implementer MUST correct the error via a software
+update available that can be applied per the mechanism just described.</p>
+
+<a name="section-12"></a><h2>12. Contact Us</h2>
+<p>You can contact the document authors at <a
+href="mailto:compatibility@android.com">compatibility@android.com</a> for
+clarifications and to bring up any issues that you think the document does not
+cover.</p>
+
+<div style="page-break-before: always;"></div>
+
+<div id="footerContent" xmlns:pdf="http://whatever">
+<pdf:pagenumber/>
+</div>
+</body>
+</html>
diff --git a/src/compatibility/5.0/versions.jd b/src/compatibility/5.0/versions.jd
index 78a11cb..1908c90 100644
--- a/src/compatibility/5.0/versions.jd
+++ b/src/compatibility/5.0/versions.jd
@@ -15,4 +15,6 @@
<code>android.os.Build.VERSION.RELEASE</code> for Android 5.0 are:</p>
<ul>
<li>5.0</li>
+<li>5.0.1</li>
+<li>5.0.2</li>
</ul>
diff --git a/src/compatibility/android-cts-manual.pdf b/src/compatibility/android-cts-manual.pdf
index ac6a125..d551495 100644
--- a/src/compatibility/android-cts-manual.pdf
+++ b/src/compatibility/android-cts-manual.pdf
Binary files differ
diff --git a/src/compatibility/contact-us.jd b/src/compatibility/contact-us.jd
index b0580ba..6c590f5 100644
--- a/src/compatibility/contact-us.jd
+++ b/src/compatibility/contact-us.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -16,7 +16,7 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<p>Thanks for your interest in Android compatibility! This page describes the
+<p>This page describes the
contact methods for inquiries regarding the Android compatibility program,
including the Compatibility Definition Document (CDD) and Compatibility Test
Suite (CTS). See the <a href="{@docRoot}community/index.html">Community</a>
@@ -37,18 +37,16 @@
href="mailto:android-compatibility+subscribe@googlegroups.com">android-compatibility</a></li>
</ul>
-<p>To make best use of this list, please first read <em>Getting the Most from
-Our Lists</em> on the <a href="{@docRoot}community/index.html">Community</a>
-page. Users looking for help with Android devices should contact their carrier
-or manufacturer for help.</p>
+<p>To make best use of this list, please first read <a
+href="{@docRoot}source/community/index.html#getting-the-most-from-our-lists">Getting
+the Most from Our Lists</a> on the Community page. Users looking for help with
+Android devices should contact their carrier or manufacturer for help.</p>
-<h2 id="for-business-inquiries">For business inquiries</h2>
-<p>Finally, business inquiries about the compatibility program, including
-requests to use branding elements and similar, can be sent to the address <a
-href="mailto:android-partnerships@google.com">android-partnerships@google.com</a>.
-This address is for specific, private inquiries; general questions will be
-directed back to the android-compatibility list.</p>
+<h2 id="for-business-inquiries">For licensing Google Mobile Services</h2>
+<p>Please send inquiries about licensing Google Mobile Services through the <a
+href="https://docs.google.com/a/google.com/forms/d/1qAHuR-MbmXeYuJ1aBd3neaUjNGxnnnCd2kzb0MEJpGQ/viewform"
+target="_blank">GMS Inquiry</a> form. Other non-GMS partnership inquiries can be sent to <a
+href="mailto:android-partnerships@google.com">android-partnerships@google.com</a>
-<p>While we read every email that
-is received at the android-partnerships alias, we cannot respond to each of them.
-Please note, we will be in contact if we can help you.</p>
+<p>While we read every message received, we cannot respond to each of them. We
+promise to contact you if we can help!</p>
diff --git a/src/compatibility/cts-intro.jd b/src/compatibility/cts-intro.jd
index f489fc6..d9dcc99 100644
--- a/src/compatibility/cts-intro.jd
+++ b/src/compatibility/cts-intro.jd
@@ -18,8 +18,12 @@
-->
<h2 id="how-does-the-cts-work">How does the CTS work?</h2>
-<div style="float: right">
- <img src="{@docRoot}images/cts-0.png">
+
+<div class="figure" style="width:383px">
+ <img src="{@docRoot}images/cts-0.png" alt="CTS flow" height="340px" id="figure1" />
+ <p class="img-caption">
+ <strong>Figure 1.</strong> How to use CTS
+ </p>
</div>
<p>The CTS is an automated testing harness that includes two major software components:</p>
diff --git a/src/compatibility/downloads.jd b/src/compatibility/downloads.jd
index a5f353c..0d729f2 100644
--- a/src/compatibility/downloads.jd
+++ b/src/compatibility/downloads.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -16,10 +16,38 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
<p>Thank you for your interest in Android Compatibility! The links below give
you access to key documents and information about the program.</p>
+<h2 id="android-50">Android 5.0</h2>
+<p>Android 5.0 is the release of the development milestone code-named Lollipop.
+The source code for the following tests can be synced with the
+'android-cts-5.0_r2' tag in the open-source tree.</p>
+<ul>
+<li><a href="5.0/android-5.0-cdd.pdf">Android 5.0 Compatibility Definition
+Document (CDD)</a></li>
+<li><a
+href="https://dl.google.com/dl/android/cts/android-cts-5.0_r2-linux_x86-arm.zip">Android
+5.0 R2 Compatibility Test Suite (CTS) - ARM</a></li>
+<li><a
+href="https://dl.google.com/dl/android/cts/android-cts-5.0_r2-linux_x86-x86.zip">Android
+5.0 R2 Compatibility Test Suite (CTS) - x86</a></li>
+<li><a
+href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.0_r2-linux_x86-arm.zip">Android
+5.0 R2 CTS Verifier - ARM</a></li>
+<li><a
+href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.0_r2-linux_x86-x86.zip">Android
+5.0 R2 CTS Verifier - x86</a></li>
+</ul>
+
<h2 id="android-44">Android 4.4</h2>
<p>Android 4.4 is the release of the development milestone code-named
KitKat. Source code for Android 4.4 is found in the
@@ -123,6 +151,7 @@
<h2 id="cts-media-files">CTS Media Files</h2>
<p>These media files are required for the CTS media stress tests.</p>
<ul>
+<li><a href="https://dl.google.com/dl/android/cts/android-cts-media-1.1.zip">CTS Media 1.1</a></li>
<li><a href="https://dl.google.com/dl/android/cts/android-cts-media-1.0.zip">CTS Media 1.0</a></li>
</ul>
<h2 id="older-android-versions">Older Android Versions</h2>
diff --git a/src/compatibility/index.jd b/src/compatibility/index.jd
index 60c2951..b3c375a 100644
--- a/src/compatibility/index.jd
+++ b/src/compatibility/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -64,9 +64,15 @@
</li>
</ol>
-<h2 id="joining-the-ecosystem">Joining the ecosystem</h2>
-<p>Once you've built a compatible device, you may wish to include Google
-Play to provide your users access to the third-party app ecosystem.
-Unfortunately, for a variety of legal and business reasons, we aren't able to
-automatically license Google Play to all compatible devices. To inquire
-about access to Google Play, you can <a href="contact-us.html">contact us</a>.</p>
+<p>After complying with the CDD and passing the CTS, your device is now Android
+compatible. Android apps in the ecosystem will have a consistent experience on
+your device.</p>
+
+<h2 id="licensing-gms">Licensing Google Mobile Services</h2>
+<p>If you've built an Android compatible device, you may wish to inquire about
+licensing Google’s proprietary suite of apps that run on top of Android -
+Google Mobile Services (GMS, which include Google Play, YouTube, Google Maps,
+Gmail, and more). Google Mobile Services is not part of the Android Open Source
+Project and is available only through a license with Google. Please visit the
+‘contact’ us section for more information on how to inquire about a GMS
+license.</p>
diff --git a/src/devices/Android-5.0-Bluetooth-HCI-Reqs.pdf b/src/devices/Android-5.0-Bluetooth-HCI-Reqs.pdf
new file mode 100644
index 0000000..40e9cee
--- /dev/null
+++ b/src/devices/Android-5.0-Bluetooth-HCI-Reqs.pdf
Binary files differ
diff --git a/src/devices/audio.jd b/src/devices/audio.jd
deleted file mode 100644
index 660ec7e..0000000
--- a/src/devices/audio.jd
+++ /dev/null
@@ -1,100 +0,0 @@
-page.title=Audio
-@jd:body
-
-<!--
- Copyright 2013 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.
--->
-<p>
- Android's audio Hardware Abstraction Layer (HAL) connects the higher level, audio-specific
- framework APIs in <a href="http://developer.android.com/reference/android/media/package-summary.html">android.media</a>
- to the underlying audio driver and hardware.
-</p>
-
-<p>
- The following figure and list describe how audio functionality is implemented and the relevant
- source code that is involved in the implementation:
-</p>
-<p>
- <img src="images/audio_hal.png" alt="Audio architecture" />
-</p>
-<dl>
- <dt>
- Application framework
- </dt>
- <dd>
- At the application framework level is the app code, which utilizes the
- <a href="http://developer.android.com/reference/android/media/package-summary.html">android.media</a>
- APIs to interact with the audio hardware. Internally, this code calls corresponding JNI glue
- classes to access the native code that interacts with the audio hardware.
- </dd>
- <dt>
- JNI
- </dt>
- <dd>
- The JNI code associated with <a href="http://developer.android.com/reference/android/media/package-summary.html">android.media</a> is located in the
- <code>frameworks/base/core/jni/</code> and <code>frameworks/base/media/jni</code> directories.
- This code calls the lower level native code to obtain access to the audio hardware.
- </dd>
- <dt>
- Native framework
- </dt>
- <dd>
- The native framework is defined in <code>frameworks/av/media/libmedia</code> and provides a
- native equivalent to the <a href="http://developer.android.com/reference/android/media/package-summary.html">android.media</a> package. The native framework calls the Binder
- IPC proxies to obtain access to audio-specific services of the media server.
- </dd>
- <dt>
- Binder IPC
- </dt>
- <dd>
- The Binder IPC proxies facilitate communication over process boundaries. They are located in
- the <code>frameworks/av/media/libmedia</code> directory and begin with the letter "I".
- </dd>
- <dt>
- Media Server
- </dt>
- <dd>
- The audio services in the media server, located in
- <code>frameworks/av/services/audioflinger</code>, is the actual code that interacts with your
- HAL implementations.
- </dd>
- <dt>
- HAL
- </dt>
- <dd>
- The HAL defines the standard interface that audio services call into
- and that you must implement to have your audio hardware function correctly. The audio HAL
- interfaces are located in
-<code>hardware/libhardware/include/hardware</code>. See <a
-href="{@docRoot}devices/halref/audio_8h_source.html">audio.h</a> for additional details.
- </dd>
- <dt>
- Kernel Driver
- </dt>
- <dd>
- The audio driver interacts with the hardware and your implementation of the HAL. You can choose
- to use ALSA, OSS, or a custom driver of your own at this level. The HAL is driver-agnostic.
- <p>
- <strong>Note:</strong> If you do choose ALSA, we recommend using <code>external/tinyalsa</code>
- for the user portion of the driver because of its compatible licensing (The standard user-mode
- library is GPL licensed).
-</p>
- </dd>
-</dl>
-
-<p>
- See the rest of the pages within the Audio section for implementation
- instructions and ways to improve performance.
-</p>
diff --git a/src/devices/audio_attributes.jd b/src/devices/audio/attributes.jd
similarity index 100%
rename from src/devices/audio_attributes.jd
rename to src/devices/audio/attributes.jd
diff --git a/src/devices/audio_avoiding_pi.jd b/src/devices/audio/avoiding_pi.jd
similarity index 88%
rename from src/devices/audio_avoiding_pi.jd
rename to src/devices/audio/avoiding_pi.jd
index ec407d7..2e0a07a 100644
--- a/src/devices/audio_avoiding_pi.jd
+++ b/src/devices/audio/avoiding_pi.jd
@@ -26,7 +26,7 @@
<p>
This article explains how the Android's audio system attempts to avoid
-priority inversion, as of the Android 4.1 release,
+priority inversion,
and highlights techniques that you can use too.
</p>
@@ -45,8 +45,8 @@
<p>
The Android AudioFlinger audio server and AudioTrack/AudioRecord
client implementation are being re-architected to reduce latency.
-This work started in Android 4.1, continued in 4.2 and 4.3, and now more
-improvements exist in version 4.4.
+This work started in Android 4.1, and continued with further improvements
+in 4.2, 4.3, 4.4, and 5.0.
</p>
<p>
@@ -54,7 +54,7 @@
important change is to assign CPU resources to time-critical
threads with a more predictable scheduling policy. Reliable scheduling
allows the audio buffer sizes and counts to be reduced while still
-avoiding artifacts due to underruns.
+avoiding underruns and overruns.
</p>
<h2 id="priorityInversion">Priority inversion</h2>
@@ -95,6 +95,11 @@
</li>
<li>
+between application callback thread for a fast AudioRecord and
+fast capture thread (similar to previous)
+</li>
+
+<li>
within the audio Hardware Abstraction Layer (HAL) implementation, e.g. for telephony or echo cancellation
</li>
@@ -103,17 +108,11 @@
</li>
<li>
-between AudioTrack callback thread and other app threads (this is out of our control)
+between AudioTrack or AudioRecord callback thread and other app threads (this is out of our control)
</li>
</ul>
-<p>
-As of this writing, reduced latency for AudioRecord is planned but
-not yet implemented. The likely priority inversion spots will be
-similar to those for AudioTrack.
-</p>
-
<h2 id="commonSolutions">Common solutions</h2>
<p>
@@ -290,6 +289,18 @@
use non-blocking algorithms or reference a non-Android open source library.
</p>
+<p>
+We have published an example non-blocking FIFO implementation that is specifically designed for
+application code. See these files located in the platform source directory
+<code>frameworks/av/audio_utils</code>:
+</p>
+<ul>
+ <li><a href="https://android.googlesource.com/platform/system/media/+/master/audio_utils/include/audio_utils/fifo.h">include/audio_utils/fifo.h</a>
+ <li><a href="https://android.googlesource.com/platform/system/media/+/master/audio_utils/fifo.c">fifo.c</a>
+ <li><a href="https://android.googlesource.com/platform/system/media/+/master/audio_utils/include/audio_utils/roundup.h">include/audio_utils/roundup.h</a>
+ <li><a href="https://android.googlesource.com/platform/system/media/+/master/audio_utils/roundup.c">roundup.c</a>
+</ul>
+
<h2 id="tools">Tools</h2>
<p>
diff --git a/src/devices/audio_debugging.jd b/src/devices/audio/debugging.jd
similarity index 94%
rename from src/devices/audio_debugging.jd
rename to src/devices/audio/debugging.jd
index 9c9b2fb..78ca801 100644
--- a/src/devices/audio_debugging.jd
+++ b/src/devices/audio/debugging.jd
@@ -46,7 +46,7 @@
</p>
<p>
-The instructions in the remainder of this section are for Android 4.4,
+The instructions in the remainder of this section are for Android 5.0,
and may require changes for other versions.
</p>
@@ -81,10 +81,10 @@
<p>
If the directory does not exist, create it as follows:
</p>
-<code>
+<pre>
mkdir /data/misc/media
chown media:media /data/misc/media
-</code>
+</pre>
</li>
<li><code>echo af.tee=# > /data/local.prop</code>
<br />Where the <code>af.tee</code> value is a number described below.
@@ -212,7 +212,7 @@
The underlying kernel system calls could block, possibly resulting in
priority inversion and consequently measurement disturbances and
inaccuracies. This is of
-special concern to time-critical threads such as <code>FastMixer</code>.
+special concern to time-critical threads such as <code>FastMixer</code> and <code>FastCapture</code>.
</li>
<li>
If a particular log is disabled to reduce log spam,
@@ -260,7 +260,11 @@
The diagram below shows the relationship of the <code>mediaserver</code> process
and the <code>init</code> process, before <code>media.log</code> is introduced:
</p>
-<img src="audio/images/medialog_before.png" alt="Architecture before media.log" />
+<img src="images/medialog_before.png" alt="Architecture before media.log" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> Architecture before media.log
+</p>
+
<p>
Notable points:
</p>
@@ -274,7 +278,11 @@
The diagram below shows the new relationship of the components,
after <code>media.log</code> is added to the architecture:
</p>
-<img src="audio/images/medialog_after.png" alt="Architecture after media.log" />
+<img src="images/medialog_after.png" alt="Architecture after media.log" id="figure2" />
+<p class="img-caption">
+ <strong>Figure 2.</strong> Architecture after media.log
+</p>
+
<p>
Important changes:
</p>
@@ -318,7 +326,7 @@
occasions when it is indispensable.
In particular, it is recommended for AudioFlinger threads that must
run frequently, periodically, and without blocking such as the
-<code>FastMixer</code> thread.
+<code>FastMixer</code> and <code>FastCapture</code> threads.
</p>
<h3>How to use</h3>
@@ -330,7 +338,7 @@
</p>
<p>
-In <code>FastMixer</code> thread, use code such as this:
+In <code>FastMixer</code> and <code>FastCapture</code> threads, use code such as this:
</p>
<pre>
logWriter->log("string");
@@ -338,7 +346,8 @@
logWriter->logTimestamp();
</pre>
<p>
-As this <code>NBLog</code> timeline is used only by the <code>FastMixer</code> thread,
+As this <code>NBLog</code> timeline is used only by the <code>FastMixer</code> and
+<code>FastCapture</code> threads,
there is no need for mutual exclusion.
</p>
@@ -351,7 +360,7 @@
mNBLogWriter->logTimestamp();
</pre>
<p>
-For threads other than <code>FastMixer</code>,
+For threads other than <code>FastMixer</code> and <code>FastCapture</code>,
the thread's <code>NBLog</code> timeline can be used by both the thread itself, and
by binder operations. <code>NBLog::Writer</code> does not provide any
implicit mutual exclusion per timeline, so be sure that all logs occur
diff --git a/src/devices/audio/images/ape_audio_tv_hdmi_tuner.png b/src/devices/audio/images/ape_audio_tv_hdmi_tuner.png
index 43a89ea..382bb45 100644
--- a/src/devices/audio/images/ape_audio_tv_hdmi_tuner.png
+++ b/src/devices/audio/images/ape_audio_tv_hdmi_tuner.png
Binary files differ
diff --git a/src/devices/audio/images/ape_audio_tv_tif.png b/src/devices/audio/images/ape_audio_tv_tif.png
index f013cfa..c8cd69e 100644
--- a/src/devices/audio/images/ape_audio_tv_tif.png
+++ b/src/devices/audio/images/ape_audio_tv_tif.png
Binary files differ
diff --git a/src/devices/audio/images/ape_audio_tv_tuner.png b/src/devices/audio/images/ape_audio_tv_tuner.png
index a25dcfb..bb062dc 100644
--- a/src/devices/audio/images/ape_audio_tv_tuner.png
+++ b/src/devices/audio/images/ape_audio_tv_tuner.png
Binary files differ
diff --git a/src/devices/audio/images/ape_fwk_audio.png b/src/devices/audio/images/ape_fwk_audio.png
new file mode 100644
index 0000000..9059a62
--- /dev/null
+++ b/src/devices/audio/images/ape_fwk_audio.png
Binary files differ
diff --git a/src/devices/audio/images/ape_fwk_hal_audio.png b/src/devices/audio/images/ape_fwk_hal_audio.png
new file mode 100644
index 0000000..fa6c47a
--- /dev/null
+++ b/src/devices/audio/images/ape_fwk_hal_audio.png
Binary files differ
diff --git a/src/devices/images/audio_hal.png b/src/devices/audio/images/audio_hal.png
similarity index 100%
rename from src/devices/images/audio_hal.png
rename to src/devices/audio/images/audio_hal.png
Binary files differ
diff --git a/src/devices/audio/images/breadboard.jpg b/src/devices/audio/images/breadboard.jpg
new file mode 100644
index 0000000..fd0ec39
--- /dev/null
+++ b/src/devices/audio/images/breadboard.jpg
Binary files differ
diff --git a/src/devices/audio/images/dac.png b/src/devices/audio/images/dac.png
index 6875035..a13027c 100644
--- a/src/devices/audio/images/dac.png
+++ b/src/devices/audio/images/dac.png
Binary files differ
diff --git a/src/devices/audio/images/display.jpg b/src/devices/audio/images/display.jpg
new file mode 100644
index 0000000..545206b
--- /dev/null
+++ b/src/devices/audio/images/display.jpg
Binary files differ
diff --git a/src/devices/audio/images/hub.jpg b/src/devices/audio/images/hub.jpg
index 0dd44bd..e825cdd 100644
--- a/src/devices/audio/images/hub.jpg
+++ b/src/devices/audio/images/hub.jpg
Binary files differ
diff --git a/src/devices/audio/images/loopback_assembled.jpg b/src/devices/audio/images/loopback_assembled.jpg
new file mode 100644
index 0000000..d54fa57
--- /dev/null
+++ b/src/devices/audio/images/loopback_assembled.jpg
Binary files differ
diff --git a/src/devices/audio/images/loopback_circuit.png b/src/devices/audio/images/loopback_circuit.png
new file mode 100644
index 0000000..4c47e53
--- /dev/null
+++ b/src/devices/audio/images/loopback_circuit.png
Binary files differ
diff --git a/src/devices/audio/images/medialog_after.png b/src/devices/audio/images/medialog_after.png
index c175fb3..0c16225 100644
--- a/src/devices/audio/images/medialog_after.png
+++ b/src/devices/audio/images/medialog_after.png
Binary files differ
diff --git a/src/devices/audio/images/medialog_before.png b/src/devices/audio/images/medialog_before.png
index 4299087..928d2f3 100644
--- a/src/devices/audio/images/medialog_before.png
+++ b/src/devices/audio/images/medialog_before.png
Binary files differ
diff --git a/src/devices/audio/images/otg.jpg b/src/devices/audio/images/otg.jpg
index 152180d..13a4071 100644
--- a/src/devices/audio/images/otg.jpg
+++ b/src/devices/audio/images/otg.jpg
Binary files differ
diff --git a/src/devices/audio/images/pcb.jpg b/src/devices/audio/images/pcb.jpg
new file mode 100644
index 0000000..a32bc35
--- /dev/null
+++ b/src/devices/audio/images/pcb.jpg
Binary files differ
diff --git a/src/devices/audio/images/round_trip.png b/src/devices/audio/images/round_trip.png
new file mode 100644
index 0000000..663552c
--- /dev/null
+++ b/src/devices/audio/images/round_trip.png
Binary files differ
diff --git a/src/devices/audio/images/round_trip_bar_graph.png b/src/devices/audio/images/round_trip_bar_graph.png
new file mode 100644
index 0000000..0476574
--- /dev/null
+++ b/src/devices/audio/images/round_trip_bar_graph.png
Binary files differ
diff --git a/src/devices/audio/images/round_trip_on_device.png b/src/devices/audio/images/round_trip_on_device.png
new file mode 100644
index 0000000..e1cf0a2
--- /dev/null
+++ b/src/devices/audio/images/round_trip_on_device.png
Binary files differ
diff --git a/src/devices/audio/images/round_trip_via_headset_connector.png b/src/devices/audio/images/round_trip_via_headset_connector.png
new file mode 100644
index 0000000..5791cf5
--- /dev/null
+++ b/src/devices/audio/images/round_trip_via_headset_connector.png
Binary files differ
diff --git a/src/devices/audio_implement.jd b/src/devices/audio/implement.jd
similarity index 98%
rename from src/devices/audio_implement.jd
rename to src/devices/audio/implement.jd
index 4535640..28f06b7 100644
--- a/src/devices/audio_implement.jd
+++ b/src/devices/audio/implement.jd
@@ -96,7 +96,7 @@
<h3 id="codecs">Media codecs</h3>
<p>Ensure the audio codecs your hardware and drivers support are properly declared for your
-product. For details on declaring supported codecs, see <a href="media.html#expose"> Exposing Codecs
+product. For details on declaring supported codecs, see <a href="{@docRoot}devices/media.html#expose">Exposing Codecs
to the Framework</a>.</p>
<h2 id="configuring">Configuring the shared library</h2>
@@ -227,7 +227,7 @@
not enable the noise suppression pre-processing effect. It should not be turned on by default when
recording from this audio source, and you should not enable it in your own audio_effects.conf file.
Turning on the effect by default will cause the device to fail the <a
-href="/compatibility/index.html"> compatibility requirement</a> regardless of whether this was on by
+href="{@docRoot}compatibility/index.html"> compatibility requirement</a> regardless of whether this was on by
default due to configuration file , or the audio HAL implementation's default behavior.</p>
<p>The following example enables pre-processing for the VoIP <code>AudioSource</code> and Camcorder
diff --git a/src/devices/audio/index.jd b/src/devices/audio/index.jd
new file mode 100644
index 0000000..bfa616d
--- /dev/null
+++ b/src/devices/audio/index.jd
@@ -0,0 +1,130 @@
+page.title=Audio
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<img style="float: right; margin: 0px 15px 15px 15px;"
+src="images/ape_fwk_hal_audio.png" alt="Android Audio HAL icon"/>
+
+<p>
+Android's audio Hardware Abstraction Layer (HAL) connects the higher-level,
+audio-specific framework APIs in <a href="http://developer.android.com/reference/android/media/package-summary.html">android.media</a> to the underlying audio driver and
+hardware. This section includes implementation instructions and tips for
+improving performance.
+</p>
+
+<h2 id="Architecture">Audio Architecture</h2>
+<p>
+Android audio architecture defines how audio functionality is implemented and
+points to the relevant source code involved in the implementation.
+</p>
+
+<img src="images/ape_fwk_audio.png" alt="Audio architecture" id="figure1" />
+
+<p class="img-caption">
+<strong>Figure 1.</strong> Android audio architecture
+</p>
+
+<dl>
+
+<dt>
+Application framework
+</dt>
+<dd>
+The application framework includes the app code, which uses the <a href="http://developer.android.com/reference/android/media/package-summary.html">android.media</a> APIs to
+interact with audio hardware. Internally, this code calls corresponding JNI glue
+classes to access the native code that interacts with audio hardware.
+</dd>
+
+<dt>
+JNI
+</dt>
+<dd>
+The JNI code associated with <a href="http://developer.android.com/reference/android/media/package-summary.html">android.media</a> calls lower level native code to access audio
+hardware. JNI is located in <code>frameworks/base/core/jni/</code> and
+<code>frameworks/base/media/jni</code>.
+</dd>
+
+<dt>
+Native framework
+</dt>
+<dd>
+The native framework provides a native equivalent to the <a href="http://developer.android.com/reference/android/media/package-summary.html">android.media</a> package, calling
+Binder IPC proxies to access the audio-specific services of the media server.
+Native framework code is located in <code>frameworks/av/media/libmedia</code>.
+</dd>
+
+<dt>
+Binder IPC
+</dt>
+<dd>
+Binder IPC proxies facilitate communication over process boundaries. Proxies are
+located in <code>frameworks/av/media/libmedia</code> and begin with the letter
+"I".
+</dd>
+
+<dt>
+Media server
+</dt>
+<dd>
+The media server contains audio services, which are the actual code that
+interacts with your HAL implementations. The media server is located in
+<code>frameworks/av/services/audioflinger</code>.
+</dd>
+
+<dt>
+HAL
+</dt>
+<dd>
+The HAL defines the standard interface that audio services call into and that
+you must implement for your audio hardware to function correctly. The audio HAL
+interfaces are located in <code>hardware/libhardware/include/hardware</code>.
+For details, see <a
+href="{@docRoot}devices/halref/audio_8h_source.html">hardware/audio.h</a>.
+</dd>
+
+<dt>
+Kernel driver
+</dt>
+<dd>
+The audio driver interacts with your hardware and HAL implementation. You can
+use Advanced Linux Sound Architecture (ALSA), Open Sound System (OSS), or a
+custom driver (HAL is driver-agnostic).
+<p class="note"><strong>Note</strong>: If you use ALSA, we recommend
+<code>external/tinyalsa</code> for the user portion of the driver because of its
+compatible licensing (the standard user-mode library is GPL-licensed).</p>
+</dd>
+
+<dt>
+Android native audio based on Open SL ES <em>(not shown)</em>
+</dt>
+<dd>
+This API is exposed as part of
+<a href="https://developer.android.com/tools/sdk/ndk/index.html">Android NDK</a>
+and is at the same architecture level as
+<a href="http://developer.android.com/reference/android/media/package-summary.html">android.media</a>.
+</dd>
+
+</dl>
\ No newline at end of file
diff --git a/src/devices/audio/latency.jd b/src/devices/audio/latency.jd
new file mode 100644
index 0000000..59c3f73
--- /dev/null
+++ b/src/devices/audio/latency.jd
@@ -0,0 +1,53 @@
+page.title=Audio Latency
+@jd:body
+
+<!--
+ Copyright 2013 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.
+-->
+<p>Audio latency is the time delay as an audio signal passes through a system.
+</p>
+
+<h3 id="resources">Resources</h3>
+
+<table>
+<tr>
+ <th>Topic</th>
+ <th>Links</th>
+</tr>
+<tr>
+ <td>Description of audio latency for purposes of Android compatibility</td>
+ <td><a href="{@docRoot}compatibility/android-cdd.pdf">Android CDD</a><br /><em>section 5.5 Audio Latency</em></td>
+</tr>
+<tr>
+ <td>Common causes of audio latency</td>
+ <td><a href="latency_contrib.html">Contributors to Audio Latency</a></td>
+</tr>
+<tr>
+ <td>Android's audio latency-reduction efforts</td>
+ <td><a href="latency_design.html">Design For Reduced Latency</a></td>
+</tr>
+<tr>
+ <td>Techniques to measure audio latency</td>
+ <td>
+ <a href="latency_measure.html">Measuring Audio Latency</a><br />
+ <a href="testing_circuit.html">Light Testing Circuit</a><br />
+ <a href="loopback.html">Audio Loopback Dongle</a>
+ </td>
+</tr>
+<tr>
+ <td>Round-trip audio latency results</td>
+ <td><a href="latency_measurements.html">Audio Latency Measurements</a></td>
+</tr>
+</table>
diff --git a/src/devices/audio/latency_contrib.jd b/src/devices/audio/latency_contrib.jd
new file mode 100644
index 0000000..fb7cd71
--- /dev/null
+++ b/src/devices/audio/latency_contrib.jd
@@ -0,0 +1,204 @@
+page.title=Contributors to Audio Latency
+@jd:body
+
+<!--
+ Copyright 2013 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>
+ This page focuses on the contributors to output latency,
+ but a similar discussion applies to input latency.
+</p>
+<p>
+ Assuming the analog circuitry does not contribute significantly, then the major
+ surface-level contributors to audio latency are the following:
+</p>
+
+<ul>
+ <li>Application</li>
+ <li>Total number of buffers in pipeline</li>
+ <li>Size of each buffer, in frames</li>
+ <li>Additional latency after the app processor, such as from a DSP</li>
+</ul>
+
+<p>
+ As accurate as the above list of contributors may be, it is also misleading.
+ The reason is that buffer count and buffer size are more of an
+ <em>effect</em> than a <em>cause</em>. What usually happens is that
+ a given buffer scheme is implemented and tested, but during testing, an audio
+ underrun or overrun is heard as a "click" or "pop." To compensate, the
+ system designer then increases buffer sizes or buffer counts.
+ This has the desired result of eliminating the underruns or overruns, but it also
+ has the undesired side effect of increasing latency.
+</p>
+
+<p>
+ A better approach is to understand the causes of the
+ underruns and overruns, and then correct those. This eliminates the
+ audible artifacts and may permit even smaller or fewer buffers
+ and thus reduce latency.
+</p>
+
+<p>
+ In our experience, the most common causes of underruns and overruns include:
+</p>
+<ul>
+ <li>Linux CFS (Completely Fair Scheduler)</li>
+ <li>high-priority threads with SCHED_FIFO scheduling</li>
+ <li>long scheduling latency</li>
+ <li>long-running interrupt handlers</li>
+ <li>long interrupt disable time</li>
+ <li>power management</li>
+ <li>security kernels</li>
+</ul>
+
+<h3 id="linuxCfs">Linux CFS and SCHED_FIFO scheduling</h3>
+<p>
+ The Linux CFS is designed to be fair to competing workloads sharing a common CPU
+ resource. This fairness is represented by a per-thread <em>nice</em> parameter.
+ The nice value ranges from -19 (least nice, or most CPU time allocated)
+ to 20 (nicest, or least CPU time allocated). In general, all threads with a given
+ nice value receive approximately equal CPU time and threads with a
+ numerically lower nice value should expect to
+ receive more CPU time. However, CFS is "fair" only over relatively long
+ periods of observation. Over short-term observation windows,
+ CFS may allocate the CPU resource in unexpected ways. For example, it
+ may take the CPU away from a thread with numerically low niceness
+ onto a thread with a numerically high niceness. In the case of audio,
+ this can result in an underrun or overrun.
+</p>
+
+<p>
+ The obvious solution is to avoid CFS for high-performance audio
+ threads. Beginning with Android 4.1, such threads now use the
+ <code>SCHED_FIFO</code> scheduling policy rather than the <code>SCHED_NORMAL</code> (also called
+ <code>SCHED_OTHER</code>) scheduling policy implemented by CFS.
+</p>
+
+<h3 id="schedFifo">SCHED_FIFO priorities</h3>
+<p>
+ Though the high-performance audio threads now use <code>SCHED_FIFO</code>, they
+ are still susceptible to other higher priority <code>SCHED_FIFO</code> threads.
+ These are typically kernel worker threads, but there may also be a few
+ non-audio user threads with policy <code>SCHED_FIFO</code>. The available <code>SCHED_FIFO</code>
+ priorities range from 1 to 99. The audio threads run at priority
+ 2 or 3. This leaves priority 1 available for lower priority threads,
+ and priorities 4 to 99 for higher priority threads. We recommend
+ you use priority 1 whenever possible, and reserve priorities 4 to 99 for
+ those threads that are guaranteed to complete within a bounded amount
+ of time, execute with a period shorter than the period of audio threads,
+ and are known to not interfere with scheduling of audio threads.
+</p>
+
+<h3 id="rms">Rate-monotonic scheduling</h3>
+<p>
+ For more information on the theory of assignment of fixed priorities,
+ see the Wikipedia article
+ <a href="http://en.wikipedia.org/wiki/Rate-monotonic_scheduling">Rate-monotonic scheduling</a> (RMS).
+ A key point is that fixed priorities should be allocated strictly based on period,
+ with higher priorities assigned to threads of shorter periods, not based on perceived "importance."
+ Non-periodic threads may be modeled as periodic threads, using the maximum frequency of execution
+ and maximum computation per execution. If a non-periodic thread cannot be modeled as
+ a periodic thread (for example it could execute with unbounded frequency or unbounded computation
+ per execution), then it should not be assigned a fixed priority as that would be incompatible
+ with the scheduling of true periodic threads.
+</p>
+
+<h3 id="schedLatency">Scheduling latency</h3>
+<p>
+ Scheduling latency is the time between when a thread becomes
+ ready to run and when the resulting context switch completes so that the
+ thread actually runs on a CPU. The shorter the latency the better, and
+ anything over two milliseconds causes problems for audio. Long scheduling
+ latency is most likely to occur during mode transitions, such as
+ bringing up or shutting down a CPU, switching between a security kernel
+ and the normal kernel, switching from full power to low-power mode,
+ or adjusting the CPU clock frequency and voltage.
+</p>
+
+<h3 id="interrupts">Interrupts</h3>
+<p>
+ In many designs, CPU 0 services all external interrupts. So a
+ long-running interrupt handler may delay other interrupts, in particular
+ audio direct memory access (DMA) completion interrupts. Design interrupt handlers
+ to finish quickly and defer lengthy work to a thread (preferably
+ a CFS thread or <code>SCHED_FIFO</code> thread of priority 1).
+</p>
+
+<p>
+ Equivalently, disabling interrupts on CPU 0 for a long period
+ has the same result of delaying the servicing of audio interrupts.
+ Long interrupt disable times typically happen while waiting for a kernel
+ <i>spin lock</i>. Review these spin locks to ensure they are bounded.
+</p>
+
+<h3 id="power">Power, performance, and thermal management</h3>
+<p>
+ <a href="http://en.wikipedia.org/wiki/Power_management">Power management</a>
+ is a broad term that encompasses efforts to monitor
+ and reduce power consumption while optimizing performance.
+ <a href="http://en.wikipedia.org/wiki/Thermal_management_of_electronic_devices_and_systems">Thermal management</a>
+ and <a href="http://en.wikipedia.org/wiki/Computer_cooling">computer cooling</a>
+ are similar but seek to measure and control heat to avoid damage due to excess heat.
+ In the Linux kernel, the CPU
+ <a href="http://en.wikipedia.org/wiki/Governor_%28device%29">governor</a>
+ is responsible for low-level policy, while user mode configures high-level policy.
+ Techniques used include:
+</p>
+
+<ul>
+ <li>dynamic voltage scaling</li>
+ <li>dynamic frequency scaling</li>
+ <li>dynamic core enabling</li>
+ <li>cluster switching</li>
+ <li>power gating</li>
+ <li>hotplug (hotswap)</li>
+ <li>various sleep modes (halt, stop, idle, suspend, etc.)</li>
+ <li>process migration</li>
+ <li><a href="http://en.wikipedia.org/wiki/Processor_affinity">processor affinity</a></li>
+</ul>
+
+<p>
+ Some management operations can result in "work stoppages" or
+ times during which there is no useful work performed by the application processor.
+ These work stoppages can interfere with audio, so such management should be designed
+ for an acceptable worst-case work stoppage while audio is active.
+ Of course, when thermal runaway is imminent, avoiding permanent damage
+ is more important than audio!
+</p>
+
+<h3 id="security">Security kernels</h3>
+<p>
+ A <a href="http://en.wikipedia.org/wiki/Security_kernel">security kernel</a> for
+ <a href="http://en.wikipedia.org/wiki/Digital_rights_management">Digital rights management</a>
+ (DRM) may run on the same application processor core(s) as those used
+ for the main operating system kernel and application code. Any time
+ during which a security kernel operation is active on a core is effectively a
+ stoppage of ordinary work that would normally run on that core.
+ In particular, this may include audio work. By its nature, the internal
+ behavior of a security kernel is inscrutable from higher-level layers, and thus
+ any performance anomalies caused by a security kernel are especially
+ pernicious. For example, security kernel operations do not typically appear in
+ context switch traces. We call this "dark time" — time that elapses
+ yet cannot be observed. Security kernels should be designed for an
+ acceptable worst-case work stoppage while audio is active.
+</p>
diff --git a/src/devices/latency_design.jd b/src/devices/audio/latency_design.jd
similarity index 85%
rename from src/devices/latency_design.jd
rename to src/devices/audio/latency_design.jd
index a2ad236..21f963f 100644
--- a/src/devices/latency_design.jd
+++ b/src/devices/audio/latency_design.jd
@@ -26,9 +26,10 @@
<p>
The Android 4.1 release introduced internal framework changes for
-a lower latency audio output path. There were no public client API
+a <a href="http://en.wikipedia.org/wiki/Low_latency">lower latency</a>
+audio output path. There were minimal public client API
or HAL API changes. This document describes the initial design,
-which is expected to evolve over time.
+which has continued to evolve over time.
Having a good understanding of this design should help device OEM and
SoC vendors implement the design correctly on their particular devices
and chipsets. This article is not intended for application developers.
@@ -43,9 +44,9 @@
</p>
<ul>
-<li>OpenSL ES</li>
-<li>SoundPool</li>
-<li>ToneGenerator</li>
+<li>Android native audio based on OpenSL ES</li>
+<li><a href="http://developer.android.com/reference/android/media/SoundPool.html">android.media.SoundPool</a></li>
+<li><a href="http://developer.android.com/reference/android/media/ToneGenerator.html">android.media.ToneGenerator</a></li>
</ul>
<p>
@@ -118,7 +119,7 @@
<p>
The fast mixer runs periodically, with a recommended period of two
-to three milliseconds (ms), or slightly higher if needed for scheduling stability.
+to three milliseconds (ms), or a slightly higher period of five ms if needed for scheduling stability.
This number was chosen so that, accounting for the complete
buffer pipeline, the total latency is on the order of 10 ms. Smaller
values are possible but may result in increased power consumption
@@ -132,6 +133,9 @@
<p>
The fast mixer runs at elevated <code>SCHED_FIFO</code> priority. It needs very
little CPU time, but must run often and with low scheduling jitter.
+<a href="http://en.wikipedia.org/wiki/Jitter">Jitter</a>
+expresses the variation in cycle time: it is the difference between the
+actual cycle time versus the expected cycle time.
Running too late will result in glitches due to underrun. Running
too early will result in glitches due to pulling from a fast track
before the track has provided data.
@@ -143,6 +147,9 @@
Ideally the fast mixer thread never blocks, other than at HAL
<code>write()</code>. Other occurrences of blocking within the fast mixer are
considered bugs. In particular, mutexes are avoided.
+Instead, <a href="http://en.wikipedia.org/wiki/Non-blocking_algorithm">non-blocking algorithms</a>
+(also known as lock-free algorithms) are used.
+See <a href="avoiding_pi.html">Avoiding Priority Inversion</a> for more on this topic.
</p>
<h4>Relationship to other components</h4>
diff --git a/src/devices/audio_latency_measure.jd b/src/devices/audio/latency_measure.jd
similarity index 78%
rename from src/devices/audio_latency_measure.jd
rename to src/devices/audio/latency_measure.jd
index 7bb6ac5..f6b1d3e 100644
--- a/src/devices/audio_latency_measure.jd
+++ b/src/devices/audio/latency_measure.jd
@@ -1,4 +1,4 @@
-page.title=Audio Latency
+page.title=Measuring Audio Latency
@jd:body
<!--
@@ -38,7 +38,7 @@
see the <a href="testing_circuit.html">Testing circuit</a> for an example test environment.
</p>
-<h3>LED and oscilloscope test</h3>
+<h3 id="ledTest">LED and oscilloscope test</h3>
<p>
This test measures latency in relation to the device's LED indicator.
If your production device does not have an LED, you can install the
@@ -88,27 +88,64 @@
on the order of one millisecond or less, which is sufficiently low enough
to ignore.</p>
-<h3>Larsen test</h3>
+<h2 id="measuringRoundTrip">Measuring Round-Trip Latency</h2>
+
+<p>
+ <a href="http://en.wikipedia.org/wiki/Round-trip_delay_time">Round-trip latency</a>
+ is the sum of output latency and input latency.
+</p>
+
+<h3 id="larsenTest">Larsen test</h3>
<p>
One of the easiest latency tests is an audio feedback
(Larsen effect) test. This provides a crude measure of combined output
and input latency by timing an impulse response loop. This test is not very useful
- by itself because of the nature of the test, but it can be useful for calibrating
- other tests</p>
+ for detailed analysis
+ by itself because of the nature of the test, but it can be useful for
+ calibrating other tests, and for establishing an upper bound.</p>
<p>To conduct this test:</p>
<ol>
<li>Run an app that captures audio from the microphone and immediately plays the
captured data back over the speaker.</li>
<li>Create a sound externally,
- such as tapping a pencil by the microphone. This noise generates a feedback loop.</li>
+ such as tapping a pencil by the microphone. This noise generates a feedback loop.
+ Alternatively, one can inject an impulse into the loop using software.</li>
<li>Measure the time between feedback pulses to get the sum of the output latency, input latency, and application overhead.</li>
</ol>
<p>This method does not break down the
component times, which is important when the output latency
- and input latency are independent. So this method is not recommended for measuring output latency, but might be useful
- to help measure output latency.</p>
+ and input latency are independent. So this method is not recommended for measuring
+ precise output latency or input latency values in isolation, but might be useful
+ for establishing rough estimates.</p>
+
+<p>
+We have published an example implementation at
+<a href="https://android.googlesource.com/platform/frameworks/wilhelm/+/master/tests/examples/slesTestFeedback.cpp">slesTestFeedback.cpp</a>.
+This is a command-line app and is built using the platform build environment;
+however it should be straightforward to adopt the code for other environments.
+You will also need the <a href="avoiding_pi.html#nonBlockingAlgorithms">non-blocking</a> FIFO code
+located in the <code>audio_utils</code> library.
+</p>
+
+<h3 id="loopback">Audio Loopback Dongle</h3>
+
+<p>
+ The <a href="loopback.html">Dr. Rick O'Rang audio loopback dongle</a> is handy for
+ measuring round-trip latency over the headset connector.
+ The image below demonstrates the result of injecting an impulse
+ into the loop once, and then allowing the feedback loop to oscillate.
+ The period of the oscillations is the round-trip latency.
+ The specific device, software release, and
+ test conditions are not specified here. The results shown
+ should not be extrapolated.
+</p>
+
+<img src="images/round_trip.png" alt="round-trip measurement" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> Round-trip measurement
+</p>
<h2 id="measuringInput">Measuring Input Latency</h2>
diff --git a/src/devices/audio/latency_measurements.jd b/src/devices/audio/latency_measurements.jd
new file mode 100644
index 0000000..e66b5f9
--- /dev/null
+++ b/src/devices/audio/latency_measurements.jd
@@ -0,0 +1,359 @@
+page.title=Audio Latency Measurements
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>
+This article gives round-trip audio latency measurements for select devices and
+platform versions.
+</p>
+
+<h2 id="definition">Definition</h2>
+
+<p>
+<a href="http://en.wikipedia.org/wiki/Latency_%28engineering%29">Latency</a>
+is an important system performance metric. There are many kinds
+of <a href="latency.html">audio latency</a>
+metrics. One useful and well-understood metric is
+<a href="latency_measure.html#measuringRoundTrip">round-trip latency</a>.
+Round-trip latency is defined as the time it takes for
+an audio signal to enter the input of a mobile device, be processed
+by an app running on the application processor, and exit the output.
+</p>
+
+<img src="images/round_trip_on_device.png" alt="Round-trip audio latency on device" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> Round-trip audio latency on device: T<sub>output</sub> - T<sub>input</sub>
+</p>
+
+<h2 id="why">Why we measure latency</h2>
+
+<p>
+We measure and report latency so Android
+app developers will have the data they need to make informed decisions about available
+latency on actual devices. By sharing these numbers for select Nexus devices, we also hope to
+encourage the entire Android community to measure, publish, and reduce
+latency on <i>all</i> devices.
+Please join us in our commitment to reducing audio latency.
+</p>
+
+<h2 id="app">Application impact on latency</h2>
+
+<p>
+There are two kinds of delays that a signal processing stage can add to latency:
+algorithmic delay and computational delay.
+Algorithmic delay is inherent and does not vary with the CPU.
+An example is the delay added by a
+<a href="http://en.wikipedia.org/wiki/Finite_impulse_response">finite impulse response</a>
+(FIR) filter.
+Computational delay is related to the number of CPU cycles required.
+For example, attenuation of a signal is usually done by a multiplication operation,
+and this multiplication will take a varying number of cycles depending on the CPU.
+</p>
+
+<h2 id="how">How we measure</h2>
+
+<p>
+The measurements below were taken with the
+<a href="loopback.html">Dr. Rick O’Rang audio loopback dongle</a>
+and an
+<a href="latency_measure.html#larsenTest">audio feedback (Larsen effect) test</a>.
+</p>
+
+<p>
+For our measurements, we assume the application signal processing
+adds zero algorithmic delay and near zero computational delay.
+</p>
+
+<p>
+We measure round-trip latency via the headset connector for several reasons:
+</p>
+<ul>
+ <li>
+ There are important music applications, such as guitar and voice processing,
+ that use the headset connector.
+ </li>
+ <li>
+ Measuring round-trip latency of the on-device microphone and speaker can
+ be cumbersome, as it is difficult to keep a feedback loop in open air from entering
+ uncontrolled oscillation.
+ </li>
+ <li>
+ The on-device transducers are small and sacrifice frequency response
+ to achieve their small size. To compensate, digital signal processing is
+ applied but increases algorithmic delay for the on-device path.
+ </li>
+</ul>
+
+<p>
+There are cases where on-device microphone and speaker latencies
+<i>do</i>
+matter, but they are usually for one direction, not round-trip.
+Techniques for measuring unidirectional latency are described at
+<a href="latency_measure.html#measuringOutput">Measuring Output Latency</a>
+and
+<a href="latency_measure.html#measuringInput">Measuring Input Latency</a>.
+</p>
+
+<img src="images/round_trip_via_headset_connector.png" alt="Round-trip latency via headset connector" id="figure2" />
+<p class="img-caption">
+ <strong>Figure 2.</strong> Round-trip latency via headset connector: T<sub>output</sub> - T<sub>input</sub>
+</p>
+
+<h2 id="measurements">Example measurements</h2>
+
+<p>
+The measurements shown are specific to a
+<a href="{@docRoot}source/build-numbers.html">build number</a>.
+Devices are listed in approximate order of initial release and within device by platform version.
+The test application uses the Android native audio API based on OpenSL ES.
+</p>
+
+<table>
+<tr>
+ <th>Model</th>
+ <th>Platform<br />version</th>
+ <th>Build<br />number</th>
+ <th>Sample rate<br />(Hz)</th>
+ <th>Buffer size<br />(frames)</th>
+ <th>Buffer size<br />(ms)</th>
+ <th>Round-trip<br />latency (ms)<br />± one buffer</th>
+</tr>
+
+<tr>
+ <td>Nexus One</td>
+ <td>2.3.6</td>
+ <td>GRK39F</td>
+ <td>44100</td>
+ <td>768</td>
+ <td>17.4</td>
+ <td>345</td>
+</tr>
+
+<tr>
+ <td>Nexus S</td>
+ <td>2.3.6</td>
+ <td>GRK39F</td>
+ <td>44100</td>
+ <td>1024</td>
+ <td>23.2</td>
+ <td>260</td>
+</tr>
+
+<tr>
+ <td>Nexus S</td>
+ <td>4.0.4</td>
+ <td>IMM76D</td>
+ <td>44100</td>
+ <td>1024</td>
+ <td>23.2</td>
+ <td>260</td>
+</tr>
+
+<tr>
+ <td>Nexus S</td>
+ <td>4.1.2</td>
+ <td>JZO54K</td>
+ <td>44100</td>
+ <td>880</td>
+ <td>20</td>
+ <td>210</td>
+</tr>
+
+<tr>
+ <td>Galaxy Nexus</td>
+ <td>4.0.1</td>
+ <td>ITL41D</td>
+ <td>44100</td>
+ <td>976</td>
+ <td>22.1</td>
+ <td>270</td>
+</tr>
+
+<tr>
+ <td>Galaxy Nexus</td>
+ <td>4.3</td>
+ <td>JWR66Y</td>
+ <td>44100</td>
+ <td>144</td>
+ <td>3.3</td>
+ <td>130</td>
+</tr>
+
+<tr>
+ <td>Nexus 4</td>
+ <td>4.2.2</td>
+ <td>JDQ39E</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>195</td>
+</tr>
+
+<tr>
+ <td>Nexus 4</td>
+ <td>5.1</td>
+ <td>LMY47O</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>58</td>
+</tr>
+
+<tr>
+ <td>Nexus 10</td>
+ <td>5.0.2</td>
+ <td>LRX22G</td>
+ <td>44100</td>
+ <td>256</td>
+ <td>5.8</td>
+ <td>36</td>
+</tr>
+
+<tr>
+ <td>Nexus 10</td>
+ <td>5.1</td>
+ <td>LMY47D</td>
+ <td>44100</td>
+ <td>256</td>
+ <td>5.8</td>
+ <td>35</td>
+</tr>
+
+<tr>
+ <td>Nexus 7<br />2013</td>
+ <td>4.3</td>
+ <td>JSR78D</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>149</td>
+</tr>
+
+<tr>
+ <td>Nexus 7<br />2013</td>
+ <td>4.4</td>
+ <td>KRT16S</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>85</td>
+</tr>
+
+<tr>
+ <td>Nexus 7<br />2013</td>
+ <td>5.0.2</td>
+ <td>LRX22G</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>64</td>
+</tr>
+
+<tr>
+ <td>Nexus 7<br />2013</td>
+ <td>5.1</td>
+ <td>LMY47O</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>55</td>
+</tr>
+
+<tr>
+ <td>Nexus 5</td>
+ <td>4.4.4</td>
+ <td>KTU84P</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>95</td>
+</tr>
+
+<tr>
+ <td>Nexus 5</td>
+ <td>5.0.0</td>
+ <td>LRX21O</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>47</td>
+</tr>
+
+<tr>
+ <td>Nexus 5</td>
+ <td>5.1</td>
+ <td>LMY47I</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>42</td>
+</tr>
+
+<tr>
+ <td>Nexus 9</td>
+ <td>5.0.0</td>
+ <td>LRX21L</td>
+ <td>48000</td>
+ <td>256</td>
+ <td>5.3</td>
+ <td>35</td>
+</tr>
+
+<tr>
+ <td>Nexus 9</td>
+ <td>5.0.1</td>
+ <td>LRX22C</td>
+ <td>48000</td>
+ <td>256</td>
+ <td>5.3</td>
+ <td>38</td>
+</tr>
+
+<tr>
+ <td>Nexus 6</td>
+ <td>5.0.1</td>
+ <td>LRX22C</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>65</td>
+</tr>
+
+<tr>
+ <td>Nexus 6</td>
+ <td>5.1</td>
+ <td>LMY47I</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>42</td>
+</tr>
+
+</table>
+
+<img src="images/round_trip_bar_graph.png" alt="Round-trip latency bar graph" id="figure3" />
+<p class="img-caption">
+ <strong>Figure 3.</strong> Round-trip latency bar graph
+</p>
diff --git a/src/devices/audio/loopback.jd b/src/devices/audio/loopback.jd
new file mode 100644
index 0000000..933972f
--- /dev/null
+++ b/src/devices/audio/loopback.jd
@@ -0,0 +1,58 @@
+page.title=Audio Loopback Dongle
+@jd:body
+
+<!--
+ Copyright 2014 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>
+The diagram and photo below show an audio loopback
+<a href="http://en.wikipedia.org/wiki/Dongle">dongle</a>
+for the
+<a href="http://en.wikipedia.org/wiki/Phone_connector_(audio)">headset connector</a>
+that we call the "Dr. Rick O'Rang audio loopback dongle."
+The Chrome hardware team designed this circuit and plug for functional testing;
+however it has many other uses too. The Android audio team uses it to measure
+<a href="latency_measure.html#measuringRoundTrip">round-trip audio latency</a>,
+via the Larsen effect (feedback loop).
+</p>
+
+<h2 id="loopbackCircuit">Circuit</h2>
+
+<img src="images/loopback_circuit.png" alt="circuit" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> circuit diagram
+</p>
+
+<p>
+To ensure that the output signal will not overload the microphone input,
+we cut it down by about 20dB.
+The resistor loads tell the microphone polarity switch that
+the audio loopback dongle is a US/CTIA pinout Tip Ring Ring Shield (TRRS) plug.
+</p>
+
+<h2 id="loopbackAssembled">Assembled</h2>
+
+<img src="images/loopback_assembled.jpg" alt="fully assembled" id="figure2" />
+<p class="img-caption">
+ <strong>Figure 2.</strong> Assembled
+</p>
diff --git a/src/devices/audio_src.jd b/src/devices/audio/src.jd
similarity index 97%
rename from src/devices/audio_src.jd
rename to src/devices/audio/src.jd
index 6238770..ab70fee 100644
--- a/src/devices/audio_src.jd
+++ b/src/devices/audio/src.jd
@@ -31,6 +31,7 @@
<a href="http://en.wikipedia.org/wiki/Resampling_(audio)">Resampling (audio)</a>
for a generic definition of sample rate conversion, also known as "resampling."
The remainder of this article describes resampling within Android.
+See <a href="terminology.html#srcTerms">Sample Rate Conversion</a> for related terminology.
</p>
<p>
diff --git a/src/devices/audio/terminology.jd b/src/devices/audio/terminology.jd
new file mode 100644
index 0000000..cec0bcd
--- /dev/null
+++ b/src/devices/audio/terminology.jd
@@ -0,0 +1,766 @@
+page.title=Audio Terminology
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>
+This glossary of audio-related terminology includes widely-used generic terms
+and Android-specific terms.
+</p>
+
+<h2 id="genericTerm">Generic Terms</h2>
+
+<p>
+Generic audio-related terms have conventional meanings.
+</p>
+
+<h3 id="digitalAudioTerms">Digital Audio</h3>
+<p>
+Digital audio terms relate to handling sound using audio signals encoded
+in digital form. For details, refer to
+<a href="http://en.wikipedia.org/wiki/Digital_audio">Digital Audio</a>.
+</p>
+
+<dl>
+
+<dt>acoustics</dt>
+<dd>
+Study of the mechanical properties of sound, such as how the physical
+placement of transducers (speakers, microphones, etc.) on a device affects
+perceived audio quality.
+</dd>
+
+<dt>attenuation</dt>
+<dd>
+Multiplicative factor less than or equal to 1.0, applied to an audio signal
+to decrease the signal level. Compare to <em>gain</em>.
+</dd>
+
+<dt>audiophile</dt>
+<dd>
+Person concerned with a superior music reproduction experience, especially
+willing to make substantial tradeoffs (expense, component size, room design,
+etc.) for sound quality. For details, refer to
+<a href="http://en.wikipedia.org/wiki/Audiophile">audiophile</a>.
+</dd>
+
+<dt>bits per sample or bit depth</dt>
+<dd>
+Number of bits of information per sample.
+</dd>
+
+<dt>channel</dt>
+<dd>
+Single stream of audio information, usually corresponding to one location of
+recording or playback.
+</dd>
+
+<dt>downmixing</dt>
+<dd>
+Decrease the number of channels, such as from stereo to mono or from 5.1 to
+stereo. Accomplished by dropping channels, mixing channels, or more advanced
+signal processing. Simple mixing without attenuation or limiting has the
+potential for overflow and clipping. Compare to <em>upmixing</em>.
+</dd>
+
+<dt>DSD</dt>
+<dd>
+Direct Stream Digital. Proprietary audio encoding based on
+<a href="http://en.wikipedia.org/wiki/Pulse-density_modulation">pulse-density
+modulation</a>. While Pulse Code Modulation (PCM) encodes a waveform as a
+sequence of individual audio samples of multiple bits, DSD encodes a waveform as
+a sequence of bits at a very high sample rate (without the concept of samples).
+Both PCM and DSD represent multiple channels by independent sequences. DSD is
+better suited to content distribution than as an internal representation for
+processing as it can be difficult to apply traditional digital signal processing
+(DSP) algorithms to DSD. DSD is used in <a href="http://en.wikipedia.org/wiki/Super_Audio_CD">Super Audio CD (SACD)</a> and in DSD over PCM (DoP) for USB. For details, refer
+to <a href="http://en.wikipedia.org/wiki/Direct_Stream_Digital">Digital Stream
+Digital</a>.
+</dd>
+
+<dt>duck</dt>
+<dd>
+Temporarily reduce the volume of a stream when another stream becomes active.
+For example, if music is playing when a notification arrives, the music ducks
+while the notification plays. Compare to <em>mute</em>.
+</dd>
+
+<dt>FIFO</dt>
+<dd>
+First In, First Out. Hardware module or software data structure that implements
+<a href="http://en.wikipedia.org/wiki/FIFO">First In, First Out</a>
+queueing of data. In an audio context, the data stored in the queue are
+typically audio frames. FIFO can be implemented by a
+<a href="http://en.wikipedia.org/wiki/Circular_buffer">circular buffer</a>.
+</dd>
+
+<dt>frame</dt>
+<dd>
+Set of samples, one per channel, at a point in time.
+</dd>
+
+<dt>frames per buffer</dt>
+<dd>
+Number of frames handed from one module to the next at one time. The audio HAL
+interface uses the concept of frames per buffer.
+</dd>
+
+<dt>gain</dt>
+<dd>
+Multiplicative factor greater than or equal to 1.0, applied to an audio signal
+to increase the signal level. Compare to <em>attenuation</em>.
+</dd>
+
+<dt>HD audio</dt>
+<dd>
+High-Definition audio. Synonym for high-resolution audio (but different than
+Intel High Definition Audio).
+</dd>
+
+<dt>Hz</dt>
+<dd>
+Units for sample rate or frame rate.
+</dd>
+
+<dt>high-resolution audio</dt>
+<dd>
+Representation with greater bit-depth and sample rate than CDs (stereo 16-bit
+PCM at 44.1 kHz) and without lossy data compression. Equivalent to HD audio.
+For details, refer to
+<a href="http://en.wikipedia.org/wiki/High-resolution_audio">high-resolution
+audio</a>.
+</dd>
+
+<dt>latency</dt>
+<dd>
+Time delay as a signal passes through a system.
+</dd>
+
+<dt>lossless</dt>
+<dd>
+A <a href="http://en.wikipedia.org/wiki/Lossless_compression">lossless data
+compression algorithm</a> that preserves bit accuracy across encoding and
+decoding, where the result of decoding previously encoded data is equivalent
+to the original data. Examples of lossless audio content distribution formats
+include <a href="http://en.wikipedia.org/wiki/Compact_disc">CDs</a>, PCM within
+<a href="http://en.wikipedia.org/wiki/WAV">WAV</a>, and
+<a href="http://en.wikipedia.org/wiki/FLAC">FLAC</a>.
+The authoring process may reduce the bit depth or sample rate from that of the
+<a href="http://en.wikipedia.org/wiki/Audio_mastering">masters</a>; distribution
+formats that preserve the resolution and bit accuracy of masters are the subject
+of high-resolution audio.
+</dd>
+
+<dt>lossy</dt>
+<dd>
+A <a href="http://en.wikipedia.org/wiki/Lossy_compression">lossy data
+compression algorithm</a> that attempts to preserve the most important features
+of media across encoding and decoding where the result of decoding previously
+encoded data is perceptually similar to the original data but not identical.
+Examples of lossy audio compression algorithms include MP3 and AAC. As analog
+values are from a continuous domain and digital values are discrete, ADC and DAC
+are lossy conversions with respect to amplitude. See also <em>transparency</em>.
+</dd>
+
+<dt>mono</dt>
+<dd>
+One channel.
+</dd>
+
+<dt>multichannel</dt>
+<dd>
+See <em>surround sound</em>. In strict terms, <em>stereo</em> is more than one
+channel and could be considered multichannel; however, such usage is confusing
+and thus avoided.
+</dd>
+
+<dt>mute</dt>
+<dd>
+Temporarily force volume to be zero, independent from the usual volume controls.
+</dd>
+
+<dt>overrun</dt>
+<dd>
+Audible <a href="http://en.wikipedia.org/wiki/Glitch">glitch</a> caused by
+failure to accept supplied data in sufficient time. For details, refer to
+<a href="http://en.wikipedia.org/wiki/Buffer_underrun">buffer underrun</a>.
+Compare to <em>underrun</em>.
+</dd>
+
+<dt>panning</dt>
+<dd>
+Direct a signal to a desired position within a stereo or multichannel field.
+</dd>
+
+<dt>PCM</dt>
+<dd>
+Pulse Code Modulation. Most common low-level encoding of digital audio. The
+audio signal is sampled at a regular interval, called the sample rate, then
+quantized to discrete values within a particular range depending on the bit
+depth. For example, for 16-bit PCM the sample values are integers between
+-32768 and +32767.
+</dd>
+
+<dt>ramp</dt>
+<dd>
+Gradually increase or decrease the level of a particular audio parameter, such
+as the volume or the strength of an effect. A volume ramp is commonly applied
+when pausing and resuming music to avoid a hard audible transition.
+</dd>
+
+<dt>sample</dt>
+<dd>
+Number representing the audio value for a single channel at a point in time.
+</dd>
+
+<dt>sample rate or frame rate</dt>
+<dd>
+Number of frames per second. While <em>frame rate</em> is more accurate,
+<em>sample rate</em> is conventionally used to mean frame rate.
+</dd>
+
+<dt>sonification</dt>
+<dd>
+Use of sound to express feedback or information, such as touch sounds and
+keyboard sounds.
+</dd>
+
+<dt>stereo</dt>
+<dd>
+Two channels.
+</dd>
+
+<dt>stereo widening</dt>
+<dd>
+Effect applied to a stereo signal to make another stereo signal that sounds
+fuller and richer. The effect can also be applied to a mono signal, where it is
+a type of upmixing.
+</dd>
+
+<dt>surround sound</dt>
+<dd>
+Techniques for increasing the ability of a listener to perceive sound position
+beyond stereo left and right.
+</dd>
+
+<dt>transparency</dt>
+<dd>
+Ideal result of lossy data compression. Lossy data conversion is transparent if
+it is perceptually indistinguishable from the original by a human subject. For
+details, refer to
+<a href="http://en.wikipedia.org/wiki/Transparency_%28data_compression%29">Transparency</a>.
+
+</dd>
+
+<dt>underrun</dt>
+<dd>
+Audible <a href="http://en.wikipedia.org/wiki/Glitch">glitch</a> caused by
+failure to supply needed data in sufficient time. For details, refer to
+<a href="http://en.wikipedia.org/wiki/Buffer_underrun">buffer underrun</a>.
+Compare to <em>overrun</em>.
+</dd>
+
+<dt>upmixing</dt>
+<dd>
+Increase the number of channels, such as from mono to stereo or from stereo to
+surround sound. Accomplished by duplication, panning, or more advanced signal
+processing. Compare to <em>downmixing</em>.
+</dd>
+
+<dt>virtualizer</dt>
+<dd>
+Effect that attempts to spatialize audio channels, such as trying to simulate
+more speakers or give the illusion that sound sources have position.
+</dd>
+
+<dt>volume</dt>
+<dd>
+Loudness, the subjective strength of an audio signal.
+</dd>
+
+</dl>
+
+<h3 id="interDeviceTerms">Inter-device interconnect</h3>
+
+<p>
+Inter-device interconnection technologies connect audio and video components
+between devices and are readily visible at the external connectors. The HAL
+implementer and end user should be aware of these terms.
+</p>
+
+<dl>
+
+<dt>Bluetooth</dt>
+<dd>
+Short range wireless technology. For details on the audio-related
+<a href="http://en.wikipedia.org/wiki/Bluetooth_profile">Bluetooth profiles</a>
+and
+<a href="http://en.wikipedia.org/wiki/Bluetooth_protocols">Bluetooth protocols</a>,
+refer to <a href="http://en.wikipedia.org/wiki/Bluetooth_profile#Advanced_Audio_Distribution_Profile_.28A2DP.29">A2DP</a> for
+music, <a href="http://en.wikipedia.org/wiki/Bluetooth_protocols#Synchronous_connection-oriented_.28SCO.29_link">SCO</a> for telephony, and <a href="http://en.wikipedia.org/wiki/List_of_Bluetooth_profiles#Audio.2FVideo_Remote_Control_Profile_.28AVRCP.29">Audio/Video Remote Control Profile (AVRCP)</a>.
+</dd>
+
+<dt>DisplayPort</dt>
+<dd>
+Digital display interface by the Video Electronics Standards Association (VESA).
+</dd>
+
+<dt>HDMI</dt>
+<dd>
+High-Definition Multimedia Interface. Interface for transferring audio and
+video data. For mobile devices, a micro-HDMI (type D) or MHL connector is used.
+</dd>
+
+<dt>Intel HDA</dt>
+<dd>
+Intel High Definition Audio (do not confuse with generic <em>high-definition
+audio</em> or <em>high-resolution audio</em>). Specification for a front-panel
+connector. For details, refer to
+<a href="http://en.wikipedia.org/wiki/Intel_High_Definition_Audio">Intel High
+Definition Audio</a>.
+</dd>
+
+<dt>MHL</dt>
+<dd>
+Mobile High-Definition Link. Mobile audio/video interface, often over micro-USB
+connector.
+</dd>
+
+<dt>phone connector</dt>
+<dd>
+Mini or sub-mini component that connects a device to wired headphones, headset,
+or line-level amplifier.
+</dd>
+
+<dt>SlimPort</dt>
+<dd>
+Adapter from micro-USB to HDMI.
+</dd>
+
+<dt>S/PDIF</dt>
+<dd>
+Sony/Philips Digital Interface Format. Interconnect for uncompressed PCM. For
+details, refer to <a href="http://en.wikipedia.org/wiki/S/PDIF">S/PDIF</a>.
+</dd>
+
+<dt>Thunderbolt</dt>
+<dd>
+Multimedia interface that competes with USB and HDMI for connecting to high-end
+peripherals. For details, refer to <a href="http://en.wikipedia.org/wiki/Thunderbolt_%28interface%29">Thunderbolt</a>.
+</dd>
+
+<dt>USB</dt>
+<dd>
+Universal Serial Bus. For details, refer to
+<a href="http://en.wikipedia.org/wiki/USB">USB</a>.
+</dd>
+
+</dl>
+
+<h3 id="intraDeviceTerms">Intra-device interconnect</h3>
+
+<p>
+Intra-device interconnection technologies connect internal audio components
+within a given device and are not visible without disassembling the device. The
+HAL implementer may need to be aware of these, but not the end user. For details
+on intra-device interconnections, refer to the following articles:
+</p>
+<ul>
+<li><a href="http://en.wikipedia.org/wiki/General-purpose_input/output">GPIO</a></li>
+<li><a href="http://en.wikipedia.org/wiki/I%C2%B2C">I²C</a>, for control channel</li>
+<li><a href="http://en.wikipedia.org/wiki/I%C2%B2S">I²S</a>, for audio data</li>
+<li><a href="http://en.wikipedia.org/wiki/McASP">McASP</a></li>
+<li><a href="http://en.wikipedia.org/wiki/SLIMbus">SLIMbus</a></li>
+<li><a href="http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus">SPI</a></li>
+</ul>
+
+<h3 id="signalTerms">Audio Signal Path</h3>
+
+<p>
+Audio signal path terms relate to the signal path that audio data follows from
+an application to the transducer or vice-versa.
+</p>
+
+<dl>
+
+<dt>ADC</dt>
+<dd>
+Analog-to-digital converter. Module that converts an analog signal (continuous
+in time and amplitude) to a digital signal (discrete in time and amplitude).
+Conceptually, an ADC consists of a periodic sample-and-hold followed by a
+quantizer, although it does not have to be implemented that way. An ADC is
+usually preceded by a low-pass filter to remove any high frequency components
+that are not representable using the desired sample rate. For details, refer to
+<a href="http://en.wikipedia.org/wiki/Analog-to-digital_converter">Analog-to-digital
+converter</a>.
+</dd>
+
+<dt>AP</dt>
+<dd>
+Application processor. Main general-purpose computer on a mobile device.
+</dd>
+
+<dt>codec</dt>
+<dd>
+Coder-decoder. Module that encodes and/or decodes an audio signal from one
+representation to another (typically analog to PCM or PCM to analog). In strict
+terms, <em>codec</em> is reserved for modules that both encode and decode but
+can be used loosely to refer to only one of these. For details, refer to
+<a href="http://en.wikipedia.org/wiki/Audio_codec">Audio codec</a>.
+</dd>
+
+<dt>DAC</dt>
+<dd>
+Digital-to-analog converter. Module that converts a digital signal (discrete in
+time and amplitude) to an analog signal (continuous in time and amplitude).
+Often followed by a low-pass filter to remove high-frequency components
+introduced by digital quantization. For details, refer to
+<a href="http://en.wikipedia.org/wiki/Digital-to-analog_converter">Digital-to-analog
+converter</a>.
+</dd>
+
+<dt>DSP</dt>
+<dd>
+Digital Signal Processor. Optional component typically located after the
+application processor (for output) or before the application processor (for
+input). Primary purpose is to off-load the application processor and provide
+signal processing features at a lower power cost.
+</dd>
+
+<dt>PDM</dt>
+<dd>
+Pulse-density modulation. Form of modulation used to represent an analog signal
+by a digital signal, where the relative density of 1s versus 0s indicates the
+signal level. Commonly used by digital to analog converters. For details, refer
+to <a href="http://en.wikipedia.org/wiki/Pulse-density_modulation">Pulse-density
+modulation</a>.
+</dd>
+
+<dt>PWM</dt>
+<dd>
+Pulse-width modulation. Form of modulation used to represent an analog signal by
+a digital signal, where the relative width of a digital pulse indicates the
+signal level. Commonly used by analog-to-digital converters. For details, refer
+to <a href="http://en.wikipedia.org/wiki/Pulse-width_modulation">Pulse-width
+modulation</a>.
+</dd>
+
+<dt>transducer</dt>
+<dd>
+Converts variations in physical real-world quantities to electrical signals. In
+audio, the physical quantity is sound pressure, and the transducers are the
+loudspeaker and microphone. For details, refer to
+<a href="http://en.wikipedia.org/wiki/Transducer">Transducer</a>.
+</dd>
+
+</dl>
+
+<h3 id="srcTerms">Sample Rate Conversion</h3>
+<p>
+Sample rate conversion terms relate to the process of converting from one
+sampling rate to another.
+</p>
+
+<dl>
+
+<dt>downsample</dt>
+<dd>Resample, where sink sample rate < source sample rate.</dd>
+
+<dt>Nyquist frequency</dt>
+<dd>
+Maximum frequency component that can be represented by a discretized signal at
+1/2 of a given sample rate. For example, the human hearing range extends to
+approximately 20 kHz, so a digital audio signal must have a sample rate of at
+least 40 kHz to represent that range. In practice, sample rates of 44.1 kHz and
+48 kHz are commonly used, with Nyquist frequencies of 22.05 kHz and 24 kHz
+respectively. For details, refer to
+<a href="http://en.wikipedia.org/wiki/Nyquist_frequency">Nyquist frequency</a>
+and
+<a href="http://en.wikipedia.org/wiki/Hearing_range">Hearing range</a>.
+</dd>
+
+<dt>resampler</dt>
+<dd>Synonym for sample rate converter.</dd>
+
+<dt>resampling</dt>
+<dd>Process of converting sample rate.</dd>
+
+<dt>sample rate converter</dt>
+<dd>Module that resamples.</dd>
+
+<dt>sink</dt>
+<dd>Output of a resampler.</dd>
+
+<dt>source</dt>
+<dd>Input to a resampler.</dd>
+
+<dt>upsample</dt>
+<dd>Resample, where sink sample rate > source sample rate.</dd>
+
+</dl>
+
+<h2 id="androidSpecificTerms">Android-Specific Terms</h2>
+
+<p>
+Android-specific terms include terms used only in the Android audio framework
+and generic terms that have special meaning within Android.
+</p>
+
+<dl>
+
+<dt>ALSA</dt>
+<dd>
+Advanced Linux Sound Architecture. An audio framework for Linux that has also
+influenced other systems. For a generic definition, refer to
+<a href="http://en.wikipedia.org/wiki/Advanced_Linux_Sound_Architecture">ALSA</a>.
+In Android, ALSA refers to the kernel audio framework and drivers and not to the
+user-mode API. See also <em>tinyalsa</em>.
+</dd>
+
+<dt>audio device</dt>
+<dd>
+Audio I/O endpoint backed by a HAL implementation.
+</dd>
+
+<dt>AudioEffect</dt>
+<dd>
+API and implementation framework for output (post-processing) effects and input
+(pre-processing) effects. The API is defined at
+<a href="http://developer.android.com/reference/android/media/audiofx/AudioEffect.html">android.media.audiofx.AudioEffect</a>.
+</dd>
+
+<dt>AudioFlinger</dt>
+<dd>
+Android sound server implementation. AudioFlinger runs within the mediaserver
+process. For a generic definition, refer to
+<a href="http://en.wikipedia.org/wiki/Sound_server">Sound server</a>.
+</dd>
+
+<dt>audio focus</dt>
+<dd>
+Set of APIs for managing audio interactions across multiple independent apps.
+For details, see <a href="http://developer.android.com/training/managing-audio/audio-focus.html">Managing Audio Focus</a> and the focus-related methods and constants of
+<a href="http://developer.android.com/reference/android/media/AudioManager.html">android.media.AudioManager</a>.
+</dd>
+
+<dt>AudioMixer</dt>
+<dd>
+Module in AudioFlinger responsible for combining multiple tracks and applying
+attenuation (volume) and effects. For a generic definition, refer to
+<a href="http://en.wikipedia.org/wiki/Audio_mixing_(recorded_music)">Audio mixing (recorded music)</a> (discusses a mixer as a hardware device or software application, rather
+than a software module within a system).
+</dd>
+
+<dt>audio policy</dt>
+<dd>
+Service responsible for all actions that require a policy decision to be made
+first, such as opening a new I/O stream, re-routing after a change, and stream
+volume management.
+</dd>
+
+<dt>AudioRecord</dt>
+<dd>
+Primary low-level client API for receiving data from an audio input device such
+as a microphone. The data is usually PCM format. The API is defined at
+<a href="http://developer.android.com/reference/android/media/AudioRecord.html">android.media.AudioRecord</a>.
+</dd>
+
+<dt>AudioResampler</dt>
+<dd>
+Module in AudioFlinger responsible for <a href="src.html">sample rate conversion</a>.
+</dd>
+
+<dt>audio source</dt>
+<dd>
+An enumeration of constants that indicates the desired use case for capturing
+audio input. For details, see <a href="http://developer.android.com/reference/android/media/MediaRecorder.AudioSource.html">audio source</a>. As of API level 21 and above,
+<a href="attributes.html">audio attributes</a> are preferred.
+</dd>
+
+<dt>AudioTrack</dt>
+<dd>
+Primary low-level client API for sending data to an audio output device such as
+a speaker. The data is usually in PCM format. The API is defined at
+<a href="http://developer.android.com/reference/android/media/AudioTrack.html">android.media.AudioTrack</a>.
+</dd>
+
+<dt>audio_utils</dt>
+<dd>
+Audio utility library for features such as PCM format conversion, WAV file I/O,
+and
+<a href="avoiding_pi.html#nonBlockingAlgorithms">non-blocking FIFO</a>, which is
+largely independent of the Android platform.
+</dd>
+
+<dt>client</dt>
+<dd>
+Usually an application or app client. However, an AudioFlinger client can be a
+thread running within the mediaserver system process, such as when playing media
+decoded by a MediaPlayer object.
+</dd>
+
+<dt>HAL</dt>
+<dd>
+Hardware Abstraction Layer. HAL is a generic term in Android; in audio, it is a
+layer between AudioFlinger and the kernel device driver with a C API (which
+replaces the C++ libaudio).
+</dd>
+
+<dt>FastCapture</dt>
+<dd>
+Thread within AudioFlinger that sends audio data to lower latency fast tracks
+and drives the input device when configured for reduced latency.
+</dd>
+
+<dt>FastMixer</dt>
+<dd>
+Thread within AudioFlinger that receives and mixes audio data from lower latency
+fast tracks and drives the primary output device when configured for reduced
+latency.
+</dd>
+
+<dt>fast track</dt>
+<dd>
+AudioTrack or AudioRecord client with lower latency but fewer features on some
+devices and routes.
+</dd>
+
+<dt>MediaPlayer</dt>
+<dd>
+Higher-level client API than AudioTrack. Plays encoded content or content that
+includes multimedia audio and video tracks.
+</dd>
+
+<dt>media.log</dt>
+<dd>
+AudioFlinger debugging feature available in custom builds only. Used for logging
+audio events to a circular buffer where they can then be retroactively dumped
+when needed.
+</dd>
+
+<dt>mediaserver</dt>
+<dd>
+Android system process that contains media-related services, including
+AudioFlinger.
+</dd>
+
+<dt>NBAIO</dt>
+<dd>
+Non-blocking audio input/output. Abstraction for AudioFlinger ports. The term
+can be misleading as some implementations of the NBAIO API support blocking. The
+key implementations of NBAIO are for different types of pipes.
+</dd>
+
+<dt>normal mixer</dt>
+<dd>
+Thread within AudioFlinger that services most full-featured AudioTrack clients.
+Directly drives an output device or feeds its sub-mix into FastMixer via a pipe.
+</dd>
+
+<dt>OpenSL ES</dt>
+<dd>
+Audio API standard by
+<a href="http://www.khronos.org/">The Khronos Group</a>. Android versions since
+API level 9 support a native audio API that is based on a subset of
+<a href="http://www.khronos.org/opensles/">OpenSL ES 1.0.1</a>.
+</dd>
+
+<dt>silent mode</dt>
+<dd>
+User-settable feature to mute the phone ringer and notifications without
+affecting media playback (music, videos, games) or alarms.
+</dd>
+
+<dt>SoundPool</dt>
+<dd>
+Higher-level client API than AudioTrack. Plays sampled audio clips. Useful for
+triggering UI feedback, game sounds, etc. The API is defined at
+<a href="http://developer.android.com/reference/android/media/SoundPool.html">android.media.SoundPool</a>.
+</dd>
+
+<dt>Stagefright</dt>
+<dd>
+See <a href="{@docRoot}devices/media.html">Media</a>.
+</dd>
+
+<dt>StateQueue</dt>
+<dd>
+Module within AudioFlinger responsible for synchronizing state among threads.
+Whereas NBAIO is used to pass data, StateQueue is used to pass control
+information.
+</dd>
+
+<dt>strategy</dt>
+<dd>
+Group of stream types with similar behavior. Used by the audio policy service.
+</dd>
+
+<dt>stream type</dt>
+<dd>
+Enumeration that expresses a use case for audio output. The audio policy
+implementation uses the stream type, along with other parameters, to determine
+volume and routing decisions. For a list of stream types, see
+<a href="http://developer.android.com/reference/android/media/AudioManager.html">android.media.AudioManager</a>.
+</dd>
+
+<dt>tee sink</dt>
+<dd>
+See <a href="debugging.html#teeSink">Audio Debugging</a>.
+</dd>
+
+<dt>tinyalsa</dt>
+<dd>
+Small user-mode API above ALSA kernel with BSD license. Recommended for HAL
+implementations.
+</dd>
+
+<dt>ToneGenerator</dt>
+<dd>
+Higher-level client API than AudioTrack. Plays dual-tone multi-frequency (DTMF)
+signals. For details, refer to
+<a href="http://en.wikipedia.org/wiki/Dual-tone_multi-frequency_signaling">Dual-tone
+multi-frequency signaling</a> and the API definition at
+<a href="http://developer.android.com/reference/android/media/ToneGenerator.html">android.media.ToneGenerator</a>.
+</dd>
+
+<dt>track</dt>
+<dd>
+Audio stream. Controlled by the AudioTrack or AudioRecord API.
+</dd>
+
+<dt>volume attenuation curve</dt>
+<dd>
+Device-specific mapping from a generic volume index to a specific attenuation
+factor for a given output.
+</dd>
+
+<dt>volume index</dt>
+<dd>
+Unitless integer that expresses the desired relative volume of a stream. The
+volume-related APIs of
+<a href="http://developer.android.com/reference/android/media/AudioManager.html">android.media.AudioManager</a>
+operate in volume indices rather than absolute attenuation factors.
+</dd>
+
+</dl>
\ No newline at end of file
diff --git a/src/devices/testing_circuit.jd b/src/devices/audio/testing_circuit.jd
similarity index 84%
rename from src/devices/testing_circuit.jd
rename to src/devices/audio/testing_circuit.jd
index 7d672f3..995062d 100644
--- a/src/devices/testing_circuit.jd
+++ b/src/devices/audio/testing_circuit.jd
@@ -1,8 +1,8 @@
-page.title=Testing Circuit
+page.title=Light Testing Circuit
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2014 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.
@@ -29,7 +29,7 @@
contains CAD files for an A/V sync and latency testing
printed circuit board (PCB).
The files include a fabrication drawing, EAGLE CAD, schematic, and BOM. See <a
-href="audio_latency.html">Audio Latency</a> for recommended testing methods.
+href="latency.html">Audio Latency</a> for recommended testing methods.
</p>
<p>
@@ -64,17 +64,21 @@
These photos show the circuit in action.
</p>
-<img style="margin:1.5em auto" src="images/breadboard.jpg" alt="breadboard prototype" />
-<br />
-<center>Breadboard prototype</center>
+<img style="margin:1.5em auto" src="images/breadboard.jpg" alt="breadboard prototype" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> Breadboard prototype
+</p>
-<img style="margin:1.5em auto" src="images/pcb.jpg" alt="an early run of the PCB" />
-<br />
-<center>An early run of the PCB</center>
+<img style="margin:1.5em auto" src="images/pcb.jpg" alt="an early run of the PCB" id="figure2" />
+<p class="img-caption">
+ <strong>Figure 2.</strong> An early run of the PCB
+</p>
-<img style="margin:1.5em auto" src="images/display.jpg" alt="example display">
-<br />
-<center>Example display</center>
+<img style="margin:1.5em auto" src="images/display.jpg" alt="example display" id="figure3" />
+<p class="img-caption">
+ <strong>Figure 3.</strong> Example display
+</p>
+
<p>
This image
shows the scope display for an unspecified device, software release, and test conditions;
diff --git a/src/devices/audio_tv.jd b/src/devices/audio/tv.jd
similarity index 96%
rename from src/devices/audio_tv.jd
rename to src/devices/audio/tv.jd
index 4bcb55e..bf60884 100644
--- a/src/devices/audio_tv.jd
+++ b/src/devices/audio/tv.jd
@@ -36,7 +36,7 @@
<p>The TIF then uses AudioPort information for the audio routing API.</p>
-<p><img src="audio/images/ape_audio_tv_tif.png" alt="Android TV Input Framework (TIF)" />
+<p><img src="images/ape_audio_tv_tif.png" alt="Android TV Input Framework (TIF)" />
<p class="img-caption"><strong>Figure 1.</strong> TV Input Framework (TIF)</p>
<h2 id="Requirements">Requirements</h2>
@@ -274,23 +274,23 @@
<p>This section includes common use cases for TV audio.</p>
-<h3>TV tuner with speaker output</h3>
+<h3 id="tvSpeaker">TV tuner with speaker output</h3>
<p>When a TV tuner becomes active, the audio routing API creates an audio patch between the tuner
and the default output (e.g. the speaker). The tuner output does not require decoding, but final
audio output is mixed with software output_stream.</p>
-<p><img src="audio/images/ape_audio_tv_tuner.png" alt="Android TV Tuner Audio Patch" />
+<p><img src="images/ape_audio_tv_tuner.png" alt="Android TV Tuner Audio Patch" />
<p class="img-caption">
<strong>Figure 2.</strong> Audio Patch for TV tuner with speaker output.</p>
-<h3>HDMI OUT during live TV</h3>
+<h3 id="hdmiOut">HDMI OUT during live TV</h3>
<p>A user is watching live TV then switches to the HDMI audio output (Intent.ACTION_HDMI_AUDIO_PLUG)
. The output device of all output_streams changes to the HDMI_OUT port, and the TIF manager changes
the sink port of the existing tuner audio patch to the HDMI_OUT port.</p>
-<p><p><img src="audio/images/ape_audio_tv_hdmi_tuner.png" alt="Android TV HDMI-OUT Audio Patch" />
+<p><p><img src="images/ape_audio_tv_hdmi_tuner.png" alt="Android TV HDMI-OUT Audio Patch" />
<p class="img-caption">
-<strong>Figure 3.</strong> Audio Patch for HDMI OUT from live TV.</p>
\ No newline at end of file
+<strong>Figure 3.</strong> Audio Patch for HDMI OUT from live TV.</p>
diff --git a/src/devices/audio_usb.jd b/src/devices/audio/usb.jd
similarity index 92%
rename from src/devices/audio_usb.jd
rename to src/devices/audio/usb.jd
index 8e8fdaf..b885f60 100644
--- a/src/devices/audio_usb.jd
+++ b/src/devices/audio/usb.jd
@@ -38,7 +38,10 @@
</p>
<p>
-End users should see the <a href="https://support.google.com/android/">Help Center</a> instead.
+End users of Nexus devices should see the article
+<a href="https://support.google.com/nexus/answer/6127700">Record and play back audio using USB host mode</a>
+at the
+<a href="https://support.google.com/nexus/">Nexus Help Center</a> instead.
Though this article is not oriented towards end users,
certain audiophile consumers may find portions of interest.
</p>
@@ -151,7 +154,11 @@
such as this is usually required:
</p>
-<img src="audio/images/otg.jpg" style="image-orientation: 90deg;" height="50%" width="50%" alt="OTG">
+<img src="images/otg.jpg" style="image-orientation: 90deg;" height="50%" width="50%" alt="OTG" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> On-the-go (OTG) adapter
+</p>
+
<p>
An Android device might not provide sufficient power to operate a
@@ -162,7 +169,10 @@
<a href="http://en.wikipedia.org/wiki/USB_hub">hub</a> such as this:
</p>
-<img src="audio/images/hub.jpg" alt="Powered hub">
+<img src="images/hub.jpg" alt="Powered hub" id="figure2" />
+<p class="img-caption">
+ <strong>Figure 2.</strong> Powered hub
+</p>
<h3 id="accessoryMode">Accessory mode</h3>
@@ -434,7 +444,10 @@
also with headphones.
</p>
-<img src="audio/images/dac.png" alt="DAC comparison">
+<img src="images/dac.png" alt="DAC comparison" id="figure3" />
+<p class="img-caption">
+ <strong>Figure 3.</strong> Comparison of two DACs
+</p>
<p>
Which design is better? The answer depends on your needs.
@@ -476,7 +489,7 @@
from the USB controllers.
</p>
-<h3 id="applications">Applications</h3>
+<h3 id="hostApplications">Host mode applications</h3>
<p>
Typical USB host mode audio applications include:
@@ -504,6 +517,16 @@
<a href="http://developer.android.com/tools/index.html">Settings / Developer Options</a>.
</p>
+<h3 id="hostDebugging">Debugging while in host mode</h3>
+
+<p>
+While in USB host mode, adb debugging over USB is unavailable.
+See section <a href="http://developer.android.com/tools/help/adb.html#wireless">Wireless usage</a>
+of
+<a href="http://developer.android.com/tools/help/adb.html">Android Debug Bridge</a>
+for an alternative.
+</p>
+
<h2 id="compatibility">Implementing USB audio</h2>
<h3 id="recommendationsPeripheral">Recommendations for audio peripheral vendors</h3>
@@ -528,13 +551,18 @@
</p>
<ul>
-<li>enable all kernel features needed: USB host mode, USB audio, isochronous transfer mode</li>
+<li>design hardware to support USB host mode</li>
+<li>enable generic USB host support at the framework level
+via the <code>android.hardware.usb.host.xml</code> feature flag</li>
+<li>enable all kernel features needed: USB host mode, USB audio, isochronous transfer mode;
+see <a href="{@docRoot}devices/tech/kernel.html">Android Kernel Configuration</a></li>
<li>keep up-to-date with recent kernel releases and patches;
despite the noble goal of class compliance, there are extant audio peripherals
with <a href="http://en.wiktionary.org/wiki/quirk">quirks</a>,
and recent kernels have workarounds for such quirks
</li>
<li>enable USB audio policy as described below</li>
+<li>add audio.usb.default to PRODUCT_PACKAGES in device.mk</li>
<li>test for inter-operability with common USB audio peripherals</li>
</ul>
@@ -592,7 +620,7 @@
implementation for USB audio is located here:
<pre>hardware/libhardware/modules/usbaudio/</pre>
The USB audio HAL relies heavily on
-<i>tinyalsa</i>, described at <a href="audio_terminology.html">Audio Terminology</a>.
+<i>tinyalsa</i>, described at <a href="terminology.html">Audio Terminology</a>.
Though USB audio relies on isochronous transfers,
this is abstracted away by the ALSA implementation.
So the USB audio HAL and tinyalsa do not need to concern
diff --git a/src/devices/audio_warmup.jd b/src/devices/audio/warmup.jd
similarity index 100%
rename from src/devices/audio_warmup.jd
rename to src/devices/audio/warmup.jd
diff --git a/src/devices/audio_latency.jd b/src/devices/audio_latency.jd
deleted file mode 100644
index 25865bc..0000000
--- a/src/devices/audio_latency.jd
+++ /dev/null
@@ -1,144 +0,0 @@
-page.title=Audio Latency
-@jd:body
-
-<!--
- Copyright 2013 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.
--->
-<div id="qv-wrapper">
- <div id="qv">
- <h2>In this document</h2>
- <ol id="auto-toc">
- </ol>
- </div>
-</div>
-
-<p>Audio latency is the time delay as an audio signal passes through a system.
- For a complete description of audio latency for the purposes of Android
- compatibility, see <em>Section 5.5 Audio Latency</em>
- in the <a href="http://source.android.com/compatibility/index.html">Android CDD</a>.
- See <a href="latency_design.html">Design For Reduced Latency</a> for an
- understanding of Android's audio latency-reduction efforts.
-</p>
-
-<p>
- This page focuses on the contributors to output latency,
- but a similar discussion applies to input latency.
-</p>
-<p>
- Assuming the analog circuitry does not contribute significantly, then the major
-surface-level contributors to audio latency are the following:
-</p>
-
-<ul>
- <li>Application</li>
- <li>Total number of buffers in pipeline</li>
- <li>Size of each buffer, in frames</li>
- <li>Additional latency after the app processor, such as from a DSP</li>
-</ul>
-
-<p>
- As accurate as the above list of contributors may be, it is also misleading.
- The reason is that buffer count and buffer size are more of an
- <em>effect</em> than a <em>cause</em>. What usually happens is that
- a given buffer scheme is implemented and tested, but during testing, an audio
- underrun is heard as a "click" or "pop." To compensate, the
- system designer then increases buffer sizes or buffer counts.
- This has the desired result of eliminating the underruns, but it also
- has the undesired side effect of increasing latency.
-</p>
-
-<p>
- A better approach is to understand the causes of the
- underruns and then correct those. This eliminates the
- audible artifacts and may even permit even smaller or fewer buffers
- and thus reduce latency.
-</p>
-
-<p>
- In our experience, the most common causes of underruns include:
-</p>
-<ul>
- <li>Linux CFS (Completely Fair Scheduler)</li>
- <li>high-priority threads with SCHED_FIFO scheduling</li>
- <li>long scheduling latency</li>
- <li>long-running interrupt handlers</li>
- <li>long interrupt disable time</li>
-</ul>
-
-<h3>Linux CFS and SCHED_FIFO scheduling</h3>
-<p>
- The Linux CFS is designed to be fair to competing workloads sharing a common CPU
- resource. This fairness is represented by a per-thread <em>nice</em> parameter.
- The nice value ranges from -19 (least nice, or most CPU time allocated)
- to 20 (nicest, or least CPU time allocated). In general, all threads with a given
- nice value receive approximately equal CPU time and threads with a
- numerically lower nice value should expect to
- receive more CPU time. However, CFS is "fair" only over relatively long
- periods of observation. Over short-term observation windows,
- CFS may allocate the CPU resource in unexpected ways. For example, it
- may take the CPU away from a thread with numerically low niceness
- onto a thread with a numerically high niceness. In the case of audio,
- this can result in an underrun.
-</p>
-
-<p>
- The obvious solution is to avoid CFS for high-performance audio
- threads. Beginning with Android 4.1, such threads now use the
- <code>SCHED_FIFO</code> scheduling policy rather than the <code>SCHED_NORMAL</code> (also called
- <code>SCHED_OTHER</code>) scheduling policy implemented by CFS.
-</p>
-
-<p>
- Though the high-performance audio threads now use <code>SCHED_FIFO</code>, they
- are still susceptible to other higher priority <code>SCHED_FIFO</code> threads.
- These are typically kernel worker threads, but there may also be a few
- non-audio user threads with policy <code>SCHED_FIFO</code>. The available <code>SCHED_FIFO</code>
- priorities range from 1 to 99. The audio threads run at priority
- 2 or 3. This leaves priority 1 available for lower priority threads,
- and priorities 4 to 99 for higher priority threads. We recommend
- you use priority 1 whenever possible, and reserve priorities 4 to 99 for
- those threads that are guaranteed to complete within a bounded amount
- of time and are known to not interfere with scheduling of audio threads.
-</p>
-
-<h3>Scheduling latency</h3>
-<p>
- Scheduling latency is the time between when a thread becomes
- ready to run, and when the resulting context switch completes so that the
- thread actually runs on a CPU. The shorter the latency the better, and
- anything over two milliseconds causes problems for audio. Long scheduling
- latency is most likely to occur during mode transitions, such as
- bringing up or shutting down a CPU, switching between a security kernel
- and the normal kernel, switching from full power to low-power mode,
- or adjusting the CPU clock frequency and voltage.
-</p>
-
-<h3>Interrupts</h3>
-<p>
- In many designs, CPU 0 services all external interrupts. So a
- long-running interrupt handler may delay other interrupts, in particular
- audio direct memory access (DMA) completion interrupts. Design interrupt handlers
- to finish quickly and defer any lengthy work to a thread (preferably
- a CFS thread or <code>SCHED_FIFO</code> thread of priority 1).
-</p>
-
-<p>
- Equivalently, disabling interrupts on CPU 0 for a long period
- has the same result of delaying the servicing of audio interrupts.
- Long interrupt disable times typically happen while waiting for a kernel
- <i>spin lock</i>. Review these spin locks to ensure that
- they are bounded.
-</p>
-
diff --git a/src/devices/audio_terminology.jd b/src/devices/audio_terminology.jd
deleted file mode 100644
index 753d402..0000000
--- a/src/devices/audio_terminology.jd
+++ /dev/null
@@ -1,649 +0,0 @@
-page.title=Audio Terminology
-@jd:body
-
-<!--
- Copyright 2014 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.
--->
-<div id="qv-wrapper">
- <div id="qv">
- <h2>In this document</h2>
- <ol id="auto-toc">
- </ol>
- </div>
-</div>
-
-<p>
-This document provides a glossary of audio-related terminology, including
-a list of widely used, generic terms and a list of terms that are specific
-to Android.
-</p>
-
-<h2 id="genericTerm">Generic Terms</h2>
-
-<p>
-These are audio terms that are widely used, with their conventional meanings.
-</p>
-
-<h3 id="digitalAudioTerms">Digital Audio</h3>
-
-<dl>
-
-<dt>acoustics</dt>
-<dd>
-The study of the mechanical properties of sound, for example how the
-physical placement of transducers such as speakers and microphones on
-a device affects perceived audio quality.
-</dd>
-
-<dt>attenuation</dt>
-<dd>
-A multiplicative factor less than or equal to 1.0,
-applied to an audio signal to decrease the signal level.
-Compare to "gain".
-</dd>
-
-<dt>bits per sample or bit depth</dt>
-<dd>
-Number of bits of information per sample.
-</dd>
-
-<dt>channel</dt>
-<dd>
-A single stream of audio information, usually corresponding to one
-location of recording or playback.
-</dd>
-
-<dt>downmixing</dt>
-<dd>
-To decrease the number of channels, e.g. from stereo to mono, or from 5.1 to stereo.
-This can be accomplished by dropping some channels, mixing channels, or more advanced signal processing.
-Simple mixing without attenuation or limiting has the potential for overflow and clipping.
-Compare to "upmixing".
-</dd>
-
-<dt>duck</dt>
-<dd>
-To temporarily reduce the volume of one stream, when another stream
-becomes active. For example, if music is playing and a notification arrives,
-then the music stream could be ducked while the notification plays.
-Compare to "mute".
-</dd>
-
-<dt>frame</dt>
-<dd>
-A set of samples, one per channel, at a point in time.
-</dd>
-
-<dt>frames per buffer</dt>
-<dd>
-The number of frames handed from one module to the next at once;
-for example the audio HAL interface uses this concept.
-</dd>
-
-<dt>gain</dt>
-<dd>
-A multiplicative factor greater than or equal to 1.0,
-applied to an audio signal to increase the signal level.
-Compare to "attenuation".
-</dd>
-
-<dt>Hz</dt>
-<dd>
-The units for sample rate or frame rate.
-</dd>
-
-<dt>latency</dt>
-<dd>
-Time delay as a signal passes through a system.
-</dd>
-
-<dt>mono</dt>
-<dd>
-One channel.
-</dd>
-
-<dt>multichannel</dt>
-<dd>
-See "surround sound".
-Strictly, since stereo is more than one channel, it is also "multi" channel.
-But that usage would be confusing.
-</dd>
-
-<dt>mute</dt>
-<dd>
-To (temporarily) force volume to be zero, independently from the usual volume controls.
-</dd>
-
-<dt>PCM</dt>
-<dd>
-Pulse Code Modulation, the most common low-level encoding of digital audio.
-The audio signal is sampled at a regular interval, called the sample rate,
-and then quantized to discrete values within a particular range depending on the bit depth.
-For example, for 16-bit PCM, the sample values are integers between -32768 and +32767.
-</dd>
-
-<dt>ramp</dt>
-<dd>
-To gradually increase or decrease the level of a particular audio parameter,
-for example volume or the strength of an effect.
-A volume ramp is commonly applied when pausing and resuming music, to avoid a hard audible transition.
-</dd>
-
-<dt>sample</dt>
-<dd>
-A number representing the audio value for a single channel at a point in time.
-</dd>
-
-<dt>sample rate or frame rate</dt>
-<dd>
-Number of frames per second;
-note that "frame rate" is thus more accurate,
-but "sample rate" is conventionally used to mean "frame rate."
-</dd>
-
-<dt>sonification</dt>
-<dd>
-The use of sound to express feedback or information,
-for example touch sounds and keyboard sounds.
-</dd>
-
-<dt>stereo</dt>
-<dd>
-Two channels.
-</dd>
-
-<dt>stereo widening</dt>
-<dd>
-An effect applied to a stereo signal, to make another stereo signal which sounds fuller and richer.
-The effect can also be applied to a mono signal, in which case it is a type of upmixing.
-</dd>
-
-<dt>surround sound</dt>
-<dd>
-Various techniques for increasing the ability of a listener to perceive
-sound position beyond stereo left and right.
-</dd>
-
-<dt>upmixing</dt>
-<dd>
-To increase the number of channels, e.g. from mono to stereo, or from stereo to surround sound.
-This can be accomplished by duplication, panning, or more advanced signal processing.
-Compare to "downmixing".
-</dd>
-
-<dt>virtualizer</dt>
-<dd>
-An effect that attempts to spatialize audio channels, such as trying to
-simulate more speakers, or give the illusion that various sound sources have position.
-</dd>
-
-<dt>volume</dt>
-<dd>
-Loudness, the subjective strength of an audio signal.
-</dd>
-
-</dl>
-
-<h3 id="hardwareTerms">Hardware and Accessories</h3>
-
-<p>
-These terms are related to audio hardware and accessories.
-</p>
-
-<h4 id="interDeviceTerms">Inter-device interconnect</h4>
-
-<p>
-These technologies connect audio and video components between devices,
-and are readily visible at the external connectors. The HAL implementor
-may need to be aware of these, as well as the end user.
-</p>
-
-<dl>
-
-<dt>Bluetooth</dt>
-<dd>
-A short range wireless technology.
-The major audio-related
-<a href="http://en.wikipedia.org/wiki/Bluetooth_profile">Bluetooth profiles</a>
-and
-<a href="http://en.wikipedia.org/wiki/Bluetooth_protocols">Bluetooth protocols</a>
-are described at these Wikipedia articles:
-
-<ul>
-
-<li><a href="http://en.wikipedia.org/wiki/Bluetooth_profile#Advanced_Audio_Distribution_Profile_.28A2DP.29">A2DP</a>
-for music
-</li>
-
-<li><a href="http://en.wikipedia.org/wiki/Bluetooth_protocols#Synchronous_connection-oriented_.28SCO.29_link">SCO</a>
-for telephony
-</li>
-
-</ul>
-
-</dd>
-
-<dt>DisplayPort</dt>
-<dd>
-Digital display interface by VESA.
-</dd>
-
-<dt>HDMI</dt>
-<dd>
-High-Definition Multimedia Interface, an interface for transferring
-audio and video data. For mobile devices, either a micro-HDMI (type D) or MHL connector is used.
-</dd>
-
-<dt>MHL</dt>
-<dd>
-Mobile High-Definition Link is a mobile audio/video interface, often
-over micro-USB connector.
-</dd>
-
-<dt>phone connector</dt>
-<dd>
-A mini or sub-mini phone connector
-connects a device to wired headphones, headset, or line-level amplifier.
-</dd>
-
-<dt>SlimPort</dt>
-<dd>
-An adapter from micro-USB to HDMI.
-</dd>
-
-<dt>S/PDIF</dt>
-<dd>
-Sony/Philips Digital Interface Format is an interconnect for uncompressed PCM.
-See Wikipedia article <a href="http://en.wikipedia.org/wiki/S/PDIF">S/PDIF</a>.
-</dd>
-
-<dt>USB</dt>
-<dd>
-Universal Serial Bus.
-See Wikipedia article <a href="http://en.wikipedia.org/wiki/USB">USB</a>.
-</dd>
-
-</dl>
-
-<h4 id="intraDeviceTerms">Intra-device interconnect</h4>
-
-<p>
-These technologies connect internal audio components within a given
-device, and are not visible without disassembling the device. The HAL
-implementor may need to be aware of these, but not the end user.
-</p>
-
-See these Wikipedia articles:
-<ul>
-<li><a href="http://en.wikipedia.org/wiki/General-purpose_input/output">GPIO</a></li>
-<li><a href="http://en.wikipedia.org/wiki/I%C2%B2C">I²C</a></li>
-<li><a href="http://en.wikipedia.org/wiki/I%C2%B2S">I²S</a></li>
-<li><a href="http://en.wikipedia.org/wiki/McASP">McASP</a></li>
-<li><a href="http://en.wikipedia.org/wiki/SLIMbus">SLIMbus</a></li>
-<li><a href="http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus">SPI</a></li>
-</ul>
-
-<h3 id="signalTerms">Audio Signal Path</h3>
-
-<p>
-These terms are related to the signal path that audio data follows from
-an application to the transducer, or vice-versa.
-</p>
-
-<dl>
-
-<dt>ADC</dt>
-<dd>
-Analog to digital converter, a module that converts an analog signal
-(continuous in both time and amplitude) to a digital signal (discrete in
-both time and amplitude). Conceptually, an ADC consists of a periodic
-sample-and-hold followed by a quantizer, although it does not have to
-be implemented that way. An ADC is usually preceded by a low-pass filter
-to remove any high frequency components that are not representable using
-the desired sample rate. See Wikipedia article
-<a href="http://en.wikipedia.org/wiki/Analog-to-digital_converter">Analog-to-digital_converter</a>.
-</dd>
-
-<dt>AP</dt>
-<dd>
-Application processor, the main general-purpose computer on a mobile device.
-</dd>
-
-<dt>codec</dt>
-<dd>
-Coder-decoder, a module that encodes and/or decodes an audio signal
-from one representation to another. Typically this is analog to PCM, or PCM to analog.
-Strictly, the term "codec" is reserved for modules that both encode and decode,
-however it can also more loosely refer to only one of these.
-See Wikipedia article
-<a href="http://en.wikipedia.org/wiki/Audio_codec">Audio codec</a>.
-</dd>
-
-<dt>DAC</dt>
-<dd>
-Digital to analog converter, a module that converts a digital signal
-(discrete in both time and amplitude) to an analog signal
-(continuous in both time and amplitude). A DAC is usually followed by
-a low-pass filter to remove any high frequency components introduced
-by digital quantization.
-See Wikipedia article
-<a href="http://en.wikipedia.org/wiki/Digital-to-analog_converter">Digital-to-analog converter</a>.
-</dd>
-
-<dt>DSP</dt>
-<dd>
-Digital Signal Processor, an optional component which is typically located
-after the application processor (for output), or before the application processor (for input).
-The primary purpose of a DSP is to off-load the application processor,
-and provide signal processing features at a lower power cost.
-</dd>
-
-<dt>PDM</dt>
-<dd>
-Pulse-density modulation
-is a form of modulation used to represent an analog signal by a digital signal,
-where the relative density of 1s versus 0s indicates the signal level.
-It is commonly used by digital to analog converters.
-See Wikipedia article
-<a href="http://en.wikipedia.org/wiki/Pulse-density_modulation">Pulse-density modulation</a>.
-</dd>
-
-<dt>PWM</dt>
-<dd>
-Pulse-width modulation
-is a form of modulation used to represent an analog signal by a digital signal,
-where the relative width of a digital pulse indicates the signal level.
-It is commonly used by analog to digital converters.
-See Wikipedia article
-<a href="http://en.wikipedia.org/wiki/Pulse-width_modulation">Pulse-width modulation</a>.
-</dd>
-
-</dl>
-
-<h3 id="srcTerms">Sample Rate Conversion</h3>
-
-<dl>
-
-<dt>downsample</dt>
-<dd>To resample, where sink sample rate < source sample rate.</dd>
-
-<dt>Nyquist frequency</dt>
-<dd>
-The Nyquist frequency, equal to 1/2 of a given sample rate, is the
-maximum frequency component that can be represented by a discretized
-signal at that sample rate. For example, the human hearing range is
-typically assumed to extend up to approximately 20 kHz, and so a digital
-audio signal must have a sample rate of at least 40 kHz to represent that
-range. In practice, sample rates of 44.1 kHz and 48 kHz are commonly
-used, with Nyquist frequencies of 22.05 kHz and 24 kHz respectively.
-See
-<a href="http://en.wikipedia.org/wiki/Nyquist_frequency" target="_android">Nyquist frequency</a>
-and
-<a href="http://en.wikipedia.org/wiki/Hearing_range" target="_android">Hearing range</a>
-for more information.
-</dd>
-
-<dt>resampler</dt>
-<dd>Synonym for sample rate converter.</dd>
-
-<dt>resampling</dt>
-<dd>The process of converting sample rate.</dd>
-
-<dt>sample rate converter</dt>
-<dd>A module that resamples.</dd>
-
-<dt>sink</dt>
-<dd>The output of a resampler.</dd>
-
-<dt>source</dt>
-<dd>The input to a resampler.</dd>
-
-<dt>upsample</dt>
-<dd>To resample, where sink sample rate > source sample rate.</dd>
-
-</dl>
-
-<h2 id="androidSpecificTerms">Android-Specific Terms</h2>
-
-<p>
-These are terms specific to the Android audio framework, or that
-may have a special meaning within Android beyond their general meaning.
-</p>
-
-<dl>
-
-<dt>ALSA</dt>
-<dd>
-Advanced Linux Sound Architecture. As the name suggests, it is an audio
-framework primarily for Linux, but it has influenced other systems.
-See Wikipedia article
-<a href="http://en.wikipedia.org/wiki/Advanced_Linux_Sound_Architecture">ALSA</a>
-for the general definition. As used within Android, it refers primarily
-to the kernel audio framework and drivers, not to the user-mode API. See
-tinyalsa.
-</dd>
-
-<dt>AudioEffect</dt>
-<dd>
-An API and implementation framework for output (post-processing) effects
-and input (pre-processing) effects. The API is defined at
-<a href="http://developer.android.com/reference/android/media/audiofx/AudioEffect.html">android.media.audiofx.AudioEffect</a>.
-</dd>
-
-<dt>AudioFlinger</dt>
-<dd>
-The sound server implementation for Android. AudioFlinger
-runs within the mediaserver process. See Wikipedia article
-<a href="http://en.wikipedia.org/wiki/Sound_server">Sound server</a>
-for the generic definition.
-</dd>
-
-<dt>audio focus</dt>
-<dd>
-A set of APIs for managing audio interactions across multiple independent apps.
-See <a href="http://developer.android.com/training/managing-audio/audio-focus.html">Managing Audio
-Focus</a> and the focus-related methods and constants of
-<a href="http://developer.android.com/reference/android/media/AudioManager.html">android.media.AudioManager</a>.
-</dd>
-
-<dt>AudioMixer</dt>
-<dd>
-The module within AudioFlinger responsible for
-combining multiple tracks and applying attenuation
-(volume) and certain effects. The Wikipedia article
-<a href="http://en.wikipedia.org/wiki/Audio_mixing_(recorded_music)">Audio mixing (recorded music)</a>
-may be useful for understanding the generic
-concept. But that article describes a mixer more as a hardware device
-or a software application, rather than a software module within a system.
-</dd>
-
-<dt>audio policy</dt>
-<dd>
-Service responsible for all actions that require a policy decision
-to be made first, such as opening a new I/O stream, re-routing after a
-change and stream volume management.
-</dd>
-
-<dt>AudioRecord</dt>
-<dd>
-The primary low-level client API for receiving data from an audio
-input device such as microphone. The data is usually in pulse-code modulation
-(PCM) format.
-The API is defined at
-<a href="http://developer.android.com/reference/android/media/AudioRecord.html">android.media.AudioRecord</a>.
-</dd>
-
-<dt>AudioResampler</dt>
-<dd>
-The module within AudioFlinger responsible for
-<a href="audio_src.html">sample rate conversion</a>.
-</dd>
-
-<dt>AudioTrack</dt>
-<dd>
-The primary low-level client API for sending data to an audio output
-device such as a speaker. The data is usually in PCM format.
-The API is defined at
-<a href="http://developer.android.com/reference/android/media/AudioTrack.html">android.media.AudioTrack</a>.
-</dd>
-
-<dt>client</dt>
-<dd>
-Usually same as application or app, but sometimes the "client" of
-AudioFlinger is actually a thread running within the mediaserver system
-process. An example of that is when playing media that is decoded by a
-MediaPlayer object.
-</dd>
-
-<dt>HAL</dt>
-<dd>
-Hardware Abstraction Layer. HAL is a generic term in Android. With
-respect to audio, it is a layer between AudioFlinger and the kernel
-device driver with a C API, which replaces the earlier C++ libaudio.
-</dd>
-
-<dt>FastMixer</dt>
-<dd>
-A thread within AudioFlinger that services lower latency "fast tracks"
-and drives the primary output device.
-</dd>
-
-<dt>fast track</dt>
-<dd>
-An AudioTrack client with lower latency but fewer features, on some devices.
-</dd>
-
-<dt>MediaPlayer</dt>
-<dd>
-A higher-level client API than AudioTrack, for playing either encoded
-content, or content which includes multimedia audio and video tracks.
-</dd>
-
-<dt>media.log</dt>
-<dd>
-An AudioFlinger debugging feature, available in custom builds only,
-for logging audio events to a circular buffer where they can then be
-dumped retroactively when needed.
-</dd>
-
-<dt>mediaserver</dt>
-<dd>
-An Android system process that contains a number of media-related
-services, including AudioFlinger.
-</dd>
-
-<dt>NBAIO</dt>
-<dd>
-An abstraction for "non-blocking" audio input/output ports used within
-AudioFlinger. The name can be misleading, as some implementations of
-the NBAIO API actually do support blocking. The key implementations of
-NBAIO are for pipes of various kinds.
-</dd>
-
-<dt>normal mixer</dt>
-<dd>
-A thread within AudioFlinger that services most full-featured
-AudioTrack clients, and either directly drives an output device or feeds
-its sub-mix into FastMixer via a pipe.
-</dd>
-
-<dt>OpenSL ES</dt>
-<dd>
-An audio API standard by The Khronos Group. Android versions since
-API level 9 support a native audio API which is based on a subset of
-OpenSL ES 1.0.1.
-</dd>
-
-<dt>silent mode</dt>
-<dd>
-A user-settable feature to mute the phone ringer and notifications,
-without affecting media playback (music, videos, games) or alarms.
-</dd>
-
-<dt>SoundPool</dt>
-<dd>
-A higher-level client API than AudioTrack, used for playing sampled
-audio clips. It is useful for triggering UI feedback, game sounds, etc.
-The API is defined at
-<a href="http://developer.android.com/reference/android/media/SoundPool.html">android.media.SoundPool</a>.
-</dd>
-
-<dt>Stagefright</dt>
-<dd>
-See <a href="{@docRoot}devices/media.html">Media</a>.
-</dd>
-
-<dt>StateQueue</dt>
-<dd>
-A module within AudioFlinger responsible for synchronizing state
-among threads. Whereas NBAIO is used to pass data, StateQueue is used
-to pass control information.
-</dd>
-
-<dt>strategy</dt>
-<dd>
-A grouping of stream types with similar behavior, used by the audio policy service.
-</dd>
-
-<dt>stream type</dt>
-<dd>
-An enumeration that expresses a use case for audio output.
-The audio policy implementation uses the stream type, along with other parameters,
-to determine volume and routing decisions.
-Specific stream types are listed at
-<a href="http://developer.android.com/reference/android/media/AudioManager.html">android.media.AudioManager</a>.
-</dd>
-
-<dt>tee sink</dt>
-<dd>
-See the separate article on tee sink in
-<a href="audio_debugging.html#teeSink">Audio Debugging</a>.
-</dd>
-
-<dt>tinyalsa</dt>
-<dd>
-A small user-mode API above ALSA kernel with BSD license, recommended
-for use in HAL implementations.
-</dd>
-
-<dt>ToneGenerator</dt>
-<dd>
-A higher-level client API than AudioTrack, used for playing DTMF signals.
-See the Wikipedia article
-<a href="http://en.wikipedia.org/wiki/Dual-tone_multi-frequency_signaling">Dual-tone multi-frequency signaling</a>,
-and the API definition at
-<a href="http://developer.android.com/reference/android/media/ToneGenerator.html">android.media.ToneGenerator</a>.
-</dd>
-
-<dt>track</dt>
-<dd>
-An audio stream, controlled by the AudioTrack API.
-</dd>
-
-<dt>volume attenuation curve</dt>
-<dd>
-A device-specific mapping from a generic volume index to a particular attenuation factor
-for a given output.
-</dd>
-
-<dt>volume index</dt>
-<dd>
-A unitless integer that expresses the desired relative volume of a stream.
-The volume-related APIs of
-<a href="http://developer.android.com/reference/android/media/AudioManager.html">android.media.AudioManager</a>
-operate in volume indices rather than absolute attenuation factors.
-</dd>
-
-</dl>
diff --git a/src/devices/bluetooth.jd b/src/devices/bluetooth.jd
index 62cf79d..8677b7d 100644
--- a/src/devices/bluetooth.jd
+++ b/src/devices/bluetooth.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -24,27 +24,32 @@
</div>
</div>
+<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_bluetooth.png" alt="Android Bluetooth HAL icon"/>
-<p>Android provides a default Bluetooth stack, BlueDroid, that is divided into two layers: The Bluetooth Embedded System (BTE), which implements the core
-Bluetooth functionality and the Bluetooth Application Layer (BTA), which communicates
-with Android framework applications. A Bluetooth system service communicates with the Bluetooth stack through JNI and with applications through
-Binder IPC. The system service provides developers access to various Bluetooth profiles. The following
-diagram shows the general structure of the Bluetooth stack:
+<p>Android provides a default Bluetooth stack, BlueDroid, that is divided into two layers: The Bluetooth Embedded System (BTE), which implements the core Bluetooth functionality and the Bluetooth Application Layer (BTA), which communicates with Android framework applications.</p>
+
+<p>To fully leverage the <a href="http://developer.android.com/about/versions/android-5.0.html#BluetoothBroadcasting">Bluetooth Low Energy APIs</a> added in Android 5.0, you should implement the <a href="Android-5.0-Bluetooth-HCI-Reqs.pdf">Android 5.0 Bluetooth HCI Requirements</a>.</p>
+
+<h2 id="architecture">Architecture</h2>
+<p>A Bluetooth system service communicates with the Bluetooth stack through JNI and with applications through Binder IPC. The system service provides developers access to various Bluetooth profiles. The following diagram shows the general structure of the Bluetooth stack:
</p>
-<p><img src="images/bt.png"></p>
+<img src="images/ape_fwk_bluetooth.png" alt="Android Bluetooth architecture" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> Bluetooth architecture
+</p>
<dl>
<dt>Application framework</dt>
<dd>At the application framework level is the app's code, which utilizes the <a
href="http://developer.android.com/reference/android/bluetooth/package-summary.html">android.bluetooth</a>
- APIs to interact with the bluetooth hardware. Internally, this code calls the Bluetooth process through
+ APIs to interact with the Bluetooth hardware. Internally, this code calls the Bluetooth process through
the Binder IPC mechanism.</dd>
<dt>Bluetooth system service</dt>
<dd>The Bluetooth system service, located in <code>packages/apps/Bluetooth</code>, is packaged as an Android
app and implements the Bluetooth service and profiles at the Android framework layer. This app
- calls into the HAL layer via JNI.</p>
+ calls into the HAL layer via JNI.</dd>
<dt>JNI</dt>
<dd>The JNI code associated with <a
@@ -56,7 +61,7 @@
<dt>HAL</dt>
<dd>The hardware abstraction layer defines the standard interface that the <a
href="http://developer.android.com/reference/android/bluetooth/package-summary.html">android.bluetooth</a> APIs
- and Bluetooth process calls into and that you must implement to have your bluetooth hardware
+ and Bluetooth process calls into and that you must implement to have your Bluetooth hardware
function correctly. The header files for the Bluetooth HAL is located
in the <code>hardware/libhardware/include/hardware/bluetooth.h</code> and
<code>hardware/libhardware/include/hardware/bt_*.h</code> files.
@@ -77,21 +82,22 @@
<h2 id="implementing">Implementing the HAL</h2>
-<p>The Bluetooth HAL is located in the <code>hardware/libhardware/include/hardware/</code> directory
- and consists of the following header files:
+<p>The Bluetooth HAL is located in the <code>hardware/libhardware/include/hardware/</code> directory. Please see that directory for the <strong>complete set</strong> of files, which include but are not limited to the following:
+</p>
<ul>
- <li><code>bluetooth.h</code>: Contains the HAL for the Bluetooth hardware on the device</li>
- <li><code>bt_av.h</code>: Contains the HAL for the advanced audio profile.</li>
- <li><code>bt_hf.h</code>: Contains the HAL for the handsfree profile.</li>
- <li><code>bt_hh.h</code>: Contains the HAL for the HID host profile</li>
- <li><code>bt_hl.h</code>: Contains the HAL for the health profile</li>
- <li><code>bt_pan.h</code>: Contains the HAL for the pan profile</li>
- <li><code>bt_sock.h</code>: Contains the HAL for the socket profile.</li>
+ <li><code>bluetooth.h</code>: Includes the interface definition for the Bluetooth hardware on the device.</li>
+ <li><code>bt_av.h</code>: Includes the interface definition for the A2DP profile.</li>
+ <li><code>bt_gatt.h</code>, <code>bt_gatt_client.h</code>, and <code>bt_gatt_server.h</code>: These include the interface definition for the GATT profile.</li>
+ <li><code>bt_hf.h</code>: Includes the interface definition for the HFP profile.</li>
+ <li><code>bt_hh.h</code>: Includes the interface definition for the HID host profile.</li>
+ <li><code>bt_hl.h</code>: Includes the interface definition for the HDP profile.</li>
+ <li><code>bt_mce.h</code>: Includes the interface definition for the MAP profile.</li>
+ <li><code>bt_pan.h</code>: Includes the interface definition for the PAN profile.</li>
+ <li><code>bt_rc.h</code>: Includes the interface definition for the AVRCP profile.</li>
+ <li><code>bt_sock.h</code>: Includes the interface definition for RFCOMM sockets.</li>
</ul>
-</p>
-
<p>Keep in mind that your Bluetooth implementation is not constrained to the features
and profiles exposed in the HAL. You can find the default implementation located
in the BlueDroid Bluetooth stack in the <code>external/bluetooth/bluedroid</code> directory,
diff --git a/src/devices/camera/camera3.jd b/src/devices/camera/camera3.jd
index 4d4d3a1..9811a98 100644
--- a/src/devices/camera/camera3.jd
+++ b/src/devices/camera/camera3.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2014 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.
@@ -67,9 +67,11 @@
<p>Each mode has slightly different and overlapping capabilities. This made it hard
to implement new types of features, such as burst mode, since it would fall
-between two of these modes.<br/>
-<img src="images/camera_block.png" alt="Camera block diagram"/><br/>
-<strong>Figure 1.</strong> Camera components</p>
+between two of these modes.</p>
+<img src="images/camera_block.png" alt="Camera block diagram" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> Camera components
+</p>
<h2 id="v3-enhance">Version 3 enhancements</h2>
@@ -122,8 +124,10 @@
request can be one-shot ( with capture() ), or it may be repeated indefinitely
(with setRepeatingRequest() ). Captures have priority over repeating
requests.</p>
-<img src="images/camera_simple_model.png" alt="Camera data model"/>
-<p><strong>Figure 2.</strong> Camera core operation model</p>
+<img src="images/camera_simple_model.png" alt="Camera data model" id="figure2" />
+<p class="img-caption">
+ <strong>Figure 2.</strong> Camera core operation model
+</p>
<h2 id="supported-version">Supported version</h2>
@@ -134,52 +138,3 @@
version 2.0 of the camera module interface (as defined by
camera_module_t.common.module_api_version).<br/>
See camera_common.h for more versioning details.</p>
-
-<h2 id="version-history">Version history</h2>
-
-<h4><strong>1.0</strong></h4>
-
-<p>Initial Android camera HAL (Android 4.0) [camera.h]:</p>
-
-<ul>
-<li>Converted from C++ CameraHardwareInterface abstraction layer.</li>
-<li>Supports android.hardware.Camera API.</li>
-</ul>
-
-<h4><strong>2.0</strong></h4>
-
-<p>Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:</p>
-
-<ul>
-<li>Sufficient for implementing existing android.hardware.Camera API.</li>
-<li>Allows for ZSL queue in camera service layer</li>
-<li>Not tested for any new features such manual capture control, Bayer RAW
-capture, reprocessing of RAW data.</li>
-</ul>
-
-<h4><strong>3.0</strong></h4>
-
-<p>First revision of expanded-capability HAL:</p>
-
-<ul>
-<li>Major version change since the ABI is completely different. No change to the
-required hardware capabilities or operational model from 2.0.</li>
-<li>Reworked input request and stream queue interfaces: Framework calls into HAL
-with next request and stream buffers already dequeued. Sync framework support
-is included, necessary for efficient implementations.</li>
-<li>Moved triggers into requests, most notifications into results.</li>
-<li>Consolidated all callbacks into framework into one structure, and all setup
-methods into a single initialize() call.</li>
-<li>Made stream configuration into a single call to simplify stream management.
-Bidirectional streams replace STREAM_FROM_STREAM construct.</li>
-<li>Limited mode semantics for older/limited hardware devices.</li>
-</ul>
-
-<h4><strong>3.1</strong></h4>
-
-<p>Minor revision of expanded-capability HAL:</p>
-
-<ul>
-<li>configure_streams passes consumer usage flags to the HAL.</li>
-<li>flush call to drop all in-flight requests/buffers as fast as possible.</li>
-</ul>
diff --git a/src/devices/camera/camera3_crop_reprocess.jd b/src/devices/camera/camera3_crop_reprocess.jd
index e617e1e..dd9f9c1 100644
--- a/src/devices/camera/camera3_crop_reprocess.jd
+++ b/src/devices/camera/camera3_crop_reprocess.jd
@@ -96,27 +96,38 @@
</p>
Crop region: (500, 375, 1000, 750) (4:3 aspect ratio)<br/>
640x480 stream crop: (500, 375, 1000, 750) (equal to crop region)<br/>
- 1280x720 stream crop: (500, 469, 1000, 562)<br/>
- <img src="images/crop-region-43-ratio.png" alt="crop-region-43-ratio"/>
+ 1280x720 stream crop: (500, 469, 1000, 562)
+</p>
+ <img src="images/crop-region-43-ratio.png" alt="crop-region-43-ratio" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> 4:3 aspect ratio
</p>
<p>Crop region: (500, 375, 1333, 750) (16:9 aspect ratio)<br/>
640x480 stream crop: (666, 375, 1000, 750)<br/>
- 1280x720 stream crop: (500, 375, 1333, 750) (equal to crop region)<br/>
- <img src="images/crop-region-169-ratio.png" alt="crop-region-169-ratio"/>
- <!-- TODO: Fix alt text and URL -->
+ 1280x720 stream crop: (500, 375, 1333, 750) (equal to crop region)
+</p>
+ <img src="images/crop-region-169-ratio.png" alt="crop-region-169-ratio" id="figure2" />
+<p class="img-caption">
+ <strong>Figure 2.</strong> 16:9 aspect ratio
</p>
<p>Crop region: (500, 375, 750, 750) (1:1 aspect ratio)<br/>
640x480 stream crop: (500, 469, 750, 562)<br/>
- 1280x720 stream crop: (500, 543, 750, 414)<br/>
- <img src="images/crop-region-11-ratio.png" alt="crop-region-11-ratio"/>
- <br/>
+ 1280x720 stream crop: (500, 543, 750, 414)
+</p>
+ <img src="images/crop-region-11-ratio.png" alt="crop-region-11-ratio" id="figure3" />
+<p class="img-caption">
+ <strong>Figure 3.</strong> 1:1 aspect ratio
+</p>
+<p>
And a final example, a 1024x1024 square aspect ratio stream instead of the 480p
stream:<br/>
Crop region: (500, 375, 1000, 750) (4:3 aspect ratio)<br/>
1024x1024 stream crop: (625, 375, 750, 750)<br/>
- 1280x720 stream crop: (500, 469, 1000, 562)<br/>
- <img src="images/crop-region-43-square-ratio.png"
-alt="crop-region-43-square-ratio"/>
+ 1280x720 stream crop: (500, 469, 1000, 562)
+</p>
+ <img src="images/crop-region-43-square-ratio.png" alt="crop-region-43-square-ratio" id="figure4" />
+<p class="img-caption">
+ <strong>Figure 4.</strong> 4:3 aspect ratio, square
</p>
<h2 id="reprocessing">Reprocessing</h2>
<p> Additional support for raw image files is provided by reprocessing support for RAW Bayer
diff --git a/src/devices/camera/camera3_requests_hal.jd b/src/devices/camera/camera3_requests_hal.jd
index 9bd4f28..9700063 100644
--- a/src/devices/camera/camera3_requests_hal.jd
+++ b/src/devices/camera/camera3_requests_hal.jd
@@ -34,9 +34,10 @@
output and processing. Multiple requests can be in flight at once, and
submitting requests is non-blocking. And the requests are always processed in
the order they are received.<br/>
- <img src="images/camera_model.png" alt="Camera request model"/>
- <br/>
- <strong>Figure 3.</strong> Camera model</p>
+ <img src="images/camera_model.png" alt="Camera request model" id="figure1" />
+ <p class="img-caption">
+ <strong>Figure 1.</strong> Camera model
+</p>
<h2 id="hal-subsystem">The HAL and camera subsystem</h2>
<p> The camera subsystem includes the implementations for components in the camera
pipeline such as the 3A algorithm and processing controls. The camera HAL
@@ -51,9 +52,10 @@
The camera pipeline also supports triggers that the app framework can initiate
to turn on things such as auto-focus. It also sends notifications back to the
app framework, notifying apps of events such as an auto-focus lock or errors.<br/>
- <img src="images/camera_hal.png" alt="Camera hardware abstraction layer"/>
- <br/>
- <strong>Figure 4.</strong> Camera pipeline<br/>
+ <img src="images/camera_hal.png" alt="Camera hardware abstraction layer" id="figure2" />
+ <p class="img-caption">
+ <strong>Figure 2.</strong> Camera pipeline
+ </p>
Please note, some image processing blocks shown in the diagram above are not
well-defined in the initial release.<br/>
The camera pipeline makes the following assumptions:</p>
@@ -92,9 +94,10 @@
<li>All capture configuration and state (except for the 3A routines) is
encapsulated in the requests and results.</li>
</ul>
-<p><img src="images/camera-hal-overview.png" alt="Camera HAL overview"/>
- <br/>
- <strong>Figure 5.</strong> Camera HAL overview</p>
+<img src="images/camera-hal-overview.png" alt="Camera HAL overview" id="figure3" />
+<p class="img-caption">
+ <strong>Figure 3.</strong> Camera HAL overview
+</p>
<h2 id="startup">Startup and expected operation sequence</h2>
<p>This section contains a detailed explanation of the steps expected when using
the camera API. Please see <a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/camera3.h">platform/hardware/libhardware/include/hardware/camera3.h</a> for definitions of these structures and methods.</p>
@@ -162,9 +165,10 @@
-ENODEV or NULL after the notify() method returns from a fatal error
message.</li>
</ol>
-<p><img src="images/camera-ops-flow.png" width="600" height="434" alt="Camera operations flow" />
+<img src="images/camera-ops-flow.png" width="600" height="434" alt="Camera operations flow" id="figure4" />
+<p class="img-caption">
+ <strong>Figure 4.</strong> Camera operational flow
</p>
-<p><strong>Figure 6.</strong> Camera operational flow</p>
<h2 id="ops-modes">Operational modes</h2>
<p>The camera 3 HAL device can implement one of two possible operational modes:
limited and full. Full support is expected from new higher-end devices. Limited
diff --git a/src/devices/camera/images/ape_fwk_camera.png b/src/devices/camera/images/ape_fwk_camera.png
new file mode 100644
index 0000000..102461e
--- /dev/null
+++ b/src/devices/camera/images/ape_fwk_camera.png
Binary files differ
diff --git a/src/devices/camera/images/ape_fwk_hal_camera.png b/src/devices/camera/images/ape_fwk_hal_camera.png
new file mode 100644
index 0000000..c8dc558
--- /dev/null
+++ b/src/devices/camera/images/ape_fwk_hal_camera.png
Binary files differ
diff --git a/src/devices/camera/camera.jd b/src/devices/camera/index.jd
similarity index 90%
rename from src/devices/camera/camera.jd
rename to src/devices/camera/index.jd
index a1e837f..1e5cab8 100644
--- a/src/devices/camera/camera.jd
+++ b/src/devices/camera/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -24,12 +24,19 @@
</div>
</div>
-<p>Android's camera HAL connects the higher level
-camera framework APIs in <a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> to your underlying camera driver and hardware.
-The following figure and list describe the components involved and where to find the source for each:
+<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_camera.png" alt="Android Camera HAL icon"/>
+
+<p>Android's camera Hardware Abstraction Layer (HAL) connects the higher level
+camera framework APIs in <a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> to your underlying camera driver and hardware. The camera subsystem includes implementations for camera pipeline components while the camera HAL provides interfaces for use in implementing your version of these components.</p>
+
+<h2 id="architecture">Architecture</h2>
+<p>The following figure and list describe the components involved and where to find the source for each:
</p>
-<p><img src="images/camera_hal.png"></p>
+<img src="images/ape_fwk_camera.png" alt="Android camera architecture" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> Camera architecture
+</p>
<dl>
diff --git a/src/devices/camera/versioning.jd b/src/devices/camera/versioning.jd
index 9f97ce3..7c4d1b3 100644
--- a/src/devices/camera/versioning.jd
+++ b/src/devices/camera/versioning.jd
@@ -130,3 +130,70 @@
Camera HAL and would also be a bug that could be easily hit by existing Camera
API1 apps. The expectation is that there should be very few bugs of this
nature. Nevertheless, any such bugs will need to be fixed.</p>
+
+<h2 id="version-history">Version history</h2>
+
+<h3 id="32">3.2</h3>
+
+<p>Second revision of expanded-capability HAL:</p>
+
+<ul>
+<li>Deprecates get_metadata_vendor_tag_ops. Please use get_vendor_tag_ops in
+camera_common.h instead.</li>
+<li>register_stream_buffers deprecated. All gralloc buffers provided by
+framework to HAL in process_capture_request may be new at any time.</li>
+<li>Add partial result support. process_capture_result may be called multiple
+times with a subset of the available result before the full result is available.</li>
+<li>Add manual template to camera3_request_template. The applications may use
+this template to control the capture settings directly.</li>
+<li>Rework the bidirectional and input stream specifications.</li>
+<li>Change the input buffer return path. The buffer is returned in
+process_capture_result instead of process_capture_request.</li>
+</ul>
+
+<h3 id="31">3.1</h3>
+
+<p>Minor revision of expanded-capability HAL:</p>
+
+<ul>
+<li>configure_streams passes consumer usage flags to the HAL.</li>
+<li>flush call to drop all in-flight requests/buffers as fast as possible.</li>
+</ul>
+
+<h3 id="30">3.0</h3>
+
+<p>First revision of expanded-capability HAL:</p>
+
+<ul>
+<li>Major version change since the ABI is completely different. No change to the
+required hardware capabilities or operational model from 2.0.</li>
+<li>Reworked input request and stream queue interfaces: Framework calls into HAL
+with next request and stream buffers already dequeued. Sync framework support
+is included, necessary for efficient implementations.</li>
+<li>Moved triggers into requests, most notifications into results.</li>
+<li>Consolidated all callbacks into framework into one structure, and all setup
+methods into a single initialize() call.</li>
+<li>Made stream configuration into a single call to simplify stream management.
+Bidirectional streams replace STREAM_FROM_STREAM construct.</li>
+<li>Limited mode semantics for older/limited hardware devices.</li>
+</ul>
+
+<h3 id="20">2.0</h3>
+
+<p>Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:</p>
+
+<ul>
+<li>Sufficient for implementing existing android.hardware.Camera API.</li>
+<li>Allows for ZSL queue in camera service layer</li>
+<li>Not tested for any new features such manual capture control, Bayer RAW
+capture, reprocessing of RAW data.</li>
+</ul>
+
+<h3 id="10">1.0</strong></h3>
+
+<p>Initial Android camera HAL (Android 4.0) [camera.h]:</p>
+
+<ul>
+<li>Converted from C++ CameraHardwareInterface abstraction layer.</li>
+<li>Supports android.hardware.Camera API.</li>
+</ul>
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 8a5353f..45ddd70 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -1,5 +1,5 @@
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 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.
@@ -15,9 +15,7 @@
-->
<?cs # Table of contents for devices.?>
<ul id="nav">
-
-<!-- Porting Android -->
- <li class="nav-section">
+ <li class="nav-section"> <!-- Begin nav section, Device Interfaces -->
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/index.html">
<span class="en">Interfaces</span>
@@ -26,38 +24,41 @@
<ul>
<li class="nav-section">
<div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/audio.html">
+ <a href="<?cs var:toroot ?>devices/audio/index.html">
<span class="en">Audio</span>
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/audio_terminology.html">Terminology</a></li>
- <li><a href="<?cs var:toroot ?>devices/audio_implement.html">Implementation</a></li>
- <li><a href="<?cs var:toroot ?>devices/audio_attributes.html">Attributes</a></li>
- <li><a href="<?cs var:toroot ?>devices/audio_warmup.html">Warmup</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/terminology.html">Terminology</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/implement.html">Implementation</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/attributes.html">Attributes</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/warmup.html">Warmup</a></li>
<li class="nav-section">
<div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/audio_latency.html">
+ <a href="<?cs var:toroot ?>devices/audio/latency.html">
<span class="en">Latency</span>
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/audio_latency_measure.html">Measure</a></li>
- <li><a href="<?cs var:toroot ?>devices/latency_design.html">Design</a></li>
- <li><a href="<?cs var:toroot ?>devices/testing_circuit.html">Testing Circuit</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/latency_contrib.html">Contributors</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/latency_design.html">Design</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/latency_measure.html">Measure</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/testing_circuit.html">Light Testing Circuit</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/loopback.html">Audio Loopback Dongle</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/latency_measurements.html">Measurements</a></li>
</ul>
</li>
- <li><a href="<?cs var:toroot ?>devices/audio_avoiding_pi.html">Priority Inversion</a></li>
- <li><a href="<?cs var:toroot ?>devices/audio_src.html">Sample Rate Conversion</a></li>
- <li><a href="<?cs var:toroot ?>devices/audio_debugging.html">Debugging</a></li>
- <li><a href="<?cs var:toroot ?>devices/audio_usb.html">USB Digital Audio</a></li>
- <li><a href="<?cs var:toroot ?>devices/audio_tv.html">TV Audio</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/avoiding_pi.html">Priority Inversion</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/src.html">Sample Rate Conversion</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/debugging.html">Debugging</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/usb.html">USB Digital Audio</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/tv.html">TV Audio</a></li>
</ul>
</li>
<li><a href="<?cs var:toroot ?>devices/bluetooth.html">Bluetooth</a></li>
<li class="nav-section">
<div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/camera/camera.html">
+ <a href="<?cs var:toroot ?>devices/camera/index.html">
<span class="en">Camera</span>
</a>
</div>
@@ -76,99 +77,77 @@
<li><a href="<?cs var:toroot ?>devices/drm.html">DRM</a></li>
<li class="nav-section">
<div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/tech/storage/index.html">
+ <a href="<?cs var:toroot ?>devices/storage/index.html">
<span class="en">External Storage</span>
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/tech/storage/config.html">Device Specific Configuration</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/storage/config-example.html">Typical Configuration Examples</a></li>
+ <li><a href="<?cs var:toroot ?>devices/storage/config.html">Device Specific Configuration</a></li>
+ <li><a href="<?cs var:toroot ?>devices/storage/config-example.html">Typical Configuration Examples</a></li>
</ul>
</li>
<li class="nav-section">
<div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/graphics.html">
+ <a href="<?cs var:toroot ?>devices/graphics/index.html">
<span class="en">Graphics</span>
</a>
</div>
<ul>
<li><a href="<?cs var:toroot ?>devices/graphics/architecture.html">Architecture</a></li>
<li><a href="<?cs var:toroot ?>devices/graphics/implement.html">Implementation</a></li>
- </ul>
- </li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/graphics/testing.html">
+ <span class="en">OpenGL ES Testing</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/graphics/build-tests.html">Building test programs</a></li>
+ <li><a href="<?cs var:toroot ?>devices/graphics/port-tests.html">Porting the test framework</a></li>
+ <li><a href="<?cs var:toroot ?>devices/graphics/run-tests.html">Running the tests</a></li>
+ <li><a href="<?cs var:toroot ?>devices/graphics/automate-tests.html">Automating the tests</a></li>
+ <li><a href="<?cs var:toroot ?>devices/graphics/test-groups.html">Using special test groups</a></li>
+ <li><a href="<?cs var:toroot ?>devices/graphics/cts-integration.html">Integrating with Android CTS</a></li>
+ </ul>
+ </li>
+ </ul> </li>
<li class="nav-section">
<div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/tech/input/index.html">
+ <a href="<?cs var:toroot ?>devices/input/index.html">
<span class="en">Input</span>
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/tech/input/overview.html">Overview</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/input/key-layout-files.html">Key Layout Files</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/input/key-character-map-files.html">Key Character Map Files</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/input/input-device-configuration-files.html">Input Device Configuration Files</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/input/migration-guide.html">Migration Guide</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/input/keyboard-devices.html">Keyboard Devices</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/input/touch-devices.html">Touch Devices</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/input/dumpsys.html">Dumpsys</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/input/getevent.html">Getevent</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/input/validate-keymaps.html">Validate Keymaps</a></li>
+ <li><a href="<?cs var:toroot ?>devices/input/overview.html">Overview</a></li>
+ <li><a href="<?cs var:toroot ?>devices/input/key-layout-files.html">Key Layout Files</a></li>
+ <li><a href="<?cs var:toroot ?>devices/input/key-character-map-files.html">Key Character Map Files</a></li>
+ <li><a href="<?cs var:toroot ?>devices/input/input-device-configuration-files.html">Input Device Configuration Files</a></li>
+ <li><a href="<?cs var:toroot ?>devices/input/migration-guide.html">Migration Guide</a></li>
+ <li><a href="<?cs var:toroot ?>devices/input/keyboard-devices.html">Keyboard Devices</a></li>
+ <li><a href="<?cs var:toroot ?>devices/input/touch-devices.html">Touch Devices</a></li>
+ <li><a href="<?cs var:toroot ?>devices/input/diagnostics.html">Diagnostics</a></li>
+ <li><a href="<?cs var:toroot ?>devices/input/getevent.html">Getevent</a></li>
+ <li><a href="<?cs var:toroot ?>devices/input/validate-keymaps.html">Validate Keymaps</a></li>
</ul>
</li>
<li><a href="<?cs var:toroot ?>devices/media.html">Media</a></li>
- <li class="nav-section">
- <div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/sensors/index.html">
- <span class="en">Sensors</span>
- </a>
- </div>
- <ul>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/sensor-stack.html">
- <span class="en">Sensor stack</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/report-modes.html">
- <span class="en">Reporting modes</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/suspend-mode.html">
- <span class="en">Suspend mode</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/power-use.html">
- <span class="en">Power consumption</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/interaction.html">
- <span class="en">Interaction</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/hal-interface.html">
- <span class="en">HAL interface</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/batching.html">
- <span class="en">Batching</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/sensor-types.html">
- <span class="en">Sensor types</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/versioning.html">
- <span class="en">Version deprecation</span>
- </a>
- </li>
- </ul>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/sensors/index.html">
+ <span class="en">Sensors</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/sensors/sensor-stack.html">Sensor stack</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/report-modes.html">Reporting modes</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/suspend-mode.html">Suspend mode</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/power-use.html">Power consumption</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/interaction.html">Interaction</span></a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/hal-interface.html">HAL interface</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/batching.html">Batching</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/sensor-types.html">Sensor types</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/versioning.html">Version deprecation</a></li>
+ </ul>
</li>
<li class="nav-section">
<div class="nav-section-header">
@@ -180,14 +159,11 @@
<li><a href="<?cs var:toroot ?>devices/tv/HDMI-CEC.html">HDMI-CEC control service</a></li>
</ul>
</li>
-
</ul>
- </li>
-<!-- End Porting Android -->
- </li>
+ </li> <!-- End nav-section, Device Interfaces-->
- <li class="nav-section">
+ <li class="nav-section"> <!--Begin nav-section, Core Technologies-->
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/index.html">
<span class="en">Core Technologies</span>
@@ -204,6 +180,8 @@
<li><a href="<?cs var:toroot ?>devices/tech/dalvik/dalvik-bytecode.html">Bytecode Format</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/dalvik/dex-format.html">.Dex Format</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/dalvik/instruction-formats.html">Instruction Formats</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/dalvik/constraints.html">Constraints</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/dalvik/configure.html">Configuration</a></li>
</ul>
</li>
@@ -225,13 +203,14 @@
</li>
<li class="nav-section">
<div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/debugtune.html">
+ <a href="<?cs var:toroot ?>devices/tech/debug/index.html">
<span class="en">Debugging and Tuning</span>
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/tuning.html">Performance Tuning</a></li>
- <li><a href="<?cs var:toroot ?>devices/native-memory.html">Native Memory Usage</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/debug/tuning.html">Performance Tuning</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/debug/native-memory.html">Native Memory Usage</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/debug/dumpsys.html">Dumpsys</a></li>
</ul>
</li>
@@ -243,80 +222,115 @@
</div>
</li>
- <li>
- <a href="<?cs var:toroot ?>devices/tech/kernel.html">
- <span class="en">Kernel</span>
- </a>
+ <li><a href="<?cs var:toroot ?>devices/tech/kernel.html">Kernel</a></li>
+
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tech/ram/index.html">
+ <span class="en">RAM</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/ram/low-ram.html">Low RAM</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/ram/procstats.html">Viewing RAM Usage Data</a></li>
+ </ul>
</li>
- <li>
- <a href="<?cs var:toroot ?>devices/low-ram.html">
- <span class="en">Low RAM</span>
- </a>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tech/ota/index.html">
+ <span class="en">OTA Updates</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/ota/tools.html">OTA Tools</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/ota/block.html">Block-based OTA</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/ota/inside_packages.html">Inside OTA Packages</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/ota/device_code.html">Device-Specific Code</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/ota/sign_builds.html">Signing Builds for Release</a></li>
+ </ul>
</li>
- <li>
- <a href="<?cs var:toroot ?>devices/tech/power.html">
- <span class="en">Power</span>
- </a>
+ <li><a href="<?cs var:toroot ?>devices/tech/netstats.html">Viewing Network Data</a></li>
+
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tech/power/index.html"><span class="en">Power</span></a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/power/batterystats.html">Viewing Battery Usage Data</a></li>
+ </ul>
</li>
- <li class="nav-section">
- <div class="nav-section-header">
+ <li class="nav-section">
+ <div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/security/index.html">
<span class="en">Security</span>
</a>
- </div>
+ </div>
<ul>
- <li>
- <a href="<?cs var:toroot ?>devices/tech/security/acknowledgements.html">
- <span class="en">Acknowledgements</span>
- </a>
- </li>
<li class="nav-section">
<div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/tech/security/enhancements.html">
- <span class="en">Enhancements</span>
+ <a href="<?cs var:toroot ?>devices/tech/security/overview/index.html">
+ <span class="en">Overview</span>
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements50.html">Android 5.0</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements44.html">Android 4.4</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements43.html">Android 4.3</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements42.html">Android 4.2</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/overview/kernel-security.html">Kernel security</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/overview/app-security.html">App security</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/overview/updates-resources.html">Updates and resources</a></li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tech/security/enhancements/index.html">
+ <span class="en">Enhancements</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements50.html">Android 5.0</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements44.html">Android 4.4</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements43.html">Android 4.3</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements42.html">Android 4.2</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements41.html">Android 4.1</a></li>
+ </ul>
+ </li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/overview/acknowledgements.html">Acknowledgements</a></li>
</ul>
</li>
- <li>
- <a href="<?cs var:toroot ?>devices/tech/security/best-practices.html">
- <span class="en">Best practices</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/tech/security/dm-verity.html">
- <span class="en">dm-verity on boot</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/tech/encryption/index.html">
- <span class="en">Encryption</span>
- </a>
- </li>
<li class="nav-section">
<div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/tech/security/se-linux.html">
- <span class="en">Security-Enhanced Linux</span>
+ <a href="<?cs var:toroot ?>devices/tech/security/implement.html">
+ <span class="en">Implementation</span>
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/concepts.html">Concepts</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/implement.html">Implementation</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/customize.html">Customization</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/validate.html">Validation</a></li>
- </ul>
- </li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/encryption/index.html">Encryption</a></li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tech/security/verifiedboot/index.html">
+ <span class="en">Verified Boot</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/verifiedboot/verified-boot.html">Verifying boot</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/verifiedboot/dm-verity.html">Implementing dm-verity</a></li>
+ </ul>
+ </li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tech/security/selinux/index.html">
+ <span class="en">Security-Enhanced Linux</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/concepts.html">Concepts</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/implement.html">Implementation</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/customize.html">Customization</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/validate.html">Validation</a></li>
+ </ul>
+ </li>
</ul>
- </li>
-
+ </li>
+ </ul>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/index.html">
@@ -324,29 +338,21 @@
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/index.html"
- >Start Here</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/machine_setup.html"
- >Machine Setup</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/devices.html"
- >Working with Devices</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/lifecycle.html"
- >Test Lifecycle</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/options.html"
- >Option Handling</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/full_example.html"
- >An End-to-End Example</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/index.html">Start Here</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/machine_setup.html">Machine Setup</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/devices.html">Working with Devices</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/lifecycle.html">Test Lifecycle</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/options.html">Option Handling</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/full_example.html">An End-to-End Example</a></li>
<li id="tradefed-tree-list" class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>reference/packages.html">
- <span class="en">Package Index</span>
- </a>
- <div>
- </li>
+ <span class="en">Package Index</span>
+ </a>
+ </div>
+ </li>
</ul>
</li>
-
</ul>
- </li>
-
-</ul>
+ </li> <!-- End nav-section, Core Technologies -->
+</ul>
diff --git a/src/devices/drm.jd b/src/devices/drm.jd
index 9a7c673..3d47e30 100644
--- a/src/devices/drm.jd
+++ b/src/devices/drm.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 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.
@@ -25,6 +25,8 @@
</div>
</div>
+<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_drm.png" alt="Android DRM HAL icon"/>
+
<p>This document provides an overview of the Android DRM framework, and
introduces the interfaces a DRM plug-in must implement. This document does not
describe robustness rules or compliance rules that may be defined by a DRM
@@ -46,18 +48,17 @@
href="https://developer.android.com/reference/android/media/MediaDrm.html">MediaDrm</a>
for the class to obtain keys for decrypting protected media streams.</p>
- <img src="images/drm_hal.png" alt="Android DRM HAL" />
+ <img src="images/ape_fwk_drm.png" alt="Android DRM HAL" />
-<p class="img-caption"><strong>Figure 1.</strong> DRM Hardware Abastraction
+<p class="img-caption"><strong>Figure 1.</strong> DRM Hardware Abstraction
Layer</p>
<p>
Availability of rich digital content is important to users on mobile devices. To
make their content widely available, Android developers and digital content
publishers need a consistent DRM implementation supported across the Android
-ecosystem. In order to make that digital content available on Android devices
-and to ensure that there is at least one consistent DRM available across all
-devices, Google provides DRM without any license fees on compatible Android devices.
+ecosystem. To make that digital content available on Android devices and to ensure at least one consistent DRM available across all
+devices, Google provides DRM without license fees on compatible Android devices.
On Android 3.0 and higher platforms, the DRM plug-in is integrated with the
Android DRM framework and can use hardware-backed protection to secure premium
content and user credentials.
@@ -96,13 +97,13 @@
for various DRM schemes.</li>
</ul>
- <img src="images/drm_framework.png" alt="Android DRM Framework" />
+ <img src="images/ape_fwk_drm_2.png" alt="Android DRM Framework" />
<p class="img-caption"><strong>Figure 2.</strong> DRM framework</p>
-<p>See the <a
+<p>For details, refer to the <a
href="http://developer.android.com/reference/android/drm/package-summary.html">Android
-DRM package reference</a> for additional details.</p>
+DRM package reference</a>.</p>
<h2 id="plug-ins">Plug-ins</h2>
<p>As shown in the figure below, the DRM framework uses a plug-in architecture
@@ -115,7 +116,7 @@
native modules. The caller of DRM framework accesses only the DrmManagerClient
and does not have to be aware of each DRM scheme. </p>
- <img src="images/drm_plugin.png" alt="Android DRM Plug-in" />
+ <img src="images/ape_fwk_drm_plugins.png" alt="Android DRM Plug-in" />
<p class="img-caption"><strong>Figure 3.</strong> DRM framework with plug-ins</p>
@@ -125,7 +126,7 @@
them under:<br/>
<code>/system/lib/drm/plugins/native/</code></p>
-<img src="images/drm_plugin_lifecycle.png" alt="Android DRM Plug-in Lifecycle" />
+<img src="images/ape_fwk_drm_plugins_life.png" alt="Android DRM Plug-in Lifecycle" />
<p class="img-caption"><strong>Figure 4.</strong> DRM plug-in lifecycle</p>
@@ -136,14 +137,13 @@
<h3 id="IDrmEngine">IDrmEngine</h3>
-<p>IDrmEngine is an interface with a set of APIs to suit DRM use cases. Plug-in
+<p>IDrmEngine is an interface with a set of APIs for DRM use cases. Plug-in
developers must implement the interfaces specified in IDrmEngine and the
-listener interfaces specified below. This document assumes the plug-in developer
-has access to the Android source tree. The interface definition is available in
-the source tree at:<br/>
+listener interfaces specified below. The interface definition is available in
+the source tree at:<p/>
<code>
-<<platform_root>/frameworks/base/drm/libdrmframework/plugins/common/include
-</code></p>
+<platform_root>/frameworks/base/drm/libdrmframework/plugins/common/include
+</code>
<h3 id="DrmInfo">DRM Info</h3>
<p>DrmInfo is a wrapper class that wraps the protocol for communicating with the
@@ -171,13 +171,15 @@
<code>int checkRightsStatus(int uniqueId, const String8& path, int
action);</code>
+
<p>Save DRM rights to the specified rights path and make association with content path.
-The input parameters are DrmRights to be saved, rights file path where rights
-are to be saved and content file path where content was saved.</p>
+The input parameters are the DrmRights to be saved, the rights file path where rights
+are to be saved, and the content file path where content was saved.</p>
<code>status_t saveRights(int uniqueId, const DrmRights& drmRights,
const String8& rightsPath, const String8&
contentPath);</code>
+
<p>Save DRM rights to specified rights path and make association with content
path.</p>
@@ -195,7 +197,7 @@
Unique identifier for a session and path of the protected content) are required.
The action, defined as Action::DEFAULT, Action::PLAY, etc., is also required.</p>
- <img src="images/drm_license_metadata.png" alt="Android DRM License Metadata" />
+ <img src="images/ape_fwk_drm_retrieve_license.png" alt="Android DRM License Metadata" />
<p class="img-caption"><strong>Figure 5.</strong> Retrieve license metadata</p>
@@ -204,7 +206,7 @@
protected content to return key-value pairs of metadata.</p>
<h3 id="metadata">Decrypt session</h3>
-<p>To maintain the decryption session, the caller of the DRM framework has to
+<p>To maintain the decryption session, the caller of the DRM framework must
invoke openDecryptSession() at the beginning of the decryption sequence.
openDecryptSession() asks each DRM plug-in if it can handle input DRM
content.</p>
diff --git a/src/devices/graphics/automate-tests.jd b/src/devices/graphics/automate-tests.jd
new file mode 100644
index 0000000..87973f2
--- /dev/null
+++ b/src/devices/graphics/automate-tests.jd
@@ -0,0 +1,145 @@
+page.title=Automating the tests
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<h2 id=intro>Introduction</h2>
+
+<p>Deqp test modules can be integrated to automated test systems in multiple ways.
+The best approach depends on the existing test infrastructure and target
+environment.</p>
+
+<p>The primary output from a test run is always the test log file, i.e. the file
+with a <code>.qpa</code> postfix. Full test results can be parsed from the test log. Console output is
+debug information only and may not be available on all platforms.</p>
+
+<p>Test binaries can be invoked directly from a test automation system. The test
+binary can be launched for a specific case, for a test set, or for all
+available tests. If a fatal error occurs during execution (such as certain API
+errors or a crash), the test execution will abort. For regression testing, the
+best approach is to invoke the test binaries for individual cases or small test
+sets separately, in order to have partial results available even in the event
+of hard failure.</p>
+
+<p>The deqp comes with command line test execution tools that can be used in
+combination with the execution service to achieve a more robust integration.
+The executor detects test process termination and will resume test execution on
+the next available case. A single log file is produced from the full test
+session. This setup is ideal for lightweight test systems that don’t provide
+crash recovery facilities.</p>
+
+<h2 id=command_line_test_execution_tools>Command line test execution tools</h2>
+
+<p>The current command line tool set includes a remote test execution tool, a test
+log comparison generator for regression analysis, a test-log-to-CSV converter,
+a test-log-to-XML converter, and a testlog-to-JUnit converter.</p>
+
+<p>The source code for these tools is in the <code>executor</code> directory, and the binaries are built into the <code><builddir>/executor</code> directory.</p>
+
+<h3 id=command_line_test_executor>Command line Test Executor</h3>
+
+<p>The command line Test Executor is a portable C++ tool for launching a test run
+on a device and collecting the resulting logs from it over TCP/IP. The Executor
+communicates with the execution service (execserver) on the target device.
+Together they provide functionality such as recovery from test process crashes.
+The following examples demonstrate how to use the command line Test Executor
+(use <code>--help</code> for more details):</p>
+
+<h4 id=example_1_run_gles2_functional_tests>Example 1: Run GLES2 functional tests on an Android device:</h4>
+
+<pre>
+executor --connect=127.0.0.1 --port=50016 --binaryname=
+com.drawelements.deqp/android.app.NativeActivity
+--caselistdir=caselists
+--testset=dEQP-GLES2.* --out=BatchResult.qpa
+--cmdline="--deqp-crashhandler=enable --deqp-watchdog=enable
+--deqp-gl-config-name=rgba8888d24s8"
+</pre>
+
+<h4 id=example_2_continue_a_partial_opengl>Example 2: Continue a partial OpenGL ES 2 test run locally:</h4>
+
+<pre>
+executor --start-server=execserver/execserver --port=50016
+--binaryname=deqp-gles2 --workdir=modules/opengl
+--caselistdir=caselists
+--testset=dEQP-GLES2.* --exclude=dEQP-GLES2.performance.* --in=BatchResult.qpa
+--out=BatchResult.qpa
+</pre>
+
+<h3 id=test_log_csv_export_and_compare>Test log CSV export and compare</h3>
+
+<p>The deqp has a tool for converting test logs (.<code>qpa </code>files) into CSV files. The CSV output contains a list of test cases and their
+results. The tool can also compare two or more batch results and list only the
+test cases that have different status codes in the input batch results. The
+comparison will also print the number of matching cases.</p>
+
+<p>The output in CSV format is very practical for further processing with standard
+command line utilities or with a spreadsheet editor. An additional, human-readable,
+plain-text format can be selected using the following command line argument: <code>--format=text</code></p>
+
+<h4 id=example_1_export_test_log_in_csv_format>Example 1: Export test log in CSV format</h4>
+
+<pre>
+testlog-to-csv --value=code BatchResult.qpa > Result_statuscodes.csv
+testlog-to-csv --value=details BatchResult.qpa > Result_statusdetails.csv
+</pre>
+
+<h4 id=example_2_list_differences>Example 2: List differences of test results between two test logs</h4>
+
+<pre>
+testlog-to-csv --mode=diff --format=text Device_v1.qpa Device_v2.qpa
+</pre>
+
+<p class="note"><strong>Note:</strong> The argument <code>--value=code</code> outputs the test result code, such as "Pass" or "Fail". The argument <code>--value=details</code> selects the further explanation of the result or numerical value produced by a performance, capability, or accuracy test.</p>
+
+<h3 id=test_log_xml_export>Test log XML export</h3>
+
+<p>Test log files can be converted to valid XML documents using the <code>testlog-to-xml</code> utility. Two output modes are supported: </p>
+
+<ul>
+ <li> Separate documents mode, where each test case and the <code>caselist.xml</code> summary document are written to a destination directory
+ <li> Single file mode, where all results in the <code>.qpa</code> file are written to single XML document.
+</ul>
+
+<p>Exported test log files can be viewed in a browser using an XML style sheet.
+Sample style sheet documents (<code>testlog.xsl</code> and <code>testlog.css</code>) are provided in the <code>doc/testlog-stylesheet</code> directory. To render the log files in a browser, copy the two style sheet
+files into the same directory where the exported XML documents are located.</p>
+
+<p>If you are using Google Chrome, the files must be accessed over HTTP as Chrome
+limits local file access for security reasons. The standard Python installation
+includes a basic HTTP server that can be launched to serve the current
+directory with the <code>python –m SimpleHTTPServer 8000</code> command. After launching the server, just point the Chrome browser to <code>http://localhost:8000</code> to view the test log.</p>
+
+<h3 id=conversion_to_a_junit_test_log>Conversion to a JUnit test log</h3>
+
+<p>Many test automation systems can generate test run result reports from JUnit
+output. The deqp test log files can be converted to the JUnit output format
+using the testlog-to-junit tool. </p>
+
+<p>The tool currently supports translating the test case verdict only. As JUnit
+supports only "pass" and "fail" results, a passing result of the deqp is mapped
+to "JUnit pass" and other results are considered failures. The original deqp
+result code is available in the JUnit output. Other data, such as log messages
+and result images, are not preserved in the conversion.</p>
diff --git a/src/devices/graphics/build-tests.jd b/src/devices/graphics/build-tests.jd
new file mode 100644
index 0000000..f43d916
--- /dev/null
+++ b/src/devices/graphics/build-tests.jd
@@ -0,0 +1,354 @@
+page.title=Building test programs
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+
+<p>The test framework has been designed with portability in mind. The only
+mandatory requirements are full C++ support and standard system libraries for
+I/O, threads and sockets.</p>
+
+<h2 id=cmake_build_system>CMake build system</h2>
+
+<p>The deqp sources have build scripts for CMake, which is the preferred tool for
+compiling the test programs.</p>
+
+<p>CMake is an open source build system that supports multiple platforms and
+toolchains. CMake generates native makefiles or IDE project files from
+target-independent configuration files. For more information on CMake,
+please see the <a href="http://www.cmake.org/cmake/help/documentation.html">CMake</a> documentation.</p>
+
+<p>CMake supports and recommends out-of-source-tree builds, i.e., you should
+always create makefiles or project files in a separate build directory
+outside the source tree. CMake does not have any kind of "distclean" target, so
+removing any files generated by CMake must be done manually.</p>
+
+<p>Configuration options are given to CMake using <code>-D<OPTION_NAME>=<VALUE></code> syntax. Some commonly used options for deqp are listed below.</p>
+
+<table>
+ <tr>
+ <th>Configuration option</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><code>DEQP_TARGET</code></td>
+<td><p>Target name, for example: "android"</p>
+<p>The deqp CMake scripts will include the file
+<code>targets/<DEQP_TARGET>/<DEQP_TARGET>.cmake</code> and expect to find target-specific build options from there.</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>CMAKE_TOOLCHAIN_FILE</code></td>
+<td><p>Path to toolchain file for CMake. Used for cross compilation.</p></td>
+ </tr>
+ <tr>
+ <td><code>CMAKE_BUILD_TYPE</code></td>
+<td><p>Build type for makefile targets. Valid values are: "Debug" and "Release"</p>
+<p>Note the interpretation and default type depend on the targeted build system.
+See the CMake documentation for details.</p>
+</td>
+ </tr>
+</table>
+
+<h2 id=creating_target_build_file>Creating a target build file</h2>
+
+<p>The deqp build system is configured for new targets using target build files.
+A target build file defines which features the platform supports and what libraries or
+additional include paths are required. Target file names follow the <code>targets/<name>/<name>.cmake</code> format and the target is selected using the <code>DEQP_TARGET</code> build parameter.</p>
+
+<p>File paths in target files are relative to the base <code>deqp</code> directory, not the <code>targets/<name></code> directory. The following standard variables can be set by target build file.</p>
+
+<table>
+ <tr>
+ <th>Variable</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>
+DEQP_TARGET_NAME</code></td>
+<td><p>Target name (will be included into test logs)</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+DEQP_SUPPORT_GLES2</code></td>
+<td><p>Whether GLES2 is supported (default: OFF)</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+DEQP_GLES2_LIBRARIES</code></td>
+<td><p>GLES2 libraries (leave empty if not supported or dynamic loading is used)</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+DEQP_SUPPORT_GLES3</code></td>
+<td><p>Whether GLES3.x is supported (default: OFF)</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+DEQP_GLES3_LIBRARIES</code></td>
+<td><p>GLES3.x libraries (leave empty if not supported or dynamic loading is used)</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+DEQP_SUPPORT_VG</code></td>
+<td><p>Whether OpenVG is supported (default: OFF)</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+DEQP_OPENVG_LIBRARIES</code></td>
+<td><p>OpenVG libraries (leave empty if not supported or dynamic loading is used)</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+DEQP_SUPPORT_EGL</code></td>
+<td><p>Whether EGL is supported (default: OFF)</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+DEQP_EGL_LIBRARIES</code></td>
+<td><p>EGL libraries (leave empty if not supported or dynamic loading is used)</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+DEQP_PLATFORM_LIBRARIES</code></td>
+<td><p>Additional platform-specific libraries required for linking</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+DEQP_PLATFORM_COPY_LIBRARIES</code></td>
+<td><p>List of libraries that are copied to each test binary build directory. Can be
+used to copy libraries that are needed for running tests but are not in default
+search path.</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+TCUTIL_PLATFORM_SRCS</code></td>
+<td><p>Platform port source list. Default sources are determined based on the
+capabilities and OS.</p>
+
+<p><strong>Note:</strong> Paths are relative to: <code>framework/platform</code></p>
+</td>
+ </tr>
+</table>
+
+<p>The target build file can add additional include or link paths using the <code>include_directories()</code> and <code>link_directories()</code> CMake functions.</p>
+
+<h2 id=win32_build>Win32 build</h2>
+
+<p>The easiest way to build deqp modules for Windows is to use the CMake build
+system. You will need CMake 2.6.12 or newer and the Microsoft Visual C/C++
+compiler. The deqp has been tested with Visual Studio 2013.</p>
+
+<p>Visual Studio project files can be generated with the following command:</p>
+
+<pre>
+cmake path\to\src\deqp -G "Visual Studio 12"
+</pre>
+
+<p>A 64-bit build can be made by selecting "Visual Studio <ver> Win64" as the build
+generator:</p>
+
+<pre>
+cmake path\to\src\deqp -G "Visual Studio 12 Win64"
+</pre>
+
+<p>You can also generate NMake makefiles with the <code>-G "NMake Makefiles"</code> option as well as the build type (<code>-DCMAKE_BUILD_TYPE="Debug"</code> or <code>"Release"</code>).</p>
+
+<h3 id=rendering_context_creation>Rendering context creation</h3>
+
+<p>Rendering context can be created either with WGL or with EGL on Windows.</p>
+
+<h4 id=wgl_support>WGL support</h4>
+
+<p>All Win32 binaries support GL context creation with WGL as it requires only
+standard libraries. WGL context can be selected using the <code>--deqp-gl-context-type=wgl</code> command line argument. In the WGL mode, the deqp uses the <code>WGL_EXT_create_context_es_profile</code> extension to create OpenGL ES contexts. This has been tested to work with
+latest drivers from NVIDIA and Intel. AMD drivers do not support the required
+extension.</p>
+
+<h4 id=egl_support>EGL support</h4>
+
+<p>The deqp is built with dynamic loading for EGL on Windows if DEQP_SUPPORT_EGL
+is ON. This is the default in most targets. Then, if the host has EGL libraries
+available, it is possible to run tests with them with the command line
+parameter: <code>--deqp-gl-context-type=egl</code></p>
+
+<h2 id=android_build>Android build</h2>
+
+<p>The Android build uses CMake build scripts for building the native test code.
+Java parts, i.e., the Test Execution Server and the Test Application Stub, are
+compiled using the standard Android build tools.</p>
+
+<p>To compile deqp test programs for Android with the provided build
+scripts, you will need:</p>
+
+<ul>
+ <li>The latest version of the <a href="http://developer.android.com/tools/sdk/ndk/index.html">Android NDK</a>; the <code>android/scripts/common.py</code> file lists the required version
+ <li>Android stand-alone SDK with API 13, SDK Tools, SDK Platform-tools, and SDK
+Build-tools <a href="http://developer.android.com/sdk/index.html#Other">packages</a> installed
+ <li><a href="http://ant.apache.org/bindownload.cgi">Apache Ant 1.9.4</a>
+ (required by the Java code build)
+ <li><a href="http://www.cmake.org/download/">CMake 2.8.12</a> or newer
+ <li><a href="https://www.python.org/downloads/">Python 2.6</a> or newer in 2.x series; Python 3.x is not supported
+ <li>For Windows: Either NMake or JOM in <code>PATH</code>
+ <ul>
+ <li><a href="http://qt-project.org/wiki/jom">JOM</a> enables faster builds
+ </ul>
+ <li> Optional: Ninja make is also supported on Linux
+</ul>
+
+<p>Ant and SDK binaries are located based on the PATH environment variable with
+certain overriding defaults. The logic is controlled by <code>android/scripts/common.py</code>. </p>
+
+<p>The NDK directory must be either <code>~/android-ndk-<version></code> or <code>C:/android/android-ndk-<version></code> or defined via the <code>ANDROID_NDK_PATH</code> environment variable.</p>
+
+<p>Deqp on-device components, the test execution service, and test programs are
+built by executing the <code>android/scripts/build.py</code> script. The final .apk is created in <code>android/package/bin</code> and can be installed by the <code>install.py</code> script. If the <a href="port-tests.html#test_execution_service">command line executor</a> is used, the ExecService is launched with <code>launch.py</code> script on the device via ADB. The scripts can be executed from any directory.</p>
+
+<h2 id=linux_build>Linux build</h2>
+
+<p>Test binaries and command line utilities can be built for Linux by generating makefiles using CMake. There are multiple, pre-defined build targets that are useful when building for Linux.</p>
+
+<table>
+ <tr>
+ <th>Build target</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><code>default</code></td>
+<td><p>Default target that uses CMake platform introspection to determine support for various APIs.</p>
+</td>
+ </tr>
+
+<tr>
+ <td><code>
+x11_glx</code></td>
+<td><p>Uses GLX to create OpenGL (ES) contexts.</p>
+</td>
+ </tr>
+
+<tr>
+ <td><code>
+x11_egl</code></td>
+<td><p>Uses EGL to create OpenGL (ES) contexts.</p>
+</td>
+ </tr>
+
+ <tr>
+ <td><code>
+x11_egl_glx</code></td>
+<td><p>Supports both GLX and EGL with X11.</p>
+</td>
+ </tr>
+</table>
+
+<p>Always use <code>-DCMAKE_BUILD_TYPE=<Debug|Release></code> to define the build type. <code>Release</code> is a good default. Without it, a default, unoptimized release build is made.</p>
+
+<p>The <code>-DCMAKE_C_FLAGS</code> and <code>-DCMAKE_CXX_FLAGS</code> command line arguments can be used to pass extra arguments to the compiler. For example the 32-bit or 64-bit build can be done by setting <code>-DCMAKE_C(XX)_FLAGS="-m32"</code> or <code>"-m64"</code> respectively. If not specified, the toolchain native architecture, typically 64-bit on the 64-bit toolchain, is used.</p>
+
+<p>The <code>-DCMAKE_LIBRARY_PATH</code> and <code>-DCMAKE_INCLUDE_PATH</code> arguments can be used for CMake to give CMake additional library or include search paths.</p>
+
+<p>An example of a full command line used to do a 32-bit debug build against
+driver headers and libraries in a custom location is the following:</p>
+
+<pre>
+$ cmake <path to src>/deqp -DDEQP_TARGET=x11_egl -DCMAKE_C_FLAGS="-m32"
+-DCMAKE_CXX_FLAGS="-m32" -DCMAKE_BUILD_TYPE=Debug
+-DCMAKE_LIBRARY_PATH="<path to driver>/lib"
+-DCMAKE_INCLUDE_PATH="<path to driver>/inc"
+$ make -j4
+</pre>
+
+<h2 id=cross-compiling>Cross-compiling</h2>
+
+<p>Cross-compiling can be achieved by using a CMake toolchain file. The toolchain
+file specifies the compiler to use, along with custom search paths for
+libraries and headers. Several toolchain files for common scenarios are
+included in the release package in the <code>framework/delibs/cmake</code> directory.</p>
+
+<p>In addition to standard CMake variables, the following deqp-specific variables
+can be set by the toolchain file. CMake can usually detect <code>DE_OS</code>, <code>DE_COMPILER</code> and <code>DE_PTR_SIZE</code> correctly but <code>DE_CPU</code> must be set by the toolchain file.</p>
+
+<table>
+ <tr>
+ <th>Variable</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>
+DE_OS</code></td>
+ <td><p>Operating system. Supported values are: <code>DE_OS_WIN32, DE_OS_UNIX, DE_OS_WINCE, DE_OS_OSX, DE_OS_ANDROID, DE_OS_SYMBIAN, DE_OS_IOS</code></p>
+ </td>
+ </tr>
+ <tr>
+ <td><code>
+DE_COMPILER</code></td>
+<td><p>Compiler type. Supported values are: <code>DE_COMPILER_GCC, DE_COMPILER_MSC, DE_COMPILER_CLANG</code></p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+DE_CPU</code></td>
+<td><p>CPU type. Supported values are: <code>DE_CPU_ARM, DE_CPU_X86</code>.</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+DE_PTR_SIZE</code></td>
+<td><p>sizeof(void*) on the platform. Supported values are: 4 and 8</p>
+</td>
+ </tr>
+</table>
+
+<p>The toolchain file can be selected using the <code>CMAKE_TOOLCHAIN_FILE</code> build parameter. For example, the following would create makefiles for a build using the CodeSourcery cross-compiler for ARM/Linux:</p>
+
+<pre>
+cmake <path to src>/deqp –DDEQP_BUILD_TYPE="Release"
+–DCMAKE_TOOLCHAIN_FILE=<path to src>/delibs/cmake/toolchain-arm-cs.cmake
+–DARM_CC_BASE=<path to cc directory>
+</pre>
+
+<h2 id=run-time_linking_of_gles_and_egl_libraries>Run-time linking of GLES and EGL libraries</h2>
+
+<p>The deqp does not need entry points of the API under test during linking. The
+test code always accesses the APIs through function pointers. Entry points can
+then be loaded dynamically at run time or the platform port can provide them at
+link time.</p>
+
+<p>If support for an API is turned on in the build settings and link libraries are
+not provided, the deqp will load the needed entry points at run time. If the
+static linking is desired, provide the needed link libraries in the <code>DEQP_<API>_LIBRARIES</code> build configuration variable.</p>
diff --git a/src/devices/graphics/cts-integration.jd b/src/devices/graphics/cts-integration.jd
new file mode 100644
index 0000000..c8be6b6
--- /dev/null
+++ b/src/devices/graphics/cts-integration.jd
@@ -0,0 +1,72 @@
+page.title=Integrating with Android CTS
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<h2 id=deqp_tests_in_android_cts>Deqp tests in Android CTS</h2>
+
+<p>Deqp tests have been part of Android CTS since the Android 5.0 release.</p>
+
+<p>Android CTS requires a certain subset of tests, called the <code>mustpass</code> list, to pass. The <code>mustpass</code> list includes OpenGL ES 3.0, OpenGL ES 3.1, and the Android Extension Pack tests. If a device doesn't support a target API or extension, tests are skipped and reported as passing.
+The <code>mustpass</code> files can be found under the <code>android/cts</code> directory in the deqp source tree.</p>
+
+<p>Deqp tests are included in the Android CTS release packages, available on the <a href="{@docRoot}compatibility/downloads.html">Android Compatibility Downloads</a> page. </p>
+
+<p>You can run deqp tests through the <code>cts-tradefed</code> utility with the following command:</p>
+
+<pre>
+cts-tradefed run cts --plan CTS-DEQP
+</pre>
+
+<h2 id=duplicating_runs_without_cts>Duplicating runs without CTS</h2>
+
+<p>To replicate the CTS run, install the deqp APK of the CTS package and use the
+following command:</p>
+
+<pre>
+adb -d shell am start -n com.drawelements.deqp/android.app.NativeActivity -e
+cmdLine "deqp --deqp-case=dEQP-GLES3.some_group.*
+--deqp-gl-config-name=rgba8888d24s8 --deqp-log-filename=/sdcard/dEQP-Log.qpa
+</pre>
+
+<p>The important part of that command is the following:</p>
+<pre>
+--deqp-gl-config-name=rgba8888d24s8
+</pre>
+
+<p>This argument requests the tests be run on an RGBA 8888 on-screen surface
+with a 24-bit depth buffer and an 8-bit stencil buffer. Also remember to set
+the desired tests, e.g. using the <code>--deqp-case</code> argument.</p>
+
+<h2 id=mapping_of_the_cts_results>Mapping of the CTS results</h2>
+
+<p>In the Android CTS, a test case can end up in three states: passed, failed, or
+not executed.</p>
+
+<p>The deqp has more result codes available. A mapping is automatically performed
+by the CTS. The following deqp result codes are mapped to a CTS pass: <code>Pass</code>, <code>NotSupported</code>, <code>QualityWarning</code>, and <code>CompatibilityWarning</code> </p>
+
+<p>The following results are interpreted as a CTS failure:
+<code>Fail</code>, <code>ResourceError</code>, <code>Crash</code>, <code>Timeout</code>, and <code>InternalError</code></p>
diff --git a/src/devices/graphics/images/ape_fwk_graphics.png b/src/devices/graphics/images/ape_fwk_graphics.png
new file mode 100644
index 0000000..6558864
--- /dev/null
+++ b/src/devices/graphics/images/ape_fwk_graphics.png
Binary files differ
diff --git a/src/devices/graphics/images/ape_fwk_hal_graphics.png b/src/devices/graphics/images/ape_fwk_hal_graphics.png
new file mode 100644
index 0000000..b29b3d3
--- /dev/null
+++ b/src/devices/graphics/images/ape_fwk_hal_graphics.png
Binary files differ
diff --git a/src/devices/graphics/images/bufferqueue.png b/src/devices/graphics/images/bufferqueue.png
index 1951f46..045c699 100644
--- a/src/devices/graphics/images/bufferqueue.png
+++ b/src/devices/graphics/images/bufferqueue.png
Binary files differ
diff --git a/src/devices/graphics/images/continuous_capture_activity.png b/src/devices/graphics/images/continuous_capture_activity.png
index 24ba1d5..5bcf176 100644
--- a/src/devices/graphics/images/continuous_capture_activity.png
+++ b/src/devices/graphics/images/continuous_capture_activity.png
Binary files differ
diff --git a/src/devices/graphics/images/dispsync.png b/src/devices/graphics/images/dispsync.png
index d97765c..c7736a5 100644
--- a/src/devices/graphics/images/dispsync.png
+++ b/src/devices/graphics/images/dispsync.png
Binary files differ
diff --git a/src/devices/graphics/images/graphics_pipeline.png b/src/devices/graphics/images/graphics_pipeline.png
index 983a517..3f4d452 100644
--- a/src/devices/graphics/images/graphics_pipeline.png
+++ b/src/devices/graphics/images/graphics_pipeline.png
Binary files differ
diff --git a/src/devices/graphics.jd b/src/devices/graphics/index.jd
similarity index 84%
rename from src/devices/graphics.jd
rename to src/devices/graphics/index.jd
index c8f11e8..3bba9dd 100644
--- a/src/devices/graphics.jd
+++ b/src/devices/graphics/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 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.
@@ -25,6 +25,9 @@
</div>
</div>
+<img style="float: right; margin: 0px 15px 15px 15px;"
+src="images/ape_fwk_hal_graphics.png" alt="Android Graphics HAL icon"/>
+
<p>The Android framework offers a variety of graphics rendering APIs for 2D and
3D that interact with manufacturer implementations of graphics drivers, so it
is important to have a good understanding of how those APIs work at a higher
@@ -48,22 +51,23 @@
<p>Beginning in Android 4.0, hardware-accelerated Canvas is enabled by default.
Consequently, a hardware GPU that supports OpenGL ES 2.0 is mandatory for
-Android 4.0 and later devices. See the <a
-href="https://developer.android.com/guide/topics/graphics/hardware-accel.html">Hardware
-Acceleration guide</a> for an explanation of how the hardware-accelerated
-drawing path works and the differences in its behavior from that of the
-software drawing path.</p>
+Android 4.0 and later devices. See the
+<a href="https://developer.android.com/guide/topics/graphics/hardware-accel.html">Hardware Acceleration guide</a> for an explanation of how the
+hardware-accelerated drawing path works and the differences in its behavior
+from that of the software drawing path.</p>
<p>In addition to Canvas, the other main way that developers render graphics is
by using OpenGL ES to directly render to a surface. Android provides OpenGL ES
-interfaces in the <a
-href="http://developer.android.com/reference/android/opengl/package-summary.html">android.opengl</a>
+interfaces in the
+<a href="http://developer.android.com/reference/android/opengl/package-summary.html">android.opengl</a>
package that developers can use to call into their GL implementations with the
SDK or with native APIs provided in the <a
href="https://developer.android.com/tools/sdk/ndk/index.html">Android
NDK</a>.</p>
-<h2 id=android_graphics_components>Android graphics components</h2>
+<p>Android implementers can test OpenGL ES functionality using the <a href="testing.html">drawElements Quality Program</a>, also known as deqp.</p>
+
+<h2 id="android_graphics_components">Android graphics components</h2>
<p>No matter what rendering API developers use, everything is rendered onto a
"surface." The surface represents the producer side of a buffer queue that is
@@ -73,19 +77,19 @@
<p>The following diagram shows how the key components work together:</p>
-<img src="graphics/images/graphics_surface.png" alt="image-rendering components">
+<img src="images/ape_fwk_graphics.png" alt="image-rendering components">
<p class="img-caption"><strong>Figure 1.</strong> How surfaces are rendered</p>
<p>The main components are described below:</p>
-<h3 id=image_stream_producers>Image Stream Producers</h3>
+<h3 id="image_stream_producers">Image Stream Producers</h3>
<p>An image stream producer can be anything that produces graphic buffers for
consumption. Examples include OpenGL ES, Canvas 2D, and mediaserver video
decoders.</p>
-<h3 id=image_stream_consumers>Image Stream Consumers</h3>
+<h3 id="image_stream_consumers">Image Stream Consumers</h3>
<p>The most common consumer of image streams is SurfaceFlinger, the system
service that consumes the currently visible surfaces and composites them onto
@@ -97,7 +101,7 @@
app consuming a camera preview image stream. Non-GL applications can be
consumers too, for example the ImageReader class.</p>
-<h3 id=window_manager>Window Manager</h3>
+<h3 id="window_manager">Window Manager</h3>
<p>The Android system service that controls a window, which is a container for
views. A window is always backed by a surface. This service oversees
@@ -106,7 +110,7 @@
The Window Manager sends all of the window metadata to SurfaceFlinger so
SurfaceFlinger can use that data to composite surfaces on the display.</p>
-<h3 id=hardware_composer>Hardware Composer</h3>
+<h3 id="hardware_composer">Hardware Composer</h3>
<p>The hardware abstraction for the display subsystem. SurfaceFlinger can
delegate certain composition work to the Hardware Composer to offload work from
@@ -120,31 +124,32 @@
support events, one of which is VSYNC. Another is hotplug for plug-and-play
HDMI support.</p>
-<p>See the <a href="{@docRoot}devices/graphics.html#hardware_composer_hal">Hardware Composer
-HAL</a> section for more information.</p>
+<p>See the
+<a href="{@docRoot}devices/graphics.html#hardware_composer_hal">Hardware
+Composer HAL</a> section for more information.</p>
-<h3 id=gralloc>Gralloc</h3>
+<h3 id="gralloc">Gralloc</h3>
<p>The graphics memory allocator is needed to allocate memory that is requested
by image producers. See the <a
href="{@docRoot}devices/graphics.html#gralloc">Gralloc HAL</a> section for more
information.</p>
-<h2 id=data_flow>Data flow</h2>
+<h2 id="data_flow">Data flow</h2>
<p>See the following diagram for a depiction of the Android graphics
pipeline:</p>
-<img src="graphics/images/graphics_pipeline.png" alt="graphics data flow">
+<img src="images/graphics_pipeline.png" alt="graphics data flow">
-<p class="img-caption"><strong>Figure 2.</strong> How graphic data flow through
+<p class="img-caption"><strong>Figure 2.</strong> Graphic data flow through
Android</p>
<p>The objects on the left are renderers producing graphics buffers, such as
the home screen, status bar, and system UI. SurfaceFlinger is the compositor
and Hardware Composer is the composer.</p>
-<h3 id=bufferqueue>BufferQueue</h3>
+<h3 id="bufferqueue">BufferQueue</h3>
<p>BufferQueues provide the glue between the Android graphics components. These
are a pair of queues that mediate the constant cycle of buffers from the
@@ -153,7 +158,8 @@
<p>See the following diagram for the BufferQueue communication process.</p>
-<img src="graphics/images/bufferqueue.png" alt="BufferQueue communication process">
+<img src="images/bufferqueue.png"
+alt="BufferQueue communication process">
<p class="img-caption"><strong>Figure 3.</strong> BufferQueue communication
process</p>
@@ -198,7 +204,7 @@
<p>The Hardware Composer HAL conducts the other half of the work. This HAL acts
as the central point for all Android graphics rendering.</p>
-<h3 id=synchronization_framework>Synchronization framework</h3>
+<h3 id="synchronization_framework">Synchronization framework</h3>
<p>Since Android graphics offer no explicit parallelism, vendors have long
implemented their own implicit synchronization within their own drivers. This
diff --git a/src/devices/graphics/port-tests.jd b/src/devices/graphics/port-tests.jd
new file mode 100644
index 0000000..48d64b3
--- /dev/null
+++ b/src/devices/graphics/port-tests.jd
@@ -0,0 +1,156 @@
+page.title=Porting the test framework
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>Porting the deqp involves three steps: adapting base portability libraries,
+implementing test-framework platform-integration interfaces, and porting the
+execution service.</p>
+
+<p>The table below lists locations for likely porting changes. Anything beyond
+them is likely to be exotic.</p>
+
+<table>
+ <tr>
+ <th>Location</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><code>
+framework/delibs/debase<br/>
+framework/delibs/dethread<br/>
+framework/delibs/deutil</code></td>
+<td><p>Any necessary implementations of OS-specific code.</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+framework/qphelper/qpCrashHandler.c</code></td>
+<td><p>Optional: Implementation for your OS.</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+framework/qphelper/qpWatchDog.c</code></td>
+<td><p>Implementation for your OS. Current one is based on <code>dethread</code> and standard C library.</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+framework/platform</code></td>
+<td><p>New platform port and application stub can be implemented as described in <a href="#test_framework_platform_port">Test framework platform port</a>.</p>
+</td>
+ </tr>
+</table>
+
+<h2 id=base_portability_libraries>Base portability libraries</h2>
+
+<p>The base portability libraries already support Windows, most Linux variants, Mac OS,
+iOS, and Android. If the test target runs on one of those operating systems,
+most likely there is no need to touch the base portability libraries at all.</p>
+
+<h2 id=test_framework_platform_port>Test framework platform port</h2>
+
+<p>The deqp test framework platform port requires two components: An application
+entry point and a platform interface implementation. </p>
+
+<p>The application entry point is responsible for creating the platform object,
+creating a command line (<code>tcu::CommandLine</code>) object, opening a test log (<code>tcu::TestLog</code>), and iterating the test application (<code>tcu::App</code>). If the target OS supports a standard <code>main()</code> entry point, <code>tcuMain.cpp</code> can be used as the entry point implementation.</p>
+
+<p>The deqp platform API is described in detail in the following files.</p>
+
+<table>
+ <tr>
+ <th>File</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>
+framework/common/tcuPlatform.hpp</code></td>
+<td><p>Base class for all platform ports</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+framework/opengl/gluPlatform.hpp</code></td>
+<td><p>OpenGL platform interface</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+framework/egl/egluPlatform.hpp</code></td>
+<td><p>EGL platform interface</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+framework/platform/tcuMain.cpp</code></td>
+<td><p>Standard application entry point</p>
+</td>
+ </tr>
+</table>
+
+<p>The base class for all platform ports is <code>tcu::Platform</code>. The platform port can optionally support GL- and EGL-specific interfaces. See
+the following table for an overview of what needs to be implemented to
+run the tests.</p>
+
+<table>
+ <tr>
+ <th>Module</th>
+ <th>Interface</th>
+ </tr>
+ <tr>
+ <td><p>OpenGL (ES) test modules</p>
+</td>
+ <td><p>GL platform interface</p>
+</td>
+ </tr>
+ <tr>
+ <td><p>EGL test module</p>
+</td>
+ <td><p>EGL platform interface</p>
+</td>
+ </tr>
+</table>
+
+<p>Detailed instructions for implementing platform ports are in the
+porting layer headers.</p>
+
+<h2 id=test_execution_service>Test execution service</h2>
+
+<p>To use the deqp test execution infrastructure or command line executor, the
+test execution service must be available on the target. A portable C++
+implementation of the service is provided in the <code>execserver</code> directory. The stand-alone binary is built as a part of the deqp test module
+build for PC targets. You can modify <code>execserver/CMakeLists.txt</code> to enable a build on other targets.</p>
+
+<p>The C++ version of the test execution service accepts two command line
+parameters:</p>
+
+<ul>
+ <li> <code>--port=<port></code> will set the TCP port that the server listens on. The default is 50016.
+ <li> <code>--single</code> will terminate the server process when the client disconnects. By default, the
+server process will stay up to serve further test execution requests.
+</ul>
diff --git a/src/devices/graphics/run-tests.jd b/src/devices/graphics/run-tests.jd
new file mode 100644
index 0000000..3da7b31
--- /dev/null
+++ b/src/devices/graphics/run-tests.jd
@@ -0,0 +1,317 @@
+page.title=Running the tests
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+
+<h2 id=linux_and_windows_environments>Linux and Windows environments</h2>
+
+<p>The following files and directories must be copied to the target.</p>
+
+<table>
+ <tr>
+ <th>Module</th>
+ <th>Directory</th>
+ <th>Target</th>
+ </tr>
+
+ <tr>
+ <td><p>Execution Server</p></td>
+ <td><code>build/execserver/execserver</code></td>
+ <td><code><dst>/execserver</code></td>
+ </tr>
+
+ <tr>
+ <td><p>EGL Module</p></td>
+ <td><code>build/modules/egl/deqp-egl</code></td>
+ <td><code><dst>/deqp-egl</code></td>
+ </tr>
+
+ <tr>
+ <td><p>GLES2 Module</p></td>
+ <td><code>build/modules/gles2/deqp-gles2data/gles2</code></td>
+ <td>
+ <code>
+<dst>/deqp-gles2<br/>
+<dst>/gles2
+ </code>
+ </td>
+ </tr>
+
+ <tr>
+ <td><p>GLES3 Module</p></td>
+ <td><code>build/modules/gles3/deqp-gles3data/gles3</code></td>
+ <td>
+ <code>
+<dst>/deqp-gles3<br/>
+<dst>/gles3
+</code>
+</td>
+ </tr>
+
+ <tr>
+ <td><p>GLES3.1 Module</p></td>
+ <td><code>build/modules/gles31/deqp-gles31data/gles31</code></td>
+ <td>
+ <code>
+<dst>/deqp-gles31<br/>
+<dst>/gles31
+ </code>
+ </td>
+ </tr>
+</table>
+
+<p>Execution service and test binaries can be deployed anywhere in the target file system. Test binaries expect to find data directories in the current working directory.</p>
+
+<p>Start the Test Execution Service on the target device. For more details on
+starting the service, see <a href="port-tests.html#test_execution_service">Test execution service</a>.</p>
+
+<h2 id=command_line_arguments>Command line arguments</h2>
+
+<p>The following table lists command line arguments that affect execution of all test programs. </p>
+
+<table width="100%">
+<col style="width:50%">
+<col style="width:50%">
+ <tr>
+ <th>Argument</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><code>
+--deqp-case=<casename></code></td>
+<td><p>Run cases that match a given pattern. Wildcard (*) is supported.</p>
+</td>
+ </tr>
+
+ <tr>
+ <td><code>
+--deqp-log-filename=<filename></code></td>
+<td><p>Write test results to the file whose name you provide. </p>
+<p>The test execution service will set the filename when starting a test.</p>
+</td>
+ </tr>
+
+ <tr>
+ <td><code>
+--deqp-stdin-caselist<br/>
+--deqp-caselist=<caselist><br/>
+--deqp-caselist-file=<filename></code></td>
+<td><p>Read case list from stdin or from a given argument. The test execution service
+will set the argument according to the execution request received. See the next
+section for a description of the case list format.</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+--deqp-test-iteration-count=<count></code></td>
+<td><p>Override iteration count for tests that support a variable number of
+iterations. </p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+--deqp-base-seed=<seed></code></td>
+<td><p>Base seed for the test cases that use randomization.</p>
+</td>
+ </tr>
+</table>
+
+<h3 id=gles2_and_gles3-specific_arguments>GLES2 and GLES3-specific arguments</h3>
+
+The following table lists the GLES2- and GLES3-specific arguments.
+
+<table>
+<table width="100%">
+<col style="width:50%">
+<col style="width:50%">
+ <tr>
+ <th>Argument</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>
+--deqp-gl-context-type=<type></code></td>
+<td><p>OpenGL context type. Available context types depend on the platform. On
+platforms supporting EGL, the value <code>egl</code> can be used to select the EGL context.</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+--deqp-gl-config-id=<id></code></td>
+<td><p>Run tests for the provided GL configuration ID. Interpretation is
+platform-dependent. On the EGL platform, this is the EGL configuration ID.</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+--deqp-gl-config-name=<name></code></td>
+<td><p>Run tests for a named GL configuration. Interpretation is platform-dependent.
+For EGL, the format is <code>rgb(a)<bits>d<bits>s<bits></code>. For example, a value of <code>rgb888s8</code> will select the first configuration where the color buffer is RGB888 and the
+stencil buffer has 8 bits.</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+--deqp-gl-context-flags=<flags></code></td>
+<td><p>Creates a context. Specify <code>robust</code> or <code>debug</code>.</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+--deqp-surface-width=<width><br/>
+--deqp-surface-height=<height></code></td>
+<td><p>Try to create a surface with a given size. Support for this is optional.</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+--deqp-surface-type=<type></code></td>
+<td><p>Use a given surface type as the main test rendering target. Possible types are <code>window</code>, <code>pixmap</code>, <code>pbuffer</code>, and <code>fbo</code>.</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+--deqp-screen-rotation=<rotation></code></td>
+<td><p>Screen orientation in increments of 90 degrees for platforms that support it.</p>
+</td>
+ </tr>
+</table>
+
+<h3 id=test_case_list_format>Test case list format</h3>
+
+<p>The test case list can be given in two formats. The first option is to list the
+full name of each test on a separate line in a standard ASCII file. As the test
+sets grow, the repetitive prefixes can be cumbersome. To avoid repeating the
+prefixes, use a trie (also known as a prefix tree) syntax shown below.</p>
+
+<pre>
+{nodeName{firstChild{…},…lastChild{…}}}
+</pre>
+
+<p>For example, please review the following:</p>
+
+<pre>
+{dEQP-EGL{config-list,create_context{rgb565_depth_stencil}}}
+</pre>
+
+<p>That list would translate into two test cases:</p>
+
+<pre>
+dEQP-EGL.config_list
+dEQP-EGL.create_context.rgb565_depth_stencil
+</pre>
+
+<h2 id=android>Android</h2>
+
+<p>The Android application package contains everything required, including the
+test execution service, test binaries, and data files. The test activity is a <code>NativeActivity </code>and it uses EGL, which requires Android 3.2 or later.</p>
+
+<p>The application package can be installed with the following command. The name shown is the name of the APK in the Android CTS package. The name depends on the build:</p>
+<pre>
+adb –d install –r com.drawelements.deqp.apk
+</pre>
+
+<p>To launch the test execution service and to setup port forwarding, use the
+following:</p>
+<pre>
+adb –d forward tcp:50016 tcp:50016
+adb –d shell am start –n com.drawelements.deqp/.execserver.ServiceStarter
+</pre>
+
+<p>Debug prints can be enabled by executing the following before starting the
+tests:</p>
+<pre>
+adb –d shell setprop log.tag.dEQP DEBUG
+</pre>
+
+<h3 id=executing_tests_on_android_without_android_cts>Executing tests on Android without Android CTS</h3>
+
+<p>If you want to manually start the test execution activity, construct an Android
+intent that targets <code>android.app.NativeActivity</code>. The activities can be found in the <code>com.drawelements.deqp</code> package. The command line must be supplied as an extra string with key <code>"cmdLine"</code> in the Intent.</p>
+
+<p>A test log will be written to <code>/sdcard/dEQP-log.qpa</code>. If the test run does not start normally, additional debug information is
+available in the device log.</p>
+
+<p>The activity can be launched from the command line using the <code>"am"</code> utility. For example, to run <code>dEQP-GLES2.info</code> tests on a platform supporting <code>NativeActivity,</code> the following command can be used:</p>
+
+<pre>
+adb -d shell am start -n com.drawelements.deqp/android.app.NativeActivity -e
+cmdLine "deqp --deqp-case=dEQP-GLES2.info.*
+--deqp-log-filename=/sdcard/dEQP-Log.qpa
+</pre>
+
+<h3 id=debugging_on_android>Debugging on Android</h3>
+
+<p>To run the tests under the GDB debugger on Android, first compile and install
+the debug build by running the following two scripts:</p>
+
+<pre>
+python android/scripts/build.py --native-build-type=Debug
+python android/scripts/install.py
+</pre>
+
+<p>After the debug build is installed on the device, to launch the tests under GDB
+running on the host, run the following command:</p>
+
+<pre>
+python android/scripts/debug.py
+--deqp-commandline="--deqp-log-filename=/sdcard/TestLog.qpa
+--deqp-case=dEQP-GLES2.functional.*"
+</pre>
+
+<p>The deqp command line will depend on test cases to be executed and other
+required parameters. The script will add a default breakpoint into the
+beginning of the deqp execution (<code>tcu::App::App</code>).</p>
+
+<p>The <code>debug.py </code>script accepts multiple command line arguments, e.g. for the following:</p>
+
+<ul>
+ <li> Setting the breakpoints for debugging
+ <li> gdbserver connection parameters
+ <li> Paths to additional binaries to debug
+</ul>
+
+<p>Running <code>debug.py --help</code> will list all command line parameters, with explanations.</p>
+
+<p>The script copies some default libraries from the target device to get symbol
+listings. </p>
+
+<p>If there is a need to step through driver code, more libraries can be added via <code>debug.py</code> command line parameters. This would be applicable, for
+example, if the GDB needs to know the locations of the binaries with full debug
+information. The <code>debug.py</code> script writes out a configuration file for the GDB starting from line 132 of
+the script file. Additional paths to binaries, etc., can be added there, but
+supplying correct command line parameters should be enough.</p>
+
+<p><strong>Notes:</strong></p>
+
+<ul>
+ <li> On Windows, the gdb binary requires <code>libpython2.7.dll</code>. Add
+<code><path to ndk>/prebuilt/windows/bin</code> to the PATH variable before launching <code>debug.py</code>.
+ <li> Native code debugging does not work on stock Android 4.3. See the Android bug
+report below for suggested workarounds. The bug has been fixed in Android 4.4;
+see the following: <a href="https://code.google.com/p/android/issues/detail?id=58373">https://code.google.com/p/android/issues/detail?id=58373</a>
+</ul>
diff --git a/src/devices/graphics/test-groups.jd b/src/devices/graphics/test-groups.jd
new file mode 100644
index 0000000..115f19a
--- /dev/null
+++ b/src/devices/graphics/test-groups.jd
@@ -0,0 +1,63 @@
+page.title=Using special test groups
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>Some test groups may need or support special command line options, or require
+special care when used on certain systems.</p>
+
+<h2 id=memory_allocation_stress_tests>Memory allocation stress tests</h2>
+
+<p>Memory allocation stress tests exercise out-of-memory conditions by repeatedly
+allocating certain resources until the driver reports an out-of-memory error.</p>
+
+<p>On certain platforms, such as Android and most Linux variants, the following
+can occur: The operating system may kill the test process instead of allowing a
+driver to handle or otherwise provide an out-of-memory error. On such
+platforms, tests that are designed to cause out-of-memory errors are disabled
+by default, and must be enabled using the <code>--deqp-test-oom=enable</code> command line argument.
+It is recommended that you run such tests manually to
+check if the system behaves correctly under resource pressure. However, in such
+a situation, a test process crash should be interpreted as a pass.</p>
+
+<h3 id=test_groups>Test groups</h3>
+
+<pre>
+dEQP-GLES2.stress.memory.*
+dEQP-GLES3.stress.memory.*
+</pre>
+
+<h2 id=long-running_rendering_stress_tests>Long-running rendering stress tests</h2>
+
+<p>Rendering stress tests are designed to reveal robustness issues under sustained
+rendering load. By default the tests will execute only a few iterations, but
+they can be configured to run indefinitely by supplying the <code>--deqp-test-iteration-count=-1</code> command line argument. The test watchdog should be disabled (<code>--deqp-watchdog=disable</code>) when running these tests for a long period of time.</p>
+
+<h3 id=test_groups2>Test groups</h3>
+
+<pre>
+dEQP-GLES2.stress.long.*
+dEQP-GLES3.stress.long.*
+</pre>
diff --git a/src/devices/graphics/testing.jd b/src/devices/graphics/testing.jd
new file mode 100644
index 0000000..56f4495
--- /dev/null
+++ b/src/devices/graphics/testing.jd
@@ -0,0 +1,158 @@
+page.title=OpenGL ES testing
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+
+<p>This page provides an overview of the GPU testing suite
+called deqp (drawElements Quality Program).</p>
+
+<p>You can access the code for deqp in AOSP at the following location: <a href="https://android.googlesource.com/platform/external/deqp">https://android.googlesource.com/platform/external/deqp</a></p>
+
+<p>To work with the latest submitted code, use the <code>deqp-dev</code> branch. If you want the code that matches the Android 5.0 CTS release, use the <code>lollipop-release</code> branch. </p>
+
+<h2 id=deploying_deqp>Deploying deqp</h2>
+
+<p>To deploy the deqp test suite to a new environment, please review the deqp information regarding the following: </p>
+
+<ul>
+ <li>Building test programs
+ <li>Porting the test framework (optional, depending on the target platform)
+ <li>Running the tests
+ <li>Automating the tests
+ <li>Using special test groups
+ <li>Integrating with Android CTS
+</ul>
+
+<h2 id=source_layout>Source layout</h2>
+
+<p>The source code layout for the deqp test modules and supporting libraries is shown in the table below. The listing is not complete but highlights the most important directories.</p>
+
+<table>
+ <tr>
+ <th>Directory</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>android</code></td>
+ <td><p>Android tester sources and build scripts</p></td>
+ </tr>
+ <tr>
+ <td><code>data</code></td>
+<td><p>Test data files</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>modules</code></td>
+<td><p>Test module sources</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+ modules/egl</code></td>
+<td><p>EGL module</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+ modules/gles2</code></td>
+<td><p>GLES2 module</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+ modules/gles3</code></td>
+<td><p>GLES3 module</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+ modules/gles31</code></td>
+<td><p>GLES3.1 module</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>targets</code></td>
+<td><p>Target-specific build configuration files</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>framework</code></td>
+<td><p>deqp test module framework and utilities</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+ framework/delibs</code></td>
+<td><p>Base portability and build libraries</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+ framework/platform</code></td>
+<td><p>Platform ports</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+ framework/qphelper</code></td>
+<td><p>Test program integration library (C)</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+ framework/common</code></td>
+<td><p>Deqp framework (C++)</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+ framework/opengl, framework/egl</code></td>
+<td><p>API-specific utilities</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+execserver</code></td>
+<td><p>Device-side ExecServer source</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+executor</code></td>
+<td><p>Host-side test executor shell tool and utilities</p>
+</td>
+ </tr>
+ <tr>
+ <td><code>
+external</code></td>
+<td><p>Build stub directory for external libs libpng and zlib</p>
+</td>
+ </tr>
+</table>
+
+<h3 id=open-source_components>Open Source components</h3>
+
+<p>The deqp uses <code>libpng</code> and <code>zlib</code>. They can be fetched from the web with the script <code>external/fetch_sources.py </code>or with git pulls from git repositories <code>platform/external/[libpng,zlib]</code>.</p>
diff --git a/src/devices/images/ape_fwk.png b/src/devices/images/ape_fwk.png
new file mode 100644
index 0000000..2bded87
--- /dev/null
+++ b/src/devices/images/ape_fwk.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_all.png b/src/devices/images/ape_fwk_all.png
new file mode 100644
index 0000000..4fa652c
--- /dev/null
+++ b/src/devices/images/ape_fwk_all.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_bluetooth.png b/src/devices/images/ape_fwk_bluetooth.png
new file mode 100644
index 0000000..c79fe5b
--- /dev/null
+++ b/src/devices/images/ape_fwk_bluetooth.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_drm.png b/src/devices/images/ape_fwk_drm.png
new file mode 100644
index 0000000..817d82f
--- /dev/null
+++ b/src/devices/images/ape_fwk_drm.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_drm_2.png b/src/devices/images/ape_fwk_drm_2.png
new file mode 100644
index 0000000..6d64e33
--- /dev/null
+++ b/src/devices/images/ape_fwk_drm_2.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_drm_plugins.png b/src/devices/images/ape_fwk_drm_plugins.png
new file mode 100644
index 0000000..4b475f5
--- /dev/null
+++ b/src/devices/images/ape_fwk_drm_plugins.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_drm_plugins_life.png b/src/devices/images/ape_fwk_drm_plugins_life.png
new file mode 100644
index 0000000..f234658
--- /dev/null
+++ b/src/devices/images/ape_fwk_drm_plugins_life.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_drm_retrieve_license.png b/src/devices/images/ape_fwk_drm_retrieve_license.png
new file mode 100644
index 0000000..38f12f7
--- /dev/null
+++ b/src/devices/images/ape_fwk_drm_retrieve_license.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_hal.png b/src/devices/images/ape_fwk_hal.png
new file mode 100644
index 0000000..e415c9b
--- /dev/null
+++ b/src/devices/images/ape_fwk_hal.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_hal_bluetooth.png b/src/devices/images/ape_fwk_hal_bluetooth.png
new file mode 100644
index 0000000..d39194e
--- /dev/null
+++ b/src/devices/images/ape_fwk_hal_bluetooth.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_hal_drm.png b/src/devices/images/ape_fwk_hal_drm.png
new file mode 100644
index 0000000..fc67294
--- /dev/null
+++ b/src/devices/images/ape_fwk_hal_drm.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_hal_media.png b/src/devices/images/ape_fwk_hal_media.png
new file mode 100644
index 0000000..3067947
--- /dev/null
+++ b/src/devices/images/ape_fwk_hal_media.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_media.png b/src/devices/images/ape_fwk_media.png
new file mode 100644
index 0000000..92a731b
--- /dev/null
+++ b/src/devices/images/ape_fwk_media.png
Binary files differ
diff --git a/src/devices/images/breadboard.jpg b/src/devices/images/breadboard.jpg
deleted file mode 100644
index f98422f..0000000
--- a/src/devices/images/breadboard.jpg
+++ /dev/null
Binary files differ
diff --git a/src/devices/images/display.jpg b/src/devices/images/display.jpg
deleted file mode 100644
index 9748ec3..0000000
--- a/src/devices/images/display.jpg
+++ /dev/null
Binary files differ
diff --git a/src/devices/images/pcb.jpg b/src/devices/images/pcb.jpg
deleted file mode 100644
index 10a2789..0000000
--- a/src/devices/images/pcb.jpg
+++ /dev/null
Binary files differ
diff --git a/src/devices/index.jd b/src/devices/index.jd
index 483c3b0..e433f1c 100644
--- a/src/devices/index.jd
+++ b/src/devices/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 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.
@@ -24,73 +24,95 @@
</div>
</div>
- <p>Android provides you with the freedom to implement your own device specifications
- and the drivers to support them. The hardware abstraction layer (HAL) gives you a
- standard way to create software hooks in between the Android
- platform stack and your hardware. In addition, the Android operating system
- is open-sourced to help you through your device's bringup.</p>
-
- <p>To ensure that your devices maintain a high level of quality and offers a consistent
- experience for your users, they must must also
- pass the tests in the compatibility test suite (CTS). CTS ensures that anyone
- building a device meets a quality standard that ensures apps run reliably well
- and gives users a good experience. For more information, see the
- <a href="{@docRoot}compatibility/index.html">Compatibility</a> section.</p>
-
- <h2>Android Low-Level System Architecture</h2>
-
-<p>Before you begin porting Android to your hardware, it is important to have an
-understanding of how Android works at a high level. Because your drivers and HAL code interact
-with many layers of Android code, this understanding can help you find
-your way through the many layers of code that are available to you through the AOSP
-(Android Open Source Project) source tree. The following diagram shows a system
-level view of how Android works:
+<p>
+Android gives you the freedom to implement your own device specifications and
+drivers. The hardware abstraction layer (HAL) provides a standard method for
+creating software hooks between the Android platform stack and your hardware.
+The Android operating system is also open source, so you can contribute your own
+interfaces and enhancements.
</p>
-<img src="images/system-architecture.png">
+<p>
+To ensure devices maintain a high level of quality and offer a consistent user
+experience, each device must pass tests in the compatibility test suite (CTS).
+The CTS verifies devices meet a quality standard that ensures apps run reliably
+and users have a good experience. For details on the CTS, see
+<a href="{@docRoot}compatibility/index.html">Compatibility</a>.
+</p>
+
+<h2 id="Android system architecture">Android system architecture</h2>
+
+<p>
+Before porting Android to your hardware, take a moment to understand the Android
+system architecture at a high level. Because your drivers and the HAL interact
+with Android, knowing how Android works can help you navigate the many layers of
+code in the Android Open Source Project (AOSP) source tree.
+</p>
+
+<img src="images/ape_fwk_all.png">
<p class="img-caption"><strong>Figure 1.</strong> Android System Architecture</p>
- <h4>Application framework</h4>
- <p>This is the level that most application developers concern themselves with. You should be
- aware of the APIs available to developers as many of them map 1:1 to the underlying HAL
- interfaces and can provide information as to how to implement your driver.
- </p>
-
- <h4>Binder IPC</h4>
- <p>
- The Binder Inter-Process Communication mechanism allows the application framework to
- cross process boundaries and call into the Android system services code. This basically allows
- high level framework APIs to interact with Android's system services. At the application framework level, all
- of this communication is hidden from the developer and things appear to "just work."
- </p>
-
- <h4>System services</h4>
- <p>Most of the functionality exposed through the application framework APIs must
- communicate with some sort of system service to access the underlying hardware. Services
- are divided into modular components with focused functionality
- such as the Window Manager, Search Service, or Notification Manager. System services are grouped
- into two buckets: system and media. The system services include things such as the Window or
- Notification Manager. The media services include all the services involved in playing and
- recording media.
- </p>
-
-<h4>Hardware abstraction layer (HAL)</h4>
-<p>The HAL serves as a standard interface that allows the Android system to call into the device
- driver layer while being agnostic about the lower-level implementations of your drivers and hardware.
- You must implement the corresponding HAL (and driver) for the particular piece of hardware that your product
- provides. Android does not mandate a standard interaction between your HAL implementation and your device drivers, so
- you have free reign to do what is best for your situation. However, you must abide by the contract
- defined in each hardware-specific HAL interface for the Android system to be able
- to correctly interact with your hardware. HAL implementations are typically built into
- shared library modules (<code>.so</code> files).
+<h3 id="Application framework">Application framework</h3>
+<p>
+The application framework is used most often by application developers. As a
+hardware developer, you should be aware of developer APIs as many map directly
+to the underlying HAL interfaces and can provide helpful information about
+implementing drivers.
</p>
-<h4>Linux Kernel</h4>
-<p>For the most part, developing your device drivers is the same as developing a typical Linux device driver.
- Android uses a specialized version of the Linux kernel with a few special additions such as
- wakelocks, a memory management system that is more agressive in preserving memory,
- the Binder IPC driver, and other features that are important for a mobile embedded platform like Android.
- These additions have less to do with driver development than with the system's functionality. You can use any version of the kernel that you want as long as it supports the required features, such as the binder driver. However, we recommend
- using the latest version of the Android kernel. For the latest Android kernel, see
- <a href="{@docRoot}source/building-kernels.html" >Building Kernels</a>.
+
+<h3 id="Binder IPC">Binder IPC</h3>
+<p>
+The Binder Inter-Process Communication (IPC) mechanism allows the application
+framework to cross process boundaries and call into the Android system services
+code. This enables high level framework APIs to interact with Android system
+services. At the application framework level, this communication is hidden from
+the developer and things appear to "just work."
</p>
+
+<h3 id="System services">System services</h3>
+<p>
+Functionality exposed by application framework APIs communicates with system
+services to access the underlying hardware. Services are modular, focused
+components such as Window Manager, Search Service, or Notification Manager.
+Android includes two groups of services: <em>system</em> (services such as
+Window Manager and Notification Manager) and <em>media</em> (services involved
+in playing and recording media).
+</p>
+
+<h3 id="Hardware Abstraction Layer">Hardware abstraction layer (HAL)</h3>
+<p>
+The HAL is a standard interface that allows the Android system to call into the
+device driver layer while being agnostic about the lower-level implementations
+of drivers and hardware.
+</p>
+
+<img src="images/ape_fwk_hal.png">
+
+<p class="img-caption"><strong>Figure 2.</strong> Hardware abstraction layer
+(HAL) components</p>
+
+<p>
+You must implement the corresponding HAL (and driver) for the specific hardware
+your product provides. HAL implementations are typically built into shared
+library modules (<code>.so</code> files). Android does not mandate a standard
+interaction between your HAL implementation and your device drivers, so you have
+free reign to do what is best for your situation. However, to enable the Android
+system to correctly interact with your hardware, you <strong>must</strong> abide
+by the contract defined in each hardware-specific HAL interface.
+</p>
+
+<h3 id="Linux kernel">Linux Kernel</h3>
+<p>
+Developing your device drivers is similar to developing a typical Linux device
+driver. Android uses a version of the Linux kernel with a few special additions
+such as wake locks (a memory management system that is more agressive in
+preserving memory), the Binder IPC driver, and other features important for a
+mobile embedded platform. These additions are primarily for system functionality
+and do not affect driver development.
+
+<p>
+You can use any version of the kernel as long as it supports the required
+features (such as the binder driver). However, we recommend using the latest
+version of the Android kernel. For details on the latest Android kernel, see <a href="{@docRoot}source/building-kernels.html" >Building Kernels</a>.
+</p>
\ No newline at end of file
diff --git a/src/devices/input/diagnostics.jd b/src/devices/input/diagnostics.jd
new file mode 100644
index 0000000..0fc7a3e
--- /dev/null
+++ b/src/devices/input/diagnostics.jd
@@ -0,0 +1,490 @@
+page.title=Dumpsys Input Diagnostics
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>The <code>dumpsys</code> input command dumps the state of the
+system’s input devices, such as keyboards and touchscreens, and the
+processing of input events.</p>
+
+<h2 id="input">Input</h2>
+<p>To dump the input system’s state, run the following command:</p>
+<pre>
+$ adb shell dumpsys input
+</pre>
+
+<h2 id="output">Output</h2>
+
+<p>The set of information reported varies depending on the version of Android
+but consists of three sections:</p>
+
+<ul>
+ <li> Event Hub State
+ <li> Input Reader State
+ <li> Input Dispatcher State
+</ul>
+
+<h3 id="event_hub_state">Event Hub State</h3>
+
+<pre><code>
+INPUT MANAGER (dumpsys input)
+
+Event Hub State:
+ BuiltInKeyboardId: -2
+ Devices:
+ -1: Virtual
+ Classes: 0x40000023
+ Path: <virtual>
+ Descriptor: a718a782d34bc767f4689c232d64d527998ea7fd
+ Location:
+ ControllerNumber: 0
+ UniqueId: <virtual>
+ Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
+ KeyLayoutFile: /system/usr/keylayout/Generic.kl
+ KeyCharacterMapFile: /system/usr/keychars/Virtual.kcm
+ ConfigurationFile:
+ HaveKeyboardLayoutOverlay: false
+ 1: msm8974-taiko-mtp-snd-card Headset Jack
+ Classes: 0x00000080
+ Path: /dev/input/event5
+ Descriptor: c8e3782483b4837ead6602e20483c46ff801112c
+ Location: ALSA
+ ControllerNumber: 0
+ UniqueId:
+ Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
+ KeyLayoutFile:
+ KeyCharacterMapFile:
+ ConfigurationFile:
+ HaveKeyboardLayoutOverlay: false
+ 2: msm8974-taiko-mtp-snd-card Button Jack
+ Classes: 0x00000001
+ Path: /dev/input/event4
+ Descriptor: 96fe62b244c555351ec576b282232e787fb42bab
+ Location: ALSA
+ ControllerNumber: 0
+ UniqueId:
+ Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
+ KeyLayoutFile: /system/usr/keylayout/msm8974-taiko-mtp-snd-card_Button_Jack.kl
+ KeyCharacterMapFile: /system/usr/keychars/msm8974-taiko-mtp-snd-card_Button_Jack.kcm
+ ConfigurationFile:
+ HaveKeyboardLayoutOverlay: false
+ 3: hs_detect
+ Classes: 0x00000081
+ Path: /dev/input/event3
+ Descriptor: 485d69228e24f5e46da1598745890b214130dbc4
+ Location:
+ ControllerNumber: 0
+ UniqueId:
+ Identifier: bus=0x0000, vendor=0x0001, product=0x0001, version=0x0001
+ KeyLayoutFile: /system/usr/keylayout/hs_detect.kl
+ KeyCharacterMapFile: /system/usr/keychars/hs_detect.kcm
+ ConfigurationFile:
+ HaveKeyboardLayoutOverlay: false
+ 4: touch_dev
+ Classes: 0x00000014
+ Path: /dev/input/event1
+ Descriptor: 4e2720e99bd2b59adae8529881343531fff7c98e
+ Location:
+ ControllerNumber: 0
+ UniqueId:
+ Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
+ KeyLayoutFile:
+ KeyCharacterMapFile:
+ ConfigurationFile: /system/usr/idc/touch_dev.idc
+ HaveKeyboardLayoutOverlay: false
+ 5: qpnp_pon
+ Classes: 0x00000001
+ Path: /dev/input/event0
+ Descriptor: fb60d4f4370f5dbe8267b63d38dea852987571ab
+ Location: qpnp_pon/input0
+ ControllerNumber: 0
+ UniqueId:
+ Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
+ KeyLayoutFile: /system/usr/keylayout/qpnp_pon.kl
+ KeyCharacterMapFile: /system/usr/keychars/qpnp_pon.kcm
+ ConfigurationFile:
+ HaveKeyboardLayoutOverlay: false
+ 6: gpio-keys
+ Classes: 0x00000081
+ Path: /dev/input/event2
+ Descriptor: d2c52ff0f656fac4cd7b7a118d575e0109a9fe1c
+ Location: gpio-keys/input0
+ ControllerNumber: 0
+ UniqueId:
+ Identifier: bus=0x0019, vendor=0x0001, product=0x0001, version=0x0100
+ KeyLayoutFile: /system/usr/keylayout/gpio-keys.kl
+ KeyCharacterMapFile: /system/usr/keychars/gpio-keys.kcm
+ ConfigurationFile:
+ HaveKeyboardLayoutOverlay: false
+</code></pre>
+
+<h4 id="things-to-look-for">Things to check</h4>
+
+<ul>
+ <li> All of the expected input devices are present.</li>
+
+ <li> 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.</li>
+
+ <li> Each input device is being classified correctly. The bits in the
+ <code>Classes</code> field correspond to flags in <code>EventHub.h</code> such
+ as <code>INPUT_DEVICE_CLASS_TOUCH_MT</code>.</li>
+
+ <li> The <code>BuiltInKeyboardId</code> is correct. If the device does not
+ have a built-in keyboard, then the id must be <code>-2</code>, otherwise it
+ should be the id of the built-in keyboard.</li>
+
+ <li>If you observe that the <code>BuiltInKeyboardId</code> is not
+ <code>-2</code> 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 <code>type
+ SPECIAL_FUNCTION</code> (that's what in the <code>tuna-gpio-keykad.kcm</code>
+ file we see mentioned above).</li>
+</ul>
+
+<h3 id="input-reader-state">Input Reader State</h3>
+<p>The <code>InputReader</code> 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 have occurred, such as key presses or touches on
+the touch screen.</p>
+
+<p>As an example, this is what a special function keypad looks like:</p>
+
+<pre>
+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
+</pre>
+
+<p>Here is a touch screen. Notice all of the information about the resolution of
+the device and the calibration parameters that were used.</p>
+
+<pre>
+Input Reader State
+...
+ 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
+</pre>
+
+<p>Here is an external keyboard / mouse combo HID device. (This device doesn't actually
+have a mouse but its HID descriptor says it does.)</p>
+
+<pre><code> 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
+</code></pre>
+<p>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.</p>
+<pre><code>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
+</code></pre>
+<p>At the end of the input reader dump there is some information about global configuration
+parameters such as the mouse pointer speed.</p>
+<pre><code> 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
+</code></pre>
+<h4 id="things-to-look-for_1">Things To Look For</h4>
+<ol>
+<li>
+<p>All of the expected input devices are present.</p>
+</li>
+<li>
+<p>Each input device has been configured appropriately. Especially check the
+ touch screen and joystick axes.</p>
+</li>
+</ol>
+<h3 id="input-dispatcher-state">Input Dispatcher State</h3>
+<p>The <code>InputDispatcher</code> 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.</p>
+<pre>
+Input Dispatcher State:
+ DispatchEnabled: 1
+ DispatchFrozen: 0
+ FocusedApplication: <null>
+ FocusedWindow: name='Window{3fb06dc3 u0 StatusBar}'
+ TouchStates: <no displays touched>
+ Windows:
+ 0: name='Window{357bbbfe u0 SearchPanel}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01820100, type=0x000007e8, layer=211000, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms
+ 1: name='Window{3b14c0ca u0 NavigationBar}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01840068, type=0x000007e3, layer=201000, frame=[0,1776][1080,1920], scale=1.000000, touchableRegion=[0,1776][1080,1920], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms
+ 2: name='Window{2c7e849c u0 com.vito.lux}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x0089031a, type=0x000007d6, layer=191000, frame=[-495,-147][1575,1923], scale=1.000000, touchableRegion=[-495,-147][1575,1923], inputFeatures=0x00000000, ownerPid=4697, ownerUid=10084, dispatchingTimeout=5000.000ms
+ 3: name='Window{31c9f22 u0 Heads Up}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01820328, type=0x000007de, layer=161000, frame=[0,0][1794,750], scale=1.000000, touchableRegion=[0,0][1794,192], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms
+ 4: name='Window{3fb06dc3 u0 StatusBar}', displayId=0, paused=false, hasFocus=true, hasWallpaper=false, visible=true, canReceiveKeys=true, flags=0x81960040, type=0x000007d0, layer=151000, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000004, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms
+ 5: name='Window{278c1d65 u0 KeyguardScrim}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01110900, type=0x000007ed, layer=131000, frame=[0,0][1080,1776], scale=1.000000, touchableRegion=[0,0][1080,1776], inputFeatures=0x00000000, ownerPid=745, ownerUid=1000, dispatchingTimeout=5000.000ms
+ 6: name='Window{869f213 u0 com.android.systemui.ImageWallpaper}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x00000318, type=0x000007dd, layer=21025, frame=[0,0][2328,1920], scale=1.000000, touchableRegion=[0,0][2328,1920], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms
+ 7: name='Window{16ab6320 u0 InputMethod}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01800108, type=0x000007db, layer=21020, frame=[0,75][1080,1920], scale=1.000000, touchableRegion=[0,986][1080,1920], inputFeatures=0x00000000, ownerPid=8409, ownerUid=10056, dispatchingTimeout=5000.000ms
+ 8: name='Window{cf4ff0b u0 com.google.android.googlequicksearchbox/com.google.android.launcher.GEL}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x81910120, type=0x00000001, layer=21015, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=14722, ownerUid=10022, dispatchingTimeout=5000.000ms
+ 9: name='Window{1a7be08a u0 com.android.systemui/com.android.systemui.recents.RecentsActivity EXITING}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x81910120, type=0x00000001, layer=21010, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms
+ 10: name='Window{2280455f u0 com.google.android.gm/com.google.android.gm.ConversationListActivityGmail}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x81810120, type=0x00000001, layer=21005, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=9897, ownerUid=10070, dispatchingTimeout=5000.000ms
+ 11: name='Window{657fee5 u0 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01810520, type=0x00000001, layer=21000, frame=[0,0][1080,1776], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=3189, ownerUid=10085, dispatchingTimeout=5000.000ms
+ MonitoringChannels:
+ 0: 'WindowManager (server)'
+ RecentQueue: length=10
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (335.0, 1465.0)]), policyFlags=0x62000000, age=217264.0ms
+ MotionEvent(deviceId=4, source=0x00001002, action=1, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (335.0, 1465.0)]), policyFlags=0x62000000, age=217255.7ms
+ MotionEvent(deviceId=4, source=0x00001002, action=0, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (330.0, 1283.0)]), policyFlags=0x62000000, age=216805.0ms
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (330.0, 1287.0)]), policyFlags=0x62000000, age=216788.3ms
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (331.0, 1297.0)]), policyFlags=0x62000000, age=216780.0ms
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (332.0, 1316.0)]), policyFlags=0x62000000, age=216771.6ms
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (333.0, 1340.0)]), policyFlags=0x62000000, age=216763.3ms
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (333.0, 1362.0)]), policyFlags=0x62000000, age=216755.0ms
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (332.0, 1384.0)]), policyFlags=0x62000000, age=216747.2ms
+ MotionEvent(deviceId=4, source=0x00001002, action=1, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (332.0, 1384.0)]), policyFlags=0x62000000, age=216738.9ms
+ PendingEvent: <none>
+ InboundQueue: <empty>
+ ReplacedKeys: <empty>
+ Connections:
+ 0: channelName='WindowManager (server)', windowName='monitor', status=NORMAL, monitor=true, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 1: channelName='278c1d65 KeyguardScrim (server)', windowName='Window{278c1d65 u0 KeyguardScrim}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 2: channelName='357bbbfe SearchPanel (server)', windowName='Window{357bbbfe u0 SearchPanel}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 3: channelName='869f213 com.android.systemui.ImageWallpaper (server)', windowName='Window{869f213 u0 com.android.systemui.ImageWallpaper}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 4: channelName='3fb06dc3 StatusBar (server)', windowName='Window{3fb06dc3 u0 StatusBar}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 5: channelName='2c7e849c (server)', windowName='Window{2c7e849c u0 com.vito.lux}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 6: channelName='cf4ff0b com.google.android.googlequicksearchbox/com.google.android.launcher.GEL (server)', windowName='Window{cf4ff0b
+u0 com.google.android.googlequicksearchbox/com.google.android.launcher.GEL}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 7: channelName='2280455f com.google.android.gm/com.google.android.gm.ConversationListActivityGmail (server)', windowName='Window{2280455f u0 com.google.android.gm/com.google.android.gm.ConversationListActivityGmail}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 8: channelName='1a7be08a com.android.systemui/com.android.systemui.recents.RecentsActivity (server)', windowName='Window{1a7be08a u0 com.android.systemui/com.android.systemui.recents.RecentsActivity EXITING}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 9: channelName='3b14c0ca NavigationBar (server)', windowName='Window{3b14c0ca u0 NavigationBar}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 10: channelName='16ab6320 InputMethod (server)', windowName='Window{16ab6320 u0 InputMethod}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 11: channelName='657fee5 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell (server)', windowName='Window{657fee5 u0 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 12: channelName='31c9f22 Heads Up (server)', windowName='Window{31c9f22 u0 Heads Up}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ AppSwitch: not pending
+ 7: channelName='2280455f com.google.android.gm/com.google.android.gm.ConversationListActivityGmail (server)', windowName='Window{2280455f u0 com.google.android.gm/com.google.android.gm.ConversationListActivityGmail}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 8: channelName='1a7be08a com.android.systemui/com.android.systemui.recents.RecentsActivity (server)', windowName='Window{1a7be08a u0 com.android.systemui/com.android.systemui.recents.RecentsActivity EXITING}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 9: channelName='3b14c0ca NavigationBar (server)', windowName='Window{3b14c0ca u0 NavigationBar}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 10: channelName='16ab6320 InputMethod (server)', windowName='Window{16ab6320 u0 InputMethod}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 11: channelName='657fee5 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell (server)', windowName='Window{657fee5 u0 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 12: channelName='31c9f22 Heads Up (server)', windowName='Window{31c9f22 u0 Heads Up}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ AppSwitch: not pending
+ Configuration:
+ KeyRepeatDelay: 50.0ms
+ KeyRepeatTimeout: 500.0ms
+</pre>
+<h4 id="things-to-look-for_2">Things To Look For</h4>
+<ol>
+ <li> In general, all input events are being processed as expected. </li>
+ <li> If you touch the touch screen and run dumpsys at the same time,
+ then the <code>TouchStates</code> line should show the window that
+ you are touching. </li>
+</ol>
+
diff --git a/src/devices/tech/input/getevent.jd b/src/devices/input/getevent.jd
similarity index 100%
rename from src/devices/tech/input/getevent.jd
rename to src/devices/input/getevent.jd
diff --git a/src/devices/input/images/ape_fwk_hal_input.png b/src/devices/input/images/ape_fwk_hal_input.png
new file mode 100644
index 0000000..e5706f7
--- /dev/null
+++ b/src/devices/input/images/ape_fwk_hal_input.png
Binary files differ
diff --git a/src/devices/tech/input/index.jd b/src/devices/input/index.jd
similarity index 71%
rename from src/devices/tech/input/index.jd
rename to src/devices/input/index.jd
index 80c5e5f..8dd1508 100644
--- a/src/devices/tech/input/index.jd
+++ b/src/devices/input/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -16,7 +16,9 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
+
+<img style="float: right; margin: 0px 135px 15px 15px;" src="images/ape_fwk_hal_input.png" alt="Android Input HAL icon"/>
+
<p>The Android input subsystem supports many different device classes,
-including keyboard, joystick, trackball, mouse and touch screen.</p>
-<p>The documentation in this section describes how to configure,
+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.</p>
diff --git a/src/devices/tech/input/input-device-configuration-files.jd b/src/devices/input/input-device-configuration-files.jd
similarity index 100%
rename from src/devices/tech/input/input-device-configuration-files.jd
rename to src/devices/input/input-device-configuration-files.jd
diff --git a/src/devices/tech/input/key-character-map-files.jd b/src/devices/input/key-character-map-files.jd
similarity index 100%
rename from src/devices/tech/input/key-character-map-files.jd
rename to src/devices/input/key-character-map-files.jd
diff --git a/src/devices/tech/input/key-layout-files.jd b/src/devices/input/key-layout-files.jd
similarity index 100%
rename from src/devices/tech/input/key-layout-files.jd
rename to src/devices/input/key-layout-files.jd
diff --git a/src/devices/tech/input/keyboard-devices.jd b/src/devices/input/keyboard-devices.jd
similarity index 100%
rename from src/devices/tech/input/keyboard-devices.jd
rename to src/devices/input/keyboard-devices.jd
diff --git a/src/devices/tech/input/migration-guide.jd b/src/devices/input/migration-guide.jd
similarity index 100%
rename from src/devices/tech/input/migration-guide.jd
rename to src/devices/input/migration-guide.jd
diff --git a/src/devices/tech/input/overview.jd b/src/devices/input/overview.jd
similarity index 100%
rename from src/devices/tech/input/overview.jd
rename to src/devices/input/overview.jd
diff --git a/src/devices/tech/input/touch-devices.jd b/src/devices/input/touch-devices.jd
similarity index 100%
rename from src/devices/tech/input/touch-devices.jd
rename to src/devices/input/touch-devices.jd
diff --git a/src/devices/tech/input/validate-keymaps.jd b/src/devices/input/validate-keymaps.jd
similarity index 97%
rename from src/devices/tech/input/validate-keymaps.jd
rename to src/devices/input/validate-keymaps.jd
index c86c49e..6a907a1 100644
--- a/src/devices/tech/input/validate-keymaps.jd
+++ b/src/devices/input/validate-keymaps.jd
@@ -25,7 +25,7 @@
<pre><code>$ mmm frameworks/base/tools/validatekeymaps
</code></pre>
<p>This command should compile a host tool called validatekeymaps into the
-<code>out/host/&lt;os&gt;/bin</code> directory.</p>
+<code>out/host/<os>/bin</code> directory.</p>
<h2 id="usage">Usage</h2>
<p>If you ran <code>envsetup.sh</code> to set up your development environment, then the
<code>validatekeymaps</code> tool should already be on your path. You can verify
diff --git a/src/devices/media.jd b/src/devices/media.jd
index 69ba702..166ba59 100644
--- a/src/devices/media.jd
+++ b/src/devices/media.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -24,20 +24,19 @@
</div>
</div>
+<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_media.png" alt="Android Media HAL icon"/>
+
<p>
- Android provides a media playback engine at the native level called Stagefright that comes built-in with
- software-based codecs for several popular media formats. Stagefright features for audio and video playback
- include integration with OpenMAX codecs, session management, time-synchronized rendering, transport control,
- and DRM. In addition, Stagefright supports integration with custom hardware codecs that you provide.
- There actually isn't a HAL to implement for custom codecs, but to provide a hardware path to encode and
- decode media, you must implement your hardware-based codec as an OpenMax IL (Integration Layer) component.
-</p>
-<h2 id="overview">
-Overview
-</h2>
+ Android provides a media playback engine at the native level called Stagefright that comes built-in with software-based codecs for several popular media formats. Stagefright features for audio and video playback include integration with OpenMAX codecs, session management, time-synchronized rendering, transport control, and DRM.</p>
+ <p>In addition, Stagefright supports integration with custom hardware codecs that you provide.
+ There actually isn't a HAL to implement for custom codecs, but to provide a hardware path to encode and decode media, you must implement your hardware-based codec as an OpenMax IL (Integration Layer) component.</p>
+
+
+<h2 id="architecture">Architecture</h2>
<p>The following diagram shows how media applications interact with the Android native multimedia framework.</p>
-<p>
- <img src="images/media.png">
+ <img src="images/ape_fwk_media.png" alt="Android media architecture" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> Media architecture
</p>
<dl>
<dt>Application Framework</dt>
diff --git a/src/devices/sensors/images/ape_fwk_hal_sensors.png b/src/devices/sensors/images/ape_fwk_hal_sensors.png
new file mode 100644
index 0000000..d5b5be8
--- /dev/null
+++ b/src/devices/sensors/images/ape_fwk_hal_sensors.png
Binary files differ
diff --git a/src/devices/sensors/images/ape_fwk_sensors.png b/src/devices/sensors/images/ape_fwk_sensors.png
new file mode 100644
index 0000000..fcd240a
--- /dev/null
+++ b/src/devices/sensors/images/ape_fwk_sensors.png
Binary files differ
diff --git a/src/devices/sensors/index.jd b/src/devices/sensors/index.jd
index dea285b..537025e 100644
--- a/src/devices/sensors/index.jd
+++ b/src/devices/sensors/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 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.
@@ -23,27 +23,14 @@
</ol>
</div>
</div>
+<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_sensors.png" alt="Android Sensors HAL icon"/>
- <h2 id="what_are_“android_sensors”">What are Android sensors?</h2>
- <p>Android sensors give applications access to a mobile device's underlying
- physical sensors. They are data-providing virtual devices defined by the
- implementation of <a
- href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a>,
- the sensor Hardware Abstraction Layer (HAL).</p>
- <ul>
- <li> Those virtual devices provide data coming from a set of physical sensors:
- accelerometers, gyroscopes, magnetometers, barometer, humidity, pressure,
- light, proximity and heart rate sensors.</li>
- <li> Notably, camera, fingerprint sensor, microphone and touch screen are currently
- not in the list of physical devices providing data through “Android sensors.”
- They have their own reporting mechanism.</li>
- <li> The separation is arbitrary, but in general, Android sensors provide lower
- bandwidth data. For example, “100hz x 3 channels” for an accelerometer versus
- “25hz x 8 MP x 3 channels” for a camera or “44kHz x 1 channel” for a
- microphone.</li>
- </ul>
- <p>How the different physical sensors are connected to the system on chip
- (SoC) is not defined by Android.</p>
+<p>Android sensors give applications access to a mobile device's underlying physical sensors. They are data-providing virtual devices defined by <a href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a>, the sensor Hardware Abstraction Layer (HAL).</p>
+
+<h2 id="what_are_“android_sensors”">What are Android sensors?</h2>
+<p>Android sensors are virtual devices that provide data coming from a set of physical sensors: accelerometers, gyroscopes, magnetometers, barometer, humidity, pressure, light, proximity and heart rate sensors.</p>
+<p>Not included in the list of physical devices providing data are camera, fingerprint sensor, microphone, and touch screen. These devices have their own reporting mechanism; the separation is arbitrary, but in general, Android sensors provide lower bandwidth data. For example, “100hz x 3 channels” for an accelerometer versus “25hz x 8 MP x 3 channels” for a camera or “44kHz x 1 channel” for a microphone.</p>
+ <p>Android does not define how the different physical sensors are connected to the system on chip (SoC).</p>
<ul>
<li> Often, sensor chips are connected to the SoC through a <a href="sensor-stack.html#sensor_hub">sensor hub</a>, allowing some low-power monitoring and processing of the data. </li>
<li> Often, Inter-Integrated Circuit (I2C) or Serial Peripheral Interface
diff --git a/src/devices/sensors/sensor-stack.jd b/src/devices/sensors/sensor-stack.jd
index 5ffcce8..7ff41bc 100644
--- a/src/devices/sensors/sensor-stack.jd
+++ b/src/devices/sensors/sensor-stack.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 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.
@@ -29,7 +29,7 @@
sensors can bypass the sensor hub when it is present. Control flows from the
applications down to the sensors, and data flows from the sensors up to the
applications.</p>
-<img src="images/sensor_layers.png" alt="Layers and owners of the Android sensor stack" />
+<img src="images/ape_fwk_sensors.png" alt="Layers and owners of the Android sensor stack" />
<p class="img-caption"><strong>Figure 1.</strong> Layers of the Android sensor stack and their respective owners</p>
<h2 id="sdk">SDK</h2>
diff --git a/src/devices/tech/storage/config-example.jd b/src/devices/storage/config-example.jd
similarity index 100%
rename from src/devices/tech/storage/config-example.jd
rename to src/devices/storage/config-example.jd
diff --git a/src/devices/tech/storage/config.jd b/src/devices/storage/config.jd
similarity index 100%
rename from src/devices/tech/storage/config.jd
rename to src/devices/storage/config.jd
diff --git a/src/devices/storage/images/ape_fwk_hal_extstor.png b/src/devices/storage/images/ape_fwk_hal_extstor.png
new file mode 100644
index 0000000..618cba2
--- /dev/null
+++ b/src/devices/storage/images/ape_fwk_hal_extstor.png
Binary files differ
diff --git a/src/devices/tech/storage/index.jd b/src/devices/storage/index.jd
similarity index 96%
rename from src/devices/tech/storage/index.jd
rename to src/devices/storage/index.jd
index 1d7192d..e8786ec 100644
--- a/src/devices/tech/storage/index.jd
+++ b/src/devices/storage/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 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.
@@ -17,6 +17,7 @@
limitations under the License.
-->
+<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_extstor.png" alt="Android external storage HAL icon"/>
<p>Android supports devices with external storage, which is defined to be a
case-insensitive filesystem with immutable POSIX permission classes and
diff --git a/src/devices/tech/dalvik/configure.jd b/src/devices/tech/dalvik/configure.jd
new file mode 100644
index 0000000..052c87f
--- /dev/null
+++ b/src/devices/tech/dalvik/configure.jd
@@ -0,0 +1,418 @@
+page.title=Configuring ART
+@jd:body
+
+<!--
+ Copyright 2014 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.
+-->
+
+
+<div id="qv-wrapper">
+<div id="qv">
+ <h2 id="Contents">In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+</div>
+</div>
+
+<h2 id=introduction>Introduction</h2>
+
+<p>This document is intended to discuss how to configure ART and its compilation
+options. Topics addressed here include configuration of pre-compilation of the
+system image, dex2oat compilation options at first boot (and post-OTA), and how
+to trade off system partition space, data partition space, and performance.</p>
+
+<p>See <a href="http://source.android.com/devices/tech/dalvik/index.html">ART
+and Dalvik</a>, the <a
+href="http://source.android.com/devices/tech/dalvik/dex-format.html">Dalvik
+Executable format</a>, and the remaining pages on source.android.com to work
+with ART. See <a
+href="http://developer.android.com/guide/practices/verifying-apps-art.html">Verifying
+App Behavior on the Android Runtime (ART)</a> to ensure your apps work
+properly.</p>
+
+<h2 id=how_art_works>How ART works</h2>
+
+<p>ART is the new Android runtime for the Android 5.0 (Lollipop or L) release and
+beyond. Dalvik is no longer available. </p>
+
+<p>Please note, this section merely summarizes ART’s configuration. For an
+in-depth description, see the <a
+href="https://www.google.com/events/io/io14videos/b750c8da-aebe-e311-b297-00155d5066d7">Android
+runtime</a> presentation conducted at Google I/O 2014. </p>
+
+<p>ART uses ahead-of-time (AOT) compilation. This means that, at installation, dex
+code is compiled to native code in OAT files, which replace Dalvik’s odex
+files. This has several implications:</p>
+
+<ul>
+ <li> Performance is improved over Dalvik. There is also a commensurate improvement
+in power consumption measured in the lab.
+ <li> There is no runtime code cache. The OAT files are mapped to memory (and are
+thus page-able). The RAM memory footprint for OAT files might seem larger in
+terms of Proportional Set Size (PSS, or the memory shared across processes
+divided evenly between the processes). But because they are pageable we have
+found the system impact is improved in terms of real memory pressure effects as
+the Dalvik JIT cache was not pageable.
+ <li> Similar to preloaded classes in the zygote, ART attempts to pre-initialize a
+set of classes at compile time. This creates a ‘boot.art’ file that comprises
+an image of the compacted heap of pre-initialized classes and related objects.
+This file is mapped into memory upon zygote startup. While this consumes
+additional storage (typically 10MB), it speeds zygote startup and creates
+opportunities for the system to swap out some preloaded classes under memory
+pressure. This also contributes to improved <a
+href="http://source.android.com/devices/low-ram.html">low-RAM</a> performance
+for ART, since in Dalvik much of this class information would have
+been stored in dirty pages in the linear alloc space.
+ <li> Dex file compilation uses a tool called dex2oat and takes more time than
+dexopt. The increase in time varies, but 2-3x increases in compile time are not
+unusual. For example, apps that typically take a second to install using dexopt
+might take 2-3 seconds.
+ <li> OAT files are larger than odex files if full compilation is enabled. We discuss
+options to mitigate this cost later in this document.
+</ul>
+
+<h2 id=compilation_options>Compilation options</h2>
+
+<p>Dex file compilation takes more time than dexopt, which can be noticeable when
+all of a user’s apps must be compiled during first boot (after factory reset or
+after receiving an OTA). To reduce the amount of compilation needed, ART
+supports the option of pre-optimizing libraries and applications in the system
+partition. Including the pre-optimized dex files takes space in the system
+image, so these options trade first boot time for system image size. Note that
+OTAs are relatively infrequent and subsequent boot times should be the same
+with or without pre-optimization.</p>
+
+<h3 id=undefined>WITH_DEXPREOPT</h3>
+
+<p>Pre-optimization is controlled by the build option
+<code>WITH_DEXPREOPT</code>. Before the L release, this was enabled by default
+in “user” builds. Starting in L, this option is opt-in and needs to be enabled
+in the product configuration such as a device’s BoardConfig.mk file.</p>
+
+<p>Enabling <code>WITH_DEXPREOPT</code> causes everything in the system image to be
+pre-optimized. If this makes the system image too large, additional options can
+be specified to reduce the amount of pre-optimization. Note that all the
+following build options with “PREOPT” in the name must have <code>WITH_DEXPREOPT</code>
+enabled to work.</p>
+
+<p>Example usage (in product’s BoardConfig.mk):</p>
+
+<pre><code>WITH_DEXPREOPT := true</code></pre>
+
+<h3 id=dont_dexpreopt_prebuilts>DONT_DEXPREOPT_PREBUILTS</h3>
+
+<p>Enabling <code>DONT_DEXPREOPT_PREBUILTS</code> prevents the prebuilts from being
+pre-optimized. These are apps that have <code>include $(BUILD_PREBUILT)</code> specified
+in their Android.mk, such as Gmail. Skipping pre-optimization of prebuilt apps
+that are likely to be updated via Google Play saves /system space but does add
+to first boot time.</p>
+
+<p>Example usage (in product’s BoardConfig.mk):</p>
+
+<pre><code>WITH_DEXPREOPT := true
+DONT_DEXPREOPT_PREBUILTS := true</code></pre>
+
+<h3 id=with_dexpreopt_boot_img_only>WITH_DEXPREOPT_BOOT_IMG_ONLY</h3>
+
+<p>Enabling <code>WITH_DEXPREOPT_BOOT_IMG_ONLY</code> only pre-optimizes the
+boot image, which consists of boot.art with the image classes and boot.oat with
+code for the boot classpath. Enabling this saves significant /system space but
+means all apps will be optimized at first boot. Typically it is better to
+selectively disable app pre-optimization via
+<code>DONT_DEXPREOPT_PREBUILTS</code> or add-product-dex-preopt-module-config.</p>
+
+<p>Example usage (in product’s BoardConfig.mk):</p>
+
+<pre><code>WITH_DEXPREOPT := true
+WITH_DEXPREOPT_BOOT_IMG_ONLY := true</code></pre>
+
+<h3 id=local_dex_preopt>LOCAL_DEX_PREOPT</h3>
+
+<p>Pre-optimization can also be enabled or disabled on an individual app basis by
+specifying the <code>LOCAL_DEX_PREOPT</code> option in the module definition.
+This can be useful for disabling pre-optimization of apps that may immediately
+receive Google Play updates since the updates would render the pre-optimized
+code in the system image obsolete. This is also useful to save space on major
+version upgrade OTAs since users may already have newer versions of apps in the
+data partition.</p>
+
+<p><code>LOCAL_DEX_PREOPT</code> supports the values ‘true’ or ‘false’ to
+enable or disable pre-optimization respectively. In addition, ‘nostripping’ can
+be specified if pre-optimization should not strip the classes.dex file from the
+apk or jar file. Normally this file is stripped since it’s no longer needed
+after pre-optimization, but this last option is necessary to allow third-party
+APK signatures to remain valid.</p>
+
+<p>Example usage (in app’s Android.mk):</p>
+
+<pre><code>LOCAL_DEX_PREOPT := false</code></pre>
+
+<h3 id=product_dex_preopt_*>PRODUCT_DEX_PREOPT_*</h3>
+
+<p>Beginning post-L release in the Android Open Source Project (AOSP), a number of
+flags have been added that give further control to how pre-optimization is
+done. <code>PRODUCT_DEX_PREOPT_BOOT_FLAGS</code> passes options to dex2oat to control how
+the boot image is compiled. It can be used to specify customized image classes
+lists, compiled classes lists, and compiler filters, all of which are described
+in later sections. Similarly, <code>PRODUCT_DEX_PREOPT_DEFAULT_FLAGS</code>
+controls default flags to pass to dex2oat for compilation of everything besides
+the boot image, namely jar and apk files.</p>
+
+<p><code>PRODUCT_DEX_PREOPT_MODULE_CONFIGS</code> provides the ability to pass
+dex2oat options for a particular module and product configuration. It is set in
+a product’s device.mk file by <code>$(call
+add-product-dex-preopt-module-config,<modules>,<option>)</code>
+where <modules> is a list of <code>LOCAL_MODULE</code> and
+<code>LOCAL_PACKAGE</code> names for jar and apk files respectively. Through
+this flag, it is possible to have fine-grained control of pre-optimization for
+each dex file and a specific device. Such tuning allows /system space to be
+maximally used to improve first boot time.</p>
+
+<p>Example usage (in product’s device.mk):</p>
+
+<pre><code>PRODUCT_DEX_PREOPT_DEFAULT_FLAGS := --compiler-filter=interpret-only
+$(call add-product-dex-preopt-module-config,services,--compiler-filter=space)</code></pre>
+
+<h2 id=preloaded_classes_list>Preloaded Classes List</h2>
+
+<p>The preloaded classes list is a list of classes the zygote will initialize on
+startup. This saves each app from having to run these class initializers
+separately, allowing them to start up faster and share pages in memory. The
+preloaded classes list file is located at frameworks/base/preloaded-classes by
+default, and it contains a list that is tuned for typical phone use. This may
+be different for other devices, such as wearables, and should be tuned
+accordingly. Be careful when tuning this since adding too many classes wastes
+memory loading unused classes; meanwhile, adding too few forces each app to
+have to have its own copy, again wasting memory.</p>
+
+<p>Example usage (in product’s device.mk):</p>
+
+<pre><code>PRODUCT_COPY_FILES += <filename>:system/etc/preloaded-classes</code></pre>
+
+<p class="note"><strong>Note:</strong> This line must be placed before
+inheriting any product configuration makefiles that get the default one from
+build/target/product/base.mk.</p>
+
+<h2 id=image_classes_list>Image Classes List</h2>
+
+<p>The image classes list is a list of classes that dex2oat initializes ahead of
+time and stores in the boot.art file. This allows the zygote to load these
+results out of the boot.art file on startup instead of running the initializers
+for these classes itself during preloading. A key feature of this is that the
+pages loaded from the image and shared between processes can be clean, allowing
+them to be swapped out easily in low-memory situations. In L, by default the
+image classes list uses the same list as the preloaded classes list. Beginning
+post-L in AOSP, a custom image classes list can be specified using
+<code>PRODUCT_DEX_PREOPT_BOOT_FLAGS</code>.</p>
+
+<p>Example usage (in product’s device.mk):</p>
+
+<pre><code>PRODUCT_DEX_PREOPT_BOOT_FLAGS += --image-classes=<filename></code></pre>
+
+<h2 id=compiled_classes_list>Compiled Classes List</h2>
+
+<p>In post-L AOSP, a subset of classes from the boot classpath can be specified to
+be compiled during pre-optimization using the compiled classes list. This can
+be a useful option for devices that are very tight on space and can’t fit the
+entire pre-optimized boot image. However, note classes not specified by this
+list will not be compiled - not even on the device - and must be interpreted,
+potentially affecting runtime performance. By default, dex2oat will look for a
+compiled classes list in $OUT/system/etc/compiled-classes, so a custom one can
+be copied to that location by the device.mk. A particular file location can
+also be specified using <code>PRODUCT_DEX_PREOPT_BOOT_FLAGS</code>.</p>
+
+<p>Example usage (in product’s device.mk):</p>
+
+<pre><code>PRODUCT_COPY_FILES += <filename>:system/etc/compiled-classes</code></pre>
+
+<p class="note"><strong>Note:</strong> This line must be placed before
+inheriting any product configuration makefiles that get the default one from
+build/target/product/base.mk.</p>
+
+<h2 id=compiler_filters>Compiler Filters</h2>
+
+<p>In L, dex2oat takes a variety of --compiler-filter options to control how it
+compiles. Passing in a compiler filter flag for a particular app specifies how
+it’s pre-optimized. Here’s a description of each available option:</p>
+
+<ul>
+ <li><em>everything</em> - compiles almost everything, excluding class initializers and some rare
+methods that are too large to be represented by the compiler’s internal
+representation.
+ <li><em>speed</em> - compiles most methods and maximizes runtime performance, which is the
+default option.
+ <li><em>balanced</em> - attempts to get the best performance return on compilation investment.
+ <li><em>space</em> - compiles a limited number of methods, prioritizing storage space.
+ <li><em>interpret-only</em> - skips all compilation and relies on the interpreter to run code.
+ <li><em>verify-none</em> - special option that skips verification and compilation, should be used only
+for trusted system code.
+</ul>
+
+<h2 id=with_dexpreopt_pic>WITH_DEXPREOPT_PIC</h2>
+
+<p>In post-L AOSP, <code>WITH_DEXPREOPT_PIC</code> can be specified to enable
+position-independent code (PIC). With this, compiled code from the image
+doesn’t have to be relocated from /system into /data/dalvik-cache, saving space
+in the data partition. However, there is a slight runtime impact because it
+disables an optimization that takes advantage of position-dependent code.
+Typically, devices wanting to save space in /data should enable PIC
+compilation.</p>
+
+<p>Example usage (in product’s device.mk):</p>
+
+<pre><code>WITH_DEXPREOPT := true
+WITH_DEXPREOPT_PIC := true</code></pre>
+
+<h2 id=with_art_small_mode>WITH_ART_SMALL_MODE</h2>
+
+<p>For devices with very limited space, <code>WITH_ART_SMALL_MODE</code> can be
+enabled. This option compiles the boot classpath and nothing else, greatly
+reducing first boot time since most compilation is skipped. It also saves on
+storage because there is no compiled code for apps. However, this impacts
+runtime performance since app code has to be interpreted. The impact is limited
+since most performance sensitive code in the framework is still compiled, but
+regressions may appear in benchmarking.</p>
+
+<p>Example usage (in product’s device.mk):</p>
+
+<pre><code>WITH_ART_SMALL_MODE := true</code></pre>
+
+<p>In future releases, this build option will be removed since it can be done with
+this (in product’s device.mk):</p>
+
+<pre><code>PRODUCT_PROPERTY_OVERRIDES += \
+ dalvik.vm.dex2oat-filter=interpret-only \
+ dalvik.vm.image-dex2oat-filter=speed</code></pre>
+
+<h2 id=dalvik_vm_properties>dalvik.vm Properties</h2>
+
+<p>Most dalvik.vm properties in ART are similar to Dalvik, but there are a few
+additional ones as described below. Note that these options affect dex2oat
+during on-device compilation as well as during pre-optimization, whereas most
+of the options discussed above affect only pre-optimization.</p>
+
+<p>To control dex2oat while it’s compiling the boot image:</p>
+
+<ul>
+ <li>dalvik.vm.image-dex2oat-Xms: initial heap size
+ <li>dalvik.vm.image-dex2oat-Xmx: maximum heap size
+ <li>dalvik.vm.image-dex2oat-filter: compiler filter option
+</ul>
+
+<p>To control dex2oat while it’s compiling everything besides the boot image:</p>
+
+<ul>
+ <li> dalvik.vm.dex2oat-Xms: initial heap size
+ <li> dalvik.vm.dex2oat-Xmx: maximum heap size
+ <li> dalvik.vm.dex2oat-filter: compiler filter option
+</ul>
+
+<p>The options that control initial and maximum heap size for dex2oat should not
+be reduced since they could limit what applications can be compiled.</p>
+
+<h2 id=sample_usage>Sample Usage</h2>
+
+<p>The goal of these compiler options is to utilize available space in the system
+and data partition to reduce the amount of dex2oat that must be performed by
+the device. </p>
+
+<p>For devices with ample system and data space, enabling dex pre-optimization is
+all that is necessary.
+
+<p>BoardConfig.mk:</p>
+
+<pre><code>WITH_DEXPREOPT := true</code></pre>
+
+<p>If this causes the system image to become too large, the next thing to try is
+disabling pre-optimization of the prebuilts.
+
+<p>BoardConfig.mk:</p>
+
+<pre><code>WITH_DEXPREOPT := true
+DONT_DEXPREOPT_PREBUILTS := true</code></pre>
+
+<p>Again, if the system image is still too large, try pre-optimizing only the boot
+image.
+
+<p>BoardConfig.mk:</p>
+
+<pre><code>WITH_DEXPREOPT := true
+WITH_DEXPREOPT_BOOT_IMG_ONLY := true</code></pre>
+
+<p>However, limiting to pre-optimizing only the boot-image means all apps will
+have to be optimized on first boot. In order to avoid this, it is possible to
+combine these high level flags with more fine-grained controls to maximize the
+amount of pre-optimized apps.</p>
+
+<p>For instance, if disabling the pre-optimization of the prebuilts almost fits
+into the system partition, compiling the boot classpath with the ‘space’ option
+may make it fit. Note this compiles fewer methods in the boot classpath,
+potentially interpreting more code and impacting runtime performance.
+
+<p>BoardConfig.mk:</p>
+
+<pre><code>WITH_DEXPREOPT := true
+DONT_DEXPREOPT_PREBUILTS := true</code></pre>
+
+<p>device.mk:</p>
+
+<pre><code>PRODUCT_DEX_PREOPT_BOOT_FLAGS := --compiler-filter=space</code></pre>
+
+<p>If a device has very limited system partition space, it’s possible to compile a
+subset of classes in the boot classpath using the compiled classes list. Boot
+classpath methods that aren’t in this list will have to be interpreted, which
+could affect runtime performance.
+
+<p>BoardConfig.mk:</p>
+
+<pre><code>WITH_DEXPREOPT := true
+WITH_DEXPREOPT_BOOT_IMG_ONLY := true</code></pre>
+
+<p>device.mk:</p>
+
+<pre><code>PRODUCT_COPY_FILES += <filename>:system/etc/compiled-classes</code></pre>
+
+<p>If a device has both limited space in the system and data partitions, compiler
+filter flags can be used to disable compilation of certain apps. This will save
+space in both system and data, as there won’t be any compiled code, but these
+apps will have to be interpreted. This example configuration would pre-optimize
+the boot classpath but prevent compilation of other apps that are not
+prebuilts. However, to prevent noticeable performance degradation of
+system_server, the services.jar is still compiled but optimized for space. Note
+that user-installed applications will still use the default compiler filter of
+speed.
+
+<p>BoardConfig.mk:</p>
+
+<pre><code>WITH_DEXPREOPT := true
+DONT_DEXPREOPT_PREBUILTS := true</code></pre>
+
+<p>device.mk:</p>
+
+<pre><code>PRODUCT_DEX_PREOPT_DEFAULT_FLAGS := --compiler-filter=interpret-only
+$(call add-product-dex-preopt-module-config,services,--compiler-filter=space)</code></pre>
+
+<p>For a major version upgrade OTA, it can be useful to blacklist certain apps
+from being pre-optimized since they will likely be out of date. This can be
+done by specifying <code>LOCAL_DEX_PREOPT</code> (for all products) or with
+<code>PRODUCT_DEX_PREOPT_MODULE_CONFIGS</code> (for a particular product).
+
+<p>BoardConfig.mk:</p>
+
+<pre><code>WITH_DEXPREOPT := true</code></pre>
+
+<p>Android.mk (of blacklisted apps):</p>
+
+<pre><code>LOCAL_DEX_PREOPT := false</code></pre>
diff --git a/src/devices/tech/dalvik/constraints.jd b/src/devices/tech/dalvik/constraints.jd
new file mode 100644
index 0000000..8ad6aac
--- /dev/null
+++ b/src/devices/tech/dalvik/constraints.jd
@@ -0,0 +1,876 @@
+page.title=Constraints
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+
+<div id="qv-wrapper">
+<div id="qv">
+ <h2 id="Contents">In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+</div>
+</div>
+
+<p>A <code>.dex</code> file is the transport format for Dalvik Bytecode. There are certain
+syntactical and semantical constraints for a file to be a valid <code>.dex</code> file, and
+a runtime is required to support only valid .dex files.</p>
+
+ <h2 id="gen-constraints">General .dex integrity constraints</h2>
+
+ <p>General integrity constraints are concerned with the larger structure of a
+ <code>.dex</code> file, as described in detail in <a href="dex-format.html"><code>.dex</code>
+ format</a>.</p>
+
+ <table>
+ <tr>
+ <th>
+ Identifier
+ </th>
+
+ <th>
+ Description
+ </th>
+ </tr>
+
+ <tr>
+ <td>
+ G1
+ </td>
+
+ <td>
+ The <code>magic</code> number of the <code>.dex</code> file must be: <code>dex\n035\0</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G2
+ </td>
+
+ <td>
+ The checksum must be an Adler-32 checksum of the whole file contents
+ except <code>magic</code> and <code>checksum</code> field.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G3
+ </td>
+
+ <td>
+ The signature must be a SHA-1 hash of the whole file contents except <code>magic</code>,
+ <code>checksum</code>, and <code>signature</code>.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G4
+ </td>
+
+ <td>
+ The <code>file_size</code> must match the actual file size in bytes.
+ </td>
+ </tr>
+
+
+ <tr>
+ <td>
+ G5
+ </td>
+
+ <td>
+ The <code>header_size</code> must have the value: <code>0x70</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G6
+ </td>
+
+ <td>
+ The <code>endian_tag</code> must have either the value:
+ <code>ENDIAN_CONSTANT</code> or <code>REVERSE_ENDIAN_CONSTANT</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G7
+ </td>
+
+ <td>
+ For each of the <code>link</code>, <code>string_ids</code>,
+ <code>type_ids</code>, <code>proto_ids</code>,
+ <code>field_ids</code>, <code>method_ids</code>, <code>class_defs</code>, and
+ <code>data</code> sections, the <code>offset</code> and <code>size</code> fields must be
+ either both zero or both non-zero. In the latter case, the offset must be
+ four-byte-aligned.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G8
+ </td>
+
+ <td>
+ All offset fields in the header except <code>map_off</code> must be four-byte-aligned.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G9
+ </td>
+
+ <td>
+ The <code>map_off</code> field must be either zero or point into the
+ data section. In the latter case, the <code>data</code> section must exist.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G10
+ </td>
+
+ <td>
+ None of the <code>link</code>, <code>string_ids</code>,
+ <code>type_ids</code>, <code>proto_ids</code>, <code>field_ids</code>,
+ <code>method_ids</code>, <code>class_defs</code> and <code>data</code> sections
+ must overlap each other or the header.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G11
+ </td>
+
+ <td>
+ If a map exists, then each map entry must have a valid type. Each type may appear at most once.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G12
+ </td>
+
+ <td>
+ If a map exists, then each map entry must have a non-zero offset and
+ size. The offset must point into the corresponding section of the file (i.e. a
+ <code>string_id_item</code> must point into the <code>string_ids</code> section) and the explicit or
+ implicit size of the item must match the actual contents and size of the
+ section.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G13
+ </td>
+
+ <td>
+ If a map exists, then the offset of map entry <code>n+1</code> must be greater or
+ equal to the offset of map entry <code>n plus than size of map entry n</code>. This implies
+ non-overlapping entries and low-to-high ordering.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G14
+ </td>
+
+ <td>
+ The following types of entries must have an offset that is
+ four-byte-aligned: <code>string_id_item</code>,
+ <code>type_id_item</code>, <code>proto_id_item</code>,
+ <code>field_id_item</code>,
+ <code>method_id_item</code>, <code>class_def_item</code>,
+ <code>type_list</code>, <code>code_item</code>,
+ <code>annotations_directory_item</code>.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G15
+ </td>
+
+ <td>
+ For each <code>string_id_item</code>, the <code>string_data_off</code> field must contain a
+ valid reference into the <code>data</code> section. For the referenced <code>string_data_item</code>, the
+ <code>data</code> field must contain a valid MUTF-8 string, and the <code>utf16_size</code> must match
+ the decoded length of the string.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G16
+ </td>
+
+ <td>
+ For each <code>type_id_item</code>, the <code>desciptor_idx</code> field must contain a valid
+ reference into the <code>string_ids</code> list. The referenced string must be a valid type
+ descriptor.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G17
+ </td>
+
+ <td>
+ For each <code>proto_id_item</code>, the <code>shorty_idx</code> field must contain a valid
+ reference into the <code>string_ids</code> list. The referenced string must be a valid
+ shorty descriptor. Also, the <code>return_type_idx</code> field must be a valid index into
+ the <code>type_ids</code> section, and the <code>parameters_off</code> field must be either zero or a
+ valid offset pointing into the <code>data</code> section. If non-zero, the parameter list
+ must not contain any void entries.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G18
+ </td>
+
+ <td>
+ For each <code>field_id_item</code>, both the <code>class_idx</code> and <code>type_idx</code> fields must
+ be valid indices into the <code>type_ids</code> list. The entry referenced by <code>class_idx</code>
+ must be a non-array reference type. In addition, the <code>name_idx</code> field must be a
+ valid reference into the <code>string_ids</code> section, and the contents of the referenced
+ entry must conform to the <code>MemberName</code> specification.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G19
+ </td>
+
+ <td>
+ For each <code>method_id_item</code>, the <code>class_idx</code> field must be a valid index
+ into the <code>type_ids</code> section, and the referenced entry must be a non-array
+ reference type. The <code>proto_id</code> field must be a valid reference into the <code>proto_ids</code>
+ list. The <code>name_idx</code> field must be a valid reference into the <code>string_ids</code> section,
+ and the contents of the referenced entry must conform to the <code>MemberName</code>
+ specification.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ G20
+ </td>
+
+ <td>
+ For each <code>field_id_item</code>, the <code>class_idx</code> field must be a valid index
+ into the <code>type_ids</code> list. The referenced entry must be a non-array reference
+ type.
+ </td>
+ </tr>
+
+</table>
+
+<h2 id="static-constraints">
+ Static bytecode constraints
+ </h2>
+
+ <p>
+ Static constraints are constraints on individual elements of the bytecode.
+ They usually can be checked without employing control or data-flow analysis
+ techniques.
+ </p>
+
+ <table>
+ <tr>
+ <th>
+ Identifier
+ </th>
+
+ <th>
+ Description
+ </th>
+ </tr>
+
+ <tr>
+ <td>
+ A1
+ </td>
+
+ <td>
+ The <code>insns</code> array must not be empty.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A2
+ </td>
+
+ <td>
+ The first opcode in the <code>insns</code> array must have index zero.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A3
+ </td>
+
+ <td>
+ The <code>insns</code> array must contain only valid Dalvik opcodes.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A4
+ </td>
+
+ <td>
+ The index of instruction <code>n+1</code> must equal the index of
+ instruction <code>n</code> plus the length of instruction
+ <code>n</code>, taking into account possible operands.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A5
+ </td>
+
+ <td>
+ The last instruction in the <code>insns</code> array must end at index
+ <code>insns_size-1</code>.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A6
+ </td>
+
+ <td>
+ All <code>goto</code> and <code>if-<kind></code> targets must
+ be opcodes within the same method.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A7
+ </td>
+
+ <td>
+ All targets of a <code>packed-switch</code> instruction must be
+ opcodes within the same method. The size and the list of targets
+ must be consistent.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A8
+ </td>
+
+ <td>
+ All targets of a <code>sparse-switch</code> instruction must be
+ opcodes within the same method. The corresponding table must be
+ consistent and sorted low-to-high.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A9
+ </td>
+
+ <td>
+ The <code>B</code> operand of the <code>const-string</code> and
+ <code>const-string/jumbo</code> instructions must be a valid index
+ into the string constant pool.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A10
+ </td>
+
+ <td>
+ The <code>C</code> operand of the <code>iget<kind></code> and
+ <code>iput<kind></code> instructions must be a valid index into
+ the field constant pool. The referenced entry must represent an
+ instance field.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A11
+ </td>
+
+ <td>
+ The <code>C</code> operand of the <code>sget<kind></code> and
+ <code>sput<kind></code> instructions must be a valid index into
+ the field constant pool. The referenced entry must represent a static
+ field.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A12
+ </td>
+
+ <td>
+ The <code>C</code> operand of the <code>invoke-virtual</code>,
+ <code>invoke-super</code>, <code>invoke-direct</code> and
+ <code>invoke-static</code> instructions must be a valid index into the
+ method constant pool. In all cases, the referenced
+ <code>method_id</code> must belong to a class (not an interface).
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A13
+ </td>
+
+ <td>
+ The <code>B</code> operand of the <code>invoke-virtual/range</code>,
+ <code>invoke-super/range</code>, <code>invoke-direct/range</code>, and
+ <code>invoke-static/range</code> instructions must be a valid index
+ into the method constant pool. In all cases, the referenced
+ <code>method_id</code> must belong to a class (not an interface).
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A14
+ </td>
+
+ <td>
+ A method the name of which starts with a '<' must only be invoked
+ implicitly by the VM, not by code originating from a <code>.dex</code> file. The
+ only exception is the instance initializer, which may be invoked by
+ <code>invoke-direct</code>.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A15
+ </td>
+
+ <td>
+ The <code>C</code> operand of the <code>invoke-interface</code>
+ instruction must be a valid index into the method constant pool. The
+ referenced <code>method_id</code> must belong to an interface (not a
+ class).
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A16
+ </td>
+
+ <td>
+ The <code>B</code> operand of the <code>invoke-interface/range</code>
+ instruction must be a valid index into the method constant pool.
+ The referenced <code>method_id</code> must belong to an interface (not
+ a class).
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A17
+ </td>
+
+ <td>
+ The <code>B</code> operand of the <code>const-class</code>,
+ <code>check-cast</code>, <code>new-instance</code>, and
+ <code>filled-new-array/range</code> instructions must be a valid index
+ into the type constant pool.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A18
+ </td>
+
+ <td>
+ The <code>C</code> operand of the <code>instance-of</code>,
+ <code>new-array</code>, and <code>filled-new-array</code>
+ instructions must be a valid index into the type constant pool.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A19
+ </td>
+
+ <td>
+ The dimensions of an array created by a <code>new-array</code>
+ instruction must be less than <code>256</code>.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A20
+ </td>
+
+ <td>
+ The <code>new</code> instruction must not refer to array classes,
+ interfaces, or abstract classes.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A21
+ </td>
+
+ <td>
+ The type referred to by a <code>new-array</code> instruction must be
+ a valid, non-reference type.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A22
+ </td>
+
+ <td>
+ All registers referred to by an instruction in a single-width
+ (non-pair) fashion must be valid for the current method. That is,
+ their indices must be non-negative and smaller than
+ <code>registers_size</code>.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ A23
+ </td>
+
+ <td>
+ All registers referred to by an instruction in a double-width (pair)
+ fashion must be valid for the current method. That is, their indices
+ must be non-negative and smaller than <code>registers_size-1</code>.
+ </td>
+ </tr>
+ </table>
+
+ <h2 id="struct-constraints">
+ Structural bytecode constraints
+ </h2>
+
+ <p>
+ Structural constraints are constraints on relationships between several
+ elements of the bytecode. They usually can't be checked without employing
+ control or data-flow analysis techniques.
+ </p>
+
+ <table>
+ <tr>
+ <th>
+ Identifier
+ </th>
+
+ <th>
+ Description
+ </th>
+ </tr>
+
+ <tr>
+ <td>
+ B1
+ </td>
+
+ <td>
+ The number and types of arguments (registers and immediate values)
+ must always match the instruction.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B2
+ </td>
+
+ <td>
+ Register pairs must never be broken up.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B3
+ </td>
+
+ <td>
+ A register (or pair) has to be assigned first before it can be
+ read.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B4
+ </td>
+
+ <td>
+ An <code>invoke-direct</code> instruction must invoke an instance
+ initializer or a method only in the current class or one of its
+ superclasses.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B5
+ </td>
+
+ <td>
+ An instance initializer must be invoked only on an uninitialized
+ instance.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B6
+ </td>
+
+ <td>
+ Instance methods may be invoked only on and instance fields may only
+ be accessed on already initialized instances.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B7
+ </td>
+
+ <td>
+ A register that holds the result of a <code>new-instance</code>
+ instruction must not be used if the same
+ <code>new-instance</code> instruction is again executed before
+ the instance is initialized.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B8
+ </td>
+
+ <td>
+ An instance initializer must call another instance initializer (same
+ class or superclass) before any instance members can be accessed.
+ Exceptions are non-inherited instance fields, which can be assigned
+ before calling another initializer, and the <code>Object</code> class
+ in general.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B9
+ </td>
+
+ <td>
+ All actual method arguments must be assignment-compatible with their
+ respective formal arguments.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B10
+ </td>
+
+ <td>
+ For each instance method invocation, the actual instance must be
+ assignment-compatible with the class or interface specified in the
+ instruction.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B11
+ </td>
+
+ <td>
+ A <code>return<kind></code> instruction must match its
+ method's return type.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B12
+ </td>
+
+ <td>
+ When accessing protected members of a superclass, the actual type of
+ the instance being accessed must be either the current class or one
+ of its subclasses.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B13
+ </td>
+
+ <td>
+ The type of a value stored into a static field must be
+ assignment-compatible with or convertible to the field's type.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B14
+ </td>
+
+ <td>
+ The type of a value stored into a field must be assignment-compatible
+ with or convertible to the field's type.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B15
+ </td>
+
+ <td>
+ The type of every value stored into an array must be
+ assignment-compatible with the array's component type.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B16
+ </td>
+
+ <td>
+ The <code>A</code> operand of a <code>throw</code> instruction must
+ be assignment-compatible with <code>java.lang.Throwable</code>.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B17
+ </td>
+
+ <td>
+ The last reachable instruction of a method must either be a backwards
+ <code>goto</code> or branch, a <code>return</code>, or a
+ <code>throw</code> instruction. It must not be possible to leave the
+ <code>insns</code> array at the bottom.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B18
+ </td>
+
+ <td>
+ The unassigned half of a former register pair may not be read (is
+ considered invalid) until it has been re-assigned by some other
+ instruction.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B19
+ </td>
+
+ <td>
+ A <code>move-result<kind></code> instruction must be immediately
+ preceded (in the <code>insns</code> array) by an
+ <code>invoke-<kind></code> instruction. The only exception is
+ the <code>move-result-object</code> instruction, which may also be
+ preceded by a <code>filled-new-array</code> instruction.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B20
+ </td>
+
+ <td>
+ A <code>move-result<kind></code> instruction must be immediately
+ preceded (in actual control flow) by a matching
+ <code>return-<kind></code> instruction (it must not be jumped
+ to). The only exception is the <code>move-result-object</code>
+ instruction, which may also be preceded by a
+ <code>filled-new-array</code> instruction.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B21
+ </td>
+
+ <td>
+ A <code>move-exception</code> instruction must appear only as the
+ first instruction in an exception handler.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ B22
+ </td>
+
+ <td>
+ The <code>packed-switch-data</code>, <code>sparse-switch-data</code>,
+ and <code>fill-array-data</code> pseudo-instructions must not be
+ reachable by control flow.
+ </td>
+ </tr>
+ </table>
diff --git a/src/devices/tech/dalvik/dalvik-bytecode.jd b/src/devices/tech/dalvik/dalvik-bytecode.jd
index 1b9b9e3..5695440 100644
--- a/src/devices/tech/dalvik/dalvik-bytecode.jd
+++ b/src/devices/tech/dalvik/dalvik-bytecode.jd
@@ -893,7 +893,7 @@
<code>B:</code> first source register or pair (8 bits)<br/>
<code>C:</code> second source register or pair (8 bits)</td>
<td>Perform the identified binary operation on the two source registers,
- storing the result in the first source register.</td>
+ storing the result in the destination register.</td>
</tr>
<tr>
<td>b0..cf 12x</td>
diff --git a/src/devices/tech/debug/dumpsys.jd b/src/devices/tech/debug/dumpsys.jd
new file mode 100644
index 0000000..ad93e2f
--- /dev/null
+++ b/src/devices/tech/debug/dumpsys.jd
@@ -0,0 +1,104 @@
+page.title=Dumpsys System Diagnostics
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>The <code>dumpsys</code> tool runs on the device and provides information about the status
+of system services. </p>
+
+<h2 id=how_to_use_dumpsys>How to use dumpsys</h2>
+
+<p>If you run <code>adb shell dumpsys</code>, you’ll get diagnostic output for
+all system services, which is usually more than you want. For more manageable
+output, specify the service you would like to examine. </p>
+
+<p>For example, the following command:</p>
+
+<pre>
+$ adb shell dumpsys input
+</pre>
+
+<p>provides system data for input components such as touchscreens or built-in
+keyboards.</p>
+
+<h2 id=list_of_system_services>List of system services</h2>
+
+
+<p>For a complete list of system services that you can use with dumpsys, try the
+following command:</p>
+
+<pre class="no-pretty-print">
+$ adb shell dumpsys -l
+Currently running services:
+ DockObserver
+ SurfaceFlinger
+ accessibility
+ account
+ activity
+ alarm
+ android.security.keystore
+ appops
+ appwidget
+ assetatlas
+ audio
+ backup
+ battery
+ batteryproperties
+ batterystats
+ bluetooth_manager
+ clipboard
+ commontime_management
+ connectivity
+ consumer_ir
+ content
+ country_detector
+ cpuinfo
+ dbinfo
+...
+</pre>
+
+<h2 id=dumpsys_command-line_options>Dumpsys command-line options</h2>
+
+<p>Command-line options are different for different services. Here are a few
+common ones:</p>
+
+<ul>
+ <li> For many services, you can append <code>-h</code> to see the help
+text.
+ <li> For some services, you can append <code>-c</code> to view the data in
+a machine-friendly format. </ul>
+
+<h2 id=understanding_diagnostic_output>Understanding diagnostic output</h2>
+
+<p>For details on some of the most commonly used dumpsys services, see the
+following articles:</p>
+
+<ul>
+ <li> <a
+ href="{@docRoot}devices/input/diagnostics.html">Viewing Input Diagnostics (dumpsys input)</a>
+ <li> <a href="{@docRoot}devices/tech/ram/procstats.html">Viewing RAM Usage Data (dumpsys procstats)</a>
+ <li> <a href="{@docRoot}devices/tech/netstats.html">Viewing Network Data (dumpsys netstats)</a>
+ <li> <a href="{@docRoot}devices/tech/power/batterystats.html">Viewing Battery Usage Data (dumpsys batterystats)</a>
+</ul>
+
diff --git a/src/devices/debugtune.jd b/src/devices/tech/debug/index.jd
similarity index 100%
rename from src/devices/debugtune.jd
rename to src/devices/tech/debug/index.jd
diff --git a/src/devices/native-memory.jd b/src/devices/tech/debug/native-memory.jd
similarity index 100%
rename from src/devices/native-memory.jd
rename to src/devices/tech/debug/native-memory.jd
diff --git a/src/devices/tuning.jd b/src/devices/tech/debug/tuning.jd
similarity index 100%
rename from src/devices/tuning.jd
rename to src/devices/tech/debug/tuning.jd
diff --git a/src/devices/tech/images/composite01.png b/src/devices/tech/images/composite01.png
new file mode 100644
index 0000000..3220521
--- /dev/null
+++ b/src/devices/tech/images/composite01.png
Binary files differ
diff --git a/src/devices/tech/images/composite07.png b/src/devices/tech/images/composite07.png
new file mode 100644
index 0000000..7125734
--- /dev/null
+++ b/src/devices/tech/images/composite07.png
Binary files differ
diff --git a/src/devices/tech/images/icon_error.png b/src/devices/tech/images/icon_error.png
new file mode 100644
index 0000000..cb3d1ab
--- /dev/null
+++ b/src/devices/tech/images/icon_error.png
Binary files differ
diff --git a/src/devices/tech/images/icon_installing.png b/src/devices/tech/images/icon_installing.png
new file mode 100644
index 0000000..571eb8b
--- /dev/null
+++ b/src/devices/tech/images/icon_installing.png
Binary files differ
diff --git a/src/devices/tech/images/icon_installing_5x.png b/src/devices/tech/images/icon_installing_5x.png
new file mode 100644
index 0000000..c2c0201
--- /dev/null
+++ b/src/devices/tech/images/icon_installing_5x.png
Binary files differ
diff --git a/src/devices/tech/images/icon_installing_overlay01.png b/src/devices/tech/images/icon_installing_overlay01.png
new file mode 100644
index 0000000..e762d6c
--- /dev/null
+++ b/src/devices/tech/images/icon_installing_overlay01.png
Binary files differ
diff --git a/src/devices/tech/images/icon_installing_overlay07.png b/src/devices/tech/images/icon_installing_overlay07.png
new file mode 100644
index 0000000..3838a85
--- /dev/null
+++ b/src/devices/tech/images/icon_installing_overlay07.png
Binary files differ
diff --git a/src/devices/tech/images/installing_text.png b/src/devices/tech/images/installing_text.png
new file mode 100644
index 0000000..11e1d3c
--- /dev/null
+++ b/src/devices/tech/images/installing_text.png
Binary files differ
diff --git a/src/devices/tech/images/ota_size_comparison.png b/src/devices/tech/images/ota_size_comparison.png
new file mode 100644
index 0000000..9204a90
--- /dev/null
+++ b/src/devices/tech/images/ota_size_comparison.png
Binary files differ
diff --git a/src/devices/tech/images/progress_1.png b/src/devices/tech/images/progress_1.png
new file mode 100644
index 0000000..aa997d0
--- /dev/null
+++ b/src/devices/tech/images/progress_1.png
Binary files differ
diff --git a/src/devices/tech/images/progress_10.png b/src/devices/tech/images/progress_10.png
new file mode 100644
index 0000000..1ca391a
--- /dev/null
+++ b/src/devices/tech/images/progress_10.png
Binary files differ
diff --git a/src/devices/tech/images/progress_50.png b/src/devices/tech/images/progress_50.png
new file mode 100644
index 0000000..8a2ac6c
--- /dev/null
+++ b/src/devices/tech/images/progress_50.png
Binary files differ
diff --git a/src/devices/tech/images/progress_empty.png b/src/devices/tech/images/progress_empty.png
new file mode 100644
index 0000000..7258183
--- /dev/null
+++ b/src/devices/tech/images/progress_empty.png
Binary files differ
diff --git a/src/devices/tech/images/progress_fill.png b/src/devices/tech/images/progress_fill.png
new file mode 100644
index 0000000..becf87b
--- /dev/null
+++ b/src/devices/tech/images/progress_fill.png
Binary files differ
diff --git a/src/devices/tech/index.jd b/src/devices/tech/index.jd
index 3eed8e9..62a1f59 100644
--- a/src/devices/tech/index.jd
+++ b/src/devices/tech/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 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.
@@ -26,35 +26,40 @@
<p>Welcome to the Android core technologies section of the site. Here you
-can find information on common features useful to people and organizations who are
-looking to modify, contribute to, or port the Android software. This is "under
-the hood" information intended for engineers.</p>
+can find information on common features useful to people and organizations who
+are looking to modify, contribute to, or port the Android software. This is
+"under the hood" information intended for engineers.</p>
<h2 id="accessory-protocol-information">Accessories</h2>
<p>Android devices can connect to hardware accessories, such as audio docks,
-keyboards and custom hardware, through USB or Bluetooth. This document
-describes the Android Open Accessory protocol for accessory hardware builders.</p>
-<p><a href="{@docRoot}accessories/index.html">» Accessory Protocol Information</a></p>
+keyboards and custom hardware, through USB or Bluetooth. This section
+describes the Android Open Accessory protocol (AOAP) for accessory hardware
+builders.</p>
+<p><a href="{@docRoot}accessories/index.html">» Accessory Protocol
+Information</a></p>
<h2 id="art-technical-information">ART</h2>
<p>The Android runtime (ART) is the heart of Android. It's a fast, ahead-of-time
-compiled runtime with modern garbage collection designed to scale. Android applications are
-compiled to Dalvik bytecode and run with ART. This section includes
-detailed information such as the Dalvik Executable format specification,
-and design information on the runtime itself.</p>
-<p><a href="{@docRoot}devices/tech/dalvik/index.html">» ART and Dalvik Information</a></p>
+compiled runtime with modern garbage collection designed to scale.
+Android applications are compiled to Dalvik bytecode and run with ART. This
+section includes detailed information such as the Dalvik Executable format
+specification, and design information on the runtime itself.</p>
+<p><a href="{@docRoot}devices/tech/dalvik/index.html">» ART and Dalvik
+Information</a></p>
<h2 id="data-usage-technical-information">Data Usage</h2>
-<p>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.</p>
-<p><a href="{@docRoot}devices/tech/datausage/index.html">» Data Usage Information</a></p>
+<p>Android's data usage features allow users to understand and control how
+their device uses network data. This section is designed for systems
+integrators and mobile operators to help explain technical details they
+should be aware of when porting Android to specific devices.</p>
+<p><a href="{@docRoot}devices/tech/datausage/index.html">» Data Usage
+Information</a></p>
<h2 id="debugging">Debugging and Tuning</h2>
<p>Android is a large and complex system. This section includes tips and tricks
-about debugging at the platform level.</p>
-<p><a href="{@docRoot}devices/debugtune.html">» Debugging Information</a></p>
+for debugging at the platform level.</p>
+<p><a href="{@docRoot}devices/tech/debug/index.html">» Debugging
+Information</a></p>
<h2 id="HAL-technical-information">HAL File Reference</h2>
<p>Android's Hardware Abstraction Layer (HAL) provides the interface between
@@ -63,30 +68,45 @@
<p><a href="{@docRoot}devices/halref/files.html">» HAL Reference</a></p>
<h2 id="kernel-technical-information">Kernel</h2>
-<p>The kernel configuration settings in this document are meant to be used as a base
-for an Android kernel configuration. All devices should have the options in android-base
-configuration enabled.</p>
-<p><a href="{@docRoot}devices/tech/kernel.html">» Kernel Information</a></p>
+<p>The kernel configuration settings in this section are meant to be used as
+a base for an Android kernel configuration. All devices should have the
+options in android-base configuration enabled.</p>
+<p><a href="{@docRoot}devices/tech/kernel.html">» Kernel Information</a>
+</p>
<h2 id="lowram-technical-information">Low RAM</h2>
-<p>Android supports devices with limited memory through various optimizations,
+<p>Android supports devices with limited memory through various optimizations
such as improved memory management, reduced system memory, and several
build-time and kernel configuration settings.</p>
-<p><a href="{@docRoot}devices/low-ram.html">» Low RAM Information</a></p>
+<p><a href="{@docRoot}devices/tech/low-ram.html">» Low RAM Information</a>
+</p>
+
+<h2 id="ota-technical-information">OTA Updates</h2>
+<p>Android devices in the field can receive and install over-the-air (OTA)
+updates to the system and application software. This section describes the
+structure of update packages and the tools to build them. It is intended for
+developers building OTA updates for new and released Android devices.</p>
+<p><a href="{@docRoot}devices/tech/ota/index.html">» OTA Information</a>
+</p>
<h2 id="power-technical-information">Power</h2>
-<p>Battery usage statistics are tracked by the framework. This involves keeping track of
-time spent by different device components in different states.</p>
-<p><a href="{@docRoot}devices/tech/power.html">» Power Information</a></p>
+<p>Battery usage statistics are tracked by the framework. This involves
+keeping track of time spent by different device components in different states.
+</p>
+<p><a href="{@docRoot}devices/tech/power.html">» Power Information</a>
+</p>
<h2 id="security-technical-information">Security</h2>
<p>Android security comes with a variety of measures, including an application
sandbox, SELinux, dm-verity, encryption, and more.</p>
-<p><a href="{@docRoot}devices/tech/security/index.html">» Security Information</a></p>
+<p><a href="{@docRoot}devices/tech/security/index.html">» Security
+Information</a></p>
-<h2 id="tradefed-test-infrastructure">Trade Federation Testing Infrastructure</h2>
-<p>Trade Federation is a continuous test framework for running tests on Android devices.
-Trade Federation's modularity makes it straightforward to slot into environments with existing build,
-test, and reporting infrastructures.</p>
-<p><a href="{@docRoot}devices/tech/test_infra/tradefed/index.html">» Trade Federation Testing Infrastructure Overview</a></p>
-
+<h2 id="tradefed-test-infrastructure">Trade Federation Testing Infrastructure
+</h2>
+<p>Trade Federation is a continuous test framework for running tests on
+Android devices. Trade Federation's modularity makes it straightforward to
+slot into environments with existing build, test, and reporting
+infrastructures.</p>
+<p><a href="{@docRoot}devices/tech/test_infra/tradefed/index.html">
+» Trade Federation Testing Infrastructure Overview</a></p>
\ No newline at end of file
diff --git a/src/devices/tech/input/dumpsys.jd b/src/devices/tech/input/dumpsys.jd
deleted file mode 100644
index 21ae764..0000000
--- a/src/devices/tech/input/dumpsys.jd
+++ /dev/null
@@ -1,344 +0,0 @@
-page.title=Dumpsys
-@jd:body
-
-<!--
- Copyright 2013 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.
--->
-<p>The <code>dumpsys</code> tool runs on the device and dumps interesting information
-about the status of system services.</p>
-<h2 id="usage">Usage</h2>
-<p>The input system is part of the window manager. To dump its state,
-run the following command.</p>
-<pre><code>$ adb shell su -- dumpsys window
-
-WINDOW MANAGER INPUT (dumpsys window input)
-Event Hub State:
- BuiltInKeyboardId: -1
- Devices:
-...
-</code></pre>
-<p>The set of information that is reported varies depending on the version of Android.</p>
-<h3 id="event-hub-state">Event Hub State</h3>
-<p>The <code>EventHub</code> component is responsible for communicating with the kernel device
-drivers and identifying device capabilities. Accordingly, its state shows
-information about how devices are configured.</p>
-<pre><code>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:
-</code></pre>
-<h4 id="things-to-look-for">Things To Look For</h4>
-<ol>
-<li>
-<p>All of the expected input devices are present.</p>
-</li>
-<li>
-<p>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.</p>
-</li>
-<li>
-<p>Each input device is being classified correctly. The bits in the <code>Classes</code>
- field correspond to flags in <code>EventHub.h</code> such as <code>INPUT_DEVICE_CLASS_TOUCH_MT</code>.</p>
-</li>
-<li>
-<p>The <code>BuiltInKeyboardId</code> is correct. If the device does not have a built-in keyboard,
- then the id must be <code>-1</code>, otherwise it should be the id of the built-in keyboard.</p>
-<p>If you observe that the <code>BuiltInKeyboardId</code> is not <code>-1</code> 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 <code>type SPECIAL_FUNCTION</code> (that's what in the <code>tuna-gpio-keykad.kcm</code>
-file we see mentioned above).</p>
-</li>
-</ol>
-<h3 id="input-reader-state">Input Reader State</h3>
-<p>The <code>InputReader</code> 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.</p>
-<p>This is what a special function keypad looks like:</p>
-<pre><code>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
-</code></pre>
-<p>Here is a touch screen. Notice all of the information about the resolution of
-the device and the calibration parameters that were used.</p>
-<pre><code> 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
-</code></pre>
-<p>Here is an external keyboard / mouse combo HID device. (This device doesn't actually
-have a mouse but its HID descriptor says it does.)</p>
-<pre><code> 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
-</code></pre>
-<p>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.</p>
-<pre><code>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
-</code></pre>
-<p>At the end of the input reader dump there is some information about global configuration
-parameters such as the mouse pointer speed.</p>
-<pre><code> 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
-</code></pre>
-<h4 id="things-to-look-for_1">Things To Look For</h4>
-<ol>
-<li>
-<p>All of the expected input devices are present.</p>
-</li>
-<li>
-<p>Each input device has been configured appropriately. Especially check the
- touch screen and joystick axes.</p>
-</li>
-</ol>
-<h3 id="input-dispatcher-state">Input Dispatcher State</h3>
-<p>The <code>InputDispatcher</code> 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.</p>
-<pre><code>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
-</code></pre>
-<h4 id="things-to-look-for_2">Things To Look For</h4>
-<ol>
-<li>
-<p>In general, all input events are being processed as expected.</p>
-</li>
-<li>
-<p>If you touch the touch screen and run dumpsys at the same time, then the <code>TouchedWindows</code>
- line should show the window that you are touching.</p>
-</li>
-</ol>
-
diff --git a/src/devices/tech/kernel.jd b/src/devices/tech/kernel.jd
index da749c5..637c5c4 100644
--- a/src/devices/tech/kernel.jd
+++ b/src/devices/tech/kernel.jd
@@ -288,3 +288,11 @@
CONFIG_TIMER_STATS=y
CONFIG_SCHED_TRACER=y
</pre>
+
+<h3>For USB host mode audio</h3>
+
+<pre>
+CONFIG_SND_USB=y
+CONFIG_SND_USB_AUDIO=y
+# CONFIG_USB_AUDIO is for a peripheral mode (gadget) driver
+</pre>
diff --git a/src/devices/tech/netstats.jd b/src/devices/tech/netstats.jd
new file mode 100644
index 0000000..8c9097c
--- /dev/null
+++ b/src/devices/tech/netstats.jd
@@ -0,0 +1,140 @@
+page.title=Viewing Network Usage Data
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<p>Using the command <code>adb shell dumpsys netstats detail</code> provides
+network usage statistics collected since the device booted up.</p>
+
+<h2 id=input>Input</h2>
+
+
+<p>To view network usage statistics, run the following command:</p>
+
+<pre class=prettyprint>
+$ adb shell dumpsys netstats detail
+</pre>
+
+
+<h2 id=output>Output</h2>
+
+
+<p>The set of information reported varies depending on the version of Android but
+consists of several sections: </p>
+
+<ul>
+ <li> Active interfaces
+ <li> Active UID interfaces
+ <li> Dev statistics
+ <li> Xt statistics
+ <li> UID statistics (sometimes also called "Detailed UID statistics")
+ <li> UID tag statistics
+</ul>
+
+<h3 id=active_interfaces_active_uid_interfaces>Active interfaces/Active UID interfaces</h3>
+
+<p>Here is sample output for the active interfaces and active UID interfaces
+sections:</p>
+
+<pre>
+Active interfaces:
+ iface=wlan0 ident=[{type=WIFI, subType=COMBINED, networkId="GoogleGuest"}]
+Active UID interfaces:
+ iface=wlan0 ident=[{type=WIFI, subType=COMBINED, networkId="GoogleGuest"}]
+</pre>
+
+
+<p>This shows network statistics for the whole device. In most cases, the
+information in these two section is the same.</p>
+
+<h3 id=dev_stats_xt_stats>Dev statistics/Xt statistics</h3>
+
+
+<p>Here is sample output for the Dev statistics section:</p>
+
+<pre>
+Dev stats:
+ Pending bytes: 170775
+ Complete history:
+ ident=[[type=MOBILE_HIPRI, subType=COMBINED, subscriberId=311111...]] uid=-1 set=ALL tag=0x0
+ NetworkStatsHistory: bucketDuration=3600000
+ bucketStart=1406138400000 activeTime=3603995 rxBytes=19467 rxPackets=53 txBytes=7500 txPackets=61 operations=0
+ bucketStart=1406142000000 activeTime=20730 rxBytes=25403 rxPackets=66 txBytes=9140 txPackets=74 operations=0
+ bucketStart=1406145600000 activeTime=29161 rxBytes=9263 rxPackets=37 txBytes=5180 txPackets=38 operations=0
+ bucketStart=1406149200000 activeTime=9054 rxBytes=12387 rxPackets=31 txBytes=4052 txPackets=35 operations=0
+ ident=[[type=WIFI, subType=COMBINED, networkId="MySSID"]] uid=-1 set=ALL tag=0x0
+ NetworkStatsHistory: bucketDuration=3600000
+ bucketStart=1406138400000 activeTime=4811082 rxBytes=335913292 rxPackets=265144 txBytes=9729261 txPackets=117220 operations=0
+ bucketStart=1406142000000 activeTime=3513477 rxBytes=1193606876 rxPackets=956855 txBytes=29450792 txPackets=306634 operations=0
+ bucketStart=1406145600000 activeTime=3297986 rxBytes=729381849 rxPackets=586396 txBytes=24247211 txPackets=237438 operations=0
+ bucketStart=1406149200000 activeTime=3580941 rxBytes=57168575 rxPackets=51610 txBytes=5291167 txPackets=29260 operations=0
+ ident=[[type=WIFI, subType=COMBINED, networkId="MySecondSSID"]] uid=-1 set=ALL tag=0x0
+ NetworkStatsHistory: bucketDuration=3600000
+</pre>
+
+<h3 id=uid_stats>UID stats</h3>
+
+<pre>
+UID stats:
+ Pending bytes: 744
+ Complete history:
+ ident=[[type=MOBILE_SUPL, subType=COMBINED, subscriberId=311111...], [type=MOBILE, subType=COMBINED, subscriberId=311111...]] uid=10007 set=DEFAULT tag=0x0
+ NetworkStatsHistory: bucketDuration=7200000
+ bucketStart=1406167200000 activeTime=7200000 rxBytes=4666 rxPackets=7 txBytes=1597 txPackets=10 operations=0
+ ident=[[type=WIFI, subType=COMBINED, networkId="MySSID"]] uid=10007 set=DEFAULT tag=0x0
+ NetworkStatsHistory: bucketDuration=7200000
+ bucketStart=1406138400000 activeTime=7200000 rxBytes=17086802 rxPackets=15387 txBytes=1214969 txPackets=8036 operations=28
+ bucketStart=1406145600000 activeTime=7200000 rxBytes=2396424 rxPackets=2946 txBytes=464372 txPackets=2609 operations=70
+ bucketStart=1406152800000 activeTime=7200000 rxBytes=200907 rxPackets=606 txBytes=187418 txPackets=739 operations=0
+ bucketStart=1406160000000 activeTime=7200000 rxBytes=826017 rxPackets=1126 txBytes=267342 txPackets=1175 operations=35
+</pre>
+
+
+<h3 id=interpreting_the_results>Interpreting the results</h3>
+
+
+<p>To find the UID for your application, you can run this command:
+<code>adb shell dumpsys package <your package name></code>.
+Then look for the line labeled <code>userId</code>.</p>
+
+<p>In our example, suppose we are trying to find network usage for our app
+“com.example.myapp”. We would run the following command:</p>
+
+<pre>
+$ adb shell dumpsys package com.example.myapp | grep userId
+
+ userId=10007 gids=[3003, 1028, 1015]
+</pre>
+
+<p>Looking at the dump above, we look for lines that have uid=10007. Two such
+lines exist, the first indicating a mobile connection, and the second a Wi-Fi
+connection. Underneath each line, the number of bytes and packets sent and
+received can be seen, bucketed into two-hour windows. </p>
+
+<p>A bit more explanation:</p>
+
+<ul>
+ <li> <code>set=DEFAULT</code> indicates foreground
+ network usage, while <code>set=BACKGROUND</code> indicates
+background usage. <code>set=ALL</code> implies both.
+ <li> <code>tag=0x0</code> indicates the socket tag associated with the traffic.
+ <li> <code>rxBytes</code> and <code>rxPackets</code> represent received bytes and received packets in the
+corresponding time interval.
+ <li> <code>txBytes</code> and <code>txPackets</code> represent sent (transmitted) bytes and sent packets in
+the corresponding time interval.
+</ul>
+
diff --git a/src/devices/tech/ota/block.jd b/src/devices/tech/ota/block.jd
new file mode 100755
index 0000000..6c4f93d
--- /dev/null
+++ b/src/devices/tech/ota/block.jd
@@ -0,0 +1,148 @@
+page.title=Block-Based OTAs
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>You can enable block-based over-the-air (OTA) updates for new devices
+running Android 5.0. OTA is the mechanism by which OEMs remotely update the
+system partition of a device:</p>
+<ul>
+<li><b>Android 5.0</b> and later versions use block OTA updates to ensure that
+each device uses the exact same partition. Instead of comparing individual
+files and computing binary patches, block OTA handles the entire partition as
+one file and computes a single binary patch, ensuring the resultant partition
+contains exactly the intended bits. This allows the device system image to
+achieve the same state via fastboot or OTA.</li>
+<li><b>Android 4.4</b> and earlier versions used file OTA updates, which
+ensured devices contained similar file contents, permissions, and modes, but
+allowed metadata such as timestamps and the layout of the underlying storage
+to vary between devices based on the update method.</li>
+
+</ul>
+<p>Because block OTA ensures that each device uses the same partition, it
+enables the use of dm-verity to cryptographically sign the system partition.
+For details on dm-verity, see
+<a href="{@docRoot}devices/tech/security/verifiedboot/index.html">Verified Boot</a>.
+</p>
+
+<p class="note"><strong>Note:</strong> You must have a working block OTA
+system before using dm-verity.</p>
+
+<h2 id="Recommendations">Recommendations</h2>
+
+<p>For devices launching with Android 5.0 or later, use block OTA updates in
+the factory ROM. To generate a block-based OTA for subsequent updates, pass
+the <code>--block</code> option to <code>ota_from_target_files</code>.</p>
+
+<p>For devices that launched with Android 4.4 or earlier, use file OTA
+updates. While is it possible to transition devices by sending a full block
+OTA of Android 5.0 or later, it requires sending out a full OTA that is
+significantly larger than an incremental OTA (and is therefore discouraged).
+</p>
+
+<p>Because dm-verity requires bootloader support found only in new devices
+shipping with Android 5.0 or later, you <i>cannot</i> enable dm-verity for
+existing devices.</p>
+
+<p>Developers working on the Android OTA system (the recovery image and the
+scripts that generate OTAs) can keep up with changes by subscribing to the
+<a href="https://groups.google.com/forum/#!forum/android-ota">android-ota@googlegroups.com</a>
+mailing list.</p>
+
+<h2 id="File vs. Block OTAs">File vs. Block OTAs</h2>
+
+<p>During a file-based OTA, Android attempts to change the contents of the
+system partition at the filesystem layer (on a file-by-file basis). The update
+is not guaranteed to write files in a consistent order, have a consistent last
+modified time or superblock, or even place the blocks in the same location on
+the block device. For this reason, file-based OTAs fail on a dm-verity-enabled
+device; after the OTA attempt, the device does not boot.</p>
+<p>During a block-based OTA, Android serves the device the difference between
+the two block images (rather than two sets of files). The update checks a
+device build against the corresponding build server at the block level (below
+the filesystem) using one of the following methods:</p>
+<ul>
+<li><b>Full update</b>. Copying the full system image is simple and makes
+patch generation easy but also generates large images that can make applying
+patches expensive.</li>
+<li><b>Incremental update</b>. Using a binary differ tool generates smaller
+images and makes patch application easy, but is memory-intensive when
+generating the patch itself.</li>
+</ul>
+
+<p class="note"><strong>Note:</strong> <code>adb fastboot</code> places the
+exact same bits on the device as a full OTA, so flashing is compatible with
+block OTA.</p>
+
+<h3 id="Unmodified Systems">Updating unmodified systems</h3>
+
+<p>For devices with <i>unmodified</i> system partitions running Android 5.0,
+the download and install process for a block OTA remains the same as for a
+file OTA. However, the OTA update itself might include one or more of the
+following differences:</p>
+<ul>
+<li><b>Download size</b>. Full block OTA updates are approximately the same
+size as full file OTA updates, and incremental updates can be just a few
+megabytes larger.</p>
+
+<img src="../images/ota_size_comparison.png" alt="comparison of OTA sizes">
+
+<p class="img-caption"><strong>Figure 1.</strong> Compare Nexus 6 OTA sizes
+between Android 5.0 and Android 5.1 releases (varying target build changes)</p>
+
+<p>In general, incremental block OTA updates are larger than incremental file
+OTA updates due to:</p>
+<ul>
+<li><i>Data preservation</i>. Block-based OTAs preserve more data (file
+metadata, dm-verity data, ext4 layout, etc.) than file-based OTA.</li>
+<li><i>Computation algorithm differences</i>. In a file OTA update, if a file
+path is identical in both builds, the OTA package contains no data for that
+file. In a block OTA update, determining little or no change in a file depends
+on the quality of the patch computation algorithm and layout of file data in
+both source and target system.</li>
+</ul>
+</li>
+<li><b>Sensitivity to faulty flash and RAM</b>. If a file is corrupted, a file
+OTA succeeds as long as it doesn't touch the corrupted file, but a block OTA
+fails if it detects any corruption on the system partition.</li>
+</ul>
+
+<h3 id="Modified Systems">Updating modified systems</h3>
+<p>For devices with <i>modified</i> system partitions running Android 5.0:</p>
+<ul>
+<li><b>Incremental block OTA updates fail</b>. A system partition might be
+modified during an <code>adb remount</code> or as a result of malware. File
+OTA tolerates some changes to the partition, such as the addition of files
+that are not part of the source or target build. However, block OTA does not
+tolerate additions to the partition, so users will need to install a full OTA
+overwriting any system partition modifications) or flash a new system image to
+enable future OTAs.</li>
+<li><b>Attempts to change modified files cause update failure</b>. For both
+file and block OTA updates, if the OTA attempts to change a file that has been
+modified, the OTA update fails.</li>
+<li><b>Attempts to access modified files generate errors </b><i>(dm-verity
+only)</i>. For both file and block OTA updates, if dm-verity is enabled and
+the OTA attempts to access modified parts of the system filesystem, the OTA
+generates an error.</li>
+</ul>
diff --git a/src/devices/tech/ota/device_code.jd b/src/devices/tech/ota/device_code.jd
new file mode 100755
index 0000000..8d23674
--- /dev/null
+++ b/src/devices/tech/ota/device_code.jd
@@ -0,0 +1,1154 @@
+page.title=Device-Specific Code
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>The recovery system includes several hooks for inserting device-specific
+code so that OTA updates can also update parts of the device other than the
+Android system (e.g., the baseband or radio processor).</p>
+<p>The following sections and examples customize the <b>tardis</b> device
+produced by the <b>yoyodyne</b> vendor.</p>
+
+<h2>Partition map</h2>
+<p>As of Android 2.3, the platform supports eMMC flash devices and the ext4
+filesystem that runs on those devices. It also supports Memory Technology Device
+(MTD) flash devices and the yaffs2 filesystem from older releases.</p>
+<p>The partition map file is specified by TARGET_RECOVERY_FSTAB; this file is
+used by both the recovery binary and the package-building tools. You can
+specify the name of the map file in TARGET_RECOVERY_FSTAB in BoardConfig.mk.</p>
+<p>A sample partition map file might look like this:</p>
+
+<p><code>device/yoyodyne/tardis/recovery.fstab</code></p>
+
+<pre>
+# mount point fstype device [device2] [options (3.0+ only)]
+
+/sdcard vfat /dev/block/mmcblk0p1 /dev/block/mmcblk0
+/cache yaffs2 cache
+/misc mtd misc
+/boot mtd boot
+/recovery emmc /dev/block/platform/s3c-sdhci.0/by-name/recovery
+/system ext4 /dev/block/platform/s3c-sdhci.0/by-name/system length=-4096
+/data ext4 /dev/block/platform/s3c-sdhci.0/by-name/userdata
+</pre>
+
+<p>With the exception of <code>/sdcard</code>, which is optional, all mount
+points in this example must be defined (devices may also add extra partitions).
+There are five supported filesystem types:</p>
+<dl>
+<dt>yaffs2</dt>
+<dd>A yaffs2 filesystem atop an MTD flash device. "device" must be the name of
+the MTD partition and must appear in <code>/proc/mtd</code>.</dd>
+<dt>mtd</dt>
+<dd>A raw MTD partition, used for bootable partitions such as boot and
+recovery. MTD is not actually mounted, but the mount point is used as a key to
+locate the partition. "device" must be the name of the MTD partition in
+<code>/proc/mtd</code>.</dd>
+<dt>ext4</dt>
+<dd>An ext4 filesystem atop an eMMC flash device. "device" must be the path of
+the block device.</dd>
+<dt>emmc</dt>
+<dd>A raw eMMC block device, used for bootable partitions such as boot and
+recovery. Similar to the mtd type, eMMc is never actually mounted, but the
+mount point string is used to locate the device in the table.</dd>
+<dt>vfat</dt>
+<dd>A FAT filesystem atop a block device, typically for external storage such
+as an SD card. The device is the block device; device2 is a second block
+device the system attempts to mount if mounting the primary device fails (for
+compatibility with SD cards which may or may not be formatted with a partition
+table).
+<p>All partitions must be mounted in the root directory (i.e. the mount point
+value must begin with a slash and have no other slashes). This restriction
+applies only to mounting filesystems in recovery; the main system is free to
+mount them anywhere. The directories <code>/boot</code>, <code>/recovery</code>,
+and <code>/misc</code> should be raw types (mtd or emmc), while the
+directories <code>/system</code>, <code>/data</code>, <code>/cache</code>, and
+<code>/sdcard</code> (if available) should be filesystem types (yaffs2, ext4,
+or vfat).</p></dd></dl>
+
+<p>Starting in Android 3.0, the recovery.fstab file gains an additional
+optional field, <i>options</i>. Currently the only defined option is <i>length
+</i>, which lets you explicitly specify the length of the partition.
+This length is used when reformatting the partition (e.g., for the userdata
+partition during a data wipe/factory reset operation, or for the system
+partition during installation of a full OTA package). If the length value is
+negative, then the size to format is taken by adding the length value to the
+true partition size. For instance, setting "length=-16384" means the last 16k
+of that partition will <i>not</i> be overwritten when that partition is
+reformatted. This supports features such as encryption of the userdata
+partition (where encryption metadata is stored at the end of the
+partition that should not be overwritten).</p>
+
+<p class="note"><strong>Note:</strong> The <b>device2</b> and <b>options</b>
+fields are optional, creating ambiguity in parsing. If the entry in the fourth
+field on the line begins with a ‘/' character, it is considered a <b>device2
+</b> entry; if the entry does not begin with a ‘/' character, it is considered
+an <b>options</b> field.</p>
+
+<h2 id="recovery-ui">Recovery UI</h2>
+<p>To support devices with different available hardware (physical buttons,
+LEDs, screens, etc.), you can customize the recovery interface to display
+status and access the manually-operated hidden features for each device.</p>
+<p>Your goal is to build a small static library with a couple of C++ objects
+to provide the device-specific functionality. The file <code>
+<b>bootable/recovery/default_device.cpp</b></code> is used by default, and
+makes a good starting point to copy when writing a version of this file for
+your device.</p>
+
+<p><code>device/yoyodyne/tardis/recovery/recovery_ui.cpp</code></p>
+
+<pre>
+#include <linux/input.h>
+
+#include "common.h"
+#include "device.h"
+#include "screen_ui.h"
+</pre>
+
+
+<h3 id="header-item-functions">Header and item functions</h3>
+<p>The Device class requires functions for returning headers and items that
+appear in the hidden recovery menu. Headers describe how to operate the menu
+(i.e. controls to change/select the highlighted item).</p>
+
+<pre>
+static const char* HEADERS[] = { "Volume up/down to move highlight;",
+ "power button to select.",
+ "",
+ NULL };
+
+static const char* ITEMS[] = {"reboot system now",
+ "apply update from ADB",
+ "wipe data/factory reset",
+ "wipe cache partition",
+ NULL };
+</pre>
+
+<p class="note"><strong>Note:</strong> Long lines are truncated (not wrapped),
+so keep the width of your device screen in mind.</p>
+
+<h3 id="customize-checkkey">Customizing CheckKey</h3>
+<p>Next, define your device's RecoveryUI implementation. This example assumes
+the <b>tardis</b> device has a screen, so you can inherit from the built-in
+ScreenRecoveryUIimplementation (see instructions for
+<a href="#devices-without-screens">devices without a screen</a>.) The only
+function to customize from ScreenRecoveryUI is <code>CheckKey()</code>, which
+does the initial asynchronous key handling:</p>
+
+<pre>
+class TardisUI : public ScreenRecoveryUI {
+ public:
+ virtual KeyAction CheckKey(int key) {
+ if (key == KEY_HOME) {
+ return TOGGLE;
+ }
+ return ENQUEUE;
+ }
+};
+</pre>
+
+
+<h4 id="key-constants">KEY constants</h4>
+<p>The KEY_* constants are defined in <code>linux/input.h</code>.<code>
+CheckKey()</code> is called no matter what is going on in the rest of
+recovery: when the menu is toggled off, when it is on, during package
+installation, during userdata wiping, etc. It can return one of four constants:
+</p>
+
+<ul>
+<li><b>TOGGLE</b>. Toggle the display of the menu and/or text log on or off
+</li>
+<li><b>REBOOT</b>. Immediately reboot the device</li>
+<li><b>IGNORE</b>. Ignore this keypress</li>
+<li><b>ENQUEUE</b>. Enqueue this keypress to be consumed synchronously (i.e.,
+by the recovery menu system if the display is enabled)</li>
+</ul>
+
+<p><code>CheckKey()</code> is called each time a key-down event is followed by
+a key-up event for the same key. (The sequence of events A-down B-down B-up
+A-up results only in <code>CheckKey(B)</code> being called.) <code>CheckKey()
+</code> can call <code>IsKeyPressed()</code>, to find out if other keys are
+being held down. (In the above sequence of key events, if <code>CheckKey(B)
+</code> called <code>IsKeyPressed(A)</code> it would have returned true.)</p>
+<p><code>CheckKey()</code> can maintain state in its class; this can be useful
+to detect sequences of keys. This example shows a slightly more complex
+setup: the display is toggled by holding down power and pressing volume-up,
+and the device can be rebooted immediately by pressing the power button five
+times in a row (with no other intervening keys):</p>
+
+<pre>
+class TardisUI : public ScreenRecoveryUI {
+ private:
+ int consecutive_power_keys;
+
+ public:
+ TardisUI() : consecutive_power_keys(0) {}
+
+ virtual KeyAction CheckKey(int key) {
+ if (IsKeyPressed(KEY_POWER) && key == KEY_VOLUMEUP) {
+ return TOGGLE;
+ }
+ if (key == KEY_POWER) {
+ ++consecutive_power_keys;
+ if (consecutive_power_keys >= 5) {
+ return REBOOT;
+ }
+ } else {
+ consecutive_power_keys = 0;
+ }
+ return ENQUEUE;
+ }
+};
+</pre>
+
+
+<h3 id="screenrecoveryui">ScreenRecoveryUI</h3>
+<p>When using your own images (error icon, installation animation, progress
+bars) with ScreenRecoveryUI, you might need to set some member variables to
+specify attributes such as the number of frames, speed, and overlay offsets.
+You can set the following variables:</p>
+
+<table>
+<tbody>
+<tr>
+<th>Variable Name</th>
+<th>Purpose</th>
+<th>Release</th>
+</tr>
+<tr>
+<td>animation_fps
+</td>
+<td>speed (in frames per second) of animations
+</td>
+<td>Android 5.x and earlier</td>
+</tr>
+<tr>
+<td>installing_frames
+</td>
+<td>number of frames in the installation animation
+</td>
+<td>Android 4.x and earlier</td>
+</tr>
+<tr>
+<td>install_overlay_offset_x,
+install_overlay_offset_y
+</td>
+<td>offset of the per-frame overlay (relative to the base image) for the
+installation animation
+</td>
+<td>Android 4.x and earlier</td>
+</tr>
+</tbody>
+</table>
+
+<p>To set variables, override the <code>ScreenRecoveryUI::Init()</code>
+function in your subclass. Set the values, then call the <code>parent Init()
+</code> function to complete initialization:</p>
+
+<pre>
+class TardisUI : public ScreenRecoveryUI {
+ ...
+ void Init() {
+ // change the speed at which animations run
+ animation_fps = 30;
+
+ ScreenRecoveryUI::Init();
+ }
+</pre>
+
+<p>The default values correspond to the default recovery images; when using
+these images you don't need to provide an <code>Init()</code> function. For
+details on images, see <a href="#recovery-ui-images">Recovery UI Images</a>.
+</p>
+
+<h3 id="device-class">Device Class</h3>
+<p>After you have a RecoveryUI implementation, define your device class
+(subclassed from the built-in Device class). It should create a single
+instance of your UI class and return that from the <code>GetUI()</code>
+function:</p>
+
+<pre>
+class TardisDevice : public Device {
+ private:
+ TardisUI* ui;
+
+ public:
+ TardisDevice() :
+ ui(new TardisUI) {
+ }
+
+ RecoveryUI* GetUI() { return ui; }
+</pre>
+
+<h3 id="startrecovery">StartRecovery</h3>
+<p>The <code>StartRecovery()</code> method is called at the start of recovery,
+after the UI has been initialized and after the arguments have been parsed,
+but before any action has been taken. The default implementation does nothing,
+so you do not need to provide this in your subclass if you have nothing to do:
+</p>
+
+<pre>
+ void StartRecovery() {
+ // ... do something tardis-specific here, if needed ....
+ }
+</pre>
+
+<h3 id="supply-manage-recovery-menu">Supplying and managing recovery menu</h3>
+<p>The system calls two methods to get the list of header lines and the list
+of items. In this implementation, it returns the static arrays defined at the
+top of the file:</p>
+
+<pre>
+const char* const* GetMenuHeaders() { return HEADERS; }
+const char* const* GetMenuItems() { return ITEMS; }
+</pre>
+
+<h4 id="handlemenukey">HandleMenuKey</h4>
+<p>Next, provide a <code>HandleMenuKey()</code> function, which takes a
+keypress and the current menu visibility, and decides what action to take:</p>
+
+<pre>
+ int HandleMenuKey(int key, int visible) {
+ if (visible) {
+ switch (key) {
+ case KEY_VOLUMEDOWN: return kHighlightDown;
+ case KEY_VOLUMEUP: return kHighlightUp;
+ case KEY_POWER: return kInvokeItem;
+ }
+ }
+ return kNoAction;
+ }
+</pre>
+
+<p>The method takes a key code (which has previously been processed and
+enqueued by the <code>CheckKey()</code> method of the UI object), and the
+current state of the menu/text log visibility. The return value is an integer.
+If the value is 0 or higher, that is taken as the position of a menu item,
+which is invoked immediately (see the <code>InvokeMenuItem()</code> method
+below). Otherwise it can be one of the following predefined constants:</p>
+
+<ul>
+<li><b>kHighlightUp</b>. Move the menu highlight to the previous item</li>
+<li><b>kHighlightDown</b>. Move the menu highlight to the next item</li>
+<li><b>kInvokeItem</b>. Invoke the currently highlighted item</li>
+<li><b>kNoAction</b>. Do nothing with this keypress</li>
+</ul>
+
+<p>As implied by the the visible argument, <code>HandleMenuKey()</code> is
+called even if the menu is not visible. Unlike <code>CheckKey()</code>, it is
+<i>not</i> called while recovery is doing something such as wiping data or
+installing a package—it's called only when recovery is idle and waiting for
+input.</p>
+
+<h4 id="trackball-mechanism">Trackball Mechanisms</h4>
+<p>If your device has a trackball-like input mechanism (generates input events
+with type EV_REL and code REL_Y), recovery synthesizes KEY_UP and KEY_DOWN
+keypresses whenever the trackball-like input device reports motion in the Y
+axis. All you need to do is map KEY_UP and KEY_DOWN events onto menu actions.
+This mapping does <i>not</i> happen for <code>CheckKey()</code>, so you can't
+use trackball motions as triggers for rebooting or toggling the display.</p>
+
+<h4 id="modifier-keys">Modifier Keys</h4>
+<p>To check for keys being held down as modifiers, call the <code>IsKeyPressed()
+</code> method of your own UI object. For example, on some
+devices pressing Alt-W in recovery would start a data wipe whether the menu
+was visible or not. YOu could implement like this:</p>
+
+<pre>
+ int HandleMenuKey(int key, int visible) {
+ if (ui->IsKeyPressed(KEY_LEFTALT) && key == KEY_W) {
+ return 2; // position of the "wipe data" item in the menu
+ }
+ ...
+ }
+</pre>
+
+<p class="note"><strong>Note:</strong> If <b>visible</b> is false, it doesn't
+make sense to return the special values that manipulate the menu (move
+highlight, invoke highlighted item) since the user can't see the highlight.
+However, you can return the values if desired.</p>
+
+<h4 id="invokemenuitem">InvokeMenuItem</h4>
+<p>Next, provide an <code>InvokeMenuItem()</code> method that maps integer
+positions in the array of items returned by <code>GetMenuItems()</code> to
+actions. For the array of items in the tardis example, use:</p>
+
+<pre>
+ BuiltinAction InvokeMenuItem(int menu_position) {
+ switch (menu_position) {
+ case 0: return REBOOT;
+ case 1: return APPLY_ADB_SIDELOAD;
+ case 2: return WIPE_DATA;
+ case 3: return WIPE_CACHE;
+ default: return NO_ACTION;
+ }
+ }
+</pre>
+
+<p>This method can return any member of the BuiltinAction enum to tell the
+system to take that action (or the NO_ACTION member if you want the system to
+do nothing). This is the place to provide additional recovery functionality
+beyond what's in the system: Add an item for it in your menu, execute it here
+when that menu item is invoked, and return NO_ACTION so the system does nothing
+else.</p>
+<p>BuiltinAction contains the following values:</p>
+<ul>
+<li><b>NO_ACTION</b>. Do nothing.</li>
+<li><b>REBOOT</b>. Exit recovery and reboot the device normally.</li>
+<li><b>APPLY_EXT, APPLY_CACHE, APPLY_ADB_SIDELOAD</b>. Install an update
+package from various places. For details, see
+<a href="#sideloading">Sideloading</a>.</li>
+<li><b>WIPE_CACHE</b>. Reformat the cache partition only. No confirmation
+required as this is relatively harmless.</li>
+<li><b>WIPE_DATA</b>. Reformat the userdata and cache partitions, also known
+as a factory data reset. The user is asked to confirm this action before
+proceeding.</li>
+</ul>
+<p>The last method, <code>WipeData()</code>, is optional and is called
+whenever a data wipe operation is initiated (either from recovery via the menu
+or when the user has chosen to do a factory data reset from the main system).
+This method is called before the user data and cache partitions are wiped. If
+your device stores user data anywhere other than those two partitions, you
+should erase it here. You should return 0 to indicate success and another
+value for failure, though currently the return value is ignored. The user data
+and cache partitions are wiped whether you return success or failure.</p>
+
+<pre>
+ int WipeData() {
+ // ... do something tardis-specific here, if needed ....
+ return 0;
+ }
+</pre>
+
+<h4 id="make-device">Make Device</h4>
+<p>Finally, include some boilerplate at the end of the recovery_ui.cpp file
+for the <code>make_device()</code> function that creates and returns an
+instance of your Device class:</p>
+
+<pre>
+class TardisDevice : public Device {
+ // ... all the above methods ...
+};
+
+Device* make_device() {
+ return new TardisDevice();
+}
+</pre>
+
+<h3 id="build-link-device-recovery">Build and link to device recovery</h3>
+<p>After completing the recovery_ui.cpp file, built it and link it to recovery
+on your device. In Android.mk, create a static library that contains only this
+C++ file:</p>
+
+<p><code>device/yoyodyne/tardis/recovery/Android.mk</code></p>
+
+<pre>
+LOCAL_PATH := $(call my-dir)
+include $(CLEAR_VARS)
+
+LOCAL_MODULE_TAGS := eng
+LOCAL_C_INCLUDES += bootable/recovery
+LOCAL_SRC_FILES := recovery_ui.cpp
+
+# should match TARGET_RECOVERY_UI_LIB set in BoardConfig.mk
+LOCAL_MODULE := librecovery_ui_tardis
+
+include $(BUILD_STATIC_LIBRARY)
+</pre>
+
+<p>Then, in the board configuration for this device, specify your static
+library as the value of TARGET_RECOVERY_UI_LIB.</p>
+
+<pre>
+device/yoyodyne/tardis/BoardConfig.mk
+ [...]
+
+# device-specific extensions to the recovery UI
+TARGET_RECOVERY_UI_LIB := librecovery_ui_tardis
+</pre>
+
+
+<h2 id="recovery-ui-images">Recovery UI images</h2>
+<p>The recovery user interface consists images. Ideally, users never interact
+with the UI: During a normal update, the phone boots into recovery, fills the
+installation progress bar, and boots back into the new system without input
+from the user. In the event of a system update problem, the only user action
+that can be taken is to call customer care.</p>
+<p>An image-only interface obviates the need for localization. However, as of
+Android 5.x the update can display a string of text (e.g. "Installing system
+update...") along with the image. For details, see <a href="#recovery-text">
+Localized recovery text</a>.</p>
+
+<h3 id="recovery-5.x">Android 5.x</h3>
+<p>The Android 5.x recovery UI uses two main images: the <b>error</b> image
+and the <b>installing</b> animation.</p>
+
+<table>
+<tbody>
+<tr>
+<td>
+<img src="../images/icon_error.png" alt="image shown during ota error">
+<p class="img-caption"><strong>Figure 1.</strong> icon_error.png</p>
+</td>
+<td>
+<img src="../images/icon_installing_5x.png" alt="image shown during ota install"
+height="275">
+<p class="img-caption"><strong>Figure 2.</strong> icon_installing.png</p>
+</td>
+</tr>
+</tbody>
+</table>
+
+<p>The installing animation is represented as a single PNG image with
+different frames of the animation interlaced by row. For example, for a
+7-frame animation that is 200x200, create a single 200x1400 image where first
+frame is rows 0, 7, 14, 21, ...; the second frame is rows 1, 8, 15, 22, ...;
+etc. The combined image includes a text chunk that indicates the number of
+animation frames. The tool <code>bootable/recovery/interlace-frames.py</code>
+takes a set of input frames and combines them into the necessary composite
+image used by recovery.</p>
+
+<p>Default images are available in different densities and are located in
+<code>bootable/recovery/res-$DENSITY/images</code> (e.g.,
+<code>bootable/recovery/res-hdpi/images</code>). To use a static image during
+installation, you need only provide the icon_installing.png image and set the
+number of frames in the animation to 0 (the error icon is not animated; it is
+always a static image).</p>
+
+
+<h3 id="recovery-4.x">Android 4.x and earlier</h3>
+<p>The Android 4.x and earlier recovery UI uses the <b>error</b> image (shown
+above) and the <b>installing</b> animation plus several overlay images:</p>
+
+<table>
+<tbody>
+<tr>
+<td rowspan="2">
+<img src="../images/icon_installing.png" alt="image shown during ota install">
+<p class="img-caption"><strong>Figure 3.</strong> icon_installing.png</p>
+</td>
+<td>
+<img src="../images/icon_installing_overlay01.png" alt="image shown as first
+overlay">
+<p class="img-caption"><strong>Figure 4.</strong> icon-installing_overlay01.png
+</p>
+</td>
+</tr>
+<tr>
+<td>
+<img src="../images/icon_installing_overlay07.png" alt="image shown as seventh
+overlay">
+<p class="img-caption"><strong>Figure 5.</strong> icon_installing_overlay07.png
+</p>
+</td>
+</tr>
+</tbody>
+</table>
+
+
+<p>During installation, the on-screen display is constructed by drawing the
+icon_installing.png image, then drawing one of the overlay frames on top of it
+at the proper offset. Here, a red box is superimposed to highlight where the
+overlay is placed on top of the base image:</p>
+
+<table style="border-collapse:collapse;">
+<tbody>
+<tr>
+<td><img align="center" src="../images/composite01.png" alt="composite image of
+install plus first overlay">
+<p class="img-caption"><strong>Figure 6.</strong> Installing animation frame 1
+(icon_installing.png + icon_installing_overlay01.png)
+</td>
+<td><img align="center" src="../images/composite01.png" alt="composite image of
+install plus seventh overlay">
+<p class="img-caption"><strong>Figure 7.</strong> Installing animation frame 7
+(icon_installing.png + icon_installing_overlay07.png)
+</td>
+</tr>
+</tbody>
+</table>
+
+<p>Subsequent frames are displayed by drawing <i>only</i> the next overlay
+image atop what's already there; the base image is not redrawn.</p>
+
+<p>The number of frames in the animation, desired speed, and x- and y-offsets
+of the overlay relative to the base are set by member variables of the
+ScreenRecoveryUI class. When using custom images instead of default images,
+override the <code>Init()</code> method in your subclass to change these
+values for your custom images (for details, see <a href="#screenrecoveryui">
+ScreenRecoveryUI</a>). The script <code>bootable/recovery/make-overlay.py
+</code> can assist in converting a set of image frames to the "base image +
+overlay images" form needed by recovery, including computing of the necessary
+offsets.</p>
+
+<p>Default images are located in <code>bootable/recovery/res/images</code>. To
+use a static image during installation, you need only provide the
+icon_installing.png image and set the number of frames in the animation to 0
+(the error icon is not animated; it is always a static image).</p>
+
+
+<h3 id="recovery-text">Localized recovery text</h3>
+<p>Android 5.x displays a string of text (e.g., "Installing system update...")
+along with the image. When the main system boots into recovery it passes the
+user's current locale as a command-line option to recovery. For each message
+to display, recovery includes a second composite image with pre-rendered text
+strings for that message in each locale.</p>
+
+<p>Sample image of recovery text strings:</p>
+
+<img src="../images/installing_text.png" alt="image of recovery text">
+<p class="img-caption"><strong>Figure 8.</strong> Localized text for recovery
+messages</p>
+
+<p>Recovery text can display the following messages:</p>
+<ul>
+<li>Installing system update...</li>
+<li>Error!</li>
+<li>Erasing... (when doing a data wipe/factory reset)</li>
+<li>No command (when a user boots into recovery manually)</li>
+</ul>
+
+<p>The Android app in <code>development/tools/recovery_l10/</code> renders
+localizations of a message and creates the composite image. For details on
+using this app, refer to the comments in <code>development/tools/recovery_l10n/
+src/com/android/recovery_l10n/Main.java</code>.
+
+<p>When a user boots into recovery manually, the locale might not be available
+and no text is displayed. Do not make the text messages critical to the
+recovery process.</p>
+
+<p class="note"><strong>Note:</strong> The hidden interface that displays log
+messages and allows the user to select actions from the menu is available only
+in English.</p>
+
+
+<h2 id="progress-bars">Progress bars</h2>
+<p>Progress bars can appear below the main image (or animation). The progress
+bar is made by combining two input images, which must be of the same size:</p>
+
+<img src="../images/progress_empty.png" alt="empty progress bar">
+<p class="img-caption"><strong>Figure 9.</strong> progress_empty.png</p>
+<img src="../images/progress_fill.png" alt="full progress bar">
+<p class="img-caption"><strong>Figure 10.</strong> progress_fill.png</p>
+
+<p>The left end of the <i>fill</i> image is displayed next to the right end of
+the <i>empty</i> image to make the progress bar. The position of the boundary
+between the two images is changed to indicate the progress. For example, with
+the above pairs of input images, display:</p>
+
+<img src="../images/progress_1.png" alt="progress bar at 1%">
+<p class="img-caption"><strong>Figure 11.</strong> Progress bar at 1%></p>
+<img src="../images/progress_10.png" alt="progress bar at 10%">
+<p class="img-caption"><strong>Figure 12.</strong> Progress bar at 10%</p>
+<img src="../images/progress_50.png" alt="progress bar at 50%">
+<p class="img-caption"><strong>Figure 13.</strong> Progress bar at 50%</p>
+
+<p>You can provide device-specific versions of these images by placing them
+into (in this example) <code>device/yoyodyne/tardis/recovery/res/images</code>
+. Filenames must match the ones listed above; when a file is found in that
+directory, the build system uses it in preference to the corresponding default
+image. Only PNGs in RGB or RGBA format with 8-bit color depth are supported.
+</p>
+
+<p class="note"><strong>Note:</strong> In Android 5.x, if the locale is known
+to recovery and is a right-to-left (RTL) language (Arabic, Hebrew, etc.), the
+progress bar fills from right to left.</p>
+
+
+<h2 id="devices-without-screens">Devices without screens</h2>
+<p>Not all Android devices have screens. If your device is a headless appliance
+or has an audio-only interface, you may need to do more extensive customization
+of recovery UI. Instead of creating a subclass of ScreenRecoveryUI, subclass its
+parent class RecoveryUI directly.</p>
+<p>RecoveryUI has methods for handling a lower-level UI operations such as
+"toggle the display," "update the progress bar," "show the menu," "change the
+menu selection," etc. You can override these to provide an appropriate
+interface for your device. Maybe your device has LEDs where you can use
+different colors or patterns of flashing to indicate state, or maybe you can
+play audio. (Perhaps you don't want to support a menu or the "text display"
+mode at all; you can prevent accessing them with <code>CheckKey()</code> and
+<code>HandleMenuKey()</code> implementations that never toggle the display on
+or select a menu item. In this case, many of the RecoveryUI methods you need
+to provide can just be empty stubs.)</p>
+<p>See <code>bootable/recovery/ui.h</code> for the declaration of RecoveryUI
+to see what methods you must support. RecoveryUI is abstract—some methods are
+pure virtual and must be provided by subclasses—but it does contain the code
+to do processing of key inputs. You can override that too, if your device
+doesn't have keys or you want to process them differently.</p>
+
+<h2 id="updater">Updater</h2>
+<p>You can use device-specific code in the installation of the update package
+by providing your own extension functions that can be called from within your
+updater script. Here's a sample function for the tardis device:</p>
+
+<p><code>device/yoyodyne/tardis/recovery/recovery_updater.c</code></p>
+<pre>
+#include <stdlib.h>
+#include <string.h>
+
+#include "edify/expr.h"
+</pre>
+
+<p>Every extension function has the same signature. The arguments are the name
+by which the function was called, a <code>State*</code> cookie, the number of
+incoming arguments, and an array of <code>Expr*</code> pointers representing
+the arguments. The return value is a newly-allocated <code>Value*</code>.</p>
+
+<pre>
+Value* ReprogramTardisFn(const char* name, State* state, int argc, Expr* argv[]) {
+ if (argc != 2) {
+ return ErrorAbort(state, "%s() expects 2 args, got %d", name, argc);
+ }
+</pre>
+
+<p>Your arguments have not been evaluated at the time your function is
+called—your function's logic determines which of them get evaluated and how
+many times. Thus, you can use extension functions to implement your own
+control structures. <code>Call Evaluate()</code> to evaluate an <code>Expr*
+</code> argument, returning a <code>Value*</code>. If <code>Evaluate()</code>
+returns NULL, you should free any resources you're holding and immediately
+return NULL (this propagates aborts up the edify stack). Otherwise, you take
+ownership of the Value returned and are responsible for eventually calling
+<code>FreeValue()</code> on it.</p>
+
+<p>Suppose the function needs two arguments: a string-valued <b>key</b> and a
+blob-valued <b>image</b>. You could read arguments like this:</p>
+
+<pre>
+ Value* key = EvaluateValue(state, argv[0]);
+ if (key == NULL) {
+ return NULL;
+ }
+ if (key->type != VAL_STRING) {
+ ErrorAbort(state, "first arg to %s() must be string", name);
+ FreeValue(key);
+ return NULL;
+ }
+ Value* image = EvaluateValue(state, argv[1]);
+ if (image == NULL) {
+ FreeValue(key); // must always free Value objects
+ return NULL;
+ }
+ if (image->type != VAL_BLOB) {
+ ErrorAbort(state, "second arg to %s() must be blob", name);
+ FreeValue(key);
+ FreeValue(image)
+ return NULL;
+ }
+</pre>
+
+<p>Checking for NULL and freeing previously evaluated arguments can get tedious
+for multiple arguments. The <code>ReadValueArgs()</code> function can make this
+easier. Instead of the code above, you could have written this:</p>
+
+<pre>
+ Value* key;
+ Value* image;
+ if (ReadValueArgs(state, argv, 2, &key, &image) != 0) {
+ return NULL; // ReadValueArgs() will have set the error message
+ }
+ if (key->type != VAL_STRING || image->type != VAL_BLOB) {
+ ErrorAbort(state, "arguments to %s() have wrong type", name);
+ FreeValue(key);
+ FreeValue(image)
+ return NULL;
+ }
+</pre>
+
+<p><code>ReadValueArgs()</code> doesn't do type-checking, so you must do that
+here; it's more convenient to do it with one <b>if</b> statement at
+the cost of producing a somewhat less specific error message when it fails.
+But <code>ReadValueArgs()</code> does handle evaluating each argument and
+freeing all the previously-evaluated arguments (as well as setting a useful
+error message) if any of the evaluations fail. You can use a <code>
+ReadValueVarArgs()</code> convenience function for evaluating a variable
+number of arguments (it returns an array of <code>Value*</code>).</p>
+
+<p>After evaluating the arguments, do the work of the function:</p>
+
+<pre>
+ // key->data is a NUL-terminated string
+ // image->data and image->size define a block of binary data
+ //
+ // ... some device-specific magic here to
+ // reprogram the tardis using those two values ...
+</pre>
+
+<p>The return value must be a <code>Value*</code> object; ownership of this
+object will pass to the caller. The caller takes ownership of any data pointed
+to by this <code>Value*</code>—specifically the datamember.</p>
+<p>In this instance, you want to return a true or false value to indicate
+success. Remember the convention that the empty string is <i>false</i> and all
+other strings are <i>true</i>. You must malloc a Value object with a malloc'd
+copy of the constant string to return, since the caller will <code>free()
+</code> both. Don't forget to call <code>FreeValue()</code> on the objects you
+got by evaluating your arguments!</p>
+
+<pre>
+ FreeValue(key);
+ FreeValue(image);
+
+ Value* result = malloc(sizeof(Value));
+ result->type = VAL_STRING;
+ result->data = strdup(successful ? "t" : "");
+ result->size = strlen(result->data);
+ return result;
+}
+</pre>
+
+<p>The convenience function <code>StringValue()</code> wraps a string into a
+new Value object. Use to write the above code more succinctly:</p>
+
+<pre>
+ FreeValue(key);
+ FreeValue(image);
+
+ return StringValue(strdup(successful ? "t" : ""));
+}
+</pre>
+
+<p>To hook functions into the edify interpreter, provide the function
+<code>Register_<i>foo</i></code> where <i>foo</i> is the name of the
+static library containing this code. Call <code>RegisterFunction()</code> to
+register each extension function. By convention, name device-specific
+functions <code><i>device</i>.<i>whatever</i></code> to avoid conflicts with
+future built-in functions added.</p>
+
+<pre>
+void Register_librecovery_updater_tardis() {
+ RegisterFunction("tardis.reprogram", ReprogramTardisFn);
+}
+</pre>
+
+<p>You can now configure the makefile to build a static library with your
+code. (This is the same makefile used to customize the recovery UI in the
+previous section; your device may have both static libraries defined here.)</p>
+
+<p><code>device/yoyodyne/tardis/recovery/Android.mk</code></p>
+
+<pre>
+include $(CLEAR_VARS)
+LOCAL_SRC_FILES := recovery_updater.c
+LOCAL_C_INCLUDES += bootable/recovery
+</pre>
+
+<p>The name of the static library must match the name of the
+<code>Register_<i>libname</i></code> function contained within it.</p>
+
+<pre>
+LOCAL_MODULE := librecovery_updater_tardis
+include $(BUILD_STATIC_LIBRARY)
+</pre>
+
+<p>Finally, configure the build of recovery to pull in your library. Add your
+library to TARGET_RECOVERY_UPDATER_LIBS (which may contain multiple libraries;
+they all get registered). If your code depends on other static libraries that
+are not themselves edify extensions (i.e., they don't have a
+<code>Register_<i>libname</i></code> function), you can list those in
+TARGET_RECOVERY_UPDATER_EXTRA_LIBS to link them to updater without calling
+their (non-existent) registration function. For example, if your
+device-specific code wanted to use zlib to decompress data, you would include
+libz here.</p>
+
+<p><code>device/yoyodyne/tardis/BoardConfig.mk</code></p>
+
+<pre>
+ [...]
+
+# add device-specific extensions to the updater binary
+TARGET_RECOVERY_UPDATER_LIBS += librecovery_updater_tardis
+TARGET_RECOVERY_UPDATER_EXTRA_LIBS +=
+</pre>
+
+<p>The updater scripts in your OTA package can now call your function as any
+other. To reprogram your tardis device, the update script might contain:
+<code>tardis.reprogram("the-key", package_extract_file("tardis-image.dat"))
+</code>. This uses the single-argument version of the built-in function <code>
+package_extract_file()</code>, which returns the contents of a file extracted
+from the update package as a blob to produce the second argument to the new
+extension function.</p>
+
+<h2>OTA package generation</h2>
+<p>The final component is getting the OTA package generation tools to know
+about your device-specific data and emit updater scripts that include calls to
+your extension functions.</p>
+<p>First, get the build system to know about a device-specific blob of data.
+Assuming your data file is in <code>device/yoyodyne/tardis/tardis.dat</code>,
+declare the following in your device's AndroidBoard.mk:</p>
+
+<p><code>device/yoyodyne/tardis/AndroidBoard.mk</code></p>
+<pre>
+ [...]
+
+$(call add-radio-file,tardis.dat)
+</pre>
+
+<p>You could also put it in an Android.mk instead, but then it must to be
+guarded by a device check, since all the Android.mk files in the tree are
+loaded no matter what device is being built. (If your tree includes multiple
+devices, you only want the tardis.dat file added when building the tardis
+device.)</p>
+
+<p><code>device/yoyodyne/tardis/Android.mk</code></p>
+<pre>
+ [...]
+
+# an alternative to specifying it in AndroidBoard.mk
+ifeq (($TARGET_DEVICE),tardis)
+ $(call add-radio-file,tardis.dat)
+endif
+</pre>
+
+<p>These are called radio files for historical reasons; they may have nothing
+to do with the device radio (if present). They are simply opaque blobs of data
+the build system copies into the target-files .zip used by the OTA generation
+tools. When you do a build, tardis.dat is stored in the target-files.zip as
+<code>RADIO/tardis.dat</code>. You can call <code>add-radio-file</code>
+multiple times to add as many files as you want.</p>
+
+<h3 id="python-module">Python module</h3>
+<p>To extend the release tools, write a Python module (must be named
+releasetools.py) the tools can call into if present. Example:</p>
+
+<p><code>device/yoyodyne/tardis/releasetools.py</code></p>
+<pre>
+import common
+
+def FullOTA_InstallEnd(info):
+ # copy the data into the package.
+ tardis_dat = info.input_zip.read("RADIO/tardis.dat")
+ common.ZipWriteStr(info.output_zip, "tardis.dat", tardis_dat)
+
+ # emit the script code to install this data on the device
+ info.script.AppendExtra(
+ """tardis.reprogram("the-key", package_extract_file("tardis.dat"));""")
+</pre>
+
+<p>A separate function handles the case of generating an incremental OTA
+package. For this example, suppose you need to reprogram the tardis only when
+the tardis.dat file has changed between two builds.</p>
+<pre>
+def IncrementalOTA_InstallEnd(info):
+ # copy the data into the package.
+ source_tardis_dat = info.source_zip.read("RADIO/tardis.dat")
+ target_tardis_dat = info.target_zip.read("RADIO/tardis.dat")
+
+ if source_tardis_dat == target_tardis_dat:
+ # tardis.dat is unchanged from previous build; no
+ # need to reprogram it
+ return
+
+ # include the new tardis.dat in the OTA package
+ common.ZipWriteStr(info.output_zip, "tardis.dat", target_tardis_dat)
+
+ # emit the script code to install this data on the device
+ info.script.AppendExtra(
+ """tardis.reprogram("the-key", package_extract_file("tardis.dat"));""")
+</pre>
+
+<h4 id="module-functions">Module functions</h4>
+<p>You can provide the following functions in the module (implement only the
+ones you need).</p>
+<dl>
+<dt><code>FullOTA_Assertions()</code></dt>
+<dd>Called near the start of generating a full OTA. This is a good place to
+emit assertions about the current state of the device. Do not emit script
+commands that make changes to the device.</dd>
+<dt><code>FullOTA_InstallBegin()</code></dt>
+<dd>Called after all the assertions about the device state have passed but
+before any changes have been made. You can emit commands for device-specific
+updates that must run before anything else on the device has been changed.</dd>
+<dt><code>FullOTA_InstallEnd()</code></dt>
+<dd>Called at the end of the script generation, after the script commands to
+update the boot and system partitions have been emitted. You can also emit
+additional commands for device-specific updates.</dd>
+<dt><code>IncrementalOTA_Assertions()</code></dt>
+<dd>Similar to <code>FullOTA_Assertions()</code> but called when generating an
+incremental update package.</dd>
+<dt><code>IncrementalOTA_VerifyBegin()</code></dt>
+<dd>Called after all assertions about the device state have passed but before
+any changes have been made. You can emit commands for device-specific updates
+that must run before anything else on the device has been changed.</dd>
+<dt><code>IncrementalOTA_VerifyEnd()</code></dt>
+<dd>Called at the end of the verification phase, when the script has finished
+confirming the files it is going to touch have the expected starting contents.
+At this point nothing on the device has been changed. You can also emit code for
+additional device-specific verifications.</dd>
+<dt><code>IncrementalOTA_InstallBegin()</code></dt>
+<dd>Called after files to be patched have been verified as having the expected
+<i>before</i> state but before any changes have been made. You can emit
+commands for device-specific updates that must run before anything else on the
+device has been changed.</dd>
+<dt><code>IncrementalOTA_InstallEnd()</code></dt>
+<dd>Similar to its full OTA package counterpart, this is called at the end of
+the script generation, after the script commands to update the boot and system
+partitions have been emitted. You can also emit additional commands for
+device-specific updates.</dd>
+</dl>
+
+<p class="note"><strong>Note:</strong> If the device loses power, OTA
+installation may restart from the beginning. Be prepared to cope with devices
+on which these commands have already been run, fully or partially.</p>
+
+<h4 id="pass-functions-to-info">Pass functions to info objects</h4>
+<p>Pass functions to a single info object that contains various useful items:
+</p>
+<ul>
+<li><b>info.input_zip</b>. (Full OTAs only) The <code>zipfile.ZipFile</code>
+object for the input target-files .zip.</li>
+<li><b>info.source_zip</b>. (Incremental OTAs only) The <code>zipfile.ZipFile
+</code> object for the source target-files .zip (the build already on the
+device when the incremental package is being installed).</li>
+<li><b>info.target_zip</b>. (Incremental OTAs only) The <code>zipfile.ZipFile
+</code> object for the target target-files .zip (the build the incremental
+package puts on the device).</li>
+<li><b>info.output_zip</b>. Package being created; a <code>zipfile.ZipFile
+</code> object opened for writing. Use common.ZipWriteStr(info.output_zip,
+<i>filename</i>, <i>data</i>) to add a file to the package.</li>
+<li><b>info.script</b>. Script object to which you can append commands. Call
+<code>info.script.AppendExtra(<i>script_text</i>)</code> to output text into
+the script. Make sure output text ends with a semicolon so it does not run
+into commands emitted afterwards.</li>
+</ul>
+
+<p>For details on the info object, refer to the
+<a href="http://docs.python.org/library/zipfile.html">Python Software Foundation
+documentation for ZIP archives</a>.</p>
+
+<h4 id="specify-module-location">Specify module location</h4>
+<p>Specify the location of your device's releasetools.py script in your
+BoardConfig.mk file:</p>
+
+<p><code>device/yoyodyne/tardis/BoardConfig.mk</code></p>
+
+<pre>
+ [...]
+
+TARGET_RELEASETOOLS_EXTENSIONS := device/yoyodyne/tardis
+</pre>
+
+<p>If TARGET_RELEASETOOLS_EXTENSIONS is not set, it defaults to the <code>
+$(TARGET_DEVICE_DIR)/../common</code> directory (<code>device/yoyodyne/common
+</code> in this example). It's best to explicitly define the location of the
+releasetools.py script. When building the tardis device, the releasetools.py
+script is included in the target-files .zip file (<code>META/releasetools.py
+</code>).</p>
+<p>When you run the release tools (either <code>img_from_target_files</code>
+or <code>ota_from_target_files</code>), the releasetools.py script in the
+target-files .zip, if present, is preferred over the one from the Android
+source tree. You can also explicitly specify the path to the device-specific
+extensions with the <code>-s</code> (or <code>--device_specific</code>)
+option, which takes the top priority. This enables you to correct errors and
+make changes in the releasetools extensions and apply those changes to old
+target-files.</p>
+<p>Now, when you run <code>ota_from_target_files</code>, it automatically
+picks up the device-specific module from the target_files .zip file and uses
+it when generating OTA packages:</p>
+
+<pre>
+% <b>./build/tools/releasetools/ota_from_target_files \
+ -i PREVIOUS-tardis-target_files.zip \
+ dist_output/tardis-target_files.zip incremental_ota_update.zip</b>
+unzipping target target-files...
+<b>using device-specific extensions from target_files</b>
+unzipping source target-files...
+ [...]
+done.
+</pre>
+
+<p>Alternatively, you can specify device-specific extensions when you run
+<code>ota_from_target_files</code>.</p>
+
+<pre>
+% <b>./build/tools/releasetools/ota_from_target_files \
+ -s device/yoyodyne/tardis \ # specify the path to device-specific extensions
+ -i PREVIOUS-tardis-target_files.zip \
+ dist_output/tardis-target_files.zip incremental_ota_update.zip</b>
+unzipping target target-files...
+<b>loaded device-specific extensions from device/yoyodyne/tardis</b>
+unzipping source target-files...
+ [...]
+done.
+</pre>
+
+<p class="note"><strong>Note:</strong> For a complete list of options, refer
+to the <code>ota_from_target_files</code> comments in <code>
+build/tools/releasetools/ota_from_target_files</code>.</p>
+
+
+<h2 id="sideloading">Sideloading</h2>
+<p>Recovery has a <b>sideloading</b> mechanism for manually installing an
+update package without downloading it over-the-air by the main system.
+Sideloading is useful for debugging or making changes on devices where the
+main system can't be booted.</p>
+<p>Historically, sideloading has been done through loading packages off the
+device's SD card; in the case of a non-booting device, the package can be put
+onto the SD card using some other computer and then the SD card inserted into
+the device. To accommodate Android devices without removable external storage,
+recovery supports two additional mechanisms for sideloading: loading packages
+from the cache partition, and loading them over USB using adb.</p>
+<p>To invoke each sideload mechanism, your device's <code>
+Device::InvokeMenuItem()</code> method can return the following values of
+BuiltinAction:</p>
+
+<ul>
+<li><b>APPLY_EXT</b>. Sideload an update package from external storage (<code>
+/sdcard</code> directory). Your recovery.fstab must define the <code>/sdcard
+</code> mount point. This is not usable on devices that emulate an SD card
+with a symlink to <code>/data</code> (or some similar mechanism). <code>/data
+</code> is typically not available to recovery because it may be encrypted.
+The recovery UI displays a menu of .zip files in <code>/sdcard</code> and
+allows the user to select one.</li>
+<li><b>APPLY_CACHE</b>. Similar to loading a package from <code>/sdcard</code>
+except that the <code>/cache</code> directory (which <i>is</i> always
+available to recovery) is used instead. From the regular system, <code>/cache
+</code> is only writable by privileged users, and if the device isn't bootable
+then the <code>/cache</code> directory can't be written to at all (which makes
+this mechanism of limited utility).</li>
+<li><b>APPLY_ADB_SIDELOAD</b>. Allows user to send a package to the device via
+a USB cable and the adb development tool. When this mechanism is invoked,
+recovery starts up its own mini version of the adbd daemon to let adb on a
+connected host computer talk to it. This mini version supports only a single
+command: <code>adb sideload <i>filename</i></code>. The named file is sent
+from the host machine to the device, which then verifies and installs it just
+as if it had been on local storage.</li>
+</ul>
+
+<p>A few caveats:</p>
+<ul>
+<li>Only USB transport is supported.</li>
+<li>If your recovery runs adbd normally (usually true for userdebug and eng
+builds), that will be shut down while the device is in adb sideload mode and
+will be restarted when adb sideload has finished receiving a package. While in
+adb sideload mode, no adb commands other than <code>sideload</code> work (
+<code>logcat</code>, <code>reboot</code>, <code>push</code>, <code>pull</code>
+, <code>shell</code>, etc. all fail).</li>
+<li>You cannot exit adb sideload mode on the device. To abort, you can send
+<code>/dev/null</code> (or anything else that's not a valid package) as the
+package, and then the device will fail to verify it and stop the installation
+procedure. The RecoveryUI implementation's <code>CheckKey()</code> method
+will continue to be called for keypresses, so you can provide a key sequence
+that reboots the device and works in adb sideload mode.</li>
+</ul>
\ No newline at end of file
diff --git a/src/devices/tech/ota/index.jd b/src/devices/tech/ota/index.jd
new file mode 100755
index 0000000..a65418c
--- /dev/null
+++ b/src/devices/tech/ota/index.jd
@@ -0,0 +1,160 @@
+page.title=OTA Updates
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>Android devices in the field can receive and install over-the-air (OTA)
+updates to the system and application software. Devices have a special
+recovery partition with the software needed to unpack a downloaded update
+package and apply it to the rest of the system.</p>
+<p>This section describes the structure of these packages and the tools
+provided to build them. It is intended for developers who want to
+make the OTA update system work on new Android devices and those who are
+building update packages for use with released devices. OTA updates are
+designed to upgrade the underlying operating system and the read-only apps
+installed on the system partition; these updates do <i>not</i> affect
+applications installed by the user from Google Play.
+</p>
+<p>This section describes the OTA system as of the Android 5.x release. For
+help porting OTA-related code from older releases, see <a href="#migrating">
+Migrating from previous releases</a>.
+</p>
+
+<h2 id="android-device-layout">Android device layout</h2>
+<p>The flash space on an Android device typically contains the following
+partitions.</p>
+
+<dl>
+<dt>boot</dt>
+<dd>Contains the Linux kernel and a minimal root filesystem (loaded into a RAM
+disk). It mounts system and other partitions and starts the runtime located on
+the system partition.</dd>
+<dt>system</dt>
+<dd>Contains system applications and libraries that have source code available
+on Android Open Source Project (AOSP). During normal operation, this partition
+is mounted read-only; its contents change only during an OTA update.</dd>
+<dt>vendor</dt>
+<dd>Contains system applications and libraries that do <em>not</em> have
+source code available on Android Open Source Project (AOSP). During normal
+operation, this partition is mounted read-only; its contents change only
+during an OTA update.</dd>
+<dt>userdata</dt>
+<dd>Stores the data saved by applications installed by the user, etc. This
+partition is not normally touched by the OTA update process.</dd>
+<dt>cache</dt>
+<dd>Temporary holding area used by a few applications (accessing this
+partition requires special app permissions) and for storage of downloaded OTA
+update packages. Other programs use this space with the expectation that files
+can disappear at any time. Some OTA package installations may result in this
+partition being wiped completely.</dd>
+<dt>recovery</dt>
+<dd>Contains a second complete Linux system, including a kernel and the
+special recovery binary that reads a package and uses its contents to update
+the other partitions.</dd>
+<dt>misc</dt>
+<dd>Tiny partition used by recovery to stash some information away about what
+it's doing in case the device is restarted while the OTA package is being
+applied.</dd></dl>
+
+<h2 id="life-ota-update">Life of an OTA update</h2>
+<p>A typical OTA update contains the following steps:</p>
+<ol>
+<li>Device performs regular check in with OTA servers and is notified of the
+availability of an update, including the URL of the update package and a
+description string to show the user.</li>
+<li>Update downloads to a cache or data partition, and its cryptographic
+signature is verified against the certificates in
+<code>/system/etc/security/otacerts.zip</code>. User is prompted to install the
+update.</li>
+<li>Device reboots into recovery mode, in which the kernel and system in the
+recovery partition are booted instead of the kernel in the boot partition.</li>
+<li>Recovery binary is started by init. It finds command-line arguments in
+<code>/cache/recovery/command</code> that point it to the downloaded package.
+</li>
+<li>Recovery verifies the cryptographic signature of the package against the
+public keys in <code>/res/keys</code> (part of the RAM disk contained in the
+recovery partition).</li>
+<li>Data is pulled from the package and used to update the boot, system,
+and/or vendor partitions as necessary. One of the new files left on the system
+partition contains the contents of the new recovery partition.</li>
+<li>Device reboots normally. <ol style="list-style-type:lower-alpha">
+<li>The newly updated boot partition is loaded, and it mounts and starts
+executing binaries in the newly updated system partition.</li>
+<li>As part of normal startup, the system checks the contents of the recovery
+partition against the desired contents (which were previously stored as a file
+in <code>/system</code>). They are different, so the recovery partition is
+reflashed with the desired contents. (On subsequent boots, the recovery
+partition already contains the new contents, so no reflash is necessary.)</li>
+</ol></li>
+</ol>
+<p>The system update is complete!</p>
+
+<h2 id="migrating">Migrating from Previous Releases</h2>
+
+<p>When migrating from Android 2.3/3.0/4.0 release, the major change is the
+conversion of all the device-specific functionality from a set of C functions
+with predefined names to C++ objects. The following table lists the old
+functions and the new methods that serve a roughly equivalent purpose:</p>
+
+<table>
+<tbody>
+<tr>
+<th>C function</th>
+<th>C++ method</th>
+</tr>
+<tr>
+<td>device_recovery_start()</td>
+<td>Device::RecoveryStart()</td>
+</tr>
+<tr>
+<td>device_toggle_display()<br>
+device_reboot_now()<br>
+</td>
+<td>RecoveryUI::CheckKey()<br>
+(also RecoveryUI::IsKeyPressed())<br>
+</td>
+</tr>
+<tr>
+<td>device_handle_key()</td>
+<td>Device::HandleMenuKey()</td>
+</tr>
+<tr>
+<td>device_perform_action()</td>
+<td>Device::InvokeMenuItem()</td>
+</tr>
+<tr>
+<td>device_wipe_data()</td>
+<td>Device::WipeData()</td>
+</tr>
+<tr>
+<td>device_ui_init()</td>
+<td>ScreenRecoveryUI::Init()</td>
+</tr>
+</tbody>
+</table>
+
+<p>Conversion of old functions to new methods should be reasonably
+straightforward. Don't forget to add the new <code>make_device()</code>
+function to create and return an instance of your new Device subclass.</p>
\ No newline at end of file
diff --git a/src/devices/tech/ota/inside_packages.jd b/src/devices/tech/ota/inside_packages.jd
new file mode 100755
index 0000000..41b3d5c
--- /dev/null
+++ b/src/devices/tech/ota/inside_packages.jd
@@ -0,0 +1,288 @@
+page.title=Inside OTA Packages
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>The system builds the updater binary from <code>bootable/recovery/updater
+</code> and uses it in an OTA package.</p>The package itself is a .zip file
+(<code>ota_update.zip</code>, <code>incremental_ota_update.zip</code>) that
+contains the executable binary <code>META-INF/com/google/android/update-binary
+</code>.
+
+<p>Updater contains several builtin functions and an interpreter for an
+extensible scripting language (<b>edify</b>) that supports commands for typical
+update-related tasks. Updater looks in the package .zip file for a script in the
+file <code>META-INF/com/google/android/updater-script</code>.</p>
+
+<p class="note"><strong>Note:</strong> Using the edify script and/or builtin
+functions is not a common activity, but can be helpful if you need to debug the
+update file.</p>
+
+<h2 id="edify-syntax">Edify syntax</h2>
+<p>An edify script is a single expression in which all values are strings.
+Empty strings are <i>false</i> in a Boolean context and all other strings are
+<i>true</i>. Edify supports the following operators (with the usual meanings):
+</p>
+
+<pre>
+(<i>expr</i> )
+ <i>expr</i> <b>+</b> <i>expr</i> # string concatenation, not integer addition
+ <i>expr</i> <b>==</b> <i>expr</i>
+ <i>expr</i> <b>!=</b> <i>expr</i>
+ <i>expr</i> <b>&&</b> <i>expr</i>
+ <i>expr</i> <b>||</b> <i>expr</i>
+ ! <i>expr</i>
+ if <i>expr</i> <b>then</b> <i>expr</i> <b>endif</b>
+ if <i>expr</i> <b>then</b> <i>expr</i> <b>else</b> <i>expr</i> <b>endif</b>
+ <i>function_name</i><b>(</b><i>expr</i><b>,</b> <i>expr</i><b>,</b><i>...</i><b>)</b>
+ <i>expr</i><b>;</b> <i>expr</i>
+</pre>
+
+<p>Any string of the characters <i>a-z, A-Z, 0-9, _, :, /, .</i> that isn't a
+reserved word is considered a string literal. (Reserved words are <b>if else
+</b> then <b>endif.</b>) String literals may also appear in double-quotes;
+this is how to create values with whitespace and other characters not in the
+above set. \n, \t, \", and \\ serve as escapes within quoted strings, as does
+\x<i>##</i>.</p>
+<p>The && and || operators are short-circuiting; the right side is not
+evaluated if the logical result is determined by the left side. The
+following are equivalent:</p>
+<pre>
+<i>e1</i> <b>&&</b> <i>e2</i>
+<b>if</b> <i>e1</i> <b>then</b> <i>e2</i> <b>endif</b></pre>
+<p>The ; operator is a sequence point; it means to evaluate first the left
+side and then the right side. Its value is the value of the right-side
+expression. A semicolon can also appear after an expression, so the effect
+simulates C-style statements:</p>
+
+<pre>
+<b>prepare();
+do_other_thing("argument");
+finish_up();</b>
+</pre>
+
+<h2 id="builtin-functions">Built-in functions</h2>
+<p>Most update functionality is contained in the functions available for
+execution by scripts. (Strictly speaking these are <i>macros</i> rather than
+<i>functions</i> in the Lisp sense, since they need not evaluate all of their
+arguments.) Unless otherwise noted, functions return <b>true</b> on success
+and <b>false</b> on error. If you want errors to abort execution of the
+script, use the <code>abort()</code> and/or <code>assert()</code> functions.
+The set of functions available in updater can also be extended to provide
+<a href="{@docRoot}devices/tech/ota/device_code.html">device-specific
+functionality</a>.
+
+<dl>
+<dt><code>abort([<i>msg</i>])</code></dt>
+<dd>Aborts execution of the script immediately, with the optional <i>msg</i>.
+If the user has turned on text display, <i>msg</i> appears in the recovery log
+and on-screen.</dd>
+<dt><code>assert(<i>expr</i>[, <i>expr</i>, ...])</code></dt>
+<dd>Evaluates each <i>expr</i> in turn. If any is false, immediately aborts
+execution with the message "assert failed" and the source text of the failed
+expression.</dd>
+<dt><code>apply_patch(<i>src_file</i>, <i>tgt_file</i>, <i>tgt_sha1</i>, <i>
+tgt_size</i>, <i>patch1_sha1</i>, <i>patch1_blob</i>, [...])</code></dt>
+<dd>Applies a binary patch to the <i>src_file</i> to produce the <i>tgt_file
+</i>. If the desired target is the same as the source, pass "-" for <i>tgt_file
+</i>. <i>tgt_sha1</i> and <i>tgt_size</i> are the expected final SHA1 hash and
+size of the target file. The remaining arguments must come in pairs: a SHA1
+hash (a 40-character hex string) and a blob. The blob is the patch to be
+applied whe the source file's current contents have the given SHA1.
+<p>The patching is done in a safe manner that guarantees the target file
+either has the desired SHA1 hash and size, or it is untouched—it will not be
+left in an unrecoverable intermediate state. If the process is interrupted
+during patching, the target file may be in an intermediate state; a copy exists
+in the cache partition so restarting the update can successfully update the
+file.</p>
+<p>Special syntax is supported to treat the contents of Memory Technology
+Device (MTD) partitions as files, allowing patching of raw partitions such as
+boot. To read an MTD partition, you must know how much data you want to read
+since the partition does not have an end-of-file notion. You can use the
+string "MTD:<i>partition</i>:<i>size_1</i>:<i>sha1_1</i>:<i>size_2</i>:<i>
+sha1_2</i>" as a filename to read the given partition. You must specify at
+least one <i>(size, sha-1)</i> pair; you can specify more than one if there
+are multiple possibilities for what you expect to read.</p></dd>
+<dt><code>apply_patch_check(<i>filename</i>, <i>sha1</i>[, <i>sha1</i>, ...])
+</code></dt>
+<dd>Returns true if the contents of <i>filename</i> or the temporary copy in
+the cache partition (if present) have a SHA1 checksum equal to one of the
+given <i>sha1</i> values. <i>sha1</i> values are specified as 40 hex digits.
+This function differs from <code>sha1_check(read_file(<i>filename</i>),
+<i>sha1</i> [, ...])</code> in that it knows to check the cache partition copy,
+so <code>apply_patch_check()</code> will succeed even if the file was corrupted
+by an interrupted <code>apply_patch() update</code>.</dd>
+<dt><code>apply_patch_space(<i>bytes</i>)</code></dt>
+<dd>Returns true if at least <i>bytes</i> of scratch space is available for
+applying binary patches.</dd>
+<dt><code>concat(<i>expr</i>[, <i>expr</i>, ...])</code></dt>
+<dd>Evaluates each expression and concatenates them. The + operator is
+syntactic sugar for this function in the special case of two arguments (but
+the function form can take any number of expressions). The expressions must be
+strings; it can't concatenate blobs.</dd>
+<dt><code>delete([<i>filename</i>, ...])</code></dt>
+<dd>Deletes all the <i>filename</i>s listed. Returns the number of files
+successfully deleted.</dd>
+<dt><code>delete_recursive([<i>dirname</i>, ...])</code></dt>
+<dd>Recursively deletes <i>dirname</i>s and all their contents. Returns the
+number of directories successfully deleted.</dd>
+<dt><code>file_getprop(<i>filename</i>, <i>key</i>)</code></dt>
+<dd>Reads the given <i>filename</i>, interprets it as a properties file (e.g.
+<code>/system/build.prop</code>), and returns the value of the given <i>key</i>
+, or the empty string if <i>key</i> is not present.</dd>
+<dt><code>format(<i>fs_type</i>, <i>partition_type</i>, <i>location</i>, <i>
+fs_size</i>, <i>mount_point</i>)</code></dt>
+<dd>Reformats a given partition. Supported partition types:
+<ul>
+<li>fs_type="yaffs2" and partition_type="MTD". Location must be the name of
+the MTD partition; an empty yaffs2 filesystem is constructed there. Remaining
+arguments are unused.</li>
+<li>fs_type="ext4" and partition_type="EMMC". Location must be the device file
+for the partition. An empty ext4 filesystem is constructed there. If
+<i>fs_size</i> is zero, the filesystem takes up the entire partition. If
+<i>fs_size</i> is a positive number, the filesystem takes the first
+<i>fs_size</i> bytes of the partition. If <i>fs_size</i> is a
+negative number, the filesystem takes all except the last <i>|fs_size|</i>
+bytes of the partition.</li>
+<li>fs_type="f2fs" and partition_type="EMMC". Location must be the device file
+for the partition. <i>fs_size</i> must be a non-negative number. If
+<i>fs_size</i> is zero, the filesystem takes up the entire partition. If
+<i>fs_size</i> is a positive number, the filesystem takes the first
+<i>fs_size</i> bytes of the partition.</li>
+<li>mount_point should be the future mount point for the filesystem.</li></ul>
+</dd>
+<dt><code>getprop(<i>key</i>)</code></dt>
+<dd>Returns the value of system property <i>key</i> (or the empty string, if
+it's not defined). The system property values defined by the recovery
+partition are not necessarily the same as those of the main system. This
+function returns the value in recovery.</dd>
+<dt><code>greater_than_int(<i>a</i>, <i>b</i>)</code></dt>
+<dd>Returns true if and only if (iff) <i>a</i> (interpreted as an integer) is
+greater than <i>b</i> (interpreted as an integer).</dd>
+<dt><code>ifelse(<i>cond</i>, <i>e1</i>[, <i>e2</i>])</code></dt>
+<dd>Evaluates <i>cond</i>, and if it is true evaluates and returns the value
+of <i>e1</i>, otherwise it evaluates and returns <i>e2</i> (if present). The
+"if ... else ... then ... endif" construct is just syntactic sugar for this
+function.</dd>
+<dt><code>is_mounted(<i>mount_point</i>)</code></dt>
+<dd>Returns true iff there is a filesystem mounted at <i>mount_point</i>.</dd>
+<dt><code>is_substring(<i>needle</i>, <i>haystack</i>)</b></code></dt>
+<dd>Returns true iff <i>needle</i> is a substring of <i>haystack</i>.</dd>
+<dt><code>less_than_int(<i>a</i>, <i>b</i>)</code></dt>
+<dd>Returns true iff <i>a</i> (interpreted as an integer) is less than <i>b</i>
+(interpreted as an integer).</dd>
+<dt><code>mount(<i>fs_type</i>, <i>partition_type</i>, <i>name</i>,
+<i>mount_point</i>)</code></dt>
+<dd>Mounts a filesystem of <i>fs_type</i> at <i>mount_point</i>.
+<i>partition_type</i> must be one of:
+<ul>
+<li><b>MTD</b>. Name is the name of an MTD partition (e.g., system, userdata;
+see <code>/proc/mtd</code> on the device for a complete list).</li>
+<li><b>EMMC.</b></li>
+</ul>
+<p>Recovery does not mount any filesystems by default (except the SD card if
+the user is doing a manual install of a package from the SD card); your script
+must mount any partitions it needs to modify.</p></dd>
+<dt><code>package_extract_dir(<i>package_dir</i>, <i>dest_dir</i>)</code></dt>
+<dd>Extracts all files from the package underneath <i>package_dir</i> and
+writes them to the corresponding tree beneath <i>dest_dir</i>. Any existing
+files are overwritten.</dd>
+<dt><code>package_extract_file(<i>package_file</i>[, <i>dest_file</i>])</code>
+</dt>
+<dd>Extracts a single <i>package_file</i> from the update package and writes
+it to <i>dest_file</i>, overwriting existing files if necessary. Without the
+<i>dest_file</i> argument, returns the contents of the package file as a
+binary blob.</dd>
+<dt><code>read_file(<i>filename</i>)</code></dt>
+<dd>Reads <i>filename</i> and returns its contents as a binary blob.</dd>
+<dt><code>rename(<i>src_filename</i>, <i>tgt_filename</i>)</code></dt>
+<dd>Renames <i>src_filename</i> to <i>tgt_filename</i>. It automatically creates
+the necessary directories for the <i>tgt_filename</i>. Example: <code>
+rename("system/app/Hangouts/Hangouts.apk",
+"system/priv-app/Hangouts/Hangouts.apk")</code>.</dd>
+<dt><code>run_program(<i>path</i>[, <i>arg</i>, ...])</code></dt>
+<dd>Executes the binary at <i>path</i>, passing <i>arg</i>s. Returns the
+program's exit status.</dd>
+<dt><code>set_metadata(<i>filename</i>, <i>key1</i>, <i>value1</i>[, <i>key2
+</i>, <i>value2</i>, ...])</code></dt>
+<dd>Sets the keys of the given <i>filename</i> to <i>values</i>. For example:
+<code>set_metadata("/system/bin/netcfg", "uid", 0, "gid", 3003, "mode", 02750,
+"selabel", "u:object_r:system_file:s0", "capabilities", 0x0)</code>.</dd>
+<dt><code>set_metadata_recursive(<i>dirname</i>, <i>key1</i>, <i>value1</i>[,
+<i>key2</i>, <i>value2</i>, ...])</code></dt>
+<dd>Recursively sets the keys of the given <i>dirname</i> and all its children
+to <i>values</i>. For example: <code>set_metadata_recursive("/system", "uid",
+0, "gid", 0, "fmode", 0644, "dmode", 0755, "selabel",
+"u:object_r:system_file:s0", "capabilities", 0x0)</code>.</dd>
+<dt><code>set_progress(<i>frac</i>)</code></dt>
+<dd>Sets the position of the progress meter within the chunk defined by the
+most recent <code>show_progress()</code> call. <i>frac</i> must be in the
+range [0.0, 1.0]. The progress meter never moves backwards; attempts to make
+it do so are ignored.</dd>
+<dt><code>sha1_check(<i>blob</i>[, <i>sha1</i>])</code></dt>
+<dd>The <i>blob</i> argument is a blob of the type returned by <code>
+read_file()</code> or the one-argument form of <code>package_extract_file()
+</code>. With no <i>sha1</i> arguments, this function returns the SHA1 hash of
+the blob (as a 40-digit hex string). With one or more <i>sha1</i> arguments,
+this function returns the SHA1 hash if it equals one of the arguments, or the
+empty string if it does not equal any of them.</dd>
+<dt><code>show_progress(<i>frac</i>, <i>secs</i>)</code></dt>
+<dd>Advances the progress meter over the next <i>frac</i> of its length over
+the <i>secs</i> seconds (must be an integer). <i>secs</i> may be 0, in which
+case the meter is not advanced automatically but by use of the <code>
+set_progress()</code> function defined above.</dd>
+<dt><code>sleep(<i>secs</i>)</code></dt>
+<dd>Sleeps for <i>secs</i> seconds (must be an integer).</dd>
+<dt><code>stdout(<i>expr</i>[, <i>expr</i>, ...])</code></dt>
+<dd>Evaluates each expression and dumps its value to stdout. Useful for
+debugging.</dd>
+<dt><code>symlink(<i>target</i>[, <i>source</i>, ...])</code></dt>
+<dd>Creates all <i>source</i>s as symlinks to <i>target</i>.</dd>
+<dt><code>tune2fs(<i>device</i>[, <i>arg</i>, …])</code></dt>
+<dd>Adjusts tunable parameters <i>args</i> on <i>device</i>.</dd>
+<dt><code>ui_print([<i>text</i>, ...])</code></dt>
+<dd>Concatenates all <i>text</i> arguments and prints the result to the UI
+(where it will be visible if the user has turned on the text display).</dd>
+<dt><code>unmount(<i>mount_point</i>)</code></dt>
+<dd>Unmounts the filesystem mounted at <i>mount_point</i>.</dd>
+<dt><code>wipe_block_device(<i>block_dev</i>, <i>len</i>)</code></dt>
+<dd>Wipes the <i>len</i> bytes of the given block device <i>block_dev</i>.</dd>
+<dt><code>wipe_cache()</code></dt>
+<dd>Causes the cache partition to be wiped at the end of a successful
+installation.</dd>
+<dt><code>write_raw_image(<i>filename_or_blob</i>, <i>partition</i>)</code>
+</dt>
+<dd>Writes the image in <i>filename_or_blob</i> to the MTD <i>partition</i>.
+<i>filename_or_blob</i> can be a string naming a local file or a blob-valued
+argument containing the data to write. To copy a file from the OTA package to
+a partition, use:
+<code>write_raw_image(package_extract_file("zip_filename"), "partition_name");
+</code>
+</dd>
+</dl>
+
+<p class="note"><strong>Note:</strong> Prior to Android 4.1, only filenames
+were accepted, so to accomplish this the data first had to be unzipped into a
+temporary local file.</p>
\ No newline at end of file
diff --git a/src/devices/tech/ota/sign_builds.jd b/src/devices/tech/ota/sign_builds.jd
new file mode 100755
index 0000000..e986920
--- /dev/null
+++ b/src/devices/tech/ota/sign_builds.jd
@@ -0,0 +1,269 @@
+page.title=Signing Builds for Release
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>Android uses cryptographic signatures in two places:</p>
+<ol>
+<li>Each .apk file must be signed. Android's Package Manager uses an .apk
+signature in two ways:<ul>
+<li>When an application is replaced, it must be signed by the same key as the
+old application in order to get access to the old application's data.</li>
+<li>If two or more applications want to share a user ID (so they can share
+data, etc.), they must be signed with the same key.</ul></li>
+<li>OTA update packages must be signed with one of the keys expected by the
+system or the installation process will reject them.</ul></li>
+</ol>
+<h2 id="certificates-keys">Certificates and keys</h2>
+<p>Each key comes in two files: the <i>certificate</i>, which has the
+extension .x509.pem, and the <i>private key</i>, which has the extension .pk8.
+The private key should be kept secret and is needed to sign a package. The key
+may itself be protected by a password—a reasonable strategy is to store your
+keys in source control along with the code—but keep them protected by a
+password known only to the people who make final releases. The certificate, in
+contrast, contains only the public half of the key, so it can be distributed
+widely. It is used to verify a package has been signed by the corresponding
+private key.</p>
+<p>The standard Android build uses four keys, all of which reside in <code>
+build/target/product/security</code>:</p>
+
+<dl>
+<dt>testkey</dt>
+<dd>Generic default key for packages that do not otherwise specify a key.</dd>
+<dt>platform</dt>
+<dd>Test key for packages that are part of the core platform.</dd>
+<dt>shared</dt>
+<dd>Test key for things that are shared in the home/contacts process.</dd>
+<dt>media</dt>
+<dd>Test key for packages that are part of the media/download system.</dd></dl>
+
+<p>Individual packages specify one of these keys by setting LOCAL_CERTIFICATE
+in their Android.mk file. (testkey is used if this variable is not set.) You
+can also specify an entirely different key by pathname, e.g.:</p>
+
+<p><code>device/yoyodyne/apps/SpecialApp/Android.mk</code></p>
+<pre>
+ [...]
+
+LOCAL_CERTIFICATE := device/yoyodyne/security/special
+</pre>
+
+<p>Now the build uses the <code>device/yoyodyne/security/special.{x509.pem,pk8}
+</code> key to sign SpecialApp.apk. The build can use only private keys that
+are <i>not </i>password protected.</p>
+
+<h2>Generating keys</h2>
+<p>Android uses 2048-bit RSA keys with public exponent 3. You can generate
+certificate/private key pairs using the openssl tool from
+<a href="http://www.openssl.org/">openssl.org</a>:</p>
+
+<pre>
+# generate RSA key
+% <b>openssl genrsa -3 -out temp.pem 2048</b>
+Generating RSA private key, 2048 bit long modulus
+....+++
+.....................+++
+e is 3 (0x3)
+
+# create a certificate with the public part of the key
+% <b>openssl req -new -x509 -key temp.pem -out releasekey.x509.pem \
+ -days 10000 \
+ -subj '/C=US/ST=California/L=San Narciso/O=Yoyodyne, Inc./OU=Yoyodyne Mobility/CN=Yoyodyne/emailAddress=yoyodyne@example.com'</b>
+
+# create a PKCS#8-formatted version of the private key
+% <b>openssl pkcs8 -in temp.pem -topk8 -outform DER -out releasekey.pk8 -nocrypt</b>
+
+# securely delete the temp.pem file
+% <b>shred --remove temp.pem</b>
+</pre>
+
+<p>The openssl pkcs8 command given above creates a .pk8 file with <i>no</i>
+password, suitable for use with the build system. To create a .pk8 secured
+with a password (which you should do for all actual release keys), replace the
+<code>-nocrypt</code> argument with <code>-passout stdin</code>; then openssl
+will encrypt the private key with a password read from standard input. No
+prompt is printed, so if stdin is the terminal the program will appear to hang
+when it's really just waiting for you to enter a password. Other values can be
+used for the-passout argument to read the password from other locations; for
+details, see the
+<a href="http://www.openssl.org/docs/apps/openssl.html#PASS_PHRASE_ARGUMENTS">
+openssl documentation</a>.</p>
+<p>The temp.pem intermediate file contains the private key without any kind of
+password protection, so dispose of it thoughtfully when generating release
+keys. In particular, the GNUshred utility may not be effective on network or
+journaled filesystems. You can use a working directory located in a RAM disk
+(such as a tmpfs partition) when generating keys to ensure the intermediates
+are not inadvertently exposed.</p>
+
+<h2 id="sign-apps-for-release">Signing apps for release</h2>
+<p>The first step in preparing a build for release is to sign all the .apk
+files in it, replacing the test keys used by the build system. This is done
+with the <code>sign_target_files_apks</code> script. It takes a target-files
+.zip as input and produces a new target-files .zip in which all the .apks have
+been signed with new keys.</p>
+<p>When you run this script, you must specify on the command line a
+replacement key for each key used in the build. The <code>-k <i>src_key</i>=<i>
+dest_key</i></code> flag specifies key replacements one at a time. The flag
+<code>-d <i>dir</i></code> lets you specify a directory with four keys to
+replace all those in <code>build/target/product/security</code>; it is
+equivalent to using <code>-k</code> four times to specify the mappings:</p>
+
+<pre>
+build/target/product/security/testkey = dir/releasekey
+build/target/product/security/platform = dir/platform
+build/target/product/security/shared = dir/shared
+build/target/product/security/media = dir/media
+</pre>
+
+<p>For the hypothetical tardis product, you need five password-protected keys:
+four to replace the four in <code>build/target/product/security</code>, and
+one to replace the additional <code>keydevice/yoyodyne/security/special</code>
+required by SpecialApp in the example above. If the keys were in the following
+files:</p>
+
+<pre>
+vendor/yoyodyne/security/tardis/releasekey.x509.pem
+vendor/yoyodyne/security/tardis/releasekey.pk8
+vendor/yoyodyne/security/tardis/platform.x509.pem
+vendor/yoyodyne/security/tardis/platform.pk8
+vendor/yoyodyne/security/tardis/shared.x509.pem
+vendor/yoyodyne/security/tardis/shared.pk8
+vendor/yoyodyne/security/tardis/media.x509.pem
+vendor/yoyodyne/security/tardis/media.pk8
+vendor/yoyodyne/security/special.x509.pem
+vendor/yoyodyne/security/special.pk8 # NOT password protected
+vendor/yoyodyne/security/special-release.x509.pem
+vendor/yoyodyne/security/special-release.pk8 # password protected
+</pre>
+
+<p>Then you would sign all the apps like this:</p>
+
+<pre>
+% <b>./build/tools/releasetools/sign_target_files_apks \
+ -d vendor/yoyodyne/security/tardis \
+ -k vendor/yoyodyne/special=vendor/yoyodyne/special-release \
+ -o \ </b># explained in the next section<b>
+ tardis-target_files.zip signed-tardis-target_files.zip</b>
+Enter password for vendor/yoyodyne/security/special-release key>
+Enter password for vendor/yoyodyne/security/tardis/media key>
+Enter password for vendor/yoyodyne/security/tardis/platform key>
+Enter password for vendor/yoyodyne/security/tardis/releasekey key>
+Enter password for vendor/yoyodyne/security/tardis/shared key>
+ signing: Phone.apk (vendor/yoyodyne/security/tardis/platform)
+ signing: Camera.apk (vendor/yoyodyne/security/tardis/media)
+ signing: Special.apk (vendor/yoyodyne/security/special-release)
+ signing: Email.apk (vendor/yoyodyne/security/tardis/releasekey)
+ [...]
+ signing: ContactsProvider.apk (vendor/yoyodyne/security/tardis/shared)
+ signing: Launcher.apk (vendor/yoyodyne/security/tardis/shared)
+rewriting SYSTEM/build.prop:
+ replace: ro.build.description=tardis-user Eclair ERC91 15449 test-keys
+ with: ro.build.description=tardis-user Eclair ERC91 15449 release-keys
+ replace: ro.build.fingerprint=generic/tardis/tardis/tardis:Eclair/ERC91/15449:user/test-keys
+ with: ro.build.fingerprint=generic/tardis/tardis/tardis:Eclair/ERC91/15449:user/release-keys
+ signing: framework-res.apk (vendor/yoyodyne/security/tardis/platform)
+rewriting RECOVERY/RAMDISK/default.prop:
+ replace: ro.build.description=tardis-user Eclair ERC91 15449 test-keys
+ with: ro.build.description=tardis-user Eclair ERC91 15449 release-keys
+ replace: ro.build.fingerprint=generic/tardis/tardis/tardis:Eclair/ERC91/15449:user/test-keys
+ with: ro.build.fingerprint=generic/tardis/tardis/tardis:Eclair/ERC91/15449:user/release-keys
+using:
+ vendor/yoyodyne/security/tardis/releasekey.x509.pem
+for OTA package verification
+done.
+</pre>
+
+<p>After prompting the user for passwords for all password-protected keys, the
+script re-signs all the .apk files in the input target .zip with the release
+keys. Before running the command, you can also set the ANDROID_PW_FILE
+environment variable to a temporary filename; the script then invokes your
+editor to allow you to enter passwords for all keys (this may be a more
+convenient way to enter passwords).<p>
+<p><code>sign_target_files_apks</code> also rewrites the build description and
+fingerprint in the build properties files to reflect the fact that this is a
+signed build. The <code>-t</code> flag can control what edits are made to the
+fingerprint. Run the script with <code>-h</code> to see documentation on all
+flags.</p>
+
+<h2 id="sign-ota-packages">Signing OTA packages</h2>
+<p>You need the following components to sign OTA packages:</p>
+<ol>
+<li>Certificates of the keys you want this build to accept.</li>
+<li>Sign the newly-created package with the private key (must correspond to
+the certificate embedded in the current build of any device to which you want
+to send this package).</li>
+</ol>
+<p>To achieve these components:</p>
+<ul>
+<li>The target-files .zip produced by the build sets the OTA certificate to
+the certificate of the test key. Passing the <code>-o</code> flag to <code>
+sign_target_files_apks</code> replaces this key with the release key from your
+build.</li>
+<li>To sign the OTA update package, use the <code>-k</code> option when
+generating it to specify the key. You should give <code>ota_from_target_files
+</code> the <i>signed</i> version of the target-files .zip as well:
+<pre>
+% <b>./build/tools/releasetools/ota_from_target_files \
+ -k vendor/yoyodyne/security/tardis/releasekey \
+ signed-tardis-target_files.zip \
+ signed-ota_update.zip</b>
+unzipping target target-files...
+(using device-specific extensions from target_files)
+Enter password for vendor/yoyodyne/security/tardis/releasekey key>
+done.</pre></li></ul>
+
+<h3 id="signatures-sideloading">Signatures and sideloading</h3>
+<p>Sideloading does not bypass recovery's normal package signature
+verification mechanism—before installing a package, recovery will verify that
+it is signed with one of the private keys matching the public keys stored in
+the recovery partition, just as it would for a package delivered over-the-air.
+</p>
+<p>Update packages received from the main system are typically verified twice:
+once by the main system, using the <code><a href="http://developer.android.com/
+reference/android/os/RecoverySystem.html#verifyPackage">RecoverySystem.
+verifyPackage()</a></code> method in the android API, and then again by
+recovery. The RecoverySystem API checks the signature against public keys
+stored in the main system, in the file <code>/system/etc/security/otacerts.zip
+</code> (by default). Recovery checks the signature against public keys stored
+in the recovery partition RAM disk, in the file <code>/res/keys</code>.</p>
+<p>Normally these two locations store the same set of keys. By adding a key to
+<i>just</i> the recovery set of keys, it's possible to sign packages that can
+be installed only via sideloading (assuming the main system's update download
+mechanism is correctly doing verification against otacerts.zip). You can
+specify extra keys to be included only in recovery by setting the
+PRODUCT_EXTRA_RECOVERY_KEYS variable in your product definition:</p>
+
+<p><code>vendor/yoyodyne/tardis/products/tardis.mk</code></p>
+<pre>
+ [...]
+
+PRODUCT_EXTRA_RECOVERY_KEYS := vendor/yoyodyne/security/tardis/sideload
+</pre>
+
+<p>This includes the public key <code>vendor/yoyodyne/security/tardis/sideload.
+x509.pem</code> in the recovery keys file so it can install packages signed
+with it. The extra key is <i>not</i> included in otacerts.zip though, so
+systems that correctly verify downloaded packages do not invoke recovery for
+packages signed with this key.</p>
\ No newline at end of file
diff --git a/src/devices/tech/ota/tools.jd b/src/devices/tech/ota/tools.jd
new file mode 100755
index 0000000..1226379
--- /dev/null
+++ b/src/devices/tech/ota/tools.jd
@@ -0,0 +1,133 @@
+page.title=OTA Package Tools
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>The <a href="https://android.googlesource.com/platform/build/+/master/tools/
+releasetools/ota_from_target_files">ota_from_target_files</a> tool provided in
+<code>build/tools/releasetools</code> can build two types of package: <i>full
+</i> and <i>incremental</i>. The tool takes the <i>target-files</i> .zip file
+produced by the Android build system as input.</p>
+
+<h2 id="full-updates">Full updates</h2>
+<p>A <i>full</i> update is one where the entire final state of the device
+(system, boot, and recovery partitions) is contained in the package. As long
+as the device is capable of receiving the package and booting the recovery
+system, the package can install the desired build regardless of the current
+state of the device.</p>
+<p>Example: Using the release tools to build a full update for the
+hypothetical <b>tardis</b> device:</p>
+
+<pre>
+# first, build the target-files .zip
+% <b>. build/envsetup.sh && lunch tardis-eng</b>
+% <b>mkdir dist_output</b>
+% <b>make dist DIST_DIR=dist_output</b>
+ [...]
+% <b>ls -l dist_output/*target_files*</b>
+-rw-r----- 1 user eng 69965275 Sep 29 15:51 tardis-target_files.zip
+</pre>
+
+<p>The target-files .zip contains everything needed to construct OTA packages.
+</p>
+
+<pre>
+% <b>./build/tools/releasetools/ota_from_target_files \
+ dist_output/tardis-target_files.zip ota_update.zip</b>
+unzipping target target-files...
+done.
+% <b>ls -l ota_update.zip</b>
+-rw-r----- 1 user eng 62236561 Sep 29 15:58 ota_update.zip
+</pre>
+
+<p>The ota_update.zip is now ready to be sent to test devices (everything is
+signed with the test key). For user devices, generate and use your own private
+keys as detailed in <a href="{@docRoot}devices/tech/ota/sign_builds
+.html">Signing builds for release</a>.
+
+<h2 id="incremental-updates">Incremental updates</h2>
+<p>An <i>incremental</i> update contains a set of binary patches to be applied
+to the data already on the device. This can result in considerably smaller
+update packages:</p>
+<ul>
+<li>Files that have not changed don't need to be included.</li>
+<li>Files that have changed are often very similar to their previous versions,
+so the package need only contain an encoding of the differences between the
+two files.</li></ul>
+<p>You can install the incremental update package only on a device that has
+the old or source build used when constructing the package. To build an
+incremental update, you need the target_files .zip from the previous build
+(the one you want to update <i>from</i>) as well as the target_files .zip from
+the new build.</p>
+
+<pre>
+% <b>./build/tools/releasetools/ota_from_target_files \
+ -i PREVIOUS-tardis-target_files.zip \ </b># make incremental from this older version<b>
+ dist_output/tardis-target_files.zip incremental_ota_update.zip</b>
+unzipping target target-files...
+unzipping source target-files...
+ [...]
+done.
+% <b>ls -l incremental_ota_update.zip</b>
+-rw-r----- 1 user eng 1175314 Sep 29 16:10 incremental_ota_update.zip
+</pre>
+
+<p>This build is very similar to the previous build, and the incremental
+update package is much smaller than the corresponding full update (about 1 MB
+instead of 60 MB).</p>
+<p class="note"><strong>Note:</strong> To generate a
+<a href="{@docRoot}devices/tech/ota/block.html">block-based OTA</a>
+for subsequent updates, pass the <code>--block</code> option to
+<code>ota_from_target_files</code>.</p>
+<p>Distribute an incremental package only to devices running exactly the same
+previous build used as the incremental package's starting point. Attempting to
+install the incremental package on a device with some other build results in
+the recovery error icon. Rebooting the device at this point returns the user
+to the old system; the package verifies the previous state of all the files it
+updates before touching them, so the device should not be left in a half
+upgraded state if this occurs.</p>
+
+<h2 id="update-packages">Update packages</h2>
+<p>An update package (<code>ota_update.zip</code>,
+<code>incremental_ota_update.zip</code>) is a .zip file that contains the
+executable binary <code>META-INF/com/google/android/update-binary</code>. After
+verifying the signature on the package, recovery extracts this binary to
+<code>/tmp</code> and runs it, passing the following arguments:</p>
+<ul>
+<li><b>Update binary API version number</b>. If the arguments passed to the
+update binary change, this number is incremented.</li>
+<li><b>File descriptor of the <i>command pipe</i></b>. The update program can
+use this pipe to send commands back to the recovery binary (mostly for UI
+changes such as indicating progress to the user).</li>
+<li><b>Filename of the update package .zip file</b>.</li>
+</ul>
+<p>A recovery package can use any statically-linked binary as the update
+binary. The OTA package construction tools use the updater program (source in
+<code>bootable/recovery/updater</code>), which provides a simple scripting
+language that can do many installation tasks. You can substitute any other
+binary running on the device.</p>
+<p>For details on the updater binary, edify syntax, and builtin functions, see
+<a href="{@docRoot}devices/tech/ota/inside_packages.html">Inside OTA Packages
+</a>.
\ No newline at end of file
diff --git a/src/devices/tech/power/batterystats.jd b/src/devices/tech/power/batterystats.jd
new file mode 100644
index 0000000..92aeb04
--- /dev/null
+++ b/src/devices/tech/power/batterystats.jd
@@ -0,0 +1,1037 @@
+page.title=Viewing Battery Usage Data
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+ <p>The <code>dumpsys batterystats</code> command generates interesting
+ statistical data about battery usage on a device, organized by unique user
+ ID (UID). The statistics include the following:</p>
+
+ <ul>
+ <li>History of battery-related events</li>
+
+ <li>Global statistics for the device</li>
+
+ <li>Approximate power use per UID and system component</li>
+
+ <li>Per-app mobile milliseconds per packet</li>
+
+ <li>System UID aggregated statistics</li>
+
+ <li>App UID aggregated statistics</li>
+ </ul>
+
+ <p class="note">You can use the <a href=
+ "https://github.com/google/battery-historian">Battery Historian</a> tool on
+ the output of the dumpsys command to generate an HTML visualization of
+ power-related events from the logs. This information makes it easier for
+ you to understand and diagnose any battery-related issues.</p>
+
+ <h2 id="command-line_options">Command line options</h2>
+
+ <p>Use the <code>--help</code> option to learn about the various options
+ for tailoring the output.</p>
+
+ <p>Use the <code>--checkin</code> option to get the results in
+ machine-readable csv format.</p>
+
+ <p>To print battery usage statistics for a given app package since the
+ device was last charged, run this command:</p>
+ <pre class="prettyprint">
+$ adb shell dumpsys batterystats --charged <package-name>
+ </pre>
+
+ <h2 id="sample_input">Input</h2>
+
+ <p>To print battery usage statistics for all apps since the device was last
+ charged, in machine-readable format, run this command:</p>
+ <pre class="prettyprint">
+$ adb shell dumpsys batterystats --charged --checkin
+ </pre>
+
+ <h2 id="output">Output</h2>
+
+ <p>The output looks like this:</p>
+
+ <p>$ adb shell dumpsys batterystats --charged --checkin</p>
+
+ <pre class="no-pretty=print">
+ 9,0,i,vers,11,116,K,L 9,0,i,uid,1000,android
+ 9,0,i,uid,1000,com.android.providers.settings
+ 9,0,i,uid,1000,com.android.inputdevices
+ 9,0,i,uid,1000,com.android.server.telecom
+ 9,0,i,uid,1000,com.android.keychain 9,0,i,uid,1000,com.android.settings
+ 9,0,i,uid,1000,com.android.location.fused
+ 9,0,i,uid,1001,com.android.providers.telephony
+ 9,0,i,uid,1001,com.android.mms.service 9,0,i,uid,1001,com.android.stk
+ 9,0,i,uid,1001,com.android.phone 9,0,i,uid,1027,com.android.nfc
+ 9,0,i,uid,2000,com.android.shell
+ 9,0,i,uid,10002,com.android.providers.calendar
+ 9,0,i,uid,10003,com.android.cellbroadcastreceiver
+ 9,0,i,uid,10004,com.android.providers.userdictionary
+ 9,0,i,uid,10004,com.android.providers.contacts
+ 9,0,i,uid,10005,com.google.android.apps.enterprise.dmagent
+ 9,0,i,uid,10006,com.android.defcontainer
+ 9,0,i,uid,10007,com.android.providers.media
+ 9,0,i,uid,10007,com.android.providers.downloads
+ 9,0,i,uid,10007,com.android.providers.downloads.ui
+ 9,0,i,uid,10008,com.android.externalstorage
+ 9,0,i,uid,10009,com.google.android.syncadapters.contacts
+ 9,0,i,uid,10009,com.google.android.gms
+ 9,0,i,uid,10009,com.google.android.gsf
+ 9,0,i,uid,10009,com.google.android.gsf.login
+ 9,0,i,uid,10009,com.google.android.backuptransport
+ 9,0,i,uid,10011,com.google.android.dialer
+ 9,0,i,uid,10013,com.google.android.onetimeinitializer
+ 9,0,i,uid,10014,com.google.android.partnersetup
+ 9,0,i,uid,10015,com.android.launcher
+ 9,0,i,uid,10016,com.android.managedprovisioning
+ 9,0,i,uid,10017,com.android.mms 9,0,i,uid,10018,com.android.musicfx
+ 9,0,i,uid,10019,com.android.vending
+ 9,0,i,uid,10022,com.android.sharedstoragebackup
+ 9,0,i,uid,10023,com.android.systemui
+ 9,0,i,uid,10025,com.google.android.googlequicksearchbox
+ 9,0,i,uid,10027,com.google.android.apps.walletnfcrel
+ 9,0,i,uid,10029,com.google.android.marvin.talkback
+ 9,0,i,uid,10031,com.google.android.apps.books
+ 9,0,i,uid,10034,com.google.android.calendar
+ 9,0,i,uid,10037,com.android.chrome
+ 9,0,i,uid,10039,com.google.android.configupdater
+ 9,0,i,uid,10040,com.google.android.deskclock
+ 9,0,i,uid,10041,com.android.documentsui
+ 9,0,i,uid,10042,com.google.android.apps.docs
+ 9,0,i,uid,10047,com.google.android.ears
+ 9,0,i,uid,10054,com.google.android.talk
+ 9,0,i,uid,10057,com.google.android.inputmethod.latin
+ 9,0,i,uid,10061,com.google.android.music
+ 9,0,i,uid,10064,com.android.packageinstaller
+ 9,0,i,uid,10068,com.google.android.apps.plus
+ 9,0,i,uid,10069,com.google.android.gm
+ 9,0,i,uid,10070,com.google.android.keep
+ 9,0,i,uid,10071,com.google.android.apps.genie.geniewidget
+ 9,0,i,uid,10072,com.android.printspooler
+ 9,0,i,uid,10076,com.google.android.videos
+ 9,0,i,uid,10079,com.google.android.youtube
+ 9,0,i,uid,10084,com.google.android.apps.magazines
+ 9,0,i,dsd,1820451,97,s-,p- 9,0,i,dsd,3517481,98,s-,p-
+ 9,0,l,bt,0,8548446,1000983,8566645,1019182,1418672206045,8541652,994188
+ 9,0,l,gn,0,0,666932,495312,0,0,2104,1444
+ 9,0,l,m,6794,0,8548446,8548446,0,0,0,666932,495312,0,697728,0,0,0,5797,0,0
+ 9,0,l,br,9,0,6785,0,0 9,0,l,sgt,8548446,0,0,0,0 9,0,l,sst,9000
+ 9,0,l,sgc,0,0,0,0,0 9,0,l,dct,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ 9,0,l,dcc,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 9,0,l,wst,0,0,0,0,0,0,0,0
+ 9,0,l,wsc,0,0,0,0,0,0,0,0 9,0,l,wsst,0,0,0,0,0,0,0,52,0,0,8548394,0,0
+ 9,0,l,wssc,0,0,0,0,0,0,0,2,0,0,2,0,0 9,0,l,wsgt,0,0,0,3016,8545430
+ 9,0,l,wsgc,0,0,0,2,1 9,0,l,bst,0,0,0,0 9,0,l,bsc,0,0,0,0 9,0,l,dc,2,3,0,3
+ 9,0,l,kwl,msm_ipc_read00000001:00000001,0,0
+ 9,0,l,kwl,rpm_regulator_tcxo,0,0 9,0,l,kwl,wlan,25423,32
+ 9,0,l,kwl,event4-648,0,0 9,0,l,kwl,qcril,187,2 9,0,l,kwl,ssr(dsps),0,0
+ 9,0,l,kwl,bq51051b_wireless_chip,0,0 9,0,l,kwl,qmi0,0,0
+ 9,0,l,kwl,event5-648,7755,1231
+ 9,0,l,kwl,PowerManagerService.WakeLocks,680435,3908
+ 9,0,l,kwl,msm_hsic_host,66258,35 9,0,l,kwl,qcom_sap_wakelock,0,0
+ 9,0,l,kwl,sns_async_ev_wakelock,91954,1244 9,0,l,kwl,qmuxd_port_wl_12,0,0
+ 9,0,l,kwl,pil-wcnss,0,0 9,0,l,kwl,event0-648,11364,1212
+ 9,0,l,kwl,dofstrim,0,0 9,0,l,kwl,ssr(lpass),0,0
+ 9,0,l,kwl,qmuxd_port_wl_11,0,0 9,0,l,kwl,event2-648,0,0
+ 9,0,l,kwl,pil-vidc,0,0 9,0,l,kwl,mmc0,0,0
+ 9,0,l,kwl,tabla_gpio_irq_resend,0,0 9,0,l,kwl,pil-q6,0,0
+ 9,0,l,kwl,radio-interface,0,0 9,0,l,kwl,msm_ipc_read00000001:00000002,0,0
+ 9,0,l,kwl,event3-648,8143,1231 9,0,l,kwl,ssr(wcnss),0,0
+ 9,0,l,kwl,ssr(gss),0,0 9,0,l,kwl,KeyEvents,98,1263
+ 9,0,l,kwl,unknown_wakeups,0,0 9,0,l,kwl,qmuxd_port_wl_10,0,0
+ 9,0,l,kwl,pil-gss,0,0 9,0,l,kwl,qcom_rx_wakelock,161828,3205
+ 9,0,l,kwl,ssr(external_modem),0,0 9,0,l,kwl,power-supply,228,23
+ 9,0,l,kwl,pil-dsps,0,0 9,0,l,kwl,wcnss,0,0 9,0,l,kwl,msm_otg,0,0
+ 9,0,l,kwl,pm8921_eoc,0,0 9,0,l,kwl,slimport_wake_lock,0,0
+ 9,0,l,kwl,smsm_snapshot,0,0 9,0,l,kwl,suspend_backoff,239760,24
+ 9,0,l,kwl,event1-648,9331,1212 9,0,l,kwl,main,429,0
+ 9,0,l,kwl,alarm,2892,270 9,0,l,kwl,PowerManagerService.Display,432,1
+ 9,0,l,kwl,qmi1,0,0 9,0,l,kwl,kickstart,211,1
+ 9,0,l,kwl,qmuxd_port_wl_9,9,102 9,0,l,kwl,ear_hook,0,0
+ 9,0,l,kwl,mmc0_detect,52,1232 9,0,l,kwl,deleted_wake_locks,0,0
+ 9,0,l,kwl,PowerManagerService.Broadcasts,7331,0 9,0,l,kwl,qmi2,0,0
+ 9,0,l,kwl,smd_sns_dsps,456,1340 9,0,l,kwl,alarm_rtc,36084,122
+ 9,0,l,pws,2100,64.4,42.0,63.0 9,10009,l,pwi,uid,20.6 9,0,l,pwi,cell,18.5
+ 9,0,l,pwi,idle,8.73 9,0,l,pwi,uid,5.46 9,1000,l,pwi,uid,5.11
+ 9,0,l,pwi,wifi,3.28 9,10019,l,pwi,uid,0.847 9,10069,l,pwi,uid,0.408
+ 9,0,l,pwi,scrn,0.385 9,10034,l,pwi,uid,0.322 9,10025,l,pwi,uid,0.185
+ 9,10002,l,pwi,uid,0.180 9,10023,l,pwi,uid,0.168 9,1001,l,pwi,uid,0.0297
+ 9,10068,l,pwi,uid,0.0296 9,10057,l,pwi,uid,0.0234 9,1027,l,pwi,uid,0.0157
+ 9,10079,l,pwi,uid,0.00905 9,10054,l,pwi,uid,0.00527
+ 9,10005,l,pwi,uid,0.00341 9,10004,l,pwi,uid,0.00204
+ 9,2000,l,pwi,uid,0.00192 9,10070,l,pwi,uid,0.00144
+ 9,10061,l,pwi,uid,0.000860 9,10014,l,pwi,uid,0.000495
+ 9,10040,l,pwi,uid,0.000286 9,1014,l,pwi,uid,0.00000157 9,0,l,pwi,over,1.36
+ 9,0,l,nt,0,0,127699,11159,0,0,975,163,0,0
+ 9,0,l,pr,file-storage,0,140,0,0,0,0 9,0,l,pr,TX_Thread,0,440,0,0,0,0
+ 9,0,l,pr,flush-179:0,0,850,0,0,0,0 9,0,l,pr,sync_supers,10,0,0,0,0,0
+ 9,0,l,pr,dhcpcd,0,30,0,0,0,0 9,0,l,pr,kauditd,50,10,0,0,0,0
+ 9,0,l,pr,sdcard,20,110,0,0,0,0 9,0,l,pr,flush-0:18,40,100,0,0,0,0
+ 9,0,l,pr,zygote,250,90,0,0,0,0 9,0,l,pr,bdi-default,0,610,0,0,0,0
+ 9,0,l,pr,ueventd,940,2630,0,0,0,0 9,0,l,pr,kswapd0,0,180,0,0,0,0
+ 9,0,l,pr,debuggerd,180,610,0,0,0,0 9,0,l,pr,jbd2/mmcblk0p20,0,50,0,0,0,0
+ 9,0,l,pr,jbd2/mmcblk0p21,0,250,0,0,0,0
+ 9,0,l,pr,jbd2/mmcblk0p22,0,90,0,0,0,0
+ 9,0,l,pr,jbd2/mmcblk0p23,0,1150,0,0,0,0 9,0,l,pr,MC_Thread,0,1270,0,0,0,0
+ 9,0,l,pr,adbd,10,40,0,0,0,0 9,0,l,pr,lmkd,360,990,0,0,0,0
+ 9,0,l,pr,logd,1550,1670,0,0,0,0 9,0,l,pr,netd,80,330,0,0,0,0
+ 9,0,l,pr,rild,160,0,0,0,0,0 9,0,l,pr,vold,50,100,0,0,0,0
+ 9,0,l,pr,/init,0,70,0,0,0,0 9,0,l,pr,mpdecision,1400,7820,0,0,0,0
+ 9,0,l,pr,khubd,0,10,0,0,0,0 9,0,l,pr,kthreadd,0,600,0,0,0,0
+ 9,0,l,pr,kworker/0:0,0,3520,0,0,0,0 9,0,l,pr,sensors.qcom,380,720,0,0,0,0
+ 9,0,l,pr,healthd,20,190,0,0,0,0 9,0,l,pr,thermald,60,360,0,0,0,0
+ 9,0,l,pr,mmcqd/0,0,8700,0,0,0,0 9,0,l,pr,qseecomd,0,90,0,0,0,0
+ 9,0,l,pr,ksoftirqd/0,0,420,0,0,0,0 9,0,l,pr,wpa_supplicant,170,160,0,0,0,0
+ 9,0,l,pr,migration/0,0,1630,0,0,0,0 9,0,l,pr,migration/1,20,0,0,0,0,0
+ 9,0,l,pr,RX_Thread,0,790,0,0,0,0 9,0,l,pr,netmgrd,40,20,0,0,0,0
+ 9,1000,l,nt,0,0,11054,11216,0,0,26,29,0,0 9,1000,l,ua,2,0,0
+ 9,1000,l,sr,5,6813,1 9,1000,l,wl,*alarm*,0,f,0,23856,p,151,0,w,0
+ 9,1000,l,st,8548446,8548446,8548446 9,1000,l,pr,system,83310,35060,0,0,0,0
+ 9,1000,l,pr,surfaceflinger,6620,9330,0,0,0,0 9,1000,l,pr,ks,0,60,0,0,0,0
+ 9,1000,l,pr,qcks,0,90,0,0,0,0 9,1000,l,pr,efsks,0,50,0,0,0,0
+ 9,1000,l,pr,com.android.server.telecom,110,100,0,0,0,0
+ 9,1000,l,pr,servicemanager,40,110,0,0,0,0
+ 9,1001,l,st,8548446,8548446,8548446 9,1001,l,pr,qmuxd,0,30,0,0,0,0
+ 9,1001,l,pr,com.android.phone,450,300,0,0,0,0
+ 9,1014,l,nt,0,0,3410,3370,0,0,10,10,0,0 9,1027,l,st,8548446,8548446,8548446
+ 9,1027,l,pr,com.android.nfc,250,160,0,0,0,0
+ 9,10002,l,apk,15,com.android.providers.calendar,com.android.providers.calendar.CalendarProviderIntentService,2383,15,15
+ 9,10005,l,nt,0,0,1241,2488,0,0,6,10,0,0
+ 9,10009,l,nt,0,0,232255,258511,0,0,472,600,0,0
+ 9,10009,l,wfl,7689000,9814000,0
+ 9,10009,l,jb,com.google.android.gms/.gcm.nts.TaskExecutionService,81,3
+ 9,10009,l,sr,0,43643,46 9,10025,l,nt,0,0,152461,42850,0,0,267,243,0,0
+ 9,10025,l,wfl,1593000,629000,0 9,10034,l,nt,0,0,77657,40093,0,0,172,170,0,0
+ 9,10068,l,nt,0,0,11929,8383,0,0,50,47,0,0
+ 9,10069,l,nt,0,0,41553,22886,0,0,85,91,0,0</pre>
+
+ <h2 id="interpreting_the_output">Interpreting the output</h2>
+
+ <p>The sample output is in CSV format. Each line in the output contains
+ statistics related to battery usage.</p>
+
+ <p>The first four values in each line correspond to the following:</p>
+
+ <ul>
+ <li>Dummy integer</li>
+
+ <li>UID</li>
+
+ <li>Aggregation mode
+
+ <ul>
+ <li>"l" for --charged, means usage since last charge.</li>
+ <li>"u" for --unplugged, which means usage since last unplugged.</li>
+ <li>"i" for information that is not
+ tied to charged/uncharged status.</li>
+ </ul>
+ </li>
+
+ <li>Section identifier, which determines how to interpret the fifth
+ value and the following ones in the line.</li>
+ </ul>
+
+ <p>Currently, there are 41 sections and the interpretation for each section
+ is shown in the following table:</p>
+
+ <table>
+ <tr>
+ <td>
+ <p><strong>Order</strong></p>
+ </td>
+
+ <td class="tab0">
+ <p><strong>Section Identifier</strong></p>
+ </td>
+
+ <td class="tab0">
+ <p><strong>Description</strong></p>
+ </td>
+
+ <td class="tab0">
+ <p><strong>Remaining Fields</strong></p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>1</p>
+ </td>
+
+ <td class="tab0">
+ <p>vers</p>
+ </td>
+
+ <td class="tab0">
+ <p>Version</p>
+ </td>
+
+ <td class="tab0">
+ <p>checkin version, parcel version, start platform version, end
+ platform version</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>2</p>
+ </td>
+
+ <td class="tab0">
+ <p>uid</p>
+ </td>
+
+ <td class="tab0">
+ <p>UID</p>
+ </td>
+
+ <td class="tab0">
+ <p>uid, package name</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>3</p>
+ </td>
+
+ <td class="tab0">
+ <p>apk</p>
+ </td>
+
+ <td class="tab0">
+ <p>APK</p>
+ </td>
+
+ <td class="tab0">
+ <p>wakeups, APK, service, start time, starts, launches</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>4</p>
+ </td>
+
+ <td class="tab0">
+ <p>pr</p>
+ </td>
+
+ <td class="tab0">
+ <p>Process</p>
+ </td>
+
+ <td class="tab0">
+ <p>process, user, system, foreground, starts</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>5</p>
+ </td>
+
+ <td class="tab0">
+ <p>sr</p>
+ </td>
+
+ <td class="tab0">
+ <p>Sensor</p>
+ </td>
+
+ <td class="tab0">
+ <p>sensor number, time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>6</p>
+ </td>
+
+ <td class="tab0">
+ <p>vib</p>
+ </td>
+
+ <td class="tab0">
+ <p>Vibrator</p>
+ </td>
+
+ <td class="tab0">
+ <p>time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>7</p>
+ </td>
+
+ <td class="tab0">
+ <p>fg</p>
+ </td>
+
+ <td class="tab0">
+ <p>Foreground</p>
+ </td>
+
+ <td class="tab0">
+ <p>time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>8</p>
+ </td>
+
+ <td class="tab0">
+ <p>st</p>
+ </td>
+
+ <td class="tab0">
+ <p>State Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>foreground, active, running</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>9</p>
+ </td>
+
+ <td class="tab0">
+ <p>wl</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wake lock</p>
+ </td>
+
+ <td class="tab0">
+ <p>wake lock, full time, 'f', full count, partial time, 'p', partial
+ count, window time, 'w', window count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>10</p>
+ </td>
+
+ <td class="tab0">
+ <p>sy</p>
+ </td>
+
+ <td class="tab0">
+ <p>Sync</p>
+ </td>
+
+ <td class="tab0">
+ <p>sync, time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>11</p>
+ </td>
+
+ <td class="tab0">
+ <p>jb</p>
+ </td>
+
+ <td class="tab0">
+ <p>Job</p>
+ </td>
+
+ <td class="tab0">
+ <p>job, time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>12</p>
+ </td>
+
+ <td class="tab0">
+ <p>kwl</p>
+ </td>
+
+ <td class="tab0">
+ <p>Kernel Wake Lock</p>
+ </td>
+
+ <td class="tab0">
+ <p>kernel wake lock, time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>13</p>
+ </td>
+
+ <td class="tab0">
+ <p>wr</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wakeup Reason</p>
+ </td>
+
+ <td class="tab0">
+ <p>wakeup reason, time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>14</p>
+ </td>
+
+ <td class="tab0">
+ <p>nt</p>
+ </td>
+
+ <td class="tab0">
+ <p>Network</p>
+ </td>
+
+ <td class="tab0">
+ <p>mobile bytes RX, mobile bytes TX, Wi-Fi bytes RX, Wi-Fi bytes TX,
+ mobile packets RX, mobile packets TX, Wi-Fi packets RX, Wi-Fi packets
+ TX, mobile active time, mobile active count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>15</p>
+ </td>
+
+ <td class="tab0">
+ <p>ua</p>
+ </td>
+
+ <td class="tab0">
+ <p>User Activity</p>
+ </td>
+
+ <td class="tab0">
+ <p>other, button, touch</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>16</p>
+ </td>
+
+ <td class="tab0">
+ <p>bt</p>
+ </td>
+
+ <td class="tab0">
+ <p>Battery</p>
+ </td>
+
+ <td class="tab0">
+ <p>start count, battery realtime, battery uptime, total realtime,
+ total uptime, start clock time, battery screen off realtime, battery
+ screen off uptime</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>17</p>
+ </td>
+
+ <td class="tab0">
+ <p>dc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Battery Discharge</p>
+ </td>
+
+ <td class="tab0">
+ <p>low, high, screen on, screen off</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>18</p>
+ </td>
+
+ <td class="tab0">
+ <p>lv</p>
+ </td>
+
+ <td class="tab0">
+ <p>Battery Level</p>
+ </td>
+
+ <td class="tab0">
+ <p>start level, current level</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>19</p>
+ </td>
+
+ <td class="tab0">
+ <p>wfl</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi</p>
+ </td>
+
+ <td class="tab0">
+ <p>full Wi-Fi lock on time, Wi-Fi scan time, Wi-Fi running time</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>20</p>
+ </td>
+
+ <td class="tab0">
+ <p>m</p>
+ </td>
+
+ <td class="tab0">
+ <p>Misc</p>
+ </td>
+
+ <td class="tab0">
+ <p>screen on time, phone on time, Wi-Fi on time, Wi-Fi running time,
+ Bluetooth on time, mobile RX total bytes, mobile TX total bytes,
+ Wi-Fi RX total bytes, Wi-Fi TX total bytes, full wake lock time
+ total, partial wake lock time total, legacy input event count, mobile
+ radio active time, mobile radio active adjusted time, interactive
+ time, low-power mode enabled time</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>21</p>
+ </td>
+
+ <td class="tab0">
+ <p>gn</p>
+ </td>
+
+ <td class="tab0">
+ <p>Global Network</p>
+ </td>
+
+ <td class="tab0">
+ <p>mobile RX total bytes, mobile TX total bytes, Wi-Fi RX total
+ bytes, Wi-Fi TX total bytes, mobile RX total packets, mobile TX total
+ packets, Wi-Fi RX total packets, Wi-Fi TX total packets</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>22</p>
+ </td>
+
+ <td class="tab0">
+ <p>br</p>
+ </td>
+
+ <td class="tab0">
+ <p>Screen Brightness</p>
+ </td>
+
+ <td class="tab0">
+ <p>dark, dim, medium, light, bright</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>23</p>
+ </td>
+
+ <td class="tab0">
+ <p>sst</p>
+ </td>
+
+ <td class="tab0">
+ <p>Signal Scanning Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>signal scanning time</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>24</p>
+ </td>
+
+ <td class="tab0">
+ <p>sgt</p>
+ </td>
+
+ <td class="tab0">
+ <p>Signal Strength Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>none, poor, moderate, good, great</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>25</p>
+ </td>
+
+ <td class="tab0">
+ <p>sgc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Signal Strength Count</p>
+ </td>
+
+ <td class="tab0">
+ <p>none, poor, moderate, good, great</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>26</p>
+ </td>
+
+ <td class="tab0">
+ <p>dct</p>
+ </td>
+
+ <td class="tab0">
+ <p>Data Connection Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>none, GPRS, EDGE, UMTS, CDMA, EVDO_0, EVDO_A, 1xRTT, HSDPA, HSUPA,
+ HSPA, IDEN, EVDO_B, LTE, EHRPD, HSPAP, other</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>27</p>
+ </td>
+
+ <td class="tab0">
+ <p>dcc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Data Connection Count</p>
+ </td>
+
+ <td class="tab0">
+ <p>none, GPRS, EDGE, UMTS, CDMA, EVDO_0, EVDO_A, 1xRTT, HSDPA, HSUPA,
+ HSPA, IDEN, EVDO_B, LTE, EHRPD, HSPAP, other</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>28</p>
+ </td>
+
+ <td class="tab0">
+ <p>wst</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi State Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>off, off scanning, on no networks, on disconnected, on connected
+ STA, on connected P2P, on connected STA P2P, soft AP</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>29</p>
+ </td>
+
+ <td class="tab0">
+ <p>wsc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi State Count</p>
+ </td>
+
+ <td class="tab0">
+ <p>off, off scanning, on no networks, on disconnected, on connected
+ STA, on connected P2P, on connected STA P2P, soft AP</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>30</p>
+ </td>
+
+ <td class="tab0">
+ <p>wsst</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi Supplicant State Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>invalid, disconnected, interface disabled, inactive, scanning,
+ authenticating, associating, associated, four-way handshake, group
+ handshake, completed, dormant, uninitialized</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>31</p>
+ </td>
+
+ <td class="tab0">
+ <p>wssc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi Supplicant State Count</p>
+ </td>
+
+ <td class="tab0">
+ <p>invalid, disconnected, interface disabled, inactive, scanning,
+ authenticating, associating, associated, four-way handshake, group
+ handshake, completed, dormant, uninitialized</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>32</p>
+ </td>
+
+ <td class="tab0">
+ <p>wsgt</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi Signal Strength Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>none, poor, moderate, good, great</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>33</p>
+ </td>
+
+ <td class="tab0">
+ <p>wsgc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi Signal Strength Count</p>
+ </td>
+
+ <td class="tab0">
+ <p>none, poor, moderate, good, great</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>34</p>
+ </td>
+
+ <td class="tab0">
+ <p>bst</p>
+ </td>
+
+ <td class="tab0">
+ <p>Bluetooth State Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>inactive, low, med, high</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>35</p>
+ </td>
+
+ <td class="tab0">
+ <p>bsc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Bluetooth State Count</p>
+ </td>
+
+ <td class="tab0">
+ <p>inactive, low, med, high</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>36</p>
+ </td>
+
+ <td class="tab0">
+ <p>pws</p>
+ </td>
+
+ <td class="tab0">
+ <p>Power Use Summary</p>
+ </td>
+
+ <td class="tab0">
+ <p>battery capacity, computed power, minimum drained power, maximum
+ drained power</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>37</p>
+ </td>
+
+ <td class="tab0">
+ <p>pwi</p>
+ </td>
+
+ <td class="tab0">
+ <p>Power Use Item</p>
+ </td>
+
+ <td class="tab0">
+ <p>label, mAh</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>38</p>
+ </td>
+
+ <td class="tab0">
+ <p>dsd</p>
+ </td>
+
+ <td class="tab0">
+ <p>Discharge Step</p>
+ </td>
+
+ <td class="tab0">
+ <p>duration, level, screen, power-save</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>39</p>
+ </td>
+
+ <td class="tab0">
+ <p>csd</p>
+ </td>
+
+ <td class="tab0">
+ <p>Charge Step</p>
+ </td>
+
+ <td class="tab0">
+ <p>duration, level, screen, power-save</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>40</p>
+ </td>
+
+ <td class="tab0">
+ <p>dtr</p>
+ </td>
+
+ <td class="tab0">
+ <p>Discharge Time Remaining</p>
+ </td>
+
+ <td class="tab0">
+ <p>battery time remaining</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>41</p>
+ </td>
+
+ <td class="tab0">
+ <p>ctr</p>
+ </td>
+
+ <td class="tab0">
+ <p>Charge Time Remaining</p>
+ </td>
+
+ <td class="tab0">
+ <p>charge time remaining</p>
+ </td>
+ </tr>
+ </table>
diff --git a/src/devices/tech/power.jd b/src/devices/tech/power/index.jd
similarity index 90%
rename from src/devices/tech/power.jd
rename to src/devices/tech/power/index.jd
index 38e1e6a..c3a6a9a 100644
--- a/src/devices/tech/power.jd
+++ b/src/devices/tech/power/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 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.
@@ -28,9 +28,9 @@
<h2 id="usage-statistics">Battery Usage Statistics</h2>
<p>The framework automatically determines battery usage statistics by tracking how long device
-components spend in different states. As components (WiFi chipset, Cellular Radio, Bluetooth, GPS,
-Display, CPU) change states (OFF/ON, idle/full power, low/high brightness, etc.), the controlling
-service reports to the framework BatteryStats service, which collects information over time and
+components spend in different states. As components (Wi-Fi chipset, cellular radio, Bluetooth, GPS,
+display, CPU) change states (OFF/ON, idle/full power, low/high brightness, etc.), the controlling
+service reports to the framework BatteryStats service. BatteryStats collects information over time and
stores it for use across reboots. The service doesn’t track battery current draw directly,
but instead collects timing information that can be used to approximate battery
consumption by different components.</p>
@@ -59,9 +59,15 @@
<h2 id="profile-values">Power Profile Values</h2>
-<p>Device manufacturers must provide a component power profile that defines the current
-consumption value for the component and the approximate the actual battery drain caused by the
-component over time. Within a power profile, power consumption is specified in milliamps (mA) of
+<p class="caution"><strong>Caution:</strong> Device manufacturers must
+provide a component power profile that defines the current consumption value
+for the component and the approximate battery drain caused by the component
+over time. This profile is defined in <a
+href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/xml/power_profile.xml">platform/frameworks/base/core/res/res/xml/power_profile.xml</a>.
+See the <a href="#power-values">Power Values</a> table for guidance on these
+settings.</p>
+
+<p>Within a power profile, power consumption is specified in milliamps (mA) of
current draw at a nominal voltage and can be a fractional value specified in microamps (uA). The
value should be the mA consumed at the battery and not a value applicable to a power rail that does
not correspond to current consumed from the battery.</p>
@@ -144,7 +150,7 @@
connecting to external power supplies. Alternatively, you can modify the system to ignore the
invalid data from the missing battery.</p>
-<a name="control-suspend"><h3 id="control-suspend">Controlling System Suspend</h3></a>
+<h3 id="control-suspend">Controlling System Suspend</h3>
<p>This section describes how to avoid system suspend state when you don’t want it to interfere with
other measurements, and how to measure the power draw of system suspend state when you do want to
@@ -191,7 +197,7 @@
</li>
</ul>
-<a name="control-cpu"><h3 id="control-cpu">Controlling CPU Speeds</h3></a>
+<h3 id="control-cpu">Controlling CPU Speeds</h3>
<p>Active CPUs can be brought online or put offline, have their clock speeds and associated voltages
changed (possibly also affecting memory bus speeds and other system core power states), and
@@ -251,14 +257,15 @@
such limiting, either using the system console output when taking measurements or by checking the
kernel log after measuring.</p>
-<p>For the <code>cpu.active</code> value, measure the power consumed when the system is not in
+<p>For the <code>cpu.awake</code> value, measure the power consumed when the system is not in
suspend and not executing tasks. The CPU should be in a low-power scheduler <em>idle loop
-</em>, possibly executing an ARM Wait For Event instruction or in an SoC-specific low power state
-with a fast exit latency suitable for idle use. Your platform might have more than one idle state in
-use with differing levels of power consumption; choose a representative idle state for
-longer periods of scheduler idle (several milliseconds). Examine the power graph on your measurement
-equipment and choose samples where the CPU is at its lowest consumption, discarding higher samples
-where the CPU exited idle.</p>
+</em>, possibly executing an ARM Wait For Event instruction or in an SoC-specific low-power state
+with a fast-exit latency suitable for idle use.</p>
+
+<p>For the <code>cpu.active</code> value, power needs to be measured when the
+system is not in suspend mode and not executing tasks. One of the CPU (usually
+the primary CPU) should be running the task, and all the other CPUs should be in
+an idle state.</p>
<h3 id="screen-power">Measuring Screen Power</h3>
@@ -302,7 +309,7 @@
<p>The <code>wifi.scan</code> value measures the power consumed during a Wi-Fi scan for access
points. Applications can trigger Wi-Fi scans using the WifiManager class
-<a href = "http://developer.android.com/reference/android/net/wifi/WifiManager.html">
+<a href ="http://developer.android.com/reference/android/net/wifi/WifiManager.html">
<code>startScan()</code>API</a>. You can also open Settings > Wi-Fi, which performs access point
scans every few seconds with an apparent jump in power consumption, but you must subtract screen
power from these measurements.</p>
@@ -409,9 +416,9 @@
with variation inherent in the loading, consider using a longer test window.</li>
</ul>
-<a name="nexus-devices"><h3>Supported Nexus Devices</h3></a>
+<h3 id="nexus-devices">Supported Nexus Devices</h3>
-<h5><a name="nexus-5">Nexus 5</a></h5>
+<h5 id="nexus-5">Nexus 5</h5>
<table>
<tbody>
@@ -436,7 +443,7 @@
</table>
-<h5><a name="nexus-6">Nexus 6</a></h5>
+<h5 id="nexus-6">Nexus 6</h5>
<table>
<tbody>
@@ -471,7 +478,7 @@
</table>
-<h5><a name="nexus-9">Nexus 9</a></h5>
+<h5 id="nexus-9">Nexus 9</h5>
<table>
<tbody>
@@ -506,7 +513,7 @@
</table>
-<h5><a name="nexus-10">Nexus 10</a></h5>
+<h5 id="nexus-10">Nexus 10</h5>
<table>
<tbody>
@@ -543,26 +550,17 @@
<h2 id="viewing-usage">Viewing Battery Usage Data</h2>
-<p>The <code>dumpsys</code> <code>batterystats</code> command generates interesting statistical data
-about battery usage on a device, organized by unique application ID. You can view a history of
-battery-related events such as mobile radio state, Wi-Fi and Bluetooth power states, and wakelock
-reasons.</p>
-
-<p>Statistics include:</p>
-
-<ul>
-<li>History of battery-related events</li>
-<li>Global statistics for the device</li>
-<li>Approximate power use per UID and system component</li>
-<li>System UID aggregated statistics</li>
-</ul>
-
-<p>Use the output of the dumpsys command with the
-<a href="https://github.com/google/battery-historian">Battery Historian</a> tool to generate HTML
-visualizations of power-related events from logs.</p>
-
+See <a href="{@docRoot}devices/tech/power/batterystats.html">Viewing Battery Usage Data</a>.
<h2 id="power-values">Power Values</h2>
+
+<p>Device manufacturers must provide a component power profile defined in
+<em><device></em>/frameworks/base/core/res/res/xml/power_profile.xml. To
+determine these values, use hardware that measures the power being used by
+the device and perform the various operations for which information is needed.
+Measure the power use during those operations and compute the values (deriving
+differences from other base-line power uses as appropriate).</p>
+
<table>
<tr>
<th>Name</th>
@@ -675,7 +673,7 @@
<tr>
<td>cpu.speeds</td>
<td>Multi-value entry that lists each possible CPU speed in KHz.</td>
- <td>125000, 250000, 500000, 1000000, 1500000</td>
+ <td>125000KHz, 250000KHz, 500000KHz, 1000000KHz, 1500000KHz</td>
<td>The number and order of entries must correspond to the mA entries in cpu.active.</td>
</tr>
@@ -691,13 +689,17 @@
<td>Additional power used when CPUs are in scheduling idle state (kernel idle loop); system is not
in system suspend state.</td>
<td>50mA</td>
- <td></td>
+ <td>Your platform might have more than one idle state in use with differing
+levels of power consumption; choose a representative idle state for longer
+periods of scheduler idle (several milliseconds). Examine the power graph on
+your measurement equipment and choose samples where the CPU is at its lowest
+consumption, discarding higher samples where the CPU exited idle.</td>
</tr>
<tr>
<td>cpu.active</td>
<td>Additional power used by CPUs when running at different speeds.</td>
- <td>100, 120, 140, 160, 200</td>
+ <td>100mA, 120mA, 140mA, 160mA, 200mA</td>
<td>Set the max speed in the kernel to each of the allowed speeds and peg the CPU at that
speed. The number of entries here correspond to the number of entries in cpu.speeds, in the
same order.</td>
@@ -712,9 +714,6 @@
</table>
-<p>The power_profile.xml file is placed in an overlay in
-device///frameworks/base/core/res/res/xml/power_profile.xml</p>
-
<h3 id="sample">Sample file</h3>
<pre>
@@ -764,4 +763,4 @@
3000
<!-- Battery capacity is 3000 mAH (at 3.6 Volts) -->
-</pre>
\ No newline at end of file
+</pre>
diff --git a/src/devices/tech/input/index.jd b/src/devices/tech/ram/index.jd
similarity index 62%
copy from src/devices/tech/input/index.jd
copy to src/devices/tech/ram/index.jd
index 80c5e5f..2bb2717 100644
--- a/src/devices/tech/input/index.jd
+++ b/src/devices/tech/ram/index.jd
@@ -1,8 +1,8 @@
-page.title=Input Technical Information
+page.title=RAM
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -16,7 +16,6 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<p>The Android input subsystem supports many different device classes,
-including keyboard, joystick, trackball, mouse and touch screen.</p>
-<p>The documentation in this section describes how to configure,
-calibrate, test, and write drivers for input devices.</p>
+
+<p> The following sections contain information, documentation, tips and tricks about Android memory managment and RAM diagnostics.</p>
+
diff --git a/src/devices/low-ram.jd b/src/devices/tech/ram/low-ram.jd
similarity index 100%
rename from src/devices/low-ram.jd
rename to src/devices/tech/ram/low-ram.jd
diff --git a/src/devices/tech/ram/procstats.jd b/src/devices/tech/ram/procstats.jd
new file mode 100644
index 0000000..48e6ed0
--- /dev/null
+++ b/src/devices/tech/ram/procstats.jd
@@ -0,0 +1,368 @@
+page.title=Viewing RAM Usage Data (procstats)
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc"></ol>
+ </div>
+</div>
+
+<p>The <code>procstats</code> tool is used to analyze application memory usage over time (versus at a
+particular snapshot in time, like <code>meminfo</code>). Its state dump displays statistics about every application’s runtime,
+proportional set size (PSS) and unique set size (USS).</p>
+
+<h2 id=input>Input</h2>
+
+
+<p>To get application memory usage stats for the last three hours, in
+human-readable form, run the following command:</p>
+
+<pre class=prettyprint>
+$ adb shell dumpsys procstats --hours 3
+</pre>
+
+
+
+<h2 id=output>Output</h2>
+
+
+<p>As can be seen in the example below, percentages display what percentage of
+time the application was running, while the numbers following show PSS and USS
+as minPSS-avgPSS-maxPSS/minUSS-avgUSS-maxUSS over samples.</p>
+
+<pre class="no-pretty-print">
+AGGREGATED OVER LAST 3 HOURS:
+ * com.android.systemui / u0a20 / v22:
+ TOTAL: 100% (109MB-126MB-159MB/108MB-125MB-157MB over 18)
+ Persistent: 100% (109MB-126MB-159MB/108MB-125MB-157MB over 18)
+ * com.android.nfc / 1027 / v22:
+ TOTAL: 100% (17MB-17MB-17MB/16MB-16MB-16MB over 18)
+ Persistent: 100% (17MB-17MB-17MB/16MB-16MB-16MB over 18)
+ * android.process.acore / u0a4 / v22:
+ TOTAL: 100% (14MB-15MB-15MB/14MB-14MB-14MB over 20)
+ Imp Fg: 100% (14MB-15MB-15MB/14MB-14MB-14MB over 20)
+ * com.google.android.inputmethod.latin / u0a56 / v21483:
+ TOTAL: 100% (57MB-59MB-59MB/56MB-58MB-58MB over 19)
+ Imp Fg: 100% (57MB-59MB-59MB/56MB-58MB-58MB over 19)
+ * com.redbend.vdmc / 1001 / v1:
+ TOTAL: 100% (9.5MB-9.6MB-9.7MB/8.8MB-8.9MB-9.0MB over 18)
+ Persistent: 100% (9.5MB-9.6MB-9.7MB/8.8MB-8.9MB-9.0MB over 18)
+ * com.android.phone / 1001 / v22:
+ TOTAL: 100% (19MB-22MB-27MB/18MB-21MB-26MB over 18)
+ Persistent: 100% (19MB-22MB-27MB/18MB-21MB-26MB over 18)
+ * com.google.android.gms.persistent / u0a8 / v7319438:
+ TOTAL: 100% (32MB-35MB-40MB/30MB-33MB-37MB over 19)
+ Imp Fg: 100% (32MB-35MB-40MB/30MB-33MB-37MB over 19)
+ * com.android.bluetooth / 1002 / v22:
+ TOTAL: 100% (9.3MB-9.7MB-10MB/8.5MB-8.9MB-9.2MB over 19)
+ Imp Fg: 100% (9.3MB-9.7MB-10MB/8.5MB-8.9MB-9.2MB over 19)
+ * com.google.android.googlequicksearchbox:interactor / u0a22 / v300404573:
+ TOTAL: 100% (3.4MB-3.5MB-3.6MB/2.8MB-2.8MB-2.8MB over 19)
+ Imp Fg: 100% (3.4MB-3.5MB-3.6MB/2.8MB-2.8MB-2.8MB over 19)
+ * com.google.process.gapps / u0a8 / v7306438:
+ TOTAL: 100% (23MB-24MB-28MB/21MB-22MB-26MB over 19)
+ Imp Fg: 100% (23MB-24MB-28MB/21MB-22MB-26MB over 19)
+ * com.vito.lux / u0a84 / v237:
+ TOTAL: 100% (32MB-48MB-83MB/31MB-47MB-82MB over 134)
+ Imp Fg: 100% (32MB-48MB-83MB/31MB-47MB-82MB over 134)
+ Service: 0.05%
+ * system / 1000 / v22:
+ TOTAL: 100% (79MB-85MB-102MB/78MB-83MB-100MB over 18)
+ Persistent: 100% (79MB-85MB-102MB/78MB-83MB-100MB over 18)
+ * com.rhapsody / u0a83 / v125:
+ TOTAL: 100% (7.9MB-12MB-19MB/6.9MB-11MB-17MB over 15)
+ Service: 100% (7.9MB-12MB-19MB/6.9MB-11MB-17MB over 15)
+ Service Rs: 0.04%
+ * com.qualcomm.qcrilmsgtunnel / 1001 / v22:
+ TOTAL: 100% (2.5MB-2.6MB-2.7MB/1.7MB-1.8MB-1.9MB over 15)
+ Service: 100% (2.5MB-2.6MB-2.7MB/1.7MB-1.8MB-1.9MB over 15)
+ Service Rs: 0.13%
+ * com.amazon.kindle / u0a82 / v1143472216:
+ TOTAL: 100% (44MB-54MB-77MB/43MB-52MB-74MB over 17)
+ Service: 100% (44MB-54MB-77MB/43MB-52MB-74MB over 17)
+ Service Rs: 0.04%
+ * com.outplaylab.VideoDiet2 / u0a93 / v21:
+ TOTAL: 100% (2.8MB-3.1MB-4.0MB/2.0MB-2.2MB-3.0MB over 15)
+ Service: 100% (2.8MB-3.1MB-4.0MB/2.0MB-2.2MB-3.0MB over 15)
+ Service Rs: 0.03%
+ * android.process.media / u0a6 / v800:
+ TOTAL: 99% (4.6MB-5.9MB-8.1MB/3.4MB-4.7MB-6.7MB over 25)
+ Imp Fg: 0.02%
+ Service: 99% (4.6MB-5.9MB-8.1MB/3.4MB-4.7MB-6.7MB over 25)
+ Service Rs: 0.02%
+ (Cached): 0.94%
+ * kr.sira.sound / u0a108 / v41:
+ TOTAL: 77% (117MB-191MB-219MB/111MB-187MB-213MB over 68)
+ Top: 77% (117MB-191MB-219MB/111MB-187MB-213MB over 68)
+ (Last Act): 18% (58MB-127MB-161MB/53MB-123MB-158MB over 3)
+ (Cached): 0.06%
+ * com.google.android.gms / u0a8 / v7319438:
+ TOTAL: 37% (41MB-45MB-57MB/38MB-42MB-53MB over 23)
+ Top: 13% (41MB-46MB-57MB/39MB-42MB-53MB over 16)
+ Imp Fg: 13% (41MB-44MB-47MB/39MB-41MB-44MB over 5)
+ Imp Bg: 0.38%
+ Service: 11% (42MB-42MB-42MB/38MB-38MB-38MB over 2)
+ Receiver: 0.03%
+ (Last Act): 2.0% (38MB-38MB-38MB/36MB-36MB-36MB over 1)
+ (Cached): 61% (39MB-40MB-43MB/37MB-37MB-40MB over 28)
+ * com.google.android.googlequicksearchbox / u0a22 / v300404573:
+ TOTAL: 22% (129MB-153MB-162MB/125MB-149MB-156MB over 20)
+ Top: 22% (129MB-153MB-162MB/125MB-149MB-156MB over 20)
+ Imp Bg: 0.04%
+ Receiver: 0.01%
+ (Home): 78% (75MB-84MB-122MB/74MB-82MB-117MB over 12)
+ * com.google.android.apps.thehub / u0a102 / v12:
+ TOTAL: 21% (6.4MB-7.6MB-8.7MB/4.8MB-6.0MB-7.2MB over 2)
+ Service: 21% (6.4MB-7.6MB-8.7MB/4.8MB-6.0MB-7.2MB over 2)
+ * com.google.android.talk / u0a54 / v22314462:
+ TOTAL: 9.3%
+ Top: 0.04%
+ Service: 9.3%
+ Receiver: 0.01%
+ (Last Act): 3.9% (69MB-70MB-71MB/67MB-68MB-69MB over 6)
+ (Cached): 87% (42MB-53MB-77MB/40MB-51MB-74MB over 137)
+ * com.google.android.apps.plus / u0a67 / v413836278:
+ TOTAL: 8.2% (9.6MB-12MB-18MB/8.1MB-11MB-16MB over 3)
+ Imp Bg: 0.10%
+ Service: 8.0% (9.6MB-12MB-18MB/8.1MB-11MB-16MB over 3)
+ Receiver: 0.05%
+ (Cached): 59% (7.8MB-19MB-33MB/6.8MB-18MB-31MB over 22)
+ * com.android.providers.calendar / u0a2 / v22:
+ TOTAL: 3.5% (7.3MB-7.7MB-8.0MB/5.9MB-6.5MB-6.9MB over 10)
+ Imp Bg: 0.32%
+ Service: 3.2% (7.3MB-7.7MB-8.0MB/5.9MB-6.5MB-6.9MB over 10)
+ Receiver: 0.01%
+ (Cached): 69% (4.7MB-6.6MB-7.8MB/3.5MB-5.5MB-6.7MB over 23)
+ * com.amazon.mShop.android / u0a104 / v5030102:
+ TOTAL: 2.7% (25MB-40MB-47MB/24MB-37MB-43MB over 6)
+ Service: 2.6% (25MB-40MB-47MB/24MB-37MB-43MB over 6)
+ Receiver: 0.15%
+ (Cached): 97% (25MB-33MB-48MB/24MB-31MB-44MB over 46)
+ * com.google.android.gm / u0a70 / v51001620:
+ TOTAL: 2.2% (209MB-209MB-209MB/203MB-203MB-203MB over 1)
+ Top: 0.48% (209MB-209MB-209MB/203MB-203MB-203MB over 1)
+ Imp Bg: 0.70%
+ Service: 1.0%
+ Receiver: 0.01%
+ (Last Act): 0.02%
+ (Cached): 94% (25MB-67MB-116MB/23MB-63MB-109MB over 61)
+ * com.google.android.googlequicksearchbox:search / u0a22 / v300404573:
+ TOTAL: 2.1% (66MB-66MB-66MB/63MB-63MB-63MB over 1)
+ Top: 1.4% (66MB-66MB-66MB/63MB-63MB-63MB over 1)
+ Imp Fg: 0.01%
+ Service: 0.66%
+ Receiver: 0.02%
+ (Cached): 98% (52MB-59MB-79MB/50MB-56MB-77MB over 56)
+ * com.google.android.calendar / u0a31 / v2015030452:
+ TOTAL: 1.4%
+ Imp Bg: 0.33%
+ Service: 1.1%
+ Receiver: 0.02%
+ (Cached): 80% (7.4MB-12MB-17MB/5.8MB-9.8MB-14MB over 18)
+ * com.android.vending / u0a16 / v80341100:
+ TOTAL: 1.3% (88MB-154MB-220MB/85MB-151MB-217MB over 2)
+ Top: 1.3% (88MB-154MB-220MB/85MB-151MB-217MB over 2)
+ Service: 0.06%
+ Receiver: 0.02%
+ (Last Act): 4.4% (46MB-68MB-89MB/45MB-66MB-87MB over 2)
+ (Cached): 11% (15MB-74MB-133MB/13MB-72MB-131MB over 2)
+ * com.google.android.apps.photos / u0a65 / v5616:
+ TOTAL: 0.94%
+ Service: 0.90%
+ Receiver: 0.04%
+ (Cached): 80% (9.2MB-12MB-17MB/7.5MB-11MB-15MB over 20)
+ * com.amazon.avod.thirdpartyclient / u0a107 / v451210:
+ TOTAL: 0.52%
+ Service: 0.49%
+ Receiver: 0.03%
+ (Cached): 97% (14MB-24MB-34MB/13MB-22MB-31MB over 40)
+ * com.google.android.gms.wearable / u0a8 / v7319438:
+ TOTAL: 0.51%
+ Imp Fg: 0.47%
+ Service: 0.04%
+ (Cached): 65% (4.7MB-6.5MB-8.2MB/3.6MB-4.2MB-5.4MB over 10)
+ * com.amazon.mShop.android.shopping / u0a103 / v5040011:
+ TOTAL: 0.50%
+ Service: 0.37%
+ Receiver: 0.13%
+ (Cached): 77% (13MB-17MB-21MB/11MB-15MB-19MB over 15)
+ * com.google.android.gms:car / u0a8 / v7319438:
+ TOTAL: 0.49% (7.1MB-7.1MB-7.1MB/4.3MB-4.3MB-4.3MB over 1)
+ Top: 0.05%
+ Imp Fg: 0.39% (7.1MB-7.1MB-7.1MB/4.3MB-4.3MB-4.3MB over 1)
+ Service: 0.05%
+ (Cached): 0.60% (6.6MB-6.6MB-6.6MB/3.6MB-3.6MB-3.6MB over 1)
+ * com.amazon.mp3 / u0a92 / v4033010:
+ TOTAL: 0.46%
+ Service: 0.43%
+ Receiver: 0.03%
+ (Cached): 84% (12MB-16MB-23MB/9.7MB-14MB-21MB over 25)
+ * com.android.chrome:privileged_process1 / u0a34 / v2272096:
+ TOTAL: 0.43%
+ Service: 0.04%
+ Service Rs: 0.39%
+ (Cached): 100% (2.9MB-4.0MB-4.9MB/1.7MB-2.9MB-3.9MB over 18)
+ * com.google.android.dialer / u0a10 / v20100:
+ TOTAL: 0.39% (93MB-93MB-93MB/89MB-89MB-89MB over 1)
+ Top: 0.23% (93MB-93MB-93MB/89MB-89MB-89MB over 1)
+ Imp Fg: 0.16%
+ (Cached): 16% (5.0MB-31MB-57MB/4.1MB-29MB-54MB over 2)
+ * com.google.android.apps.maps / u0a58 / v906101124:
+ TOTAL: 0.38%
+ Service: 0.33%
+ Receiver: 0.05%
+ (Cached): 69% (8.7MB-15MB-18MB/7.2MB-14MB-17MB over 8)
+ * com.google.android.youtube / u0a80 / v101451214:
+ TOTAL: 0.26%
+ Service: 0.26%
+ (Cached): 36% (15MB-22MB-29MB/13MB-19MB-27MB over 5)
+ * com.google.android.apps.fitness / u0a45 / v2015109100:
+ TOTAL: 0.26%
+ Service: 0.23%
+ Receiver: 0.02%
+ (Cached): 82% (3.9MB-6.4MB-9.2MB/2.8MB-5.3MB-7.9MB over 19)
+ * com.google.android.apps.enterprise.dmagent / u0a37 / v630:
+ TOTAL: 0.06%
+ Service: 0.06%
+ Receiver: 0.01%
+ (Cached): 2.2% (6.5MB-7.4MB-8.2MB/4.8MB-5.8MB-6.8MB over 2)
+ * com.audible.application / u0a95 / v3068:
+ TOTAL: 0.06%
+ Receiver: 0.06%
+ (Cached): 34% (14MB-16MB-19MB/11MB-14MB-17MB over 7)
+ * com.android.defcontainer / u0a5 / v22:
+ TOTAL: 0.06%
+ Imp Fg: 0.06%
+ (Cached): 0.12%
+ * com.google.android.music:main / u0a60 / v1847:
+ TOTAL: 0.04%
+ Top: 0.01%
+ Service: 0.02%
+ Receiver: 0.01%
+ (Cached): 9.8% (10MB-12MB-14MB/8.3MB-9.6MB-11MB over 2)
+ * com.google.android.apps.magazines / u0a61 / v2015040100:
+ TOTAL: 0.03%
+ Top: 0.02%
+ Receiver: 0.01%
+ (Cached): 8.7% (12MB-14MB-16MB/9.7MB-11MB-13MB over 2)
+ * com.google.android.videos / u0a77 / v37191:
+ TOTAL: 0.03%
+ Imp Fg: 0.01%
+ Service: 0.02%
+ (Cached): 1.3% (11MB-12MB-13MB/9.1MB-10MB-12MB over 2)
+ * com.google.android.apps.books / u0a28 / v30336:
+ TOTAL: 0.03%
+ Imp Fg: 0.01%
+ Service: 0.02%
+ (Cached): 1.3% (7.9MB-9.6MB-11MB/6.3MB-8.0MB-9.7MB over 2)
+ * com.google.android.keep / u0a71 / v3115:
+ TOTAL: 0.02%
+ Service: 0.01%
+ Receiver: 0.01%
+ (Cached): 11% (6.3MB-8.7MB-9.6MB/5.1MB-7.4MB-8.3MB over 4)
+ * com.android.chrome / u0a34 / v2272096:
+ TOTAL: 0.02%
+ Service: 0.01%
+ Receiver: 0.02%
+ (Cached): 90% (5.1MB-70MB-96MB/3.4MB-66MB-92MB over 15)
+ * com.google.android.apps.gcs / u0a94 / v14:
+ TOTAL: 0.02%
+ Service: 0.02%
+ (Cached): 17% (5.8MB-5.9MB-6.0MB/4.6MB-4.7MB-4.8MB over 2)
+ * com.android.chrome:privileged_process0 / u0a34 / v2272096:
+ TOTAL: 0.02%
+ Service: 0.01%
+ Receiver: 0.01%
+ (Cached): 73% (162MB-163MB-164MB/157MB-157MB-157MB over 13)
+ * com.android.chrome:sandboxed_process12 / u0a34 / v2272096:
+ TOTAL: 0.02%
+ Service: 0.01%
+ Receiver: 0.01%
+ (Cached): 73% (48MB-49MB-51MB/46MB-47MB-50MB over 13)
+ * com.google.android.apps.docs / u0a40 / v51410735:
+ TOTAL: 0.01%
+ Receiver: 0.01%
+ (Cached): 0.45% (10MB-10MB-10MB/9.3MB-9.3MB-9.3MB over 1)
+ * com.google.android.deskclock / u0a38 / v303:
+ TOTAL: 0.01%
+ Receiver: 0.01%
+ (Cached): 82% (2.5MB-3.3MB-4.3MB/1.7MB-2.3MB-3.2MB over 13)
+ * com.google.android.gm.exchange / u0a69 / v500065:
+ TOTAL: 0.01%
+ Imp Bg: 0.01%
+ (Cached): 27% (3.3MB-3.7MB-3.9MB/2.2MB-2.7MB-2.9MB over 6)
+ * com.android.cellbroadcastreceiver / u0a3 / v22:
+ TOTAL: 0.01%
+ Service: 0.01%
+ (Cached): 1.1% (3.5MB-3.5MB-3.5MB/2.5MB-2.5MB-2.5MB over 1)
+ * com.coulombtech / u0a106 / v26:
+ TOTAL: 0.01%
+ Receiver: 0.01%
+ (Cached): 21% (4.9MB-5.0MB-5.2MB/3.8MB-3.9MB-4.1MB over 2)
+ * com.softcoil.mms / u0a86 / v32:
+ TOTAL: 0.01%
+ (Cached): 0.25%
+ * com.udemy.android / u0a91 / v38:
+ TOTAL: 0.01%
+ Receiver: 0.01%
+ (Cached): 0.75% (9.8MB-9.8MB-9.8MB/8.5MB-8.5MB-8.5MB over 1)
+ * com.qualcomm.timeservice / u0a76 / v22:
+ (Cached): 16% (2.3MB-2.4MB-2.4MB/1.6MB-1.6MB-1.6MB over 4)
+ * com.lge.SprintHiddenMenu / 1000 / v22:
+ (Cached): 0.16%
+ * com.android.chrome:sandboxed_process13 / u0a34 / v2272096:
+ (Cached): 0.01%
+ * com.google.android.partnersetup / u0a13 / v22:
+ (Cached): 0.14%
+ * com.android.musicfx / u0a15 / v10400:
+ (Cached): 0.41% (2.5MB-2.5MB-2.5MB/1.6MB-1.6MB-1.6MB over 1)
+ * com.android.chrome:sandboxed_process9 / u0a34 / v2272096:
+ (Cached): 30% (34MB-34MB-34MB/32MB-32MB-32MB over 9)
+ * com.android.chrome:sandboxed_process11 / u0a34 / v2272096:
+ (Cached): 7.2% (56MB-56MB-56MB/54MB-54MB-54MB over 3)
+
+Run time Stats:
+ SOff/Norm: +32m52s226ms
+ SOn /Norm: +2h10m8s364ms
+ Mod : +17s930ms
+ TOTAL: +2h43m18s520ms
+
+Memory usage:
+ Kernel : 265MB (38 samples)
+ Native : 73MB (38 samples)
+ Persist: 262MB (90 samples)
+ Top : 190MB (325 samples)
+ ImpFg : 204MB (569 samples)
+ ImpBg : 754KB (345 samples)
+ Service: 93MB (1912 samples)
+ Receivr: 227KB (1169 samples)
+ Home : 66MB (12 samples)
+ LastAct: 30MB (255 samples)
+ CchAct : 220MB (450 samples)
+ CchCAct: 193MB (71 samples)
+ CchEmty: 182MB (652 samples)
+ Cached : 58MB (38 samples)
+ Free : 60MB (38 samples)
+ TOTAL : 1.9GB
+ ServRst: 50KB (278 samples)
+
+ Start time: 2015-04-08 13:44:18
+ Total elapsed time: +2h43m18s521ms (partial) libart.so
+</pre>
+
diff --git a/src/devices/tech/encryption/index.jd b/src/devices/tech/security/encryption/index.jd
similarity index 96%
rename from src/devices/tech/encryption/index.jd
rename to src/devices/tech/security/encryption/index.jd
index d7e9328..957e9ed 100644
--- a/src/devices/tech/encryption/index.jd
+++ b/src/devices/tech/security/encryption/index.jd
@@ -40,8 +40,10 @@
currently support fast encryption.
<li>Added the <code>forceencrypt</code> flag to encrypt on first boot.
<li>Added support for patterns and encryption without a password.
- <li>Added hardware-backed storage of the encryption key. See <a
- href="#storing_the_encrypted_key">Storing the encrypted key</a> for more details.
+ <li>Added hardware-backed storage of the encryption key using Trusted
+ Execution Environment’s (TEE) signing capability (such as in a TrustZone).
+ See <a href="#storing_the_encrypted_key">Storing the encrypted key</a> for more
+ details.
</ul>
<p class="caution"><strong>Caution:</strong> Devices upgraded to Android 5.0 and then
@@ -50,8 +52,10 @@
<h2 id=how_android_encryption_works>How Android encryption works</h2>
-<p>Android disk encryption is based on <code>dm-crypt</code>, which is a kernel feature that works at the block device layer. Because of
-this, encryption works with Embedded MultiMediaCard<strong> (</strong>eMMC) and similar flash devices that present themselves to the kernel as block
+<p>Android disk encryption is based on <code>dm-crypt</code>, which is a kernel
+feature that works at the block device layer. Because of
+this, encryption works with Embedded MultiMediaCard<strong> (</strong>eMMC) and
+similar flash devices that present themselves to the kernel as block
devices. Encryption is not possible with YAFFS, which talks directly to a raw
NAND flash chip. </p>
@@ -71,10 +75,14 @@
<li>pattern
</ul>
-<p>Upon first boot, the device generates a 128-bit key. This key is then encrypted
-with a default password, and the encrypted key is stored in the crypto
-metadata. The 128-bit key generated is valid until the next factory reset. Upon
-factory reset, a new 128-bit key is generated.</p>
+<p>Upon first boot, the device creates a randomly generated 128-bit master key
+and then hashes it with a default password and stored salt. The default password is: "default_password"
+However, the resultant hash is also signed through a TEE (such as TrustZone),
+which uses a hash of the signature to encrypt the master key.</p>
+
+<p>You can find the default password defined in the Android Open Source Project <a
+href="https://android.googlesource.com/platform/system/vold/+/master/cryptfs.c">cryptfs.c</a>
+file.</p>
<p>When the user sets the PIN/pass or password on the device, only the 128-bit key
is re-encrypted and stored. (ie. user PIN/pass/pattern changes do NOT cause
diff --git a/src/devices/tech/security/enhancements/enhancements41.jd b/src/devices/tech/security/enhancements/enhancements41.jd
new file mode 100644
index 0000000..60ae754
--- /dev/null
+++ b/src/devices/tech/security/enhancements/enhancements41.jd
@@ -0,0 +1,44 @@
+page.title=Security Enhancements in Android 1.5 through 4.1
+@jd:body
+
+<p>
+Android provides a multi-layered security model described in the <a href="{@docRoot}devices/tech/security/index.html">Android
+Security Overview</a>. Each update to Android includes dozens of
+security enhancements to protect users. The following are some of the security
+enhancements introduced in Android versions 1.5 through 4.1:</p>
+
+<dl>
+<dt><strong>Android 1.5</strong></dt>
+<dd><ul>
+<li>ProPolice to prevent stack buffer overruns (-fstack-protector)</li>
+<li>safe_iop to reduce integer overflows</li>
+<li>Extensions to OpenBSD dlmalloc to prevent double free() vulnerabilities and
+to prevent chunk consolidation attacks. Chunk consolidation attacks are a
+common way to exploit heap corruption.</li>
+<li>OpenBSD calloc to prevent integer overflows during memory allocation</li>
+</ul>
+</dd>
+
+<dt><strong>Android 2.3</strong></dt>
+<dd><ul>
+<li>Format string vulnerability protections (-Wformat-security -Werror=format-security)</li>
+<li>Hardware-based No eXecute (NX) to prevent code execution on the stack and heap</li>
+<li>Linux mmap_min_addr to mitigate null pointer dereference privilege
+escalation (further enhanced in Android 4.1)</li>
+</ul>
+</dd>
+
+<dt><strong>Android 4.0</strong></dt>
+<dd>Address Space Layout Randomization (ASLR) to randomize key locations in memory
+</dd>
+
+<dt><strong>Android 4.1</strong></dt>
+<dd><ul>
+<li>PIE (Position Independent Executable) support</li>
+<li>Read-only relocations / immediate binding (-Wl,-z,relro -Wl,-z,now)</li>
+<li>dmesg_restrict enabled (avoid leaking kernel addresses)</li>
+<li>kptr_restrict enabled (avoid leaking kernel addresses)</li>
+</ul>
+</dd>
+
+</dl>
diff --git a/src/devices/tech/security/enhancements42.jd b/src/devices/tech/security/enhancements/enhancements42.jd
similarity index 100%
rename from src/devices/tech/security/enhancements42.jd
rename to src/devices/tech/security/enhancements/enhancements42.jd
diff --git a/src/devices/tech/security/enhancements43.jd b/src/devices/tech/security/enhancements/enhancements43.jd
similarity index 100%
rename from src/devices/tech/security/enhancements43.jd
rename to src/devices/tech/security/enhancements/enhancements43.jd
diff --git a/src/devices/tech/security/enhancements44.jd b/src/devices/tech/security/enhancements/enhancements44.jd
similarity index 100%
rename from src/devices/tech/security/enhancements44.jd
rename to src/devices/tech/security/enhancements/enhancements44.jd
diff --git a/src/devices/tech/security/enhancements50.jd b/src/devices/tech/security/enhancements/enhancements50.jd
similarity index 100%
rename from src/devices/tech/security/enhancements50.jd
rename to src/devices/tech/security/enhancements/enhancements50.jd
diff --git a/src/devices/tech/security/enhancements.jd b/src/devices/tech/security/enhancements/index.jd
similarity index 100%
rename from src/devices/tech/security/enhancements.jd
rename to src/devices/tech/security/enhancements/index.jd
diff --git a/src/devices/tech/security/images/boot_orange.png b/src/devices/tech/security/images/boot_orange.png
new file mode 100644
index 0000000..1a239d3
--- /dev/null
+++ b/src/devices/tech/security/images/boot_orange.png
Binary files differ
diff --git a/src/devices/tech/security/images/boot_red.png b/src/devices/tech/security/images/boot_red.png
new file mode 100644
index 0000000..44deda3
--- /dev/null
+++ b/src/devices/tech/security/images/boot_red.png
Binary files differ
diff --git a/src/devices/tech/security/images/boot_yellow1.png b/src/devices/tech/security/images/boot_yellow1.png
new file mode 100644
index 0000000..b68572d
--- /dev/null
+++ b/src/devices/tech/security/images/boot_yellow1.png
Binary files differ
diff --git a/src/devices/tech/security/images/boot_yellow2.png b/src/devices/tech/security/images/boot_yellow2.png
new file mode 100644
index 0000000..57732f5
--- /dev/null
+++ b/src/devices/tech/security/images/boot_yellow2.png
Binary files differ
diff --git a/src/devices/tech/security/images/device_states.png b/src/devices/tech/security/images/device_states.png
new file mode 100644
index 0000000..319c345
--- /dev/null
+++ b/src/devices/tech/security/images/device_states.png
Binary files differ
diff --git a/src/devices/tech/security/images/dm-verity-hash-table.png b/src/devices/tech/security/images/dm-verity-hash-table.png
index 3761dc6..d094531 100644
--- a/src/devices/tech/security/images/dm-verity-hash-table.png
+++ b/src/devices/tech/security/images/dm-verity-hash-table.png
Binary files differ
diff --git a/src/devices/tech/security/images/dm-verity_mgmt.png b/src/devices/tech/security/images/dm-verity_mgmt.png
new file mode 100644
index 0000000..f67b93f
--- /dev/null
+++ b/src/devices/tech/security/images/dm-verity_mgmt.png
Binary files differ
diff --git a/src/devices/tech/security/images/verified_boot.png b/src/devices/tech/security/images/verified_boot.png
new file mode 100644
index 0000000..592aee8
--- /dev/null
+++ b/src/devices/tech/security/images/verified_boot.png
Binary files differ
diff --git a/src/devices/tech/security/best-practices.jd b/src/devices/tech/security/implement.jd
similarity index 98%
rename from src/devices/tech/security/best-practices.jd
rename to src/devices/tech/security/implement.jd
index 94b4984..6b9c80e 100644
--- a/src/devices/tech/security/best-practices.jd
+++ b/src/devices/tech/security/implement.jd
@@ -1,4 +1,4 @@
-page.title=Security best practices
+page.title=Implementing Security
@jd:body
<!--
@@ -39,7 +39,7 @@
software on devices.</p>
<p>Where possible, the Android Security Team will incorporate tests into the
-<a href="http://source.android.com/compatibility/cts-intro.html">Android Compatibility Test
+<a href="{@docRoot}compatibility/cts-intro.html">Android Compatibility Test
Suite</a> (CTS) and
<a href="http://tools.android.com/tips/lint">Android Lint</a> to facilitate adoption of
these best practices. We encourage partners to contribute tests that can help
diff --git a/src/devices/tech/security/index.jd b/src/devices/tech/security/index.jd
index b2982d7..1c67377 100644
--- a/src/devices/tech/security/index.jd
+++ b/src/devices/tech/security/index.jd
@@ -1,8 +1,7 @@
-page.title=Android Security Overview
+page.title=Security
@jd:body
-
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -19,821 +18,123 @@
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
- <ol id="auto-toc">
- </ol>
+ <ol id="auto-toc"></ol>
</div>
</div>
<h2 id="introduction">Introduction</h2>
<p>Android is a modern mobile platform that was designed to be truly open. Android
-applications make use of advanced hardware and software, as well as local and
-served data, exposed through the platform to bring innovation and value to
-consumers. To protect that value, the platform must offer an application
-environment that ensures the security of users, data, applications, the device,
-and the network.</p>
-
-<p>Securing an open platform requires a robust security architecture and rigorous
-security programs. Android was designed with multi-layered security that
-provides the flexibility required for an open platform, while providing
-protection for all users of the platform.</p>
-
+ applications make use of advanced hardware and software, as well as local and
+ served data, exposed through the platform to bring innovation and value to
+ consumers. To protect that value, the platform must offer an application
+ environment that ensures the security of users, data, applications, the device,
+ and the network.</p>
+<p>Securing an open platform requires a robust security architecture and
+ rigorous security programs. Android was designed with multi-layered
+ security that provides the flexibility required for an open platform, while
+ providing protection for all users of the platform. For information about
+ reporting security issues and the update process,
+ see <a href="{@docRoot}devices/tech/security/overview/updates-resources.html">Security Updates and Resources</a>.</p>
<p>Android was designed with developers in mind. Security controls were designed
-to reduce the burden on developers. Security-savvy developers can easily work
-with and rely on flexible security controls. Developers less familiar with
-security will be protected by safe defaults.</p>
-
+ to reduce the burden on developers. Security-savvy developers can easily work
+ with and rely on flexible security controls. Developers less familiar with
+ security will be protected by safe defaults.</p>
<p>Android was designed with device users in mind. Users are provided visibility
-into how applications work, and control over those applications. This design
-includes the expectation that attackers would attempt to perform common
-attacks, such as social engineering attacks to convince device users to install
-malware, and attacks on third-party applications on Android. Android was
-designed to both reduce the probability of these attacks and greatly limit the
-impact of the attack in the event it was successful.</p>
+ into how applications work, and control over those applications. This design
+ includes the expectation that attackers would attempt to perform common
+ attacks, such as social engineering attacks to convince device users to install
+ malware, and attacks on third-party applications on Android. Android was
+ designed to both reduce the probability of these attacks and greatly limit the
+ impact of the attack in the event it was successful.</p>
+<p>This documentation outlines the goals of the Android security program, describes the
+ fundamentals of the Android security architecture, and answers the most
+ pertinent questions for system architects and security analysts. This document
+ focuses on the security features of Android's core platform and does not
+ discuss security issues that are unique to specific applications, such as those
+ related to the browser or SMS application. Recommended best practices for
+ building Android devices, deploying Android devices, or developing applications
+ for Android are not the goal of this document and are provided elsewhere.</p>
-<p>This document outlines the goals of the Android security program, describes the
-fundamentals of the Android security architecture, and answers the most
-pertinent questions for system architects and security analysts. This document
-focuses on the security features of Android's core platform and does not
-discuss security issues that are unique to specific applications, such as those
-related to the browser or SMS application. Recommended best practices for
-building Android devices, deploying Android devices, or developing applications
-for Android are not the goal of this document and are provided elsewhere.</p>
-
-<h1 id="background">Background</h1>
+<h2 id="background">Background</h2>
<p>Android provides an open source platform and application environment for mobile
-devices.</p>
-<p>The main Android platform building blocks are:</p>
-<ul>
-<li>
-<p><strong>Device Hardware</strong>: Android runs on a wide range of hardware configurations
-including smart phones, tablets, and set-top-boxes. Android is
-processor-agnostic, but it does take advantage of some hardware-specific
-security capabilities such as ARM v6 eXecute-Never.</p>
-</li>
-<li>
-<p><strong>Android Operating System</strong>: The core operating system is built on top of
-the Linux kernel. All device resources, like camera functions, GPS data,
-Bluetooth functions, telephony functions, network connections, etc. are
-accessed through the operating system.</p>
-</li>
-<li>
-<p><strong>Android Application Runtime</strong>: Android applications are most often written
-in the Java programming language and run in the Android runtime (ART).
-However, many applications, including core Android services and applications
-are native applications or include native libraries. Both ART and native
-applications run within the same security environment, contained within the
-Application Sandbox. Applications get a dedicated part of the filesystem in
-which they can write private data, including databases and raw files.</p>
-</li>
-</ul>
-<p>Android applications extend the core Android operating system. There are two
-primary sources for applications:</p>
-<ul>
-<li>
-<p><strong>Pre-Installed Applications</strong>: Android includes a set of pre-installed
-applications including phone, email, calendar, web browser, and contacts. These
-function both as user applications and to provide key device capabilities that
-can be accessed by other applications. Pre-installed applications may be part
-of the open source Android platform, or they may be developed by an OEM for a
-specific device.</p>
-</li>
-<li>
-<p><strong>User-Installed Applications</strong>: Android provides an open development
-environment supporting any third-party application. Google Play offers
-users hundreds of thousands of applications.</p>
-</li>
-</ul>
-<p>Google provides a set of cloud-based services that are available to any
-compatible Android device. The primary services are:</p>
-<ul>
-<li>
-<p><strong>Google Play</strong>: Google Play is a collection of services that
-allow users to discover, install, and purchase applications from their Android
-device or the web. Google Play makes it easy for developers to reach Android
-users and potential customers. Google Play also provides community review,
-application <a href="https://developer.android.com/guide/publishing/licensing.html">license
-verification</a>, application security scanning, and other security services.</p>
-</li>
-<li>
-<p><strong>Android Updates</strong>: The Android update service delivers new capabilities and
-security updates to Android devices, including updates through the web or over
-the air (OTA).</p>
-</li>
-<li>
-<p><strong>Application Services</strong>: Frameworks that allow Android applications to use
-cloud capabilities such as (<a href="https://developer.android.com/guide/topics/data/backup.html">backing
-up</a>) application
-data and settings and cloud-to-device messaging
-(<a href="https://developers.google.com/android/c2dm/">C2DM</a>)
-for push messaging.</p>
-</li>
-</ul>
-<p>These services are not part of the Android Open Source Project and are out
-of scope for this document. But they are relevant to the security of most
-Android devices, so a related security document titled “Google Services for
-Android: Security Overview” is available.</p>
-<h2 id="android-security-program-overview">Android Security Program Overview</h2>
-<p>Early on in development, the core Android development team recognized that a
-robust security model was required to enable a vigorous ecosystem of
-applications and devices built on and around the Android platform and supported
-by cloud services. As a result, through its entire development lifecycle,
-Android has been subjected to a professional security program. The Android team
-has had the opportunity to observe how other mobile, desktop, and server platforms
-prevented and reacted to security issues and built a security
-program to address weak points observed in other offerings.</p>
-<p>The key components of the Android Security Program include:</p>
-<ul>
-<li><strong>Design Review</strong>: The Android security process begins early in the
-development lifecycle with the creation of a rich and configurable security
-model and design. Each major feature of the platform is reviewed by engineering
-and security resources, with appropriate security controls integrated into the
-architecture of the system.</li>
-<li><strong>Penetration Testing and Code Review</strong>: During the development of the
-platform, Android-created and open-source components are subject to vigorous
-security reviews. These reviews are performed by the Android Security Team,
-Google’s Information Security Engineering team, and independent security
-consultants. The goal of these reviews is to identify weaknesses and possible
-vulnerabilities well before the platform is open-sourced, and to simulate the
-types of analysis that will be performed by external security experts upon
-release.</li>
-<li><strong>Open Source and Community Review</strong>: The Android Open Source Project enables
-broad security review by any interested party. Android also uses open source
-technologies that have undergone significant external security review,
-such as the Linux kernel. Google Play provides a forum for users and companies
-to provide information about specific applications directly to users.</li>
-<li><strong>Incident Response</strong>: Even with all of these precautions, security issues
-may occur after shipping, which is why the Android project has created a
-comprehensive security response process. A full-time Android security team
-constantly monitors Android-specific and the general security community for
-discussion of potential vulnerabilities. Upon the discovery of legitimate
-issues, the Android team has a response process that enables the rapid
-mitigation of vulnerabilities to ensure that potential risk to all Android
-users is minimized. These cloud-supported responses can include updating the
-Android platform (over-the-air updates), removing applications from Google
-Play, and removing applications from devices in the field.</li>
-</ul>
-<h2 id="android-platform-security-architecture">Android Platform Security Architecture</h2>
-<p>Android seeks to be the most secure and usable operating system for mobile
-platforms by re-purposing traditional operating system security controls to:</p>
-<ul>
-<li>Protect user data</li>
-<li>Protect system resources (including the network)</li>
-<li>Provide application isolation</li>
-</ul>
-<p>To achieve these objectives, Android provides these key security features:</p>
-<ul>
-<li>Robust security at the OS level through the Linux kernel</li>
-<li>Mandatory application sandbox for all applications</li>
-<li>Secure interprocess communication</li>
-<li>Application signing</li>
-<li>Application-defined and user-granted permissions</li>
-</ul>
-<p>The sections below describe these and other security features of the Android
-platform. <em>Figure 1</em> summarizes the security components and considerations of
-the various levels of the Android software stack. Each component assumes that
-the components below are properly secured. With the exception of a small amount
-of Android OS code running as root, all code above the Linux Kernel is
-restricted by the Application Sandbox.</p>
+ devices.</p>
+<p>The sections and pages below describe the security features of the Android
+ platform. <em>Figure 1</em> summarizes the security components and considerations of
+ the various levels of the Android software stack. Each component assumes that
+ the components below are properly secured. With the exception of a small amount
+ of Android OS code running as root, all code above the Linux Kernel is
+ restricted by the Application Sandbox.</p>
<p><img alt="Figure 1: Android software stack" src="images/image00.png" /></p>
<p><em>Figure 1: Android software stack.</em></p>
-<h1 id="system-and-kernel-level-security">System and Kernel Level Security</h1>
-<p>At the operating system level, the Android platform provides the security of
-the Linux kernel, as well as a secure inter-process communication (IPC)
-facility to enable secure communication between applications running in
-different processes. These security features at the OS level ensure that even
-native code is constrained by the Application Sandbox. Whether that code is
-the result of included application behavior or a exploitation of an application
-vulnerability, the system would prevent the rogue application from harming
-other applications, the Android system, or the device itself.</p>
-<h2 id="linux-security">Linux Security</h2>
-<p>The foundation of the Android platform is the Linux kernel. The Linux kernel
-itself has been in widespread use for years, and is used in millions of
-security-sensitive environments. Through its history of constantly being
-researched, attacked, and fixed by thousands of developers, Linux has become a
-stable and secure kernel trusted by many corporations and security
-professionals.</p>
-<p>As the base for a mobile computing environment, the Linux kernel provides
-Android with several key security features, including:</p>
+<p>The main Android platform building blocks are:</p>
<ul>
-<li>A user-based permissions model</li>
-<li>Process isolation</li>
-<li>Extensible mechanism for secure IPC</li>
-<li>The ability to remove unnecessary and potentially insecure parts of the kernel</li>
+ <li>
+ <p><strong>Device Hardware</strong>: Android runs on a wide range of hardware configurations
+ including smart phones, tablets, and set-top-boxes. Android is
+ processor-agnostic, but it does take advantage of some hardware-specific
+ security capabilities such as ARM v6 eXecute-Never.</p>
+ </li>
+ <li>
+ <p><strong>Android Operating System</strong>: The core operating system is built on top of
+ the Linux kernel. All device resources, like camera functions, GPS data,
+ Bluetooth functions, telephony functions, network connections, etc. are
+ accessed through the operating system.</p>
+ </li>
+ <li>
+ <p><strong>Android Application Runtime</strong>: Android applications are most often written
+ in the Java programming language and run in the Dalvik virtual machine.
+ However, many applications, including core Android services and applications
+ are native applications or include native libraries. Both Dalvik and native
+ applications run within the same security environment, contained within the
+ Application Sandbox. Applications get a dedicated part of the filesystem in
+ which they can write private data, including databases and raw files.</p>
+ </li>
</ul>
-<p>As a multiuser operating system, a fundamental security objective of the Linux
-kernel is to isolate user resources from one another. The Linux security
-philosophy is to protect user resources from one another. Thus, Linux:</p>
+<p>Android applications extend the core Android operating system. There are two
+ primary sources for applications:</p>
<ul>
-<li>Prevents user A from reading user B's files</li>
-<li>Ensures that user A does not exhaust user B's memory</li>
-<li>Ensures that user A does not exhaust user B's CPU resources</li>
-<li>Ensures that user A does not exhaust user B's devices (e.g. telephony, GPS,
-bluetooth)</li>
+ <li>
+ <p><strong>Pre-Installed Applications</strong>: Android includes a set of pre-installed
+ applications including phone, email, calendar, web browser, and contacts. These
+ function both as user applications and to provide key device capabilities that
+ can be accessed by other applications. Pre-installed applications may be part
+ of the open source Android platform, or they may be developed by an OEM for a
+ specific device.</p>
+ </li>
+ <li>
+ <p><strong>User-Installed Applications</strong>: Android provides an open development
+ environment supporting any third-party application. Google Play offers
+ users hundreds of thousands of applications.</p>
+ </li>
</ul>
-
-<h2 id="the-application-sandbox">The Application Sandbox</h2>
-<p>The Android platform takes advantage of the Linux user-based protection as a
-means of identifying and isolating application resources. The Android system
-assigns a unique user ID (UID) to each Android application and runs it as that user
-in a separate process. This approach is different from other operating systems
-(including the traditional Linux configuration), where multiple applications
-run with the same user permissions.</p>
-<p>This sets up a kernel-level Application Sandbox. The kernel enforces security
-between applications and the system at the process level through standard Linux
-facilities, such as user and group IDs that are assigned to applications. By
-default, applications cannot interact with each other and applications have
-limited access to the operating system. If application A tries to do something
-malicious like read application B's data or dial the phone without permission
-(which is a separate application), then the operating system protects against
-this because application A does not have the appropriate user privileges. The
-sandbox is simple, auditable, and based on decades-old UNIX-style user
-separation of processes and file permissions.</p>
-<p>Since the Application Sandbox is in the kernel, this security model extends to
-native code and to operating system applications. All of the software above the
-kernel in <em>Figure 1</em>, including operating system libraries, application
-framework, application runtime, and all applications run within the Application
-Sandbox. On some platforms, developers are constrained to a specific
-development framework, set of APIs, or language in order to enforce security.
-On Android, there are no restrictions on how an application can be written that
-are required to enforce security; in this respect, native code is just as
-secure as interpreted code.</p>
-<p>In some operating systems, memory corruption errors generally lead to
-completely compromising the security of the device. This is not the case in
-Android due to all applications and their resources being sandboxed at the OS
-level. A memory corruption error will only allow arbitrary code execution in
-the context of that particular application, with the permissions established by
-the operating system.</p>
-<p>Like all security features, the Application Sandbox is not unbreakable.
-However, to break out of the Application Sandbox in a properly configured
-device, one must compromise the security of the the Linux kernel.</p>
-<h2 id="system-partition-and-safe-mode">System Partition and Safe Mode</h2>
-<p>The system partition contains Android's kernel as well as the operating system
-libraries, application runtime, application framework, and applications. This
-partition is set to read-only. When a user boots the device into Safe Mode,
-only core Android applications are available. This ensures that the user can
-boot their phone into an environment that is free of third-party software.</p>
-
-<h2 id="filesystem-permissions">Filesystem Permissions</h2>
-<p>In a UNIX-style environment, filesystem permissions ensure that one user cannot
-alter or read another user's files. In the case of Android, each application
-runs as its own user. Unless the developer explicitly exposes files to other
-applications, files created by one application cannot be read or altered by
-another application.</p>
-
-<h2 id="se-linux">Security-Enhanced Linux</h2>
-
-<p>Android uses Security-Enhanced
-Linux (SELinux) to apply access control policies and establish an environment of
-mandatory access control (mac). See <a
-href="{@docRoot}devices/tech/security/se-linux.html">Validating
-Security-Enhanced Linux in
-Android</a> for details.</p>
-
-<h2 id="crypto">Cryptography</h2>
-
-<p>
-Android provides a set of cryptographic APIs for use by applications. These
-include implementations of standard and commonly used cryptographic primitives
-such as AES, RSA, DSA, and SHA. Additionally, APIs are provided for higher level
-protocols such as SSL and HTTPS.
-</p>
-
-<p>
-Android 4.0 introduced the
-<a href="http://developer.android.com/reference/android/security/KeyChain.html">KeyChain</a>
-class to allow applications to use the system credential storage for private
-keys and certificate chains.
-</p>
-
-<h2 id="memory-mgmt">Memory Management Security Enhancements</h2>
-
-Android includes many features that make common security issues harder to
-exploit. The Android SDK, compilers, and OS use tools to make common memory
-corruption issues significantly harder to exploit, including:
-
-<dl>
-<dt><strong>Android 1.5</strong></dt>
-<dd><ul>
-<li>ProPolice to prevent stack buffer overruns (-fstack-protector)</li>
-<li>safe_iop to reduce integer overflows</li>
-<li>Extensions to OpenBSD dlmalloc to prevent double free() vulnerabilities and
-to prevent chunk consolidation attacks. Chunk consolidation attacks are a
-common way to exploit heap corruption.</li>
-<li>OpenBSD calloc to prevent integer overflows during memory allocation</li>
-</ul>
-</dd>
-
-<dt><strong>Android 2.3</strong></dt>
-<dd><ul>
-<li>Format string vulnerability protections (-Wformat-security -Werror=format-security)</li>
-<li>Hardware-based No eXecute (NX) to prevent code execution on the stack and heap</li>
-<li>Linux mmap_min_addr to mitigate null pointer dereference privilege
-escalation (further enhanced in Android 4.1)</li>
-</ul>
-</dd>
-
-<dt><strong>Android 4.0</strong></dt>
-<dd>Address Space Layout Randomization (ASLR) to randomize key locations in memory
-</dd>
-
-<dt><strong>Android 4.1</strong></dt>
-<dd><ul>
-<li>PIE (Position Independent Executable) support</li>
-<li>Read-only relocations / immediate binding (-Wl,-z,relro -Wl,-z,now)</li>
-<li>dmesg_restrict enabled (avoid leaking kernel addresses)</li>
-<li>kptr_restrict enabled (avoid leaking kernel addresses)</li>
-</ul>
-</dd>
-
-<dt><strong>Android 4.2</strong></dt>
-<dd><code>FORTIFY_SOURCE</code> for system code</dd>
-
-</dl>
-
-<h2 id="rooting">Rooting of Devices</h2>
-<p>
-By default, on Android only the kernel and a small subset of the core
-applications run with root permissions. Android does not prevent a user or
-application with root permissions from modifying the operating system, kernel,
-and any other application. In general, root has full access to all
-applications and all application data. Users that change the permissions on an
-Android device to grant root access to applications increase the security
-exposure to malicious applications and potential application flaws.
-</p>
-<p>
-The ability to modify an Android device they own is important to developers
-working with the Android platform. On many Android devices users have the
-ability to unlock the bootloader in order to allow installation of an alternate
-operating system. These alternate operating systems may allow an owner to gain
-root access for purposes of debugging applications and system components or to
-access features not presented to applications by Android APIs.
-</p>
-<p>
-On some devices, a person with physical control of a device and a USB cable is
-able to install a new operating system that provides root privileges to the
-user. To protect any existing user data from compromise the bootloader unlock
-mechanism requires that the bootloader erase any existing user data as part of
-the unlock step. Root access gained via exploiting a kernel bug or security
-hole can bypass this protection.
-</p>
-<p>
-Encrypting data with a key stored on-device does not protect the application
-data from root users. Applications can add a layer of data protection using
-encryption with a key stored off-device, such as on a server or a user
-password. This approach can provide temporary protection while the key is not
-present, but at some point the key must be provided to the application and it
-then becomes accessible to root users.
-</p>
-<p>
-A more robust approach to protecting data from root users is through the use of
-hardware solutions. OEMs may choose to implement hardware solutions that limit
-access to specific types of content such as DRM for video playback, or the
-NFC-related trusted storage for Google wallet.
-</p>
-<p>
-In the case of a lost or stolen device, full filesystem encryption on Android
-devices uses the device password to protect the encryption key, so modifying
-the bootloader or operating system is not sufficient to access user data
-without the user’s device password.
-</p>
-<h2 id="user-sec">User Security Features</h2>
-
-<h3 id="filesystem-encryption">Filesystem Encryption</h3>
-
-<p>Android 3.0 and later provides full filesystem encryption, so all user data can
-be encrypted in the kernel using the dmcrypt implementation of AES128 with CBC
-and ESSIV:SHA256. The encryption key is protected by AES128 using a key
-derived from the user password, preventing unauthorized access to stored data
-without the user device password. To provide resistance against systematic
-password guessing attacks (e.g. “rainbow tables” or brute force), the
-password is combined with a random salt and hashed repeatedly with SHA1 using
-the standard PBKDF2 algorithm prior to being used to decrypt the filesystem
-key. To provide resistance against dictionary password guessing attacks,
-Android provides password complexity rules that can be set by the device
-administrator and enforced by the operating system. Filesystem encryption
-requires the use of a user password, pattern-based screen lock is not supported.</p>
-<p>More details on implementation of filesystem encryption are available at
-<a href="{@docRoot}devices/tech/encryption/index.html">Encryption</a>.</p>
-
-<h2 id="password-protection">Password Protection</h2>
-<p>Android can be configured to verify a user-supplied password prior to providing
-access to a device. In addition to preventing unauthorized use of the device,
-this password protects the cryptographic key for full filesystem encryption.</p>
-<p>Use of a password and/or password complexity rules can be required by a device
-administrator.</p>
-
-<h2 id="device-administration">Device Administration</h2>
-<p>Android 2.2 and later provide the Android Device Administration API, which
-provides device administration features at the system level. For example, the
-built-in Android Email application uses the APIs to improve Exchange support.
-Through the Email application, Exchange administrators can enforce password
-policies — including alphanumeric passwords or numeric PINs — across
-devices. Administrators can also remotely wipe (that is, restore factory
-defaults on) lost or stolen handsets.</p>
-<p>In addition to use in applications included with the Android system, these APIs
-are available to third-party providers of Device Management solutions. Details
-on the API are provided here:
-<a href="https://devel
-oper.android.com/guide/topics/admin/device-admin.html">https://developer.android.com/guide/topics/admin/device-admin.html</a>.</p>
-
-<h1 id="android-application-security">Android Application Security</h1>
-<h2 id="elements-of-applications">Elements of Applications</h2>
-<p>Android provides an open source platform and application environment for mobile
-devices. The core operating system is based on the Linux kernel. Android
-applications are most often written in the Java programming language and run in
-the ART runtime. However, applications can also be written in native
-code. Applications are installed from a single file with the .apk file
-extension.</p>
-<p>The main Android application building blocks are:</p>
+<p>Google provides a set of cloud-based services that are available to any
+ compatible Android device. The primary services are:</p>
<ul>
-<li>
-<p><strong>AndroidManifest.xml</strong>: The
-<a href="https://developer.android.com/guide/topics/manifest/manifes
-t-intro.html">AndroidManifest.xml</a> file is the control file that tells the system what to do with
-all the top-level components (specifically activities, services, broadcast
-receivers, and content providers described below) in an application. This also
-specifies which permissions are required.</p>
-</li>
-<li>
-<p><strong>Activities</strong>: An
-<a href="https://developer.android.com/guide/topics/fundamentals/activities.htm
-l">Activity</a> is, generally, the code for a single, user-focused task. It usually
-includes displaying a UI to the user, but it does not have to -- some
-Activities never display UIs. Typically, one of the application's Activities
-is the entry point to an application.</p>
-</li>
-<li>
-<p><strong>Services</strong>: A
-<a href="https://developer.android.com/guide/topics/fundamentals/services.html">Service</a>
-is a body of code that runs in the background. It can run in its own process,
-or in the context of another application's process. Other components "bind" to
-a Service and invoke methods on it via remote procedure calls. An example of a
-Service is a media player: even when the user quits the media-selection UI, the
-user probably still intends for music to keep playing. A Service keeps the
-music going even when the UI has completed.</p>
-</li>
-<li>
-<p><strong>Broadcast Receiver</strong>: A
-<a href="https://developer.android.com/reference/android/content/Broad
-castReceiver.html">BroadcastReceiver</a> is an object that is instantiated when an IPC mechanism
-known as an
-<a href="https://developer.android.com/reference/android/content/Intent.html">Intent</a>
-is issued by the operating system or another application. An application may
-register a receiver for the low battery message, for example, and change its
-behavior based on that information.</p>
-</li>
+ <li>
+ <p><strong>Google Play</strong>: Google Play is a collection of services that
+ allow users to discover, install, and purchase applications from their Android
+ device or the web. Google Play makes it easy for developers to reach Android
+ users and potential customers. Google Play also provides community review,
+ application <a href="https://developer.android.com/guide/publishing/licensing.html">license
+ verification</a>, application security scanning, and other security services.</p>
+ </li>
+ <li>
+ <p><strong>Android Updates</strong>: The Android update service delivers new capabilities and
+ security updates to Android devices, including updates through the web or over
+ the air (OTA).</p>
+ </li>
+ <li>
+ <p><strong>Application Services</strong>: Frameworks that allow Android applications to use
+ cloud capabilities such as (<a href="https://developer.android.com/guide/topics/data/backup.html">backing
+ up</a>) application
+ data and settings and cloud-to-device messaging
+ (<a href="https://developers.google.com/android/c2dm/">C2DM</a>)
+ for push messaging.</p>
+ </li>
</ul>
+<p>These services are not part of the Android Open Source Project and are out
+ of scope for this document. But they are relevant to the security of most
+ Android devices, so a related security document titled “Google Services for
+ Android: Security Overview” is available.</p>
-<h2 id="the-android-permission-model-accessing-protected-apis">The Android Permission Model: Accessing Protected APIs</h2>
-<p>All applications on Android run in an Application Sandbox, described earlier in this document.
-By default, an Android application can only access a limited range of system
-resources. The system manages Android application access to resources that, if
-used incorrectly or maliciously, could adversely impact the user experience,
-the network, or data on the device.</p>
-<p>These restrictions are implemented in a variety of different forms. Some
-capabilities are restricted by an intentional lack of APIs to the sensitive
-functionality (e.g. there is no Android API for directly manipulating the SIM
-card). In some instances, separation of roles provides a security measure, as
-with the per-application isolation of storage. In other instances, the
-sensitive APIs are intended for use by trusted applications and protected
-through a security mechanism known as Permissions.</p>
-<p>These protected APIs include:</p>
-<ul>
-<li>Camera functions</li>
-<li>Location data (GPS)</li>
-<li>Bluetooth functions</li>
-<li>Telephony functions</li>
-<li>SMS/MMS functions</li>
-<li>Network/data connections</li>
-</ul>
-<p>These resources are only accessible through the operating system. To make use
-of the protected APIs on the device, an application must define the
-capabilities it needs in its manifest. When preparing to install an
-application, the system displays a dialog to the user that indicates the
-permissions requested and asks whether to continue the installation. If the
-user continues with the installation, the system accepts that the user has
-granted all of the requested permissions. The user can not grant or deny
-individual permissions -- the user must grant or deny all of the requested
-permissions as a block.</p>
-<p>Once granted, the permissions are applied to the application as long as it is
-installed. To avoid user confusion, the system does not notify the user again
-of the permissions granted to the application, and applications that are
-included in the core operating system or bundled by an OEM do not request
-permissions from the user. Permissions are removed if an application is
-uninstalled, so a subsequent re-installation will again result in display of
-permissions.</p>
-<p>Within the device settings, users are able to view permissions for applications
-they have previously installed. Users can also turn off some functionality
-globally when they choose, such as disabling GPS, radio, or wi-fi.</p>
-<p>In the event that an application attempts to use a protected feature which has
-not been declared in the application's manifest, the permission failure will
-typically result in a security exception being thrown back to the application.
-Protected API permission checks are enforced at the lowest possible level to
-prevent circumvention. An example of the user messaging when an application is
-installed while requesting access to protected APIs is shown in <em>Figure 2</em>.</p>
-<p>The system default permissions are described at
-<a href="https://developer.android.com/reference/android/Manifest.permission.html">https://developer.android.com/reference/android/Manifest.permission.html</a>.
-Applications may declare their own permissions for other applications to use.
-Such permissions are not listed in the above location.</p>
-<p>When defining a permission a protectionLevel attribute tells the system how the
-user is to be informed of applications requiring the permission, or who is
-allowed to hold a permission. Details on creating and using application
-specific permissions are described at
-<a href="https://develo
-per.android.com/guide/topics/security/security.html">https://developer.android.com/guide/topics/security/security.html</a>.</p>
-<p>There are some device capabilities, such as the ability to send SMS broadcast
-intents, that are not available to third-party applications, but that may be
-used by applications pre-installed by the OEM. These permissions use the
-signatureOrSystem permission.</p>
-<h2 id="how-users-understand-third-party-applications">How Users Understand Third-Party Applications</h2>
-<p>Android strives to make it clear to users when they are interacting with
-third-party applications and inform the user of the capabilities those
-applications have. Prior to installation of any application, the user is shown
-a clear message about the different permissions the application is requesting.
-After install, the user is not prompted again to confirm any permissions.</p>
-<p>There are many reasons to show permissions immediately prior to installation
-time. This is when user is actively reviewing information about the
-application, developer, and functionality to determine whether it matches their
-needs and expectations. It is also important that they have not yet
-established a mental or financial commitment to the app, and can easily compare
-the application to other alternative applications.</p>
-<p>Some other platforms use a different approach to user notification, requesting
-permission at the start of each session or while applications are in use. The
-vision of Android is to have users switching seamlessly between applications at
-will. Providing confirmations each time would slow down the user and prevent
-Android from delivering a great user experience. Having the user review
-permissions at install time gives the user the option to not install the
-application if they feel uncomfortable.</p>
-<p>Also, many user interface studies have shown that over-prompting the user
-causes the user to start saying "OK" to any dialog that is shown. One of
-Android's security goals is to effectively convey important security
-information to the user, which cannot be done using dialogs that the user will
-be trained to ignore. By presenting the important information once, and only
-when it is important, the user is more likely to think about what they are
-agreeing to.</p>
-<p>Some platforms choose not to show any information at all about application
-functionality. That approach prevents users from easily understanding and
-discussing application capabilities. While it is not possible for all users to
-always make fully informed decisions, the Android permissions model makes
-information about applications easily accessible to a wide range of users. For
-example, unexpected permissions requests can prompt more sophisticated users to
-ask critical questions about application functionality and share their concerns
-in places such as <a href="htts://play.google.com">Google Play</a> where they
-are visible to all users.</p>
-<table>
-<tr>
-<td><strong>Permissions at Application Install -- Google Maps</strong></td>
-<td><strong>Permissions of an Installed Application -- gMail</strong></td>
-</tr>
-<tr>
-<td>
-<img alt="Permissions at Application Install -- Google Maps" width=250
-src="images/image_install.png"/>
-</td>
-<td>
-<img alt="Permissions of an Installed Application -- gMail" width=250
-src="images/image_gmail_installed.png"/>
-</td>
-</tr>
-</table>
-<p><em>Figure 2: Display of permissions for applications</em></p>
-<h2 id="interprocess-communication">Interprocess Communication</h2>
-<p>Processes can communicate using any of the traditional UNIX-type mechanisms.
-Examples include the filesystem, local sockets, or signals. However, the Linux
-permissions still apply.</p>
-<p>Android also provides new IPC mechanisms:</p>
-<ul>
-<li>
-<p><strong>Binder</strong>: A lightweight capability-based remote procedure call mechanism
-designed for high performance when performing in-process and cross-process
-calls. Binder is implemented using a custom Linux driver. See
-<a href="https://developer
-.android.com/reference/android/os/Binder.html">https://developer.android.com/reference/android/os/Binder.html</a>.</p>
-</li>
-<li>
-<p><strong>Services</strong>: Services (discussed above) can provide interfaces directly
-accessible using binder.</p>
-</li>
-<li>
-<p><strong>Intents</strong>: An Intent is a simple message object that represents an
-"intention" to do something. For example, if your application wants to display
-a web page, it expresses its "Intent" to view the URL by creating an Intent
-instance and handing it off to the system. The system locates some other piece
-of code (in this case, the Browser) that knows how to handle that Intent, and
-runs it. Intents can also be used to broadcast interesting events (such as a
-notification) system-wide. See
-<a href="https://developer.android.com/reference/android/content/Intent.html">https://developer.android.com/reference/android/content/Intent.html</a>.</p>
-</li>
-<li>
-<p><strong>ContentProviders</strong>: A ContentProvider is a data storehouse that provides
-access to data on the device; the classic example is the ContentProvider that
-is used to access the user's list of contacts. An application can access data
-that other applications have exposed via a ContentProvider, and an application
-can also define its own ContentProviders to expose data of its own. See
-<a href="https://developer.android.com/reference/android/content/ContentProvider.html">https://developer.android.com/reference/android/content/ContentProvider.html</a>.</p>
-</li>
-</ul>
-<p>While it is possible to implement IPC using other mechanisms such as network
-sockets or world-writable files, these are the recommended Android IPC
-frameworks. Android developers will be encouraged to use best practices around
-securing users' data and avoiding the introduction of security vulnerabilities.</p>
-<h2 id="cost-sensitive-apis">Cost-Sensitive APIs</h2>
-<p>A cost sensitive API is any function that might generate a cost for the user or
-the network. The Android platform has placed cost sensitive APIs in the list of
-protected APIs controlled by the OS. The user will have to grant explicit
-permission to third-party applications requesting use of cost sensitive APIs.
-These APIs include:</p>
-<ul>
-<li>Telephony</li>
-<li>SMS/MMS</li>
-<li>Network/Data</li>
-<li>In-App Billing</li>
-<li>NFC Access</li>
-</ul>
-
-<p> Android 4.2 adds further control on the use of SMS. Android will provide a
-notification if an application attempts to send SMS to a short code that uses
-premium services which might cause additional charges. The user can choose
-whether to allow the application to send the message or block it.
-</p>
-
-<h2 id="sim-card-access">SIM Card Access</h2>
-<p>Low level access to the SIM card is not available to third-party apps. The OS
-handles all communications with the SIM card including access to personal
-information (contacts) on the SIM card memory. Applications also cannot access
-AT commands, as these are managed exclusively by the Radio Interface Layer
-(RIL). The RIL provides no high level APIs for these commands.</p>
-<h2 id="personal-information">Personal Information</h2>
-<p>Android has placed APIs that provide access to user data into the set of
-protected APIs. With normal usage, Android devices will also accumulate user
-data within third-party applications installed by users. Applications that
-choose to share this information can use Android OS permission checks to
-protect the data from third-party applications.</p>
-<p><img alt="Figure 3: Access to sensitive user data is only available through protected
-APIs" src="images/image03.png" /></p>
-<p><em>Figure 3: Access to sensitive user data is only available through protected
-APIs</em></p>
-<p>System content providers that are likely to contain personal or personally
-identifiable information such as contacts and calendar have been created with
-clearly identified permissions. This granularity provides the user with clear
-indication of the types of information that may be provided to the application.
- During installation, a third-party application may request permission to
-access these resources. If permission is granted, the application can be
-installed and will have access to the data requested at any time when it is
-installed.</p>
-<p>Any applications which collect personal information will, by default, have that
-data restricted only to the specific application. If an application chooses to
-make the data available to other applications though IPC, the application
-granting access can apply permissions to the IPC mechanism that are enforced by
-the operating system.</p>
-<h2 id="sensitive-data-input-devices">Sensitive Data Input Devices</h2>
-<p>Android devices frequently provide sensitive data input devices that allow
-applications to interact with the surrounding environment, such as camera,
-microphone or GPS. For a third-party application to access these devices, it
-must first be explicitly provided access by the user through the use of Android
-OS Permissions. Upon installation, the installer will prompt the user
-requesting permission to the sensor by name.</p>
-<p>If an application wants to know the user's location, the application requires a
-permission to access the user's location. Upon installation, the installer will
-prompt the user asking if the application can access the user's location. At
-any time, if the user does not want any application to access their location,
-then the user can run the "Settings" application, go to "Location & Security",
-and uncheck the "Use wireless networks" and "Enable GPS satellites". This will
-disable location based services for all applications on the user's device.</p>
-<h2 id="device-metadata">Device Metadata</h2>
-<p>Android also strives to restrict access to data that is not intrinsically
-sensitive, but may indirectly reveal characteristics about the user, user
-preferences, and the manner in which they use a device.</p>
-<p>By default applications do not have access to operating system logs,
-browser history, phone number, or hardware / network identification
-information. If an application requests access to this information at install
-time, the installer will prompt the user asking if the application can access
-the information. If the user does not grant access, the application will not be
-installed.</p>
-<h2 id="application-signing">Application Signing</h2>
-<p>Code signing allows developers to identify the author of the application and to
-update their application without creating complicated interfaces and
-permissions. Every application that is run on the Android platform must be
-signed by the developer. Applications that attempt to install without being
-signed will rejected by either Google Play or the package installer on
-the Android device.</p>
-<p>On Google Play, application signing bridges the trust Google has with the
-developer and the trust the developer has with their application. Developers
-know their application is provided, unmodified to the Android device; and
-developers can be held accountable for behavior of their application.</p>
-<p>On Android, application signing is the first step to placing an application in
-its Application Sandbox. The signed application certificate defines which user
-id is associated with which application; different applications run under
-different user IDs. Application signing ensures that one application cannot
-access any other application except through well-defined IPC.</p>
-<p>When an application (APK file) is installed onto an Android device, the Package
-Manager verifies that the APK has been properly signed with the certificate
-included in that APK. If the certificate (or, more accurately, the public key
-in the certificate) matches the key used to sign any other APK on the device,
-the new APK has the option to specify in the manifest that it will share a UID
-with the other similarly-signed APKs.</p>
-<p>Applications can be signed by a third-party (OEM, operator, alternative market)
-or self-signed. Android provides code signing using self-signed certificates
-that developers can generate without external assistance or permission.
-Applications do not have to be signed by a central authority. Android currently
-does not perform CA verification for application certificates.</p>
-<p>Applications are also able to declare security permissions at the Signature
-protection level, restricting access only to applications signed with the same
-key while maintaining distinct UIDs and Application Sandboxes. A closer
-relationship with a shared Application Sandbox is allowed via the
-<a href="https://developer.android.com/guide/topics/manifest/manifest-element.html#uid">shared UID
-feature</a> where two or more applications signed with same developer key can
-declare a shared UID in their manifest.</p>
-
-<h2 id="app-verification">Application Verification</h2>
-<p>
-Android 4.2 and later support application verification. Users can choose to
-enable “Verify Apps" and have applications evaluated by an application verifier
-prior to installation. App verification can alert the user if they try to
-install an app that might be harmful; if an application is especially bad, it
-can block installation.
-</p>
-
-<h2 id="digital-rights-management">Digital Rights Management</h2>
-<p>The Android platform provides an extensible DRM framework that lets
-applications manage rights-protected content according to the license
-constraints that are associated with the content. The DRM framework supports
-many DRM schemes; which DRM schemes a device supports is left to the device
-manufacturer.</p>
-<p>The <a href="https://developer.android.com/reference/android/drm/package-summary.html">Android DRM
-framework</a>
-is implemented in two architectural layers (see figure below):</p>
-<ul>
-<li>
-<p>A DRM framework API, which is exposed to applications through the Android
-application framework and runs through the ART runtime for standard applications.</p>
-</li>
-<li>
-<p>A native code DRM manager, which implements the DRM framework and exposes an
-interface for DRM plug-ins (agents) to handle rights management and decryption
-for various DRM schemes</p>
-</li>
-</ul>
-<p><img alt="Figure 4: Architecture of Digital Rights Management on Android
-platform" src="images/image02.png" /></p>
-<p><em>Figure 4: Architecture of Digital Rights Management on Android platform</em></p>
-<h1 id="android-updates">Android Updates</h1>
-<p>Android provides system updates for both security and feature related purposes.</p>
-<p>There are two ways to update the code on most Android devices: over-the-air
-(OTA updates) or side-loaded updates. OTA updates can be rolled out over a
-defined time period or be pushed to all devices at once, depending on how the
-OEM and/or carrier would like to push the updates. Side-loaded updates can be
-provided from a central location for users to download as a zip file to their
-local desktop machine or directly to their handset. Once the update is copied
-or downloaded to the SD card on the device, Android will recognize the update,
-verify its integrity and authenticity, and automatically update the device.</p>
-<p>If a dangerous vulnerability is discovered internally or responsibly reported
-to Google or the Android Open Source Project, the Android security team will
-start the following process.</p>
-<ol>
-<li>The Android team will notify companies who have signed NDAs regarding the
-problem and begin discussing the solution.</li>
-<li>The owners of code will begin the fix.</li>
-<li>The Android team will fix Android-related security issues.</li>
-<li>When a patch is available, the fix is provided to the NDA companies.</li>
-<li>The Android team will publish the patch in the Android Open Source Project</li>
-<li>OEM/carrier will push an update to customers.</li>
-</ol>
-<p>The NDA is required to ensure that the security issue does not become public
-prior to availabilty of a fix and put users at risk. Many OHA members run their
-own code on Android devices such as the bootloader, wifi drivers, and the
-radio. Once the Android Security team is notified of a security issue in this
-partner code, they will consult with OHA partners to quickly find a fix for the
-problem at hand and similar problems. However, the OHA member who wrote the
-faulty code is ultimately responsible for fixing the problem.</p>
-<p>If a dangerous vulnerability is not responsibly disclosed (e.g., if it is
-posted to a public forum without warning), then Google and/or the Android Open
-Source Project will work as quickly as possible to create a patch. The patch
-will released to the public (and any partners) when the patch is tested and
-ready for use.</p>
-<p>At Google I/O 2011, many of the largest OHA partners committed to providing
-updates to devices for 18 months after initial shipment. This will provide
-users with access to the most recent Android features, as well as security
-updates.</p>
-<p>Any developer, Android user, or security researcher can notify the Android
-security team of potential security issues by sending email to
-security@android.com. If desired, communication can be encrypted using the
-Android security team PGP key available here:
-<a href="https://developer.android.com/security_at_android_dot_com.txt">https://developer.android.com/security_at_android_dot_com.txt</a>.</p>
-<h1 id="other-resources">Other Resources</h1>
-<p>Information about the Android Open Source Project is available at
-<a href="https://source.android.com">https://source.android.com</a>.</p>
-<p>Information for Android application developers is here:
-<a href="https://developer.android.com">https://developer.android.com</a>.</p>
-<p>The Android Security team can be reached at
-<a href="mailto:security@android.com">security@android.com</a>.</p>
-<p>Security information exists throughout the Android Open Source and Developer
-Sites. A good place to start is here:
-<a href="https://developer.android.com/guide/topics/security/security.html">https://developer.android.com/guide/topics/security/security.html</a>.</p>
-<p>A Security FAQ for developers is located here:
-<a href="https://developer.android.com/resources/faq/security.html">https://developer.android.com/resources/faq/security.html</a>.</p>
-<p>Security Best Practices for developers is located here:
-<a href="https://developer.android.com/guide/practices/security.html">https://developer.android.com/guide/practices/security.html</a>.</p>
-<p>A community resource for discussion about Android security exists here:
-<a href="https://groups.google.com/forum/?fromgroups#!forum/android-security-discuss">https://groups.google.com/forum/?fromgroups#!forum/android-security-discuss</a>.</p>
diff --git a/src/devices/tech/security/acknowledgements.jd b/src/devices/tech/security/overview/acknowledgements.jd
similarity index 79%
rename from src/devices/tech/security/acknowledgements.jd
rename to src/devices/tech/security/overview/acknowledgements.jd
index 097da07..19e79ec 100644
--- a/src/devices/tech/security/acknowledgements.jd
+++ b/src/devices/tech/security/overview/acknowledgements.jd
@@ -16,7 +16,6 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-
<p>The Android Security Team would like to thank the following people and
parties for helping to improve Android security. They have done this either by
finding and responsibly reporting security vulnerabilities to <a
@@ -25,6 +24,27 @@
for the <a href="https://www.google.com/about/appsecurity/patch-rewards/">Patch
Rewards</a> program.</p>
+<h2>2015</h2>
+
+<div style="LINE-HEIGHT:25px;">
+
+<p><a href="mailto:higongguang@gmail.com">Guang Gong</a> of <a href="http://www.360safe.com/">Qihoo 360 Technology Co. Ltd</a> (<a href="https://twitter.com/oldfresher">@oldfresher</a>)</p>
+
+<p>Stephan Huber of Testlab Mobile Security, <a
+href="https://www.sit.fraunhofer.de/">Fraunhofer SIT</a> (<a
+href="mailto:Stephan.Huber@sit.fraunhofer.de">Stephan.Huber@sit.fraunhofer.de</a>)
+</p>
+
+<p><a
+href="http://www.ec-spride.tu-darmstadt.de/en/research-groups/secure-software-engineering-group/staff/siegfried-rasthofer/">Siegfried
+Rasthofer</a> of <a href="http://sseblog.ec-spride.de/">Secure Software
+Engineering Group</a>, EC SPRIDE Technische Universität Darmstadt (<a
+href="mailto:siegfried.rasthofer@gmail.com">siegfried.rasthofer@gmail.com</a>)</p>
+
+<p><a href="mailto:laginimaineb@gmail.com">Gal Beniamini</a> (<a href="http://bits-please.blogspot.com">http://bits-please.blogspot.com</a>)</p>
+
+</div>
+
<h2>2014</h2>
<div style="LINE-HEIGHT:25px;">
@@ -104,7 +124,7 @@
href="mailto:hanxinhui@pku.edu.cn">hanxinhui@pku.edu.cn</a>)</p>
<p><a href="http://thejh.net/">Jann Horn</a> <a href="https://android-review.googlesource.com/#/c/98197/">
-<img style="vertical-align:middle;" src="images/tiny-robot.png"
+<img style="vertical-align:middle;" src="../images/tiny-robot.png"
alt="Green Droid Patch Symbol"
title="This person contributed code that improved Android security">
</a></p>
@@ -112,21 +132,21 @@
<p>Robert Craig of <a href="https://www.nsa.gov/research/ia_research/">
Trusted Systems Research Group</a>, US National Security Agency
<a href="https://android-review.googlesource.com/#/q/owner:%22Robert+Craig+%253Crpcraig%2540tycho.ncsc.mil%253E%22+status:merged">
-<img style="vertical-align:middle" src="images/tiny-robot.png" alt="Patch Symbol"
+<img style="vertical-align:middle" src="../images/tiny-robot.png" alt="Patch Symbol"
title="This person contributed code that improved Android security"></a></p>
<p>Stephen Smalley of <a href="https://www.nsa.gov/research/ia_research/">
Trusted Systems Research Group</a>, US National Security Agency
<a href=
"https://android-review.googlesource.com/#/q/owner:%22Stephen+Smalley+%253Csds%2540tycho.nsa.gov%253E%22+status:merged">
-<img style="vertical-align:middle" src="images/tiny-robot.png"
+<img style="vertical-align:middle" src="../images/tiny-robot.png"
alt="Patch Symbol" title="This person contributed code that improved Android security"></a></p>
<p><a href="http://www.linkedin.com/in/billcroberts">
William Roberts</a> (<a href="mailto:bill.c.roberts@gmail.com">bill.c.roberts@gmail.com</a>)
<a href=
"https://android-review.googlesource.com/#/q/owner:bill.c.roberts%2540gmail.com+status:merged">
-<img style="vertical-align:middle" src="images/tiny-robot.png"
+<img style="vertical-align:middle" src="../images/tiny-robot.png"
alt="Patch Symbol" title="This person contributed code that improved Android security"></a></p>
<p>Scotty Bauer of University of Utah (<a href="mailto:sbauer@eng.utah.edu">sbauer@eng.utah.edu</a>)</p>
@@ -141,7 +161,7 @@
<p>Sebastian Brenza</p>
-<p>Wang Tao of <a href="http://sec.baidu.com">Baidu AdLab</a> (<a href="mailto:wintao@gmail.com">wintao@gmail.com</a>)</p>
+<p>Wang Tao of <a href="http://xteam.baidu.com">Baidu X-Team</a> (<a href="mailto:wintao@gmail.com">wintao@gmail.com</a>)</p>
<p><a href="http://www.linkedin.com/in/danamodio">Dan Amodio</a> of <a href="https://www.aspectsecurity.com/">Aspect Security</a> (<a href="https://twitter.com/DanAmodio">@DanAmodio</a>)</p>
@@ -153,6 +173,18 @@
<p>Marc Blanchou (<a href="https://twitter.com/marcblanchou">@marcblanchou</a>)</p>
+<p>Wang Yu of <a href="http://xteam.baidu.com">Baidu X-Team</a> (<a href="https://twitter.com/xi4oyu">@xi4oyu</a>)</p>
+
+<p>Zhang Dong Hui of <a href="http://xteam.baidu.com">Baidu X-Team</a> (<a href="http://weibo.com/shineastdh">shineastdh</a>)</p>
+
+<p>Alex Park (<a href="https://twitter.com/saintlinu">@saintlinu</a>)</p>
+
+<p><a href="http://www.sonymobile.com">Sony Mobile</a></p>
+
+<p><a href="https://twitter.com/isciurus">Andrey Labunets</a> of <a href="https://www.facebook.com">Facebook</a></p>
+
+<p>Imre Rad of <a href="http://www.search-lab.hu/">Search-Lab Ltd.</a></p>
+
</div>
<h2>2013</h2>
@@ -165,7 +197,7 @@
<p>Joshua J. Drake of <a href="http://www.accuvant.com/">Accuvant LABS
</a> (<a href="https://twitter.com/jduck">@jduck</a>)
<a href="https://android-review.googlesource.com/#/q/change:72228+OR+change:72229">
-<img style="vertical-align:middle" src="images/patchreward.png"
+<img style="vertical-align:middle" src="../images/patchreward.png"
alt="Patch Rewards Symbol" title="This person qualified for the Patch Rewards program!"></a></p>
<p>Ruben Santamarta of IOActive
@@ -199,27 +231,37 @@
<p>Robert Craig of <a href="https://www.nsa.gov/research/ia_research/">
Trusted Systems Research Group</a>, US National Security Agency
<a href="https://android-review.googlesource.com/#/q/owner:%22Robert+Craig+%253Crpcraig%2540tycho.ncsc.mil%253E%22+status:merged">
-<img style="vertical-align:middle" src="images/tiny-robot.png" alt="Patch Symbol"
+<img style="vertical-align:middle" src="../images/tiny-robot.png" alt="Patch Symbol"
title="This person contributed code that improved Android security"></a></p>
<p>Stephen Smalley of <a href="https://www.nsa.gov/research/ia_research/">
Trusted Systems Research Group</a>, US National Security Agency
<a href=
"https://android-review.googlesource.com/#/q/owner:%22Stephen+Smalley+%253Csds%2540tycho.nsa.gov%253E%22+status:merged">
-<img style="vertical-align:middle" src="images/tiny-robot.png"
+<img style="vertical-align:middle" src="../images/tiny-robot.png"
alt="Patch Symbol" title="This person contributed code that improved Android security"></a></p>
<p><a href="http://www.linkedin.com/in/billcroberts">
William Roberts</a> (<a href="mailto:bill.c.roberts@gmail.com">bill.c.roberts@gmail.com</a>)
<a href=
"https://android-review.googlesource.com/#/q/owner:bill.c.roberts%2540gmail.com+status:merged">
-<img style="vertical-align:middle" src="images/tiny-robot.png"
+<img style="vertical-align:middle" src="../images/tiny-robot.png"
alt="Patch Symbol" title="This person contributed code that improved Android security"></a></p>
<p><a href="http://roeehay.blogspot.com/">Roee Hay</a>
<br>(<a href="https://twitter.com/roeehay">@roeehay</a>,
<a href="mailto:roeehay@gmail.com">roeehay@gmail.com</a>)</p>
+<p><a href="http://homes.soic.indiana.edu/luyixing">Luyi Xing</a> of Indiana
+University Bloomington (<a
+href="mailto:xingluyi@gmail.com">xingluyi@gmail.com</a>)</p>
+
+<p>Xiaorui Pan of Indiana University Bloomington (<a href="mailto:eagle200467@gmail.com">eagle200467@gmail.com</a>)<p>
+
+<p>XiaoFeng Wang of Indiana University Bloomington (<a href="mailto:xw7@indiana.edu">xw7@indiana.edu</a>)</p>
+
+<p>Kan Yuan</p>
+
</div>
<h2>2012</h2>
@@ -228,21 +270,21 @@
<p>Robert Craig of <a href="https://www.nsa.gov/research/ia_research/">
Trusted Systems Research Group</a>, US National Security Agency
<a href="https://android-review.googlesource.com/#/q/owner:%22Robert+Craig+%253Crpcraig%2540tycho.ncsc.mil%253E%22+status:merged">
-<img style="vertical-align:middle" src="images/tiny-robot.png" alt="Patch Symbol"
+<img style="vertical-align:middle" src="../images/tiny-robot.png" alt="Patch Symbol"
title="This person contributed code that improved Android security"></a></p>
<p>Stephen Smalley of <a href="https://www.nsa.gov/research/ia_research/">
Trusted Systems Research Group</a>, US National Security Agency
<a href=
"https://android-review.googlesource.com/#/q/owner:%22Stephen+Smalley+%253Csds%2540tycho.nsa.gov%253E%22+status:merged">
-<img style="vertical-align:middle" src="images/tiny-robot.png"
+<img style="vertical-align:middle" src="../images/tiny-robot.png"
alt="Patch Symbol" title="This person contributed code that improved Android security"></a></p>
<p><a href="http://www.linkedin.com/in/billcroberts">
William Roberts</a> (<a href="mailto:bill.c.roberts@gmail.com">bill.c.roberts@gmail.com</a>)
<a href=
"https://android-review.googlesource.com/#/q/owner:bill.c.roberts%2540gmail.com+status:merged">
-<img style="vertical-align:middle" src="images/tiny-robot.png"
+<img style="vertical-align:middle" src="../images/tiny-robot.png"
alt="Patch Symbol" title="This person contributed code that improved Android security"></a></p>
<p><a href="http://thejh.net/">Jann Horn</a></p>
@@ -255,6 +297,8 @@
<br>(<a href="https://twitter.com/roeehay">@roeehay</a>,
<a href="mailto:roeehay@gmail.com">roeehay@gmail.com</a>)</p>
+<p>David Weinstein of <a href="https://viaforensics.com/">viaForensics</a> (<a href="https://twitter.com/insitusec">@insitusec</a>)</p>
+
</div>
<h2>2011</h2>
diff --git a/src/devices/tech/security/overview/app-security.jd b/src/devices/tech/security/overview/app-security.jd
new file mode 100644
index 0000000..3f2811c
--- /dev/null
+++ b/src/devices/tech/security/overview/app-security.jd
@@ -0,0 +1,345 @@
+page.title=Application security
+@jd:body
+
+<!--
+ Copyright 2014 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc"></ol>
+ </div>
+</div>
+
+<h2 id="elements-of-applications">Elements of Applications</h2>
+<p>Android provides an open source platform and application environment for mobile
+ devices. The core operating system is based on the Linux kernel. Android
+ applications are most often written in the Java programming language and run in
+ the Dalvik virtual machine. However, applications can also be written in native
+ code. Applications are installed from a single file with the .apk file
+ extension.</p>
+<p>The main Android application building blocks are:</p>
+<ul>
+ <li>
+ <p><strong>AndroidManifest.xml</strong>: The <a href="https://developer.android.com/guide/topics/manifest/manifes
+t-intro.html">AndroidManifest.xml</a> file is the control file that tells the system what to do with
+ all the top-level components (specifically activities, services, broadcast
+ receivers, and content providers described below) in an application. This also
+ specifies which permissions are required.</p>
+ </li>
+ <li>
+ <p><strong>Activities</strong>: An <a href="https://developer.android.com/guide/topics/fundamentals/activities.htm
+l">Activity</a> is, generally, the code for a single, user-focused task. It usually
+ includes displaying a UI to the user, but it does not have to -- some
+ Activities never display UIs. Typically, one of the application's Activities
+ is the entry point to an application.</p>
+ </li>
+ <li>
+ <p><strong>Services</strong>: A <a href="https://developer.android.com/guide/topics/fundamentals/services.html">Service</a> is a body of code that runs in the background. It can run in its own process,
+ or in the context of another application's process. Other components "bind" to
+ a Service and invoke methods on it via remote procedure calls. An example of a
+ Service is a media player: even when the user quits the media-selection UI, the
+ user probably still intends for music to keep playing. A Service keeps the
+ music going even when the UI has completed.</p>
+ </li>
+ <li>
+ <p><strong>Broadcast Receiver</strong>: A <a href="https://developer.android.com/reference/android/content/Broad
+castReceiver.html">BroadcastReceiver</a> is an object that is instantiated when an IPC mechanism
+ known as an <a href="https://developer.android.com/reference/android/content/Intent.html">Intent</a> is issued by the operating system or another application. An application may
+ register a receiver for the low battery message, for example, and change its
+ behavior based on that information.</p>
+ </li>
+</ul>
+<h2 id="the-android-permission-model-accessing-protected-apis">The Android Permission Model: Accessing Protected APIs</h2>
+<p>All applications on Android run in an Application Sandbox, described earlier in this document.
+ By default, an Android application can only access a limited range of system
+ resources. The system manages Android application access to resources that, if
+ used incorrectly or maliciously, could adversely impact the user experience,
+ the network, or data on the device.</p>
+<p>These restrictions are implemented in a variety of different forms. Some
+ capabilities are restricted by an intentional lack of APIs to the sensitive
+ functionality (e.g. there is no Android API for directly manipulating the SIM
+ card). In some instances, separation of roles provides a security measure, as
+ with the per-application isolation of storage. In other instances, the
+ sensitive APIs are intended for use by trusted applications and protected
+ through a security mechanism known as Permissions.</p>
+<p>These protected APIs include:</p>
+<ul>
+ <li>Camera functions</li>
+ <li>Location data (GPS)</li>
+ <li>Bluetooth functions</li>
+ <li>Telephony functions</li>
+ <li>SMS/MMS functions</li>
+ <li>Network/data connections</li>
+</ul>
+<p>These resources are only accessible through the operating system. To make use
+ of the protected APIs on the device, an application must define the
+ capabilities it needs in its manifest. When preparing to install an
+ application, the system displays a dialog to the user that indicates the
+ permissions requested and asks whether to continue the installation. If the
+ user continues with the installation, the system accepts that the user has
+ granted all of the requested permissions. The user can not grant or deny
+ individual permissions -- the user must grant or deny all of the requested
+ permissions as a block.</p>
+<p>Once granted, the permissions are applied to the application as long as it is
+ installed. To avoid user confusion, the system does not notify the user again
+ of the permissions granted to the application, and applications that are
+ included in the core operating system or bundled by an OEM do not request
+ permissions from the user. Permissions are removed if an application is
+ uninstalled, so a subsequent re-installation will again result in display of
+ permissions.</p>
+<p>Within the device settings, users are able to view permissions for applications
+ they have previously installed. Users can also turn off some functionality
+ globally when they choose, such as disabling GPS, radio, or wi-fi.</p>
+<p>In the event that an application attempts to use a protected feature which has
+ not been declared in the application's manifest, the permission failure will
+ typically result in a security exception being thrown back to the application.
+ Protected API permission checks are enforced at the lowest possible level to
+ prevent circumvention. An example of the user messaging when an application is
+ installed while requesting access to protected APIs is shown in <em>Figure 2</em>.</p>
+<p>The system default permissions are described at <a href="https://developer.android.com/reference/android/Manifest.permission.html">https://developer.android.com/reference/android/Manifest.permission.html</a>.
+ Applications may declare their own permissions for other applications to use.
+ Such permissions are not listed in the above location.</p>
+<p>When defining a permission a protectionLevel attribute tells the system how the
+ user is to be informed of applications requiring the permission, or who is
+ allowed to hold a permission. Details on creating and using application
+ specific permissions are described at <a href="https://develo
+per.android.com/guide/topics/security/security.html">https://developer.android.com/guide/topics/security/security.html</a>.</p>
+<p>There are some device capabilities, such as the ability to send SMS broadcast
+ intents, that are not available to third-party applications, but that may be
+ used by applications pre-installed by the OEM. These permissions use the
+ signatureOrSystem permission.</p>
+<h2 id="how-users-understand-third-party-applications">How Users Understand Third-Party Applications</h2>
+<p>Android strives to make it clear to users when they are interacting with
+ third-party applications and inform the user of the capabilities those
+ applications have. Prior to installation of any application, the user is shown
+ a clear message about the different permissions the application is requesting.
+ After install, the user is not prompted again to confirm any permissions.</p>
+<p>There are many reasons to show permissions immediately prior to installation
+ time. This is when user is actively reviewing information about the
+ application, developer, and functionality to determine whether it matches their
+ needs and expectations. It is also important that they have not yet
+ established a mental or financial commitment to the app, and can easily compare
+ the application to other alternative applications.</p>
+<p>Some other platforms use a different approach to user notification, requesting
+ permission at the start of each session or while applications are in use. The
+ vision of Android is to have users switching seamlessly between applications at
+ will. Providing confirmations each time would slow down the user and prevent
+ Android from delivering a great user experience. Having the user review
+ permissions at install time gives the user the option to not install the
+ application if they feel uncomfortable.</p>
+<p>Also, many user interface studies have shown that over-prompting the user
+ causes the user to start saying "OK" to any dialog that is shown. One of
+ Android's security goals is to effectively convey important security
+ information to the user, which cannot be done using dialogs that the user will
+ be trained to ignore. By presenting the important information once, and only
+ when it is important, the user is more likely to think about what they are
+ agreeing to.</p>
+<p>Some platforms choose not to show any information at all about application
+ functionality. That approach prevents users from easily understanding and
+ discussing application capabilities. While it is not possible for all users to
+ always make fully informed decisions, the Android permissions model makes
+ information about applications easily accessible to a wide range of users. For
+ example, unexpected permissions requests can prompt more sophisticated users to
+ ask critical questions about application functionality and share their concerns
+ in places such as <a href="htts://play.google.com">Google Play</a> where they
+ are visible to all users.</p>
+<table>
+ <tr>
+ <td><strong>Permissions at Application Install -- Google Maps</strong></td>
+ <td><strong>Permissions of an Installed Application -- Gmail</strong></td>
+ </tr>
+ <tr>
+ <td><img alt="Permissions at Application Install -- Google Maps" width=250
+src="../images/image_install.png" /></td>
+ <td><img alt="Permissions of an Installed Application -- Gmail" width=250
+src="../images/image_gmail_installed.png" id="figure1" /></td>
+ </tr>
+</table>
+<p class="img-caption">
+ <strong>Figure 1.</strong> Display of permissions for applications
+</p>
+<h2 id="interprocess-communication">Interprocess Communication</h2>
+<p>Processes can communicate using any of the traditional UNIX-type mechanisms.
+ Examples include the filesystem, local sockets, or signals. However, the Linux
+ permissions still apply.</p>
+<p>Android also provides new IPC mechanisms:</p>
+<ul>
+ <li>
+ <p><strong>Binder</strong>: A lightweight capability-based remote procedure call mechanism
+ designed for high performance when performing in-process and cross-process
+ calls. Binder is implemented using a custom Linux driver. See <a href="https://developer
+.android.com/reference/android/os/Binder.html">https://developer.android.com/reference/android/os/Binder.html</a>.</p>
+ </li>
+ <li>
+ <p><strong>Services</strong>: Services (discussed above) can provide interfaces directly
+ accessible using binder.</p>
+ </li>
+ <li>
+ <p><strong>Intents</strong>: An Intent is a simple message object that represents an
+ "intention" to do something. For example, if your application wants to display
+ a web page, it expresses its "Intent" to view the URL by creating an Intent
+ instance and handing it off to the system. The system locates some other piece
+ of code (in this case, the Browser) that knows how to handle that Intent, and
+ runs it. Intents can also be used to broadcast interesting events (such as a
+ notification) system-wide. See
+ [https://developer.android.com/reference/android/content/Intent.html](https://developer.android.com/reference/android/content/Intent.html.</p>
+ </li>
+ <li>
+ <p><strong>ContentProviders</strong>: A ContentProvider is a data storehouse that provides
+ access to data on the device; the classic example is the ContentProvider that
+ is used to access the user's list of contacts. An application can access data
+ that other applications have exposed via a ContentProvider, and an application
+ can also define its own ContentProviders to expose data of its own. See <a href="https://developer.android.com/reference/android/content/ContentProvider.html">https://developer.android.com/reference/android/content/ContentProvider.html</a>.</p>
+ </li>
+</ul>
+<p>While it is possible to implement IPC using other mechanisms such as network
+ sockets or world-writable files, these are the recommended Android IPC
+ frameworks. Android developers will be encouraged to use best practices around
+ securing users' data and avoiding the introduction of security vulnerabilities.</p>
+<h2 id="cost-sensitive-apis">Cost-Sensitive APIs</h2>
+<p>A cost sensitive API is any function that might generate a cost for the user or
+ the network. The Android platform has placed cost sensitive APIs in the list of
+ protected APIs controlled by the OS. The user will have to grant explicit
+ permission to third-party applications requesting use of cost sensitive APIs.
+ These APIs include:</p>
+<ul>
+ <li>Telephony</li>
+ <li>SMS/MMS</li>
+ <li>Network/Data</li>
+ <li>In-App Billing</li>
+ <li>NFC Access</li>
+</ul>
+<p> Android 4.2 adds further control on the use of SMS. Android will provide a
+ notification if an application attempts to send SMS to a short code that uses
+ premium services which might cause additional charges. The user can choose
+ whether to allow the application to send the message or block it. </p>
+<h2 id="sim-card-access">SIM Card Access</h2>
+<p>Low level access to the SIM card is not available to third-party apps. The OS
+ handles all communications with the SIM card including access to personal
+ information (contacts) on the SIM card memory. Applications also cannot access
+ AT commands, as these are managed exclusively by the Radio Interface Layer
+ (RIL). The RIL provides no high level APIs for these commands.</p>
+<h2 id="personal-information">Personal Information</h2>
+<p>Android has placed APIs that provide access to user data into the set of
+ protected APIs. With normal usage, Android devices will also accumulate user
+ data within third-party applications installed by users. Applications that
+ choose to share this information can use Android OS permission checks to
+ protect the data from third-party applications.</p>
+<img alt="Access to sensitive user data available only through protected
+APIs" src="../images/image03.png" id="figure2" />
+<p class="img-caption">
+ <strong>Figure 2.</strong> Access to sensitive user data is available only through protected APIs
+</p>
+<p>System content providers that are likely to contain personal or personally
+ identifiable information such as contacts and calendar have been created with
+ clearly identified permissions. This granularity provides the user with clear
+ indication of the types of information that may be provided to the application.
+ During installation, a third-party application may request permission to
+ access these resources. If permission is granted, the application can be
+ installed and will have access to the data requested at any time when it is
+ installed.</p>
+<p>Any applications which collect personal information will, by default, have that
+ data restricted only to the specific application. If an application chooses to
+ make the data available to other applications though IPC, the application
+ granting access can apply permissions to the IPC mechanism that are enforced by
+ the operating system.</p>
+<h2 id="sensitive-data-input-devices">Sensitive Data Input Devices</h2>
+<p>Android devices frequently provide sensitive data input devices that allow
+ applications to interact with the surrounding environment, such as camera,
+ microphone or GPS. For a third-party application to access these devices, it
+ must first be explicitly provided access by the user through the use of Android
+ OS Permissions. Upon installation, the installer will prompt the user
+ requesting permission to the sensor by name.</p>
+<p>If an application wants to know the user's location, the application requires a
+ permission to access the user's location. Upon installation, the installer will
+ prompt the user asking if the application can access the user's location. At
+ any time, if the user does not want any application to access their location,
+ then the user can run the "Settings" application, go to "Location & Security",
+ and uncheck the "Use wireless networks" and "Enable GPS satellites". This will
+ disable location based services for all applications on the user's device.</p>
+<h2 id="device-metadata">Device Metadata</h2>
+<p>Android also strives to restrict access to data that is not intrinsically
+ sensitive, but may indirectly reveal characteristics about the user, user
+ preferences, and the manner in which they use a device.</p>
+<p>By default applications do not have access to operating system logs,
+ browser history, phone number, or hardware / network identification
+ information. If an application requests access to this information at install
+ time, the installer will prompt the user asking if the application can access
+ the information. If the user does not grant access, the application will not be
+ installed.</p>
+<h2 id="application-signing">Application Signing</h2>
+<p>Code signing allows developers to identify the author of the application and to
+ update their application without creating complicated interfaces and
+ permissions. Every application that is run on the Android platform must be
+ signed by the developer. Applications that attempt to install without being
+ signed will rejected by either Google Play or the package installer on
+ the Android device.</p>
+<p>On Google Play, application signing bridges the trust Google has with the
+ developer and the trust the developer has with their application. Developers
+ know their application is provided, unmodified to the Android device; and
+ developers can be held accountable for behavior of their application.</p>
+<p>On Android, application signing is the first step to placing an application in
+ its Application Sandbox. The signed application certificate defines which user
+ id is associated with which application; different applications run under
+ different user IDs. Application signing ensures that one application cannot
+ access any other application except through well-defined IPC.</p>
+<p>When an application (APK file) is installed onto an Android device, the Package
+ Manager verifies that the APK has been properly signed with the certificate
+ included in that APK. If the certificate (or, more accurately, the public key
+ in the certificate) matches the key used to sign any other APK on the device,
+ the new APK has the option to specify in the manifest that it will share a UID
+ with the other similarly-signed APKs.</p>
+<p>Applications can be signed by a third-party (OEM, operator, alternative market)
+ or self-signed. Android provides code signing using self-signed certificates
+ that developers can generate without external assistance or permission.
+ Applications do not have to be signed by a central authority. Android currently
+ does not perform CA verification for application certificates.</p>
+<p>Applications are also able to declare security permissions at the Signature
+ protection level, restricting access only to applications signed with the same
+ key while maintaining distinct UIDs and Application Sandboxes. A closer
+ relationship with a shared Application Sandbox is allowed via the <a href="https://developer.android.com/guide/topics/manifest/manifest-element.html#uid">shared UID
+ feature</a> where two or more applications signed with same developer key can
+ declare a shared UID in their manifest.</p>
+<h2 id="app-verification">Application Verification</h2>
+<p> Android 4.2 and later support application verification. Users can choose to
+ enable “Verify Apps" and have applications evaluated by an application verifier
+ prior to installation. App verification can alert the user if they try to
+ install an app that might be harmful; if an application is especially bad, it
+ can block installation. </p>
+<h2 id="digital-rights-management">Digital Rights Management</h2>
+<p>The Android platform provides an extensible DRM framework that lets
+ applications manage rights-protected content according to the license
+ constraints that are associated with the content. The DRM framework supports
+ many DRM schemes; which DRM schemes a device supports is left to the device
+ manufacturer.</p>
+<p>The <a href="https://developer.android.com/reference/android/drm/package-summary.html">Android DRM
+ framework</a> is implemented in two architectural layers (see figure below):</p>
+<ul>
+ <li>
+ <p>A DRM framework API, which is exposed to applications through the Android
+ application framework and runs through the Dalvik VM for standard applications.</p>
+ </li>
+ <li>
+ <p>A native code DRM manager, which implements the DRM framework and exposes an
+ interface for DRM plug-ins (agents) to handle rights management and decryption
+ for various DRM schemes</p>
+ </li>
+</ul>
+<p><img alt="Architecture of Digital Rights Management on Android
+platform" src="../images/image02.png" id="figure3" /></p>
+<p class="img-caption">
+ <strong>Figure 3.</strong> Architecture of Digital Rights Management on Android platform
+</p>
diff --git a/src/devices/tech/security/overview/index.jd b/src/devices/tech/security/overview/index.jd
new file mode 100644
index 0000000..e23d734
--- /dev/null
+++ b/src/devices/tech/security/overview/index.jd
@@ -0,0 +1,80 @@
+page.title=Security overview
+@jd:body
+<!--
+ Copyright 2014 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc"></ol>
+ </div>
+</div>
+
+<h2 id="android-security-program-overview">Security Program Overview</h2>
+<p>Early on in development, the core Android development team recognized that a
+ robust security model was required to enable a vigorous ecosystem of
+ applications and devices built on and around the Android platform and supported
+ by cloud services. As a result, through its entire development lifecycle,
+ Android has been subjected to a professional security program. The Android team
+ has had the opportunity to observe how other mobile, desktop, and server platforms
+ prevented and reacted to security issues and built a security
+ program to address weak points observed in other offerings.</p>
+<p>The key components of the Android Security Program include:</p>
+<ul>
+ <li><strong>Design Review</strong>: The Android security process begins early in the
+ development lifecycle with the creation of a rich and configurable security
+ model and design. Each major feature of the platform is reviewed by engineering
+ and security resources, with appropriate security controls integrated into the
+ architecture of the system.</li>
+ <li><strong>Penetration Testing and Code Review</strong>: During the development of the
+ platform, Android-created and open-source components are subject to vigorous
+ security reviews. These reviews are performed by the Android Security Team,
+ Google’s Information Security Engineering team, and independent security
+ consultants. The goal of these reviews is to identify weaknesses and possible
+ vulnerabilities well before the platform is open-sourced, and to simulate the
+ types of analysis that will be performed by external security experts upon
+ release.</li>
+ <li><strong>Open Source and Community Review</strong>: The Android Open Source Project enables
+ broad security review by any interested party. Android also uses open source
+ technologies that have undergone significant external security review,
+ such as the Linux kernel. Google Play provides a forum for users and companies
+ to provide information about specific applications directly to users.</li>
+ <li><strong>Incident Response</strong>: Even with all of these precautions, security issues
+ may occur after shipping, which is why the Android project has created a
+ comprehensive security response process. A full-time Android security team
+ constantly monitors Android-specific and the general security community for
+ discussion of potential vulnerabilities. Upon the discovery of legitimate
+ issues, the Android team has a response process that enables the rapid
+ mitigation of vulnerabilities to ensure that potential risk to all Android
+ users is minimized. These cloud-supported responses can include updating the
+ Android platform (over-the-air updates), removing applications from Google
+ Play, and removing applications from devices in the field.</li>
+</ul>
+<h2 id="android-platform-security-architecture">Platform Security Architecture</h2>
+<p>Android seeks to be the most secure and usable operating system for mobile
+ platforms by re-purposing traditional operating system security controls to:</p>
+<ul>
+ <li>Protect user data</li>
+ <li>Protect system resources (including the network)</li>
+ <li>Provide application isolation</li>
+</ul>
+<p>To achieve these objectives, Android provides these key security features:</p>
+<ul>
+ <li>Robust security at the OS level through the Linux kernel</li>
+ <li>Mandatory application sandbox for all applications</li>
+ <li>Secure interprocess communication</li>
+ <li>Application signing</li>
+ <li>Application-defined and user-granted permissions</li>
+</ul>
diff --git a/src/devices/tech/security/overview/kernel-security.jd b/src/devices/tech/security/overview/kernel-security.jd
new file mode 100644
index 0000000..12ae1bb
--- /dev/null
+++ b/src/devices/tech/security/overview/kernel-security.jd
@@ -0,0 +1,188 @@
+page.title=System and kernel security
+@jd:body
+
+<!--
+ Copyright 2014 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc"></ol>
+ </div>
+</div>
+
+<p>At the operating system level, the Android platform provides the security of
+ the Linux kernel, as well as a secure inter-process communication (IPC)
+ facility to enable secure communication between applications running in
+ different processes. These security features at the OS level ensure that even
+ native code is constrained by the Application Sandbox. Whether that code is
+ the result of included application behavior or a exploitation of an application
+ vulnerability, the system would prevent the rogue application from harming
+ other applications, the Android system, or the device itself.</p>
+<h3 id="linux-security">Linux Security</h3>
+<p>The foundation of the Android platform is the Linux kernel. The Linux kernel
+ itself has been in widespread use for years, and is used in millions of
+ security-sensitive environments. Through its history of constantly being
+ researched, attacked, and fixed by thousands of developers, Linux has become a
+ stable and secure kernel trusted by many corporations and security
+ professionals.</p>
+<p>As the base for a mobile computing environment, the Linux kernel provides
+ Android with several key security features, including:</p>
+<ul>
+ <li>A user-based permissions model</li>
+ <li>Process isolation</li>
+ <li>Extensible mechanism for secure IPC</li>
+ <li>The ability to remove unnecessary and potentially insecure parts of the kernel</li>
+</ul>
+<p>As a multiuser operating system, a fundamental security objective of the Linux
+ kernel is to isolate user resources from one another. The Linux security
+ philosophy is to protect user resources from one another. Thus, Linux:</p>
+<ul>
+ <li>Prevents user A from reading user B's files</li>
+ <li>Ensures that user A does not exhaust user B's memory</li>
+ <li>Ensures that user A does not exhaust user B's CPU resources</li>
+ <li>Ensures that user A does not exhaust user B's devices (e.g. telephony, GPS,
+ bluetooth)</li>
+</ul>
+<h3 id="the-application-sandbox">The Application Sandbox</h3>
+<p>The Android platform takes advantage of the Linux user-based protection as a
+ means of identifying and isolating application resources. The Android system
+ assigns a unique user ID (UID) to each Android application and runs it as that user
+ in a separate process. This approach is different from other operating systems
+ (including the traditional Linux configuration), where multiple applications
+ run with the same user permissions.</p>
+<p>This sets up a kernel-level Application Sandbox. The kernel enforces security
+ between applications and the system at the process level through standard Linux
+ facilities, such as user and group IDs that are assigned to applications. By
+ default, applications cannot interact with each other and applications have
+ limited access to the operating system. If application A tries to do something
+ malicious like read application B's data or dial the phone without permission
+ (which is a separate application), then the operating system protects against
+ this because application A does not have the appropriate user privileges. The
+ sandbox is simple, auditable, and based on decades-old UNIX-style user
+ separation of processes and file permissions.</p>
+<p>Since the Application Sandbox is in the kernel, this security model extends to
+ native code and to operating system applications. All of the software above the
+ kernel in <em>Figure 1</em>, including operating system libraries, application
+ framework, application runtime, and all applications run within the Application
+ Sandbox. On some platforms, developers are constrained to a specific
+ development framework, set of APIs, or language in order to enforce security.
+ On Android, there are no restrictions on how an application can be written that
+ are required to enforce security; in this respect, native code is just as
+ secure as interpreted code.</p>
+<p>In some operating systems, memory corruption errors generally lead to
+ completely compromising the security of the device. This is not the case in
+ Android due to all applications and their resources being sandboxed at the OS
+ level. A memory corruption error will only allow arbitrary code execution in
+ the context of that particular application, with the permissions established by
+ the operating system.</p>
+<p>Like all security features, the Application Sandbox is not unbreakable.
+ However, to break out of the Application Sandbox in a properly configured
+ device, one must compromise the security of the the Linux kernel.</p>
+<h3 id="system-partition-and-safe-mode">System Partition and Safe Mode</h3>
+<p>The system partition contains Android's kernel as well as the operating system
+ libraries, application runtime, application framework, and applications. This
+ partition is set to read-only. When a user boots the device into Safe Mode,
+ only core Android applications are available. This ensures that the user can
+ boot their phone into an environment that is free of third-party software.</p>
+<h3 id="filesystem-permissions">Filesystem Permissions</h3>
+<p>In a UNIX-style environment, filesystem permissions ensure that one user cannot
+ alter or read another user's files. In the case of Android, each application
+ runs as its own user. Unless the developer explicitly exposes files to other
+ applications, files created by one application cannot be read or altered by
+ another application.</p>
+<h3 id="se-linux">Security-Enhanced Linux</h3>
+<p>Android uses Security-Enhanced
+ Linux (SELinux) to apply access control policies and establish an environment of
+ mandatory access control (mac). See <a
+href="{@docRoot}devices/tech/security/selinux/index.html">Validating
+ Security-Enhanced Linux in
+ Android</a> for details.</p>
+<h3 id="crypto">Cryptography</h3>
+<p> Android provides a set of cryptographic APIs for use by applications. These
+ include implementations of standard and commonly used cryptographic primitives
+ such as AES, RSA, DSA, and SHA. Additionally, APIs are provided for higher level
+ protocols such as SSL and HTTPS. </p>
+<p> Android 4.0 introduced the <a href="http://developer.android.com/reference/android/security/KeyChain.html">KeyChain</a> class to allow applications to use the system credential storage for private
+ keys and certificate chains. </p>
+<h3>Rooting of Devices</h3>
+<p> By default, on Android only the kernel and a small subset of the core
+ applications run with root permissions. Android does not prevent a user or
+ application with root permissions from modifying the operating system, kernel,
+ and any other application. In general, root has full access to all
+ applications and all application data. Users that change the permissions on an
+ Android device to grant root access to applications increase the security
+ exposure to malicious applications and potential application flaws. </p>
+<p> The ability to modify an Android device they own is important to developers
+ working with the Android platform. On many Android devices users have the
+ ability to unlock the bootloader in order to allow installation of an alternate
+ operating system. These alternate operating systems may allow an owner to gain
+ root access for purposes of debugging applications and system components or to
+ access features not presented to applications by Android APIs. </p>
+<p> On some devices, a person with physical control of a device and a USB cable is
+ able to install a new operating system that provides root privileges to the
+ user. To protect any existing user data from compromise the bootloader unlock
+ mechanism requires that the bootloader erase any existing user data as part of
+ the unlock step. Root access gained via exploiting a kernel bug or security
+ hole can bypass this protection. </p>
+<p> Encrypting data with a key stored on-device does not protect the application
+ data from root users. Applications can add a layer of data protection using
+ encryption with a key stored off-device, such as on a server or a user
+ password. This approach can provide temporary protection while the key is not
+ present, but at some point the key must be provided to the application and it
+ then becomes accessible to root users. </p>
+<p> A more robust approach to protecting data from root users is through the use of
+ hardware solutions. OEMs may choose to implement hardware solutions that limit
+ access to specific types of content such as DRM for video playback, or the
+ NFC-related trusted storage for Google wallet. </p>
+<p> In the case of a lost or stolen device, full filesystem encryption on Android
+ devices uses the device password to protect the encryption key, so modifying
+ the bootloader or operating system is not sufficient to access user data
+ without the user’s device password. </p>
+<h3>User Security Features</h3>
+<h4 id="filesystem-encryption">Filesystem Encryption</h4>
+<p>Android 3.0 and later provides full filesystem encryption, so all user data can
+ be encrypted in the kernel using the dmcrypt implementation of AES128 with CBC
+ and ESSIV:SHA256. The encryption key is protected by AES128 using a key
+ derived from the user password, preventing unauthorized access to stored data
+ without the user device password. To provide resistance against systematic
+ password guessing attacks (e.g. “rainbow tables” or brute force), the
+ password is combined with a random salt and hashed repeatedly with SHA1 using
+ the standard PBKDF2 algorithm prior to being used to decrypt the filesystem
+ key. To provide resistance against dictionary password guessing attacks,
+ Android provides password complexity rules that can be set by the device
+ administrator and enforced by the operating system. Filesystem encryption
+ requires the use of a user password, pattern-based screen lock is not supported.</p>
+<p>More details on implementation of filesystem encryption are available at <a
+href="/devices/tech/security/encryption/index.html">Encryption</a>.</p>
+<h3 id="password-protection">Password Protection</h3>
+<p>Android can be configured to verify a user-supplied password prior to providing
+ access to a device. In addition to preventing unauthorized use of the device,
+ this password protects the cryptographic key for full filesystem encryption.</p>
+<p>Use of a password and/or password complexity rules can be required by a device
+ administrator.</p>
+<h3 id="device-administration">Device Administration</h3>
+<p>Android 2.2 and later provide the Android Device Administration API, which
+ provides device administration features at the system level. For example, the
+ built-in Android Email application uses the APIs to improve Exchange support.
+ Through the Email application, Exchange administrators can enforce password
+ policies — including alphanumeric passwords or numeric PINs — across
+ devices. Administrators can also remotely wipe (that is, restore factory
+ defaults on) lost or stolen handsets.</p>
+<p>In addition to use in applications included with the Android system, these APIs
+ are available to third-party providers of Device Management solutions. Details
+ on the API are provided at <a
+href="https://developer.android.com/guide/topics/admin/device-admin.html">Device
+Administration</a>.</p>
diff --git a/src/devices/tech/security/overview/updates-resources.jd b/src/devices/tech/security/overview/updates-resources.jd
new file mode 100644
index 0000000..5fc3095
--- /dev/null
+++ b/src/devices/tech/security/overview/updates-resources.jd
@@ -0,0 +1,87 @@
+page.title= Security updates and resources
+@jd:body
+
+<!--
+ Copyright 2014 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc"></ol>
+ </div>
+</div>
+
+<h2 id="reporting-security-issues">Reporting Security Issues</h2>
+<p class="note"><strong>Note:</strong> The preferred way to report security
+issues is sending an email detailing the issue to security@android.com.</p>
+<p>Any developer, Android user, or security researcher can notify the Android
+security team of potential security issues. Your message can be encrypted
+using the Android security team PGP key <a href="https://developer.android.com/security_at_android_dot_com.txt">here</a>.</p>
+<p>Sending an email to security@android.com is preferable to using the
+public Android bug tracker. Bugs marked as security issues are not externally
+visible, but they may eventually be made visible. If you plan to submit a
+patch to resolve a security issue, please contact security@android.com and
+wait for a response before submitting the patch to AOSP.</p>
+
+<h2 id="android-updates">Android Updates</h2>
+<p>Android provides system updates for both security and feature related purposes.</p>
+<p>There are two ways to update the code on most Android devices: over-the-air
+ (OTA updates) or side-loaded updates. OTA updates can be rolled out over a
+ defined time period or be pushed to all devices at once, depending on how the
+ OEM and/or carrier would like to push the updates. Side-loaded updates can be
+ provided from a central location for users to download as a zip file to their
+ local desktop machine or directly to their handset. Once the update is copied
+ or downloaded to the SD card on the device, Android will recognize the update,
+ verify its integrity and authenticity, and automatically update the device.</p>
+<p>If a dangerous vulnerability is discovered internally or responsibly reported
+ to Google or the Android Open Source Project, the Android security team will
+ start the following process.</p>
+<ol>
+ <li>The Android team will notify companies who have signed NDAs regarding the
+ problem and begin discussing the solution.</li>
+ <li>The owners of code will begin the fix.</li>
+ <li>The Android team will fix Android-related security issues.</li>
+ <li>When a patch is available, the fix is provided to the NDA companies.</li>
+ <li>The Android team will publish the patch in the Android Open Source Project</li>
+ <li>OEM/carrier will push an update to customers.</li>
+</ol>
+<p>The NDA is required to ensure that the security issue does not become public
+ prior to availabilty of a fix and put users at risk. Many OHA members run their
+ own code on Android devices such as the bootloader, wifi drivers, and the
+ radio. Once the Android Security team is notified of a security issue in this
+ partner code, they will consult with OHA partners to quickly find a fix for the
+ problem at hand and similar problems. However, the OHA member who wrote the
+ faulty code is ultimately responsible for fixing the problem.</p>
+<p>If a dangerous vulnerability is not responsibly disclosed (e.g., if it is
+ posted to a public forum without warning), then Google and/or the Android Open
+ Source Project will work as quickly as possible to create a patch. The patch
+ will released to the public (and any partners) when the patch is tested and
+ ready for use.</p>
+<p>At Google I/O 2011, many of the largest OHA partners committed to providing
+ updates to devices for 18 months after initial shipment. This will provide
+ users with access to the most recent Android features, as well as security
+ updates.</p>
+<p>Any developer, Android user, or security researcher can notify the Android
+ security team of potential security issues by sending email to
+ security@android.com. If desired, communication can be encrypted using the
+ Android security team PGP key available here: <a href="https://developer.android.com/security_at_android_dot_com.txt">https://developer.android.com/security_at_android_dot_com.txt</a>.</p>
+<h2 id="other-resources">Other Resources</h2>
+<p>Information for Android application developers is here: <a href="https://developer.android.com">https://developer.android.com</a>.</p>
+<p>The Android Security team can be reached at <a href="mailto:security@android.com">security@android.com</a>.</p>
+<p>Security information exists throughout the Android Open Source and Developer
+ Sites. A good place to start is here: <a href="https://developer.android.com/guide/topics/security/security.html">https://developer.android.com/guide/topics/security/security.html</a>.</p>
+<p>A Security FAQ for developers is located here: <a href="https://developer.android.com/resources/faq/security.html">https://developer.android.com/resources/faq/security.html</a>.</p>
+<p>Security Best Practices for developers is located here: <a href="https://developer.android.com/guide/practices/security.html">https://developer.android.com/guide/practices/security.html</a>.</p>
+<p>A community resource for discussion about Android security exists here: <a href="https://groups.google.com/forum/?fromgroups#!forum/android-security-discuss">https://groups.google.com/forum/?fromgroups#!forum/android-security-discuss</a>.</p>
diff --git a/src/devices/tech/security/selinux/concepts.jd b/src/devices/tech/security/selinux/concepts.jd
index a0eb2cc..1958474 100644
--- a/src/devices/tech/security/selinux/concepts.jd
+++ b/src/devices/tech/security/selinux/concepts.jd
@@ -110,7 +110,7 @@
<p>The policy rules come in the form: allow <em>domains</em> <em>types</em>:<em>classes</em> <em>permissions</em>;, where:</p>
<ul>
- <li><em>Domain</em> - A label for the process or set of processes.
+ <li><em>Domain</em> - A label for the process or set of processes. Also called a domain type as it is just a type for a process.
<li><em>Type</em> - A label for the object (e.g. file, socket) or set of objects.
<li><em>Class</em> - The kind of object (e.g. file, socket) being accessed.
<li><em>Permission</em> - The operation (e.g. read, write) being performed.
@@ -119,23 +119,22 @@
<p>And so an example use of this would follow the structure:</p>
<code>allow appdomain app_data_file:file rw_file_perms;</code>
-<p>This says an application is allowed to read and write files labeled
+<p>This says that all application domains are allowed to read and write files labeled
app_data_file. Note that this rule relies upon macros defined in the
global_macros file, and other helpful macros can also be found in the te_macros
-file. Macros are provided for common groupings of classes, permissions and
+file, both of which can be found in the <a href="https://android.googlesource.com/platform/external/sepolicy/">external/sepolicy</a> directory in the AOSP source tree. Macros are provided for common groupings of classes, permissions and
rules, and should be used whenever possible to help reduce the likelihood of
-failures due to denials on related permissions. During compilation, those
-overrides are concatenated to the existing SELinux settings and into a single
-security policy. These overrides add to the base security policy rather than
-subtract from existing settings.</p>
+failures due to denials on related permissions.</p>
+
+<p>In addition to individually listing domains or types in a rule, one can also refer to a set of domains or types via an <em>attribute</em>. An attribute is simply a name for a set of domains or types. Each domain or type can be associated with any number of attributes. When a rule is written that specifies an attribute name, that name is automatically expanded to the list of domains or types associated with the attribute. For example, the <em>domain</em> attribute is associated with all process domains, and the <em>file_type</em> attribute is associated with all file types.</p>
<p>Use the syntax above to create avc rules that comprise the essence of an
SELinux policy. A rule takes the form:
<pre>
-<rule variant> <source_type> <target_type> : <class> <permission>
+<rule variant> <source_types> <target_types> : <classes> <permissions>
</pre>
-<p>The rule indicates what should happen when an object labeled with the <em>source_type </em>attempts an action corresponding to <em>permission </em>on an object of class <em>class </em>which has the <em>target_type </em>label. The most common example of one of these rules is an allow rule, e.g.:</p>
+<p>The rule indicates what should happen when a subject labeled with any of the <em>source_types</em> attempts an action corresponding to any of the <em>permissions</em> on an object with any of the class <em>classes</em> which has any of the <em>target_types</em> label. The most common example of one of these rules is an allow rule, e.g.:</p>
<pre>
allow domain null_device:chr_file { open };
@@ -143,32 +142,33 @@
<p>
-This rule allows a process with <em>source_type</em> of ‘domain’to take the action described by the <em>permission</em> ‘open’ on an object of <em>class</em> ‘chr_file’ that has the <em>target_type</em> label of ‘null_device.’ In practice, this rule may be extended to include other permissions: </p>
+This rule allows a process with any <em>domain</em> associated with the ‘domain’ attribute to take the action described by the <em>permission</em> ‘open’ on an object of <em>class</em> ‘chr_file’ (character device file) that has the <em>target_type</em> label of ‘null_device.’ In practice, this rule may be extended to include other permissions: </p>
<pre>
-allow domain null_device:chr_file { getattr open read ioctl lock append write};
+allow domain null_device:chr_file { getattr open read ioctl lock append write};
</pre>
-<p>When combined with the knowledge that ‘domain’ is a label for all processes and
-that null_device is the label for the ‘chr_file’ /dev/null, this rule basically
+<p>When combined with the knowledge that ‘domain’ is an attribute assigned to
+all process domains and
+that null_device is the label for the character device /dev/null, this rule basically
permits reading and writing to <code>/dev/null</code>.</p>
<p>A <em>domain</em> generally corresponds to a process and will have a label associated with it.</p>
-<p>For example, a typical Android app is running it its own process and has the
+<p>For example, a typical Android app is running in its own process and has the
label of untrusted_app that grants it certain restricted permissions.</p>
<p>Platform apps built into the system run under a separate label and are granted
-a distinct set of permissions. System apps that are part of the core Android
+a distinct set of permissions. System UID apps that are part of the core Android
system run under the system_app label for yet another set of privileges.</p>
-<p>These generic labels require further specification:</p>
+<p>Access to the following generic labels should never be directly allowed to domains; instead, a more specific type should be created for the object or objects:</p>
<ul>
<li> socket_device
<li> device
<li> block_device
<li> default_service
- <li> system_data_type
+ <li> system_data_file
<li> tmpfs
</ul>
diff --git a/src/devices/tech/security/selinux/customize.jd b/src/devices/tech/security/selinux/customize.jd
index 79ca5d6..63b3b56 100644
--- a/src/devices/tech/security/selinux/customize.jd
+++ b/src/devices/tech/security/selinux/customize.jd
@@ -72,9 +72,8 @@
<li>Put those policies in *.te files (the extension for SELinux policy source
files) within the <code>/device/manufacturer/device-name/sepolicy</code> directory and use
<code>BOARD_SEPOLICY</code> variables to include them in your build.
- <li>Make new domains permissive initially. In Android 4.4 and earlier, this is done
-using a permissive declaration. In later versions of Android, per-domain
-permissive mode is specified using the <code>permissive_or_unconfined()</code> macro.
+ <li>Make new domains permissive initially. This is done by
+using a permissive declaration in the domain's .te file.
<li>Analyze results and refine your domain definitions.
<li>Remove the permissive declaration when no further denials appear in userdebug
builds.
@@ -100,7 +99,7 @@
<p>First, note SELinux is based upon the <a href="https://www.gnu.org/software/m4/manual/index.html">M4</a> computer language and therefore supports a variety of macros to save time.</p>
-<p>In the following example, all domains are granted access to read or write to <code>/dev/null</code> and read from <code>/dev/0</code>.</p>
+<p>In the following example, all domains are granted access to read from or write to <code>/dev/null</code> and read from <code>/dev/zero</code>.</p>
<pre>
# Allow read / write access to /dev/null
@@ -127,7 +126,7 @@
<pre>
type dhcp, domain;
-permissive_or_unconfined(dhcp)
+permissive dhcp;
type dhcp_exec, exec_type, file_type;
type dhcp_data_file, file_type, data_file_type;
@@ -162,7 +161,7 @@
security policy (<code>domain</code>). From the previous statement examples, we know DHCP can read from and write
to <code>/dev/null.</code></p>
-<p>In the second line, DHCP is identified as an experimental domain (<code>permissive_or_unconfined</code>) with only minimal rules enforced.</p>
+<p>In the second line, DHCP is identified as a permissive domain.</p>
<p>In the <code>init_daemon_domain(dhcp)</code> line, the policy states DHCP is spawned from <code>init</code> and is allowed to communicate with it.</p>
@@ -181,10 +180,10 @@
<table>
<tr>
<td>
-<p><strong>Domain</strong></p>
+<p><strong>Class</strong></p>
</td>
<td>
-<p><strong>Capability</strong></p>
+<p><strong>Permission</strong></p>
</td>
</tr>
<tr>
diff --git a/src/devices/tech/security/selinux/implement.jd b/src/devices/tech/security/selinux/implement.jd
index 9e2e724..aa89303 100644
--- a/src/devices/tech/security/selinux/implement.jd
+++ b/src/devices/tech/security/selinux/implement.jd
@@ -31,7 +31,7 @@
is out of the scope of this document, but an understanding of how to write
policy rules is now essential when bringing up new Android devices. There is a
great deal of information available regarding SELinux already. See <a
-href="{@docRoot}devices/tech/security/se-linux.html#supporting_documentation">Supporting
+href="{@docRoot}devices/tech/security/selinux/index.html#supporting_documentation">Supporting
documentation</a> for suggested resources.</p>
<h2 id=summary_of_steps>Summary of steps</h2>
@@ -44,9 +44,9 @@
<li>Grant each service (process or daemon) started from <code>init</code> its own domain.
<li>Identify these services by:
<ul>
- <li>Reviewing the init file and finding all services.
- <li>Examining warnings in <code>dmesg</code>.
- <li>Searching (<code>grep</code>) through processes to see which run in the init domain.
+ <li>Reviewing the init.<device>.rc file and finding all services.
+ <li>Examining warnings of the form <em>init: Warning! Service name needs a SELinux domain defined; please fix!</em> in <code>dmesg</code> output.
+ <li>Checking <code>ps -Z | grep init</code> output to see which services are running in the init domain.
</ul>
<li>Label all new processes, drivers, sockets, etc.
All objects need to be labeled
@@ -76,16 +76,53 @@
<p>Here are the files you must create or edit in order to implement SELinux:</p>
<ul>
- <li><em>New SELinux policy source (*.te) files</em> - Located in the <root>/device/manufacturer/device-name/sepolicy directory. These files define domains and their labels. The new policy files get
+ <li><em>New SELinux policy source (*.te) files</em> - Located in the
+<root>/device/manufacturer/device-name/sepolicy directory. These files define
+domains and their labels. The new policy files get
concatenated with the existing policy files during compilation into a single
SELinux kernel policy file.
-<p class="caution"><strong>Important:</strong> Do not alter the app.te file provided by the Android Open Source Project.
+<p class="caution"><strong>Important:</strong> Do not alter the app.te file
+provided by the Android Open Source Project.
Doing so risks breaking all third-party applications.</p>
- <li><em>Updated BoardConfig.mk makefile</em> - Located in the <device-name> directory containing the sepolicy subdirectory. It must be updated to reference the sepolicy subdirectory once created if it
+ <li><em>Updated BoardConfig.mk makefile</em> - Located in the <device-name>
+directory containing the sepolicy subdirectory. It must be updated to reference
+the sepolicy subdirectory once created if it
wasn’t in initial implementation.
- <li><em>Updated *_contexts files</em> - Located in the sepolicy subdirectory. These label files and
-are managed in the userspace. As you create new policies, update these files to
-reference them. In order to apply new *_contexts, you must run <code>restorecon</code> on the file to be relabeled.
+ <li><em>file_contexts</em> - Located in the sepolicy subdirectory. This file
+assigns labels to files and is used by various userspace components. As you
+create new policies, create or update this file to
+assign new labels to files. In order to apply new file_contexts, you must
+rebuild the filesystem image or run <code>restorecon</code> on the file to be
+relabeled. On upgrades, changes to file_contexts are automatically applied to
+the system and userdata partitions as part of the upgrade. Changes can also be
+automatically applied on upgrade to other partitions by adding
+restorecon_recursive calls to your init.<em>board</em>.rc file after the
+partition has been mounted read-write.
+ <li><em>genfs_contexts</em> - Located in the sepolicy subdirectory. This file
+assigns labels to filesystems such as proc or vfat that do not support extended
+attributes. This configuration is loaded as part of the kernel policy but
+changes may not take effect for in-core inodes, requiring a reboot or
+unmounting and re-mounting the filesystem to fully apply the change. Specific
+labels may also be assigned to specific mounts such as vfat using the context=
+mount option.
+ <li><em>property_contexts</em> - Located in the sepolicy subdirectory. This
+file assigns labels to Android system properties to control what processes can
+set them. This configuration is read by the init process during startup and
+whenever the selinux.reload_policy property is set to 1.
+ <li><em>service_contexts</em> - Located in the sepolicy subdirectory. This
+file assigns labels to Android binder services to control what processes can
+add (register) and find (lookup) a binder reference for the service. This
+configuration is read by the servicemanager process during startup and whenever
+the selinux.reload_policy property is set to 1.
+ <li><em>seapp_contexts</em> - Located in the sepolicy subdirectory. This file
+assigns labels to app processes and /data/data directories. This configuration
+is read by the zygote process on each app launch and by installd during startup
+and whenever the selinux.reload_policy property is set to 1.
+ <li><em>mac_permissions.xml</em> - Located in the sepolicy subdirectory. This
+file assigns a seinfo tag to apps based on their signature and optionally their
+package name. The seinfo tag can then be used as a key in the seapp_contexts
+file to assign a specific label to all apps with that seinfo tag. This
+configuration is read by system_server during startup.
</ul>
<p>Then just update your BoardConfig.mk makefile - located in the directory
@@ -156,12 +193,20 @@
<li>Enable SELinux in the kernel:
<code>CONFIG_SECURITY_SELINUX=y</code>
<li>Change the kernel_cmdline parameter so that:<br/>
-<code>BOARD_KERNEL_CMDLINE := androidboot.selinux=permissive</code>
+<code>BOARD_KERNEL_CMDLINE := androidboot.selinux=permissive</code>.
+<br/>
+This is only for initial development of policy for the device. Once you have
+an initial bootstrap policy, remove this parameter so that your device is
+enforcing or it will fail CTS.
<li>Boot up the system in permissive and see what denials are encountered on boot:<br/>
-<code>su -c dmesg | grep denied > ~/t.tmp su -c dmesg | grep denied | audit2allow</code>
+On Ubuntu 14.04 or newer:
+<br/>
+<code>adb shell su -c dmesg | grep denied | audit2allow -p out/target/product/<em>board</em>/root/sepolicy</code>
+<br/>
+On Ubuntu 12.04:
+<code>adb shell su -c dmesg | grep denied | audit2allow</code>
<li>Evaluate the output. See <a href="validate.html">Validation</a> for instructions and tools.
- <li>Identify devices, and other new files that need labeling.Identify devices, and
-other new files that need labeling.
+ <li>Identify devices, and other new files that need labeling.
<li>Use existing or new labels for your objects.
Look at the *_contexts files to
see how things were previously labeled and use knowledge of the label meanings
@@ -171,14 +216,14 @@
<li>Identify domains/processes that should have their own security domains. A policy will likely need to be written for each of these from scratch. All services spawned from <code>init</code>, for instance, should have their own. The following commands help reveal those that remain running (but ALL services need such a treatment):<br/>
<code>$ adb shell su -c ps -Z | grep init</code><br/>
<code>$ adb shell su -c dmesg | grep 'avc: '</code>
- <li>Review init.<device>.rc to identify any which are without a type.
+ <li>Review init.<device>.rc to identify any which are without a type.
These should
be given domains EARLY in order to avoid adding rules to init or otherwise
confusing <code>init</code> accesses with ones that are in their own policy.
- <li>Set up <code>BOARD_CONFIG.mk</code> to use <code>BOARD_SEPOLICY_UNION</code> and <code>BOARD_SEPOLICY_DIRS</code>. See
-the README in /sepolicy for details on setting this up.
- <li> Examine the init.<device>.rc file and make sure every use of “mount”
-corresponds to a properly labeled filesystem.
+ <li>Set up <code>BOARD_CONFIG.mk</code> to use <code>BOARD_SEPOLICY_*</code> variables. See
+the README in external/sepolicy for details on setting this up.
+ <li> Examine the init.<device>.rc and fstab.<device> file and make sure every use of “mount”
+corresponds to a properly labeled filesystem or that a context= mount option is specified.
<li> Go through each denial and create SELinux policy to properly handle each. See
the examples within <a href="customize.html">Customization</a>.
</ol>
diff --git a/src/devices/tech/security/se-linux.jd b/src/devices/tech/security/selinux/index.jd
similarity index 94%
rename from src/devices/tech/security/se-linux.jd
rename to src/devices/tech/security/selinux/index.jd
index bbc6ed8..3553bc7 100644
--- a/src/devices/tech/security/se-linux.jd
+++ b/src/devices/tech/security/selinux/index.jd
@@ -85,16 +85,20 @@
<p><a href="https://www.codeproject.com/Articles/806904/Android-Security-Customization-with-SEAndroid">https://www.codeproject.com/Articles/806904/Android-Security-Customization-with-SEAndroid</a></p>
-<p><a href="https://www.nsa.gov/research/_files/publications/implementing_selinux.pdf">https://www.nsa.gov/research/_files/publications/implementing_selinux.pdf</a></p>
-
<p><a href="https://events.linuxfoundation.org/sites/events/files/slides/abs2014_seforandroid_smalley.pdf">https://events.linuxfoundation.org/sites/events/files/slides/abs2014_seforandroid_smalley.pdf</a></p>
<p><a href="https://www.internetsociety.org/sites/default/files/02_4.pdf">https://www.internetsociety.org/sites/default/files/02_4.pdf</a></p>
-<p><a href="https://www.gnu.org/software/m4/manual/index.html">https://www.gnu.org/software/m4/manual/index.html</a></p>
-
<p><a href="http://freecomputerbooks.com/books/The_SELinux_Notebook-4th_Edition.pdf">http://freecomputerbooks.com/books/The_SELinux_Notebook-4th_Edition.pdf</a></p>
+<p><a href="http://selinuxproject.org/page/ObjectClassesPerms">http://selinuxproject.org/page/ObjectClassesPerms</a></p>
+
+<p><a href="https://www.nsa.gov/research/_files/publications/implementing_selinux.pdf">https://www.nsa.gov/research/_files/publications/implementing_selinux.pdf</a></p>
+
+<p><a href="https://www.nsa.gov/research/_files/publications/selinux_configuring_policy.pdf">https://www.nsa.gov/research/_files/publications/selinux_configuring_policy.pdf</a></p>
+
+<p><a href="https://www.gnu.org/software/m4/manual/index.html">https://www.gnu.org/software/m4/manual/index.html</a></p>
+
<h2 id=help>Help</h2>
<p>Over time, Android intends to support common manufacturer additions in its
diff --git a/src/devices/tech/security/selinux/validate.jd b/src/devices/tech/security/selinux/validate.jd
index 2734665..34199f5 100644
--- a/src/devices/tech/security/selinux/validate.jd
+++ b/src/devices/tech/security/selinux/validate.jd
@@ -41,7 +41,7 @@
<p>Then check for errors. Errors are routed as event logs to dmesg and <code>logcat</code> and are viewable locally on the device. Manufacturers should examine the
SELinux output to dmesg on these devices and refine settings prior to public
release in permissive mode and eventual switch to enforcing mode. SELinux log
-messages contain "AVC" and so may easily be found with <code>grep</code>. It is
+messages contain "avc:" and so may easily be found with <code>grep</code>. It is
possible to capture the ongoing denial logs by running <code>cat /proc/kmsg</code>
or to capture denial logs from the previous boot by running cat <code>/proc/last_kmsg</code>.</p>
@@ -53,7 +53,7 @@
enforcing mode and why. Here is an example:</p>
<pre>
-denied { connectto } for pid=2671 comm="ping" path="/dev/socket/dnsproxyd"
+avc: denied { connectto } for pid=2671 comm="ping" path="/dev/socket/dnsproxyd"
scontext=u:r:shell:s0 tcontext=u:r:netd:s0 tclass=unix_stream_socket
</pre>
@@ -121,12 +121,18 @@
$ sudo apt-get install policycoreutils
</pre>
-<p>To use it:</p>
+<p>To use it on Ubuntu 12.04, run:</p>
<pre>
$ adb shell su -c dmesg | audit2allow
</pre>
+<p>On Ubuntu 14.04 and newer, audit2allow requires you to specify the Android policy
+using the -p option, e.g.
+<pre>
+$ adb shell su -c dmesg | audit2allow -p out/target/product/<device>/root/sepolicy
+</pre>
+
<p>Nevertheless, care must be taken to examine each potential addition for
overreaching permissions. For example, feeding audit2allow the <code>rmt_storage</code> denial shown earlier results in the following suggested SELinux policy
statement:</p>
diff --git a/src/devices/tech/security/dm-verity.jd b/src/devices/tech/security/verifiedboot/dm-verity.jd
similarity index 63%
rename from src/devices/tech/security/dm-verity.jd
rename to src/devices/tech/security/verifiedboot/dm-verity.jd
index e017299..f86c1b2 100644
--- a/src/devices/tech/security/dm-verity.jd
+++ b/src/devices/tech/security/verifiedboot/dm-verity.jd
@@ -1,8 +1,8 @@
-page.title=dm-verity on boot
+page.title=Implementing dm-verity
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -24,35 +24,6 @@
</div>
</div>
-<h2 id="introduction">Introduction</h2>
-
-<p>Android 4.4 supports verified boot through the optional device-mapper-verity
-(dm-verity) kernel feature, which provides transparent integrity checking of
-block devices. dm-verity helps prevent persistent rootkits that can hold onto
-root privileges and compromise devices. This experimental feature helps Android
-users be sure when booting a device it is in the same state as when it was last
-used.</p>
-
-<p>Clever malware with root privileges can hide from detection programs and
-otherwise mask themselves. The rooting software can do this because it is often
-more privileged than the detectors, enabling the software to "lie" to to the
-detection programs.</p>
-
-<p>The dm-verity feature lets you look at a block device, the underlying storage
-layer of the file system, and determine if it matches its expected
-configuration. It does this using a cryptographic hash tree. For every block
-(typically 4k), there is a SHA256 hash.</p>
-
-<p>And since the hash values are stored in a tree of pages, only the top-level
-"root" hash must be trusted to verify the rest of the tree. The ability to
-modify any of the blocks would be equivalent to breaking the cryptographic hash.
-See the following diagram for a depiction of this structure.</p>
-
-<p><img src="images/dm-verity-hash-table.png" alt="dm-verity-hash-table"/><br/>
-A public key is included on the boot partition, which must be verified
-externally by the OEM. That key is used to verify the signature for that hash
-and confirm the device's system partition is protected and unchanged.</p>
-
<h2 id="operation">Operation</h2>
<p>dm-verity protection lives in the kernel. So if rooting software compromises the
@@ -63,9 +34,9 @@
<p>Manufacturers use that key to verify the signature on the first-level
bootloader, which in turn verifies the signature on subsequent levels, the
application bootloader and eventually the kernel. Each manufacturer wishing to
-take advantage of verified boot should have a method for verifying the integrity
-of the kernel. Assuming the kernel has been verified, the kernel can look at a
-block device and verify it as it is mounted.</p>
+take advantage of <a href="verified-boot.html">verified boot</a> should have a
+method for verifying the integrity of the kernel. Assuming the kernel has been
+verified, the kernel can look at a block device and verify it as it is mounted.</p>
<p>One way of verifying a block device is to directly hash its contents and compare
them to a stored value. However, attempting to verify an entire block device can
@@ -86,58 +57,17 @@
those results are not required to the application's primary function. However,
if the application cannot continue without the data, it will fail.</p>
-<h2 id="prerequisites">Prerequisites</h2>
-
-<h3 id="block-otas">Switching to block-oriented OTAs</h3>
-
-<p>To enable dm-verity on your devices, you <strong>must</strong> move from file-based "over the
-air" (OTA) updates to block-oriented OTAs. This is needed because during OTA,
-Android attempts to change the contents of the system partition at the
-filesystem layer.<br/>
-And since OTA works on a file-by-file basis, it is not guaranteed to write files
-in a consistent order, have a consistent last modified time or superblock, or
-even place the blocks in the same location on the block device. For this reason,
-<em>file-based OTAs will fail on a dm-verity-enabled device.</em><strong>The device will
-not boot after OTA.</strong></p>
-
-<p>So you must use block-oriented OTAs. With block-oriented OTAs, you serve the
-device the difference between the two block images rather than the two sets of
-files. Many manufacturers have already moved to block-oriented OTAs to make them
-more reproducible and predictable.</p>
-
-<p>A block-oriented OTA checks a device build against the corresponding build
-server at the block device level, below the filesystem. This can be done in a
-couple of different ways, each with their own benefits and drawbacks:</p>
-
-<ul>
-<li><em>Copy the full system image to the device</em> - This is simple and makes patch
-generation easy. But it also makes the application of those patches quite
-expensive as the resulting images are large.</li>
-<li><em>Employ a binary differ</em> - These tools, such as <code>bsdiff</code>, simplify patch
-application as images are much smaller. But these tools tend to be memory
-intensive and therefore expensive in generating the patches themselves.</li>
-</ul>
-
-<h3 id="config-dm-verity">Configuring dm-verity</h3>
-
-<p>After switching to block-oriented OTAs, incorporate the latest Android kernel or
-use a stock upstream kernel and enable dm-verity support by including the
-relevant configuration option:<br/>
-<code>CONFIG_DM_VERITY
-</code></p>
-<p>When using the Android kernel, dm-verity is turned on when the kernel is built.</p>
-
<h2 id="implementation">Implementation</h2>
<h3 id="summary">Summary</h3>
<ol>
<li>Generate an ext4 system image.</li>
-<li><a href="#heading=h.wiiuowe37q8h">Generate a hash tree</a> for that image.</li>
-<li><a href="#heading=h.cw7mesnrerea">Build a dm-verity table</a> for that hash tree.</li>
-<li><a href="#heading=h.maq6jfk4vx92">Sign that dm-verity table</a> to produce a table
+<li><a href="#hash-tree">Generate a hash tree</a> for that image.</li>
+<li><a href="#mapping-table">Build a dm-verity table</a> for that hash tree.</li>
+<li><a href="#signing">Sign that dm-verity table</a> to produce a table
signature.</li>
-<li><a href="#heading=h.tkceh5wnx7z2">Bundle the table signature</a> and dm-verity table
+<li><a href="#metadata">Bundle the table signature</a> and dm-verity table
into verity metadata.</li>
<li>Concatenate the system image, the verity metadata, and the hash tree.</li>
</ol>
@@ -148,7 +78,7 @@
<h3 id="hash-tree">Generating the hash tree</h3>
-<p>As described in the <a href="#heading=h.q4z3ftrhbehy">Introduction</a>, the hash tree is
+<p>As described in the <a href="#introduction">Introduction</a>, the hash tree is
integral to dm-verity. The
<a href="https://code.google.com/p/cryptsetup/wiki/DMVerity">cryptsetup</a> tool will
generate a hash tree for you. Alternatively, a compatible one is defined here:</p>
@@ -303,15 +233,3 @@
<td>0</td>
</tr>
</table>
-
-<p>For additional assistance, contact security@android.com.</p>
-
-<h2 id="supporting-docs">Supporting documentation</h2>
-
-<p><a href="https://code.google.com/p/cryptsetup/wiki/DMVerity">cryptsetup - dm-verity: device-mapper block integrity checking
-target</a><br/>
-<a href="http://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot">The Chromium Projects - Verified
-Boot</a><br/>
-<a
-href="http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/device-mapper/verity.txt">Linux Kernel Documentation:
-verity.txt</a></p>
diff --git a/src/devices/tech/security/verifiedboot/index.jd b/src/devices/tech/security/verifiedboot/index.jd
new file mode 100644
index 0000000..9146f1a
--- /dev/null
+++ b/src/devices/tech/security/verifiedboot/index.jd
@@ -0,0 +1,93 @@
+page.title=Verified Boot
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<h2 id="introduction">Introduction</h2>
+
+<p>Android 4.4 and later supports verified boot through the optional device-mapper-verity
+(dm-verity) kernel feature, which provides transparent integrity checking of
+block devices. dm-verity helps prevent persistent rootkits that can hold onto
+root privileges and compromise devices. This experimental feature helps Android
+users be sure when booting a device it is in the same state as when it was last
+used.</p>
+
+<p>Clever malware with root privileges can hide from detection programs and
+otherwise mask themselves. The rooting software can do this because it is often
+more privileged than the detectors, enabling the software to "lie" to to the
+detection programs.</p>
+
+<p>The dm-verity feature lets you look at a block device, the underlying storage
+layer of the file system, and determine if it matches its expected
+configuration. It does this using a cryptographic hash tree. For every block
+(typically 4k), there is a SHA256 hash.</p>
+
+<p>And since the hash values are stored in a tree of pages, only the top-level
+"root" hash must be trusted to verify the rest of the tree. The ability to
+modify any of the blocks would be equivalent to breaking the cryptographic hash.
+See the following diagram for a depiction of this structure.</p>
+
+<img src="../images/dm-verity-hash-table.png" alt="dm-verity-hash-table" id="figure1"/>
+<p class="img-caption">
+ <strong>Figure 1.</strong> dm-verity hash table
+</p>
+
+<p>
+A public key is included on the boot partition, which must be verified
+externally by the OEM. That key is used to verify the signature for that hash
+and confirm the device's system partition is protected and unchanged.</p>
+
+<h2 id="prerequisites">Prerequisites</h2>
+
+<h3 id="verified-boot">Establishing a verified boot flow</h3>
+<p>To greatly reduce the risk of compromise, verify the kernel using a key
+burned into the device. For details, see <a href="verified-boot.html">Verified boot</a>.</p>
+
+<h3 id="block-otas">Switching to block-oriented OTAs</h3>
+<p>To enable dm-verity for a device, you must use block-based over-the-air
+(OTA) updates to ensure all devices use the same system partition. For details,
+see <a href="{@docRoot}devices/tech/ota/block.html">Block-Based OTAs</a>.</p>
+
+<h3 id="config-dm-verity">Configuring dm-verity</h3>
+
+<p>After switching to block-oriented OTAs, incorporate the latest Android kernel or
+use a stock upstream kernel and enable dm-verity support by including the
+relevant configuration option:<br/>
+<code>CONFIG_DM_VERITY
+</code></p>
+<p>When using the Android kernel, dm-verity is turned on when the kernel is built. For details, see <a href="dm-verity.html">Implementing dm-verity</a>.</p>
+
+<h2 id="supporting-docs">Supporting documentation</h2>
+<p><a href="verified-boot.html">Verifying Boot</a><br/>
+<a href="{@docRoot}devices/tech/ota/block.html">Block-Based OTA</a><br/>
+<a href="dm-verity.html">Implementing dm-verity</a><br/>
+<a href="https://code.google.com/p/cryptsetup/wiki/DMVerity">cryptsetup - dm-verity: device-mapper block integrity checking
+target</a><br/>
+<a href="http://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot">The Chromium Projects - Verified
+Boot</a><br/>
+<a
+href="http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/device-mapper/verity.txt">Linux Kernel Documentation:
+verity.txt</a></p>
+
+<p>For additional assistance, contact <a href="mailto:security@android.com">security@android.com</a>.</p>
diff --git a/src/devices/tech/security/verifiedboot/verified-boot.jd b/src/devices/tech/security/verifiedboot/verified-boot.jd
new file mode 100644
index 0000000..c96d930
--- /dev/null
+++ b/src/devices/tech/security/verifiedboot/verified-boot.jd
@@ -0,0 +1,630 @@
+page.title=Verifying Boot
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<h2 id=objective>Objective</h2>
+<p>Verified boot guarantees the integrity of the device software starting from a
+hardware root of trust up to the system partition. During boot, each stage
+verifies the integrity and authenticity of the next stage before executing it.</p>
+
+<p>This capability can be used to warn users of unexpected changes to the
+software when they acquire a used device, for example. It will also provide an
+additional signal of device integrity for remote attestation, and together with
+encryption and Trusted Execution Environment (TEE) root of trust binding, adds
+another layer of protection for user data against malicious system software.</p>
+
+<p>Note that if verification fails at any stage, the user must be visibly
+notified and always be given an option to continue using the device at
+their own discretion.</p>
+
+<h2 id=glossary>Glossary</h2>
+
+<table>
+ <tr>
+ <td>
+<p><strong>Term</strong></p>
+</td>
+ <td>
+<p><strong>Definition</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Boot state</p>
+</td>
+ <td>
+<p>The boot state of the device describes the level of protection provided to the
+end user if the device boots. Boot states are GREEN, YELLOW, ORANGE, and RED.</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Device state</p>
+</td>
+ <td>
+<p>The device state indicates how freely software can be flashed to the device.
+Device states are LOCKED, UNLOCKED, or VERIFIED.</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>dm-verity</p>
+</td>
+ <td>
+<p>Linux kernel driver for verifying the integrity of a partition at runtime using
+a hash tree and signed metadata.</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Keystore</p>
+</td>
+ <td>
+<p>A keystore is a signed collection of public keys.</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>OEM key</p>
+</td>
+ <td>
+<p>The OEM key is a fixed, tamper-protected key available to the bootloader that
+must be used to verify the boot image.</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>User provided keystore</p>
+</td>
+ <td>
+<p>The user keystore is a keystore flashed to the device via <code>fastboot
+flash keystore <path></code>.</p>
+</td>
+ </tr>
+</table>
+
+<h2 id=overview>Overview</h2>
+
+<p>In addition to device state - which already exists in devices and controls
+whether the bootloader allows new software to be flashed - we introduce the
+concept of boot state that indicates the state of device integrity. We also
+add a third device state, which allows developers for example, to flash the
+software more frequently without a data wipe while still benefiting from
+verification.</p>
+
+<h3 id=verification_keys>Verification keys</h3>
+
+<p>Bootloader integrity must be verified using a hardware root of trust. For
+verifying boot and recovery images, the bootloader must have a fixed OEM key
+available to it. It must always attempt to verify the boot image using the OEM
+key and only try other possible keys if this verification fails.</p>
+
+<p>It must be possible for the user to flash alternative image verification keys
+to the device, and the bootloader must try verification using these keys if
+verification using the OEM key fails. However, using an image signed with the
+user-provided keystore must result in a notification to be shown, as described
+below.</p>
+
+<h3 id=boot_state>Boot state</h3>
+
+<p>A verified device will ultimately boot into one of four states during each boot
+attempt:</p>
+
+<ul>
+ <li> GREEN, indicating a full chain of trust extending from the bootloader to the
+system partition, including the bootloader, boot partition, and system
+partition.
+</ul>
+
+<ul>
+ <li> YELLOW, indicating a chain of trust starting from a user-provided keystore
+and extending up. To enable users to acquire trust in their keystore,
+bootloaders are required to display a partial hash of the verifying keystore
+during boot.
+</ul>
+
+<ul>
+ <li> ORANGE, indicating a device may be freely modified. Device integrity is
+left to the user to verify out-of-band.
+</ul>
+
+<ul>
+ <li> RED, indicating the device has failed verification. This must display a
+warning to the user before allowing the boot process to continue.
+</ul>
+
+<p>The recovery partition must also be verified and should be verified in the
+exact same way.</p>
+
+<img src="../images/verified_boot.png" alt="Verified boot flow" id="figure1" />
+<p class="img-caption"><strong>Figure 1.</strong> Verified boot flow</p>
+
+<h3 id=device_state>Device state</h3>
+
+<p>The device is required to be in one of three states at all times:</p>
+
+<ol>
+ <li>LOCKED, indicating the device cannot currently be flashed. In the image
+above, a LOCKED device must boot into the GREEN state, YELLOW state, or RED
+state during any attempted boot. It must not be possible to alter the user
+keystore in the LOCKED state.
+
+ <li>VERIFIED, indicating someone in physical control of the device may perform
+limited actions intended to change the state of the device but may not break
+its current chain of trust. In the image above, a VERIFIED device must boot
+into the GREEN state, YELLOW state, or RED state during each attempted boot. It
+must not be possible to alter the user keystore in the VERIFIED state. It must
+be possible to:
+ <ol>
+ <li> Flash the following partitions:
+ <ol>
+ <li> bootloader
+ <li> boot partition
+ <li> system partition
+ <li> vendor partition
+ <li> recovery partition
+ </ol>
+ <li> Erase the following partitions:
+ <ol>
+ <li> userdata
+ <li> cache
+ </ol>
+ </ol>
+
+<p>Boot and recovery image signatures may be verified during the flashing process,
+and the bootloader may reject images that do not validate against the OEM key
+or the user-provided keystore at this point. However, signatures must also be
+verified again at every boot.
+
+ <li>UNLOCKED, indicating the device may be flashed freely and is not intended
+to be verified.
+</ol>
+
+<h2 id=detailed_design>Detailed design</h2>
+
+<p>Achieving full chain of trust requires support from both the bootloader and the
+software on the boot partition, specifically <code>init</code>, which is responsible for
+mounting additional partitions. Verification metadata must also be appended to the
+system partition and any additional partitions whose integrity should be
+verified.</p>
+
+<h3 id=bootloader_requirements>Bootloader requirements</h3>
+
+<p>The bootloader is the guardian of the device state, manages the user-provided
+keystore, and is responsible for initializing the TEE and binding its root of
+trust.</p>
+
+<p>Most importantly, the bootloader must verify the integrity of the boot and/or
+recovery partition before moving execution to the kernel and display the
+warnings or notifications in the section <a href="#boot_state">Boot state</a>.</p>
+
+<h4 id=changing_device_state><strong>Changing device state</strong></h4>
+
+<p>State changes are performed using the <code>fastboot flashing [unlock |
+verified | lock]</code> command. And to protect user data, <strong>all</strong>
+state transitions require a data wipe. Note the user must be asked for
+confirmation before data is deleted.</p>
+
+<img src="../images/device_states.png" alt="Changing device states" id="figure2" />
+<p class="img-caption"><strong>Figure 2.</strong> Changing device states</p>
+
+<ol>
+ <li>The UNLOCKED to LOCKED transition is anticipated when a user buys a used
+development device. As a result of locking the device, the user should have
+confidence that it is in a state produced by the OEM.
+
+ <li>The LOCKED to UNLOCKED transition is expected in the case where a developer
+wishes to disable verification on the device.
+
+ <li>The LOCKED to VERIFIED transition is expected in the case where a developer
+wishes to do development on the device and doesn’t want to wipe data frequently.
+
+ <li>The VERIFIED to LOCKED transition is idempotent with the above.
+
+ <li>The UNLOCKED to VERIFIED transition is anticipated when a user wishes to put a
+development device in a more secure state but may not want to prevent
+themselves from flashing new system images.
+
+ <li> The VERIFIED to UNLOCKED transition is idempotent with the above.
+</ol>
+
+<p>Requirements for <code>fastboot</code> commands that alter device state are listed in the table below:</p>
+<table>
+ <tr>
+ <td>
+<p><strong><code>fastboot</code> command</strong></p>
+</td>
+ <td>
+<p><strong>Requirements</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<code>
+flashing lock</code></td>
+ <td>
+<ul>
+ <li>Wipe data after asking the user for confirmation
+ <li>Clear a write-protected bit indicating the device is unlocked
+ <li>Clear a write-protected bit indicating the device is verified
+</ul>
+</td>
+ </tr>
+ <tr>
+ <td>
+<code>
+flashing unlock</code></td>
+ <td>
+<ul>
+ <li>Wipe data after asking the user for confirmation
+ <li>Set a write-protected bit indicating the device is unlocked
+ <li>Clear a write-protected bit indicating the device is verified
+</ul>
+</td>
+ </tr>
+ <tr>
+ <td>
+<code>
+flashing verified</code></td>
+ <td>
+<ul>
+ <li>Wipe data after asking the user for confirmation
+ <li>Clear a write-protected bit indicating the device is unlocked
+ <li>Set a write-protected bit indicating the device is verified
+</ul>
+</td>
+ </tr>
+</table>
+
+<p>When altering partition contents, the bootloader must check the bits set by
+the above commands as described in the following table:</p>
+<table>
+ <tr>
+ <td>
+<p><strong><code>fastboot</code> command</strong></p>
+</td>
+ <td>
+<p><strong>Requirements</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<code>
+flash <partition></code></td>
+ <td>
+<ul>
+ <li>If the bit set by <code>flashing unlock</code> is set, flash the partition as normal
+ <li>If this bit is not set, check the bit set by <code>flashing verified</code>
+ <ul>
+ <li>If this bit is not set, exit with an error
+ <li>If this bit is set and <partition> is on the list provided in
+ the section <a href="#device_state">Device state</a>, flash the partition as normal.
+ </ul>
+</ul>
+ </td>
+ </tr>
+</table>
+
+<p>The same checks should be performed for any <code>fastboot</code> command that can be used to change the contents of partitions.</p>
+
+<h4 id=managing_user_provided_keystore><strong>Managing user-provided keystore</strong></h4>
+
+<p>Users can flash their own verification keys to the device, which must be
+used to verify the integrity of boot and recovery images if verification
+against the OEM key fails. This allows a developer to change the system
+software frequently, for example, while still keeping verified boot enabled.</p>
+
+<p>The bootloader is responsible for maintaining the integrity of the user
+keystore. It must not be possible to change the contents of the keystore unless
+the device is UNLOCKED. When the user flashes a new keystore to the device, the
+bootloader must sign it using the TEE and store the signed keystore. Before
+using keys from the keystore, the bootloader must use the TEE to verify the
+signature.</p>
+
+<p>Requirements for <code>fastboot</code> commands used to manage the user-provided keystore are listed in the table
+below:</p>
+<table>
+ <tr>
+ <td>
+<p><strong><code>fastboot</code> command</strong></p>
+</td>
+ <td>
+<p>Requirements</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<code>
+flash keystore <filename></code></td>
+ <td>
+<ul>
+ <li>Check the bit set by <code>flashing unlock</code>; if not set, exit with an error
+ <li>Validate the given keystore against the format provided in section <a href="#keystore_format">Keystore format</a>
+ <li>Pass the keystore to the TEE for signing
+ <li>Write the signed keystore to the write-protected user keystore storage
+ area (location to be determined by the OEM)
+</ul>
+</td>
+ </tr>
+ <tr>
+ <td>
+<code>
+erase keystore</code></td>
+ <td>
+<ul>
+ <li>Check the bit set by <code>flashing unlock</code>; if not set, exit with an error
+ <li>Erase the keystore stored in the write-protected user keystore storage area
+</ul>
+ </td>
+ </tr>
+</table>
+
+<h4 id=binding_tee_root_of_trust><strong>Binding TEE root of trust</strong></h4>
+
+<p>After the bootloader has initialized the TEE and performed boot image
+verification steps, it must pass the following information to the TEE Keymaster
+as the root of trust:</p>
+
+<ol>
+ <li>The public key that was used to sign the boot image
+ <li>The current device state (LOCKED, VERIFIED, or UNLOCKED)
+</ol>
+
+<p>This changes the keys derived by the TEE. For disk encryption, for example,
+this prevents user data from being decrypted when the device is booted using a
+potentially untrusted image signed with a different key.</p>
+
+<p class="note"><strong>Note:</strong> This means if the system software or the
+device state changes, encrypted user data will no longer be accessible as the
+TEE will attempt to use a different key to decrypt the data.</p>
+
+<h4 id=booting_into_recovery><strong>Booting into recovery</strong></h4>
+
+<p>The recovery image should be verified in exactly the same manner as the boot
+image.</p>
+
+<h3 id=boot_partition>Boot partition</h3>
+
+<p>Once execution has moved to the boot and/or recovery image, <code>init</code> is responsible
+for setting up verification for further partitions. Due to its large size, the
+system partition cannot be verified similarly to previous parts but must be
+verified in real time as it’s being accessed by using the dm-verity kernel
+driver.</p>
+
+<p>When <code>fs_mgr</code> flags in the device’s <code>fstab</code> indicate a partition should be
+verified, <code>init</code> will verify the signed verity metadata appended to the partition
+before mounting it and set up the dm-verity device for the partition.</p>
+
+<h4 id=managing_dm-verity><strong>Managing dm-verity</strong></h4>
+
+<p>By default, dm-verity operates in verifying mode and verifies each block read
+from the device against a hash tree passed to it by <code>init</code> during set up. If it
+comes across a block that fails to verify, it returns an I/O error and makes
+the block with unexpected contents inaccessible to user space. Depending on
+which block is corrupted, this may cause some of the programs that reside on
+the partition to malfunction.</p>
+
+<p>Using a persistent flag, dm-verity can also be configured to function in
+logging mode. This flag is read by <code>init</code> when setting up dm-verity. And if the
+mode flag is set to logging or verity metadata cannot be verified, a warning
+must be displayed to the user, similar to the warning the bootloader shows
+before booting into RED state.</p>
+
+<img src="../images/dm-verity_mgmt.png" alt="dm-verity management" id="figure3" />
+<p class="img-caption"><strong>Figure 3.</strong> dm-verity management</p>
+
+<h4 id=recovering_from_dm-verity_errors><strong>Recovering from dm-verity errors</strong></h4>
+
+<p>Since the system partition is by far larger than the boot partition, the
+probability of verification errors is also higher. Specifically, there is a
+larger probability of unintentional disk corruption, which will cause a
+verification failure and can potentially make an otherwise functional device
+unusable if a critical block in the partition can no longer be accessed.</p>
+
+<p>It’s generally not possible to distinguish disk corruption from malicious
+changes, so any change to the system partition must result in the user being
+notified, and no unverified data must leak to user space until a warning has
+been shown. However, we must also assume most verification failures are
+not the result of malicious behavior; so the user must also have an option to
+continue using the device without verification.</p>
+
+<p>If dm-verity is in verifying mode and a block of a partition fails to verify,
+it will send a <code>uevent</code> to notify user space of the error. This event must be
+handled by software in the boot partition as potentially any program residing
+on the verified partition may not function anymore. When the event is received,
+the persistent dm-verity state must be updated to set the mode flag to logging
+mode, and the device must be rebooted. When the device restarts,
+<code>init</code> will warn the user of changes to the partition before mounting it.</p>
+
+<h3 id=verified_partition>Verified partition</h3>
+
+<p>In a verified device, the system partition must always be verified. But any
+other read-only partition can also be set to be verified, as well. Specifically,
+any read-only partition that contains executable code must be verified on a
+verified device. This include the vendor partition, if one exists, for example.</p>
+
+<p>In order for a partition to be verified, signed verity metadata must be
+appended to it. The metadata consists of a hash tree of the partition contents
+and a verity table containing signed parameters and the root of the hash tree.
+If this information is missing or invalid when <code>init</code> attempts to
+mount the device, the user must be warned.</p>
+
+<h2 id=implementation_details>Implementation details</h2>
+
+<h3 id=key_types_and_sizes>Key types and sizes</h3>
+
+<p>The OEM key is recommended to be an RSA key with a modulus of 2048 bits or
+higher and a public exponent of 65537 (F4). The OEM key is required to be of
+equivalent or greater strength than such a key.</p>
+
+<h3 id=signature_format>Signature format</h3>
+
+
+<p>The signature on an Android verifiable boot image is an ASN.1 DER-encoded
+message, which can be parsed with a decoder similar to the one found at: <a
+href="https://android.googlesource.com/platform/bootable/recovery/+/f4a6ab27b335b69fbc419a9c1ef263004b561265/asn1_decoder.cpp">platform/bootable/recovery/asn1_decoder.cpp</a><br/>
+The message format itself is as follows:</p>
+
+<pre>
+AndroidVerifiedBootSignature DEFINITIONS ::=
+ BEGIN
+ FormatVersion ::= INTEGER
+ Certificate ::= Certificate OPTIONAL
+ AlgorithmIdentifier ::= SEQUENCE {
+ algorithm OBJECT IDENTIFIER,
+ parameters ANY DEFINED BY algorithm OPTIONAL
+ }
+ AuthenticatedAttributes ::= SEQUENCE {
+ target CHARACTER STRING,
+ length INTEGER
+ }
+
+ Signature ::= OCTET STRING
+ END
+</pre>
+
+<p>The <code>Certificate</code> field is the full X.509 certificate containing
+the public key used for signing, as defined by <a
+href="http://tools.ietf.org/html/rfc5280#section-4.1.1.2">RFC5280</a> section
+4.1. The bootloader must ignore this field and must NOT use the key
+specified in the certificate to verify the signature. Signatures must always be
+verified against the OEM key or the user-provided keystore only.</p>
+
+<p>The remaining structure is similar to that defined by <a
+href="http://tools.ietf.org/html/rfc5280#section-4.1.1.2">RFC5280</a> sections
+4.1.1.2 and 4.1.1.3 with the exception of the
+<code>AuthenticatedAttributes</code> field. This field contains the length of
+the image to be verified as an integer and the partition where the image can
+be found (boot, recovery, etc.).</p>
+
+<h3 id=signing_and_verifying_an_image>Signing and verifying an image</h3>
+
+<p>To produce a signed image:</p>
+<ol>
+ <li>Generate the unsigned image.
+ <li>0-pad the image to the next page size boundary (omit this step if already
+aligned).
+ <li>Populate the fields of the <code>AuthenticatedAttributes</code> section above based on the padded image and desired target partition.
+ <li>Append the <code>AuthenticatedAttributes</code> structure above to the image.
+ <li>Sign the image.
+</ol>
+
+<p>To verify the image:</p>
+<ol>
+ <li>Determine the size of the image to be loaded including padding (eg, by reading
+a header).
+ <li>Read the signature located at the offset above.
+ <li>Validate the contents of the <code>AuthenticatedAttributes</code> field.
+If these values do not validate, treat it as a signature validation error.
+ <li>Verify the image and <code>AuthenticatedAttributes</code> sections.
+</ol>
+
+<h3 id=keystore_format>Keystore format</h3>
+
+<p>The Android verified boot keystore format is an ASN.1 DER-encoded document. Its
+ specification follows:</p>
+
+<pre>
+AndroidVerifiedBootKeystore DEFINITIONS ::=
+ BEGIN
+ FormatVersion ::= INTEGER
+ KeyBag ::= SEQUENCE {
+ Key ::= SEQUENCE {
+ AlgorithmIdentifier ::= SEQUENCE {
+ algorithm OBJECT IDENTIFIER,
+ parameters ANY DEFINED BY algorithm
+ OPTIONAL
+ }
+ KeyMaterial ::= RSAPublicKey
+ }
+ }
+ Signature ::= AndroidVerifiedBootSignature OPTIONAL
+ END
+</pre>
+
+<p>Where <code>RSAPublicKey</code>, <code>AlgorithmIdentifier</code>, and
+parameters are as specified in <a
+href="http://tools.ietf.org/html/rfc3279#section-2.3.1">RFC3279</a>. Other key
+types specified in RFC3279 section 2.3 may optionally be supported,
+in which case the appropriate type for <code>Key</code> must be used.</p>
+
+<h3 id=keystore_location>Keystore location</h3>
+
+<p>The location of the keystore is not specified here, but that location must be
+known to the bootloader and both readable and writable by it. Reading should
+happen as per the above; writing a new keystore should be accomplished through
+<code>fastboot flash keystore <path></code>. Sufficient storage must be
+provided for at least one key, with storage for additional keys recommended.</p>
+
+<h3 id=user_experience>User experience</h3>
+
+<p>A user in the GREEN boot state should see no additional user interaction besides that
+required by normal device boot. In other boot states, the user should see a
+warning for at least five seconds. Should the user interact with the device during
+this time, the warning should remain visible until the user agrees to continue.</p>
+
+<p>Sample user interaction screens for other states are shown in the following table:</p>
+<table>
+ <tr>
+ <td>
+<p><strong>Device state</strong></p>
+</td>
+ <td>
+<p><strong>Sample UX</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>YELLOW (before and after user interaction)</p>
+</td>
+ <td>
+<img src="../images/boot_yellow1.png" alt="Yellow device state 1" id="figure4" />
+<p class="img-caption"><strong>Figure 4.</strong> Yellow state example 1 UI</p>
+</td>
+ <td>
+<img src="../images/boot_yellow2.png" alt="Yellow device state 2" id="figure5" />
+<p class="img-caption"><strong>Figure 5.</strong> Yellow state example 2 UI</p>
+</td>
+
+ </tr>
+ <tr>
+ <td>
+<p>ORANGE</p>
+</td>
+ <td>
+<img src="../images/boot_orange.png" alt="Orange device state" id="figure6" />
+<p class="img-caption"><strong>Figure 6.</strong> Orange state example UI</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>RED</p>
+</td>
+ <td>
+<img src="../images/boot_red.png" alt="Red device state" id="figure7" />
+<p class="img-caption"><strong>Figure 7.</strong> Red state example UI</p>
+</td>
+ </tr>
+</table>
diff --git a/src/devices/tv/images/ape_fwk_hal_tv.png b/src/devices/tv/images/ape_fwk_hal_tv.png
new file mode 100644
index 0000000..c7b3613
--- /dev/null
+++ b/src/devices/tv/images/ape_fwk_hal_tv.png
Binary files differ
diff --git a/src/devices/tv/index.jd b/src/devices/tv/index.jd
index 1b8f75f..d502872 100644
--- a/src/devices/tv/index.jd
+++ b/src/devices/tv/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 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.
@@ -24,19 +24,12 @@
</div>
</div>
-<h2 id=introduction>Introduction</h2>
+<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_tv.png" alt="Android TV HAL icon"/>
-<p>The Android TV Input Framework (TIF) simplifies the delivery of live content to
-Android TV. The Android TIF provides a standard API for manufacturers to use to
-create input modules for controlling Android TV. It also enables live TV search
-and recommendations via metadata published by the TV Input. The framework does
-not seek to implement TV standards or regional requirements.</p>
+<p>The Android TV Input Framework (TIF) simplifies delivery of live content to Android TV. The Android TIF provides a standard API for manufacturers to create input modules for controlling Android TV, and enables live TV search and recommendations via metadata published by the TV Input.</p>
+<p>The framework does not seek to implement TV standards or regional requirements, but does makes it easier for device manufacturers to meet regional digital TV broadcast standards without re-implementation. Documentation in this section might also be useful to third-party app developers who want to create custom TV Inputs.</p>
-<p>The Android TIF makes it easier for device manufacturers to meet regional digital TV
-broadcast standards without re-implementation. This document may also inform
-third-party app developers who would like to create custom TV Inputs.</p>
-
-<h2 id=components>Components</h2>
+<h2 id="components">Components</h2>
<p>The Android TV Input Framework implementation includes a TV Input Manager.
The TIF works with the TV App, a system app that can’t be replaced by a
@@ -63,7 +56,7 @@
<img src="images/TIF_Overview.png" alt="Overview of the Android TIF architecture">
<p class="img-caption"><strong>Figure 1.</strong> Android TV Input Framework (TIF) architecture</p>
-<h2 id=flow>Flow</h2>
+<h2 id="flow">Flow</h2>
<p>Here is how the architecture is exercised:</p>
@@ -75,7 +68,7 @@
identifies the state of TV Inputs for the TV App. See <em>TV Input Manager</em> below for more details about these limitations.
</ol>
-<h2 id=permissions>Permissions</h2>
+<h2 id="permissions">Permissions</h2>
<ul>
<li>Only <code><a
@@ -96,7 +89,7 @@
add and remove its supported TV Inputs.
</ul>
-<h2 id=tv_provider>TV Provider</h2>
+<h2 id="tv_provider">TV Provider</h2>
<p>The TV Provider database stores the channels and programs from TV Inputs. The
TV Provider also publishes and manages the associated permissions so that TV
@@ -129,7 +122,7 @@
available to make certain channels unavailable in search (such as to meet
country-specific requirements for content protection).</p>
-<h3 id=tv_provider_database_field_examples>Database field examples</h3>
+<h3 id="tv_provider_database_field_examples">Database field examples</h3>
<p>The TV Provider supports structured data in channel (<code>android.provider.TvContract.Channels</code>) and program (<code>android.provider.TvContract.Programs</code>) tables. These tables are populated and accessed by TV Inputs and system apps
like the TV App. These tables have four types of fields:</p>
@@ -157,7 +150,7 @@
<p>For a more exhaustive list of the fields, see <code>android/frameworks/base/media/java/android/media/tv/TvContract.java</code></p>
-<h3 id=permissions_and_access_control>Permissions and access control</h3>
+<h3 id="permissions_and_access_control">Permissions and access control</h3>
<p>All fields are visible to anyone with access to the corresponding row. No
fields are directly accessible to users; they see only what the TV App, System
@@ -173,7 +166,7 @@
<li>Only <code>signatureOrSystem</code> apps can acquire <code>ACCESS_ALL_EPG_DATA</code> permission to access the entire database.
</ul>
-<h2 id=tv_input_manager>TV Input Manager</h2>
+<h2 id="tv_input_manager">TV Input Manager</h2>
<p>The TV Input Manager provides a central system API to the overall Android TV
Input Framework. It arbitrates interaction between apps and TV Inputs and
@@ -203,7 +196,7 @@
device manufacturers to create their own TV Apps while helping all third-party TV Inputs
work on all TV Apps.</p>
-<h2 id=tv_inputs>TV Inputs</h2>
+<h2 id="tv_inputs">TV Inputs</h2>
<p>TV Inputs are Android apps in the sense they have an AndroidManifest.xml and
are installed (via Play, pre-installed, or sideloaded). Android TV supports
@@ -258,7 +251,7 @@
specific TV Input for picture in picture (PIP) display. Those button presses
are interpreted by the hardware driver supplied by the device manufacturer,
converting hardware scancodes to Android keycodes and passing them to the
-standard Android <a href="http://source.android.com/devices/tech/input/overview.html">input pipeline</a> <code>InputReader</code> and <code>InputDispatcher</code> functions as <a href="http://developer.android.com/reference/android/view/KeyEvent.html">KeyEvents</a>. These in turn trigger events on the TV App if it is in focus. </p>
+standard Android <a href="{@docRoot}devices/input/overview.html">input pipeline</a> <code>InputReader</code> and <code>InputDispatcher</code> functions as <a href="http://developer.android.com/reference/android/view/KeyEvent.html">KeyEvents</a>. These in turn trigger events on the TV App if it is in focus. </p>
<p>Only system TV Inputs are eligible to receive <code>InputEvents</code>, and only if they have the <code>RECEIVE_INPUT_EVENT</code> system permission. The TV Input is responsible to determine which InputEvents
to consume and should allow the TV App to handle the keys it does not need to
@@ -267,7 +260,7 @@
<p>The TV App is responsible for knowing which system TV Input is active, meaning
selected by the user, and to disambiguate incoming <code>KeyEvents</code> and route them to the correct TV Input Manager session, calling <code>dispatchInputEvent()</code> to pass on the event to the associated TV Input. </p>
-<h3 id=mheg-5_input_example>MHEG-5 input example</h3>
+<h3 id="mheg-5_input_example">MHEG-5 input example</h3>
<p>The following diagram shows a more detailed view of how <code>KeyEvents</code> are routed through the Android TIF.</p>
@@ -295,13 +288,13 @@
<p class="note"><strong>Note</strong>: Third-party TV inputs never receive keys. </p>
-<h2 id=tv_input_hal>TV Input HAL</h2>
+<h2 id="tv_input_hal">TV Input HAL</h2>
<p>The TV Input HAL aids development of TV Inputs to access TV-specific hardware.
As with other Android HALs, the TV Input HAL (<code>tv_input</code>) is
available in the AOSP source tree and the vendor develops its implementation.</p>
-<h2 id=tv_app>TV App</h2>
+<h2 id="tv_app">TV App</h2>
<p>The TV App provides channel and program search results (via
<code>com.android.tv.search.TvProviderSearch</code>) and passes keys, tune, and
@@ -315,7 +308,7 @@
manufacturer or country-specific features. Instead, it handles these tasks by
default:</p>
-<h3 id=setup_and_configuration>Setup and configuration</h3>
+<h3 id="setup_and_configuration">Setup and configuration</h3>
<ul>
<li>Auto-detect TV Inputs
@@ -327,7 +320,7 @@
</ul>
</ul>
-<h3 id=viewing>Viewing</h3>
+<h3 id="viewing">Viewing</h3>
<ul>
<li>Access and navigate all TV channels
<li>Access TV program information bar
@@ -339,7 +332,7 @@
</ul>
</ul>
-<h2 id=parental_control>Parental Control</h2>
+<h2 id="parental_control">Parental Control</h2>
<p>Parental control lets a user block undesired channels and programs, but bypass
the block by entering a PIN code.</p>
@@ -347,20 +340,20 @@
<p>Responsibility for parental control functionality is shared amongst the TV App,
TV Input Manager service, TV Provider, and TV Input. </p>
-<h3 id=tv_provider>TV Provider</h3>
+<h3 id="tv_provider">TV Provider</h3>
<p>Each channel row has a <code>COLUMN_LOCKED</code> field that is used to lock
specific channels from viewing without entering a PIN code. The program field
<code>COLUMN_CONTENT_RATING</code> is intended for display and is not used to
enforce parental control.</p>
-<h3 id=tv_input_manager>TV Input Manager</h3>
+<h3 id="tv_input_manager">TV Input Manager</h3>
<p>The TV Input Manager stores every blocked <code>TvContentRating</code> and
responds to <code>isRatingBlocked()</code> to advise if content with the given
rating should be blocked.</p>
-<h3 id=tv_input>TV Input</h3>
+<h3 id="tv_input">TV Input</h3>
<p>The TV Input checks if the current content should be blocked by calling
<code>isRatingBlocked()</code> on the TV Input Manager when the rating of the
@@ -374,7 +367,7 @@
be blocked, the TV Input enables audio and video and notifies the TV App
the current content is allowed by calling <code>notifyContentAllowed()</code>.</p>
-<h3 id=tv_app>TV App</h3>
+<h3 id="tv_app">TV App</h3>
<p>The TV App shows parental control settings to users and a PIN code UI when it
is notified by a TV Input that the current content is blocked or when the user
@@ -385,7 +378,7 @@
<code>TvContentRating</code> is stored by the TV Input Manager, and blocked
channels are stored by the TV Provider.</p>
-<h2 id=hdmi-cec>HDMI-CEC</h2>
+<h2 id="hdmi-cec">HDMI-CEC</h2>
<p>HDMI-CEC allows one device to control another, thereby enabling a single remote
to control multiple appliances in a home theater. It is used by Android TV to
@@ -422,9 +415,9 @@
back to HDMI Control Service when the surface is set.
</ol>
-<h2 id=tv_integration_guidelines>TV integration guidelines</h2>
+<h2 id="tv_integration_guidelines">TV integration guidelines</h2>
-<h3 id=broadcast_app>Broadcast app</h3>
+<h3 id="broadcast_app">Broadcast app</h3>
<p>Because each country has broadcast-specific requirements (MHEG, Teletext,
HbbTV, and more), manufacturers are expected to supply their own solutions for
@@ -455,7 +448,7 @@
<p>For voice search/recommendation, the broadcast app may support In-app search
for voice search.</p>
-<h3 id=dvr>DVR</h3>
+<h3 id="dvr">DVR</h3>
<p>Android TV supports digital video recording (DVR) with device manufacturer development. The
DVR function works like so:</p>
diff --git a/src/images/android_framework_details.png b/src/images/android_framework_details.png
new file mode 100644
index 0000000..618f027
--- /dev/null
+++ b/src/images/android_framework_details.png
Binary files differ
diff --git a/src/images/android_framework_small.png b/src/images/android_framework_small.png
new file mode 100644
index 0000000..475f58d
--- /dev/null
+++ b/src/images/android_framework_small.png
Binary files differ
diff --git a/src/images/code-lines.png b/src/images/code-lines.png
index f86260c..ae1dac1 100644
--- a/src/images/code-lines.png
+++ b/src/images/code-lines.png
Binary files differ
diff --git a/src/images/workflow-0.png b/src/images/workflow-0.png
index d8456b5..db40c47 100644
--- a/src/images/workflow-0.png
+++ b/src/images/workflow-0.png
Binary files differ
diff --git a/src/index.jd b/src/index.jd
index 20b7aea..0aa6826 100644
--- a/src/index.jd
+++ b/src/index.jd
@@ -6,7 +6,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 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.
@@ -41,48 +41,60 @@
<div class="landing-docs">
<div class="col-8">
<h3>What's New</h3>
+<a href="{@docRoot}devices/tech/debug/dumpsys.html">
+ <h4>Example Dumpsys Diagnostic Output</h4></a>
+ <p>In addition to the aforementioned <strong><a
+ href="{@docRoot}devices/input/diagnostics.html">Input
+ Diagnostics</a></strong>, you can now find Dumpsys examples of usage
+ data for <strong><a href="{@docRoot}devices/tech/ram/procstats.html">RAM
+ (procstats)</a></strong>, <strong><a
+ href="{@docRoot}devices/tech/netstats.html">network (netstats)</a></strong>,
+ and <strong><a
+ href="{@docRoot}devices/tech/power/batterystats.html">battery (batterystats)</a></strong>.</p>
-<a href="{@docRoot}devices/audio.html">
- <h4>Audio gains attributes, USB, and headset documentation</h4></a>
- <p>The <strong><a
- href="{@docRoot}devices/audio.html">Audio section</a></strong> now describes <strong><a
- href="{@docRoot}devices/audio_attributes.html">Attributes</a></strong> and <strong><a
- href="{@docRoot}devices/audio_usb.html">USB digital audio</a></strong> support, while a <strong><a
- href="{@docRoot}accessories/headset-spec.html">Wired audio headset
- specification</a></strong> can now be found in the <strong><a
- href="{@docRoot}accessories/index.html">Accessories section</a></strong>.</p>
+<a href="{@docRoot}devices/audio/latency_measurements.html">
+ <h4>Audio Latency Measurements</h4></a>
+ <p>The Android audio team has published <strong><a
+ href="{@docRoot}devices/audio/latency_measurements.html">round-trip audio latency
+ measurements</a></strong> for select Nexus devices to help partners compare their
+ own devices and reduce latency further.</p>
-<img border="0" src="images/Android_Robot_100.png" alt="Android Partner icon" style="display:inline;float:right;margin:5px 10px">
-
-<a href="{@docRoot}devices/tech/security/index.html">
- <h4>Encryption and SELinux revised</h4></a>
+<a href="{@docRoot}devices/tech/power/index.html">
+ <h4>Power Profile Details</h4></a>
<p><strong><a
- href="{@docRoot}devices/tech/encryption/index.html">Encryption</a></strong> and <strong><a
- href="{@docRoot}devices/tech/security/se-linux.html">Security-Enhanced Linux</a></strong> have been
- updated to describe the latest features of Android 5.0, such as default
- encryption and full enforcement of SELinux.</p>
+ href="{@docRoot}devices/tech/power/index.html">Power</a></strong>
+ information has been moved and expanded to include details on
+ <code>cpu.awake</code> and <code>cpu.active</code>. The need to create a
+ <code>power_profile.xml</code> file is also emphasized throughout.</p>
-<a href="{@docRoot}devices/sensors/index.html">
- <h4>Sensors and Power rewritten</h4></a>
+<a href="{@docRoot}source/initializing.html">
+ <h4>Initializing Improvements</h4></a>
+ <p>Build environment <strong><a
+ href="{@docRoot}source/initializing.html#setting-up-a-mac-os-x-build-environment">Initializing</a></strong>
+ instructions now explain how to resize and unmount Mac OS sparse
+ images. And the ccache section has been moved to an optional <strong><a
+ href="{@docRoot}source/initializing.html#optimizing-a-build-environment">Optimizing
+ a build environment</a></strong> section.</p>
+
+<a href="{@docRoot}devices/tech/security/selinux/index.html">
+ <h4>SELinux Permissive Declarations</h4></a>
+ <p>SELinux <strong><a
+ href="{@docRoot}devices/tech/security/selinux/customize.html">Customizing</a></strong>
+ and <strong><a
+ href="{@docRoot}devices/tech/security/selinux/implement.html">Implementing</a></strong>
+ instructions have been updated to recommend using permissive declarations
+ directly as <code>permissive_or_unconfined()</code> has been deprecated.
+ Similarly, <code>BOARD_SEPOLICY_UNION</code> has been removed, so
+ <code>BOARD_SEPOLICY_*</code> variables are suggested insead.</p>
+
+<a href="{@docRoot}devices/bluetooth.html">
+ <h4>Android 5.0 Bluetooth HCI Requirements</h4></a>
<p><strong><a
- href="{@docRoot}devices/sensors/index.html">Sensors</a></strong> and <strong><a
- href="{@docRoot}devices/tech/power.html">Power</a></strong> have been
- completely rewritten to reflect the latest Android release and include
- new gesture sensors and tools for measuring power consumption.</p>
-
-<a href="{@docRoot}devices/tv/index.html">
- <h4>TV Input Framework and more come to Android</h4></a>
- <p>The <strong><a
- href="{@docRoot}devices/tv/index.html">TV Input Framework</a></strong> and <strong><a
- href="{@docRoot}devices/tv/HDMI-CEC.html">HDMI-CEC</a></strong> enable TV development, while <strong><a
- href="{@docRoot}devices/audio_tv.html">TV Audio</a></strong> describes audio routing through televisions.</p>
-
-<a href="{@docRoot}devices/camera/versioning.html">
- <h4>Camera versioning added, security enhancements updated</h4></a>
- <p>The Camera team now describes its <strong><a
- href="{@docRoot}devices/tv/index.html">Version support</a></strong>, while the Security team lists new <strong><a
- href="{@docRoot}devices/tech/security/enhancements.html">Enhancements</a></strong> and <strong><a
- href="{@docRoot}devices/tech/security/acknowledgements.html">Acknowledgements</a></strong>.</p>
+ href="{@docRoot}devices/Android-5.0-Bluetooth-HCI-Reqs.pdf">Bluetooth
+ Host Controller Interface (HCI) requirements</a></strong> to leverage
+ the Bluetooth Low Energy APIs in Android 5.0 have
+ been published and linked from the <strong><a
+ href="{@docRoot}devices/bluetooth.html">Bluetooth</a></strong> introduction.</p>
</div>
<div class="col-8">
@@ -90,11 +102,13 @@
<a href="{@docRoot}source/index.html">
<h4>Explore the Source</h4></a>
<p>Get the complete Android platform and modify and build it to suit your needs. You can
- also <strong><a
-href="https://android-review.googlesource.com/#/q/status:open">contribute to</a></strong> the <strong><a
-href="https://android.googlesource.com/">Android Open Source Project
-repository</a></strong> to make your changes available to everyone else in
- the Android ecosystem.</p>
+ also <strong><a
+ href="https://android-review.googlesource.com/#/q/status:open">contribute
+ to</a></strong> the <strong><a
+ href="https://android.googlesource.com/">Android Open Source Project (AOSP)
+ repository</a></strong> to make your changes available to everyone else
+ in the Android ecosystem.</p>
+<a href="{@docRoot}source/index.html"><img border="0" src="images/android_framework_small.png" alt="Android framework summary" style="display:inline;float:left;margin:5px 10px"></a>
<a href="{@docRoot}devices/index.html">
<h4>Port Android to Devices</h4></a>
<p>Port the latest Android platform and
@@ -109,6 +123,13 @@
<p>Being Android-compatible lets you offer custom features but still give users and developers a consistent
and standard experience across all Android-powered devices. Android provides guidance
and a test suite to verify your Android compatibility.</p>
+
+ <a href="https://android.googlesource.com/platform/docs/source.android.com/">
+ <h4>Help this Site</h4></a>
+ <p>Please note, source.android.com is maintained in the Android Open Source Project. See the <strong><a
+ href="https://android.googlesource.com/platform/docs/source.android.com/+log/master">docs/source.android.com
+ project log in AOSP</a></strong> for the complete list of changes to this site.
+ Contribute your own updates to that same project and help maintain source.android.com.</p>
</div>
</div>
diff --git a/src/source/64-bit-builds.jd b/src/source/64-bit-builds.jd
new file mode 100644
index 0000000..2373886
--- /dev/null
+++ b/src/source/64-bit-builds.jd
@@ -0,0 +1,225 @@
+page.title=Android Platform 64-bit Build Instructions
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<h2 id=overview>Overview</h2>
+
+<p>From the build system’s perspective, the most prominent change is that now it
+supports building binaries for two target CPU architectures (64-bit and 32-bit)
+in the same build. That’s also known as <em>Multilib build</em>.</p>
+
+<p>For native static libraries and shared libraries, the build system sets up
+rules to build binaries for both architectures. The product configuration
+(PRODUCT_PACKAGES), together with the dependency graph, determines which
+binaries are built and installed to the system image.</p>
+
+<p>For executables and apps, the build system builds only the 64-bit version by
+default, but you can override this setting by using a global
+<code>BoardConfig.mk</code> variable or a module-scoped variable.</p>
+
+<p class="caution"><strong>Caution:</strong> If an app exposes an API to other
+apps that can be either 32- or 64-bit, the app must have the
+<code>android:multiarch</code> property set to a value of <code>true</code>
+within its manifest to avoid potential errors.</p>
+
+<h2 id=product_configuration>Product Configuration</h2>
+
+
+<p>In <code>BoardConfig.mk</code>, we added the following variables to
+configure the second CPU architecture and ABI:</p>
+
+<pre class=prettyprint>
+TARGET_2ND_ARCH
+TARGET_2ND_ARCH_VARIANT
+TARGET_2ND_CPU_VARIANT
+TARGET_2ND_CPU_ABI
+TARGET_2ND_CPU_ABI2
+</pre>
+
+
+<p>You can see an example in <code>build/target/board/generic_arm64/BoardConfig.mk</code>.</p>
+
+<p>If you want the build system to build 32-bit executables and apps by default,
+set the following variable:</p>
+
+<pre class=prettyprint>
+TARGET_PREFER_32_BIT := true
+</pre>
+
+<p>However, you can override this setting by using module-specific variables in
+<code>Android.mk</code>.</p>
+
+<p>In a Multilib build, module names in <code>PRODUCT_PACKAGES</code> cover
+both the 32-bit and 64-bit binaries, as long as they are defined by the build
+system. For libraries pulled in by dependency, a 32-bit library is installed
+only if it’s required by another 32-bit library or executable. The same is true
+for 64-bit libraries.</p>
+
+<p>However, module names on the <code>make</code> command line cover only the
+64-bit version. For example, after running <code>lunch
+aosp_arm64-eng</code>,<code>make libc</code> builds only the 64-bit libc. To
+build the 32-bit libc, you need to run <code>make libc_32</code>.</p>
+
+<h2 id=module_definition_in_android_mk>Module Definition in Android.mk</h2>
+
+<p>You can use the <code>LOCAL_MULTILIB</code> variable to configure your build
+for 32-bit and/or 64-bit and override the global
+<code>TARGET_PREFER_32_BIT</code>.</p>
+
+<p>Set <code>LOCAL_MULTILIB</code> to one of the following:</p>
+
+<ul>
+ <li>"both”: build both 32-bit and 64-bit.</li>
+ <li>“32”: build only 32-bit.</li>
+ <li>“64”: build only 64-bit.</li>
+ <li>“first”: build for only the first arch (32-bit in 32-bit devices and 64-bit
+in 64-bit devices).</li>
+ <li>“”: the default; the build system decides what arch to build based on the
+module class and other LOCAL_ variables, such as LOCAL_MODULE_TARGET_ARCH,
+LOCAL_32_BIT_ONLY, etc.</li>
+</ul>
+
+<p>In a Multilib build, conditionals like <code>ifeq $(TARGET_ARCH)</code> don’t work any
+more. </p>
+
+<p>If you want to build your module for some specific arch(s), the following
+variables can help you:</p>
+
+<ul>
+ <li>LOCAL_MODULE_TARGET_ARCH<br>It can be set to a list of archs, something
+like “arm x86 arm64”. Only if the arch being built is among that list will the
+current module be included by the build system.</li>
+
+ <li>LOCAL_MODULE_UNSUPPORTED_TARGET_ARCH<br>The opposite of
+LOCAL_MODULE_TARGET_ARCH. Only if the arch being built is not among the list,
+the current module will be included.</li>
+</ul>
+
+<p>There are minor variants of the above two variables:</p>
+
+<ul>
+ <li>LOCAL_MODULE_TARGET_ARCH_WARN</li>
+ <li>LOCAL_MODULE_UNSUPPORTED_TARGET_ARCH_WARN</li>
+</ul>
+
+<p>The build system will give warning if the current module is skipped due to
+archs limited by them.</p>
+
+<p>To set up arch-specific build flags, use the arch-specific LOCAL_ variables. An
+arch-specific LOCAL_ variable is a normal LOCAL_ variable with an arch suffix,
+for example:</p>
+
+<ul>
+ <li> <code>LOCAL_SRC_FILES_arm, LOCAL_SRC_FILES_x86,</code>
+ <li> <code>LOCAL_CFLAGS_arm, LOCAL_CFLAGS_arm64,</code>
+ <li> <code>LOCAL_LDFLAGS_arm, LOCAL_LDFLAGS_arm64,</code>
+</ul>
+
+<p>Those variables will be applied only if a binary is currently being built for
+that arch.</p>
+
+<p>Sometimes it’s more convenient to set up flags based on whether the binary is
+currently being built for 32-bit or 64-bit. In that case you can use the LOCAL_
+variable with a _32 or _64 suffix, for example:</p>
+
+<ul>
+ <li> <code>LOCAL_SRC_FILES_32, LOCAL_SRC_FILES_64,</code>
+ <li> <code>LOCAL_CFLAGS_32, LOCAL_CFLAGS_64,</code>
+ <li> <code>LOCAL_LDFLAGS_32, LOCAL_LDFLAGS_64,</code>
+</ul>
+
+<p>Note that not all of the LOCAL_ variables support the arch-specific variants.
+For an up-to-date list of such variables, refer to <code>build/core/clear_vars.mk</code>.</p>
+
+<h2 id=install_path>Install path</h2>
+
+
+<p>In the past, you could use LOCAL_MODULE_PATH to install a library to a
+location other than the default one. For example, <code>LOCAL_MODULE_PATH :=
+$(TARGET_OUT_SHARED_LIBRARIES)/hw</code>.</p>
+
+<p>In Multilib build, use LOCAL_MODULE_RELATIVE_PATH instead:</p>
+
+<pre class=prettyprint>
+LOCAL_MODULE_RELATIVE_PATH := hw
+</pre>
+
+
+<p>so that both the 64-bit and 32-bit libraries can be installed to the right
+place.</p>
+
+<p>If you build an executable as both 32-bit and 64-bit, you’ll need to use one of
+the following variables to distinguish the install path:</p>
+
+<ul>
+ <li><code>LOCAL_MODULE_STEM_32, LOCAL_MODULE_STEM_64</code><br>Specifies the installed file name.
+ <li><code>LOCAL_MODULE_PATH_32, LOCAL_MODULE_PATH_64</code><br>Specifies the install path.
+</ul>
+
+<h2 id=generated_sources>Generated sources </h2>
+
+<p>In a Multilib build, if you generate source files to
+<code>$(local-intermediates-dir)</code> (or <code>$(intermediates-dir-for)
+</code>with explicit variables), it won’t reliably work any more. That’s
+because the intermediate generated sources will be required by both 32-bit and
+64-bit build, but <code>$(local-intermediates-dir)</code> only points to one of
+the two intermediate directories.</p>
+
+<p>Happily, the build system now provides a dedicated, Multilib-friendly,
+intermediate directory for generating sources. You can call<code>
+$(local-generated-sources-dir)</code> or
+<code>$(generated-sources-dir-for)</code> to get the directory’s path. Their
+usages are similar to <code>$(local-intermediates-dir)</code> and
+<code>$(intermediates-dir-for)</code>. </p>
+
+<p>If a source file is generated to the new dedicated directory and picked up
+by <code>LOCAL_GENERATED_SOURCES</code>, it is built for both 32-bit and 64-bit
+in multilib build.</p>
+
+<h2 id=prebuilts>Prebuilts</h2>
+
+
+<p>In Multilib, you can’t use <code>TARGET_ARCH</code> (or together with
+<code>TARGET_2ND_ARCH</code>) to tell the build system what arch the prebuilt
+binary is targeted for. Use the aforementioned <code>LOCAL_</code> variable
+<code>LOCAL_MODULE_TARGET_ARCH</code> or
+<code>LOCAL_MODULE_UNSUPPORTED_TARGET_ARCH</code> instead.</p>
+
+<p>With these variables, the build system can choose the corresponding 32-bit
+prebuilt binary even if it’s currently doing a 64-bit Multilib build.</p>
+
+<p>If you want to use the chosen arch to compute the source path for the prebuilt
+binary , you can call<code> $(get-prebuilt-src-arch)</code>.</p>
+
+<h2 id=dex-preopt>Dex-preopt</h2>
+
+
+<p>For 64-bit devices, by default we generate both 32-bit and 64-bit odex files
+for the boot image and any Java libraries. For APKs, by default we generate
+odex only for the primary 64-bit arch. If an app will be launched in both
+32-bit and 64-bit processes, please use <code>LOCAL_MULTILIB := both</code> to make sure
+both 32-bit and 64-bit odex files are generated. That flag also tells the build
+system to include both 32-bit and 64-bit JNI libraries, if the app has any.</p>
+
diff --git a/src/source/build-numbers.jd b/src/source/build-numbers.jd
index eea5f48..d116739 100644
--- a/src/source/build-numbers.jd
+++ b/src/source/build-numbers.jd
@@ -41,84 +41,24 @@
</thead>
<tbody>
<tr>
-<td>(no code name)</td>
-<td>1.0</td>
-<td>API level 1</td>
+<td>Lollipop</td>
+<td>5.1</td>
+<td>API level 22</td>
</tr>
<tr>
-<td>(no code name)</td>
-<td>1.1</td>
-<td>API level 2</td>
+<td>Lollipop</td>
+<td>5.0</td>
+<td>API level 21</td>
</tr>
<tr>
-<td>Cupcake</td>
-<td>1.5</td>
-<td>API level 3, NDK 1</td>
-</tr>
-<tr>
-<td>Donut</td>
-<td>1.6</td>
-<td>API level 4, NDK 2</td>
-</tr>
-<tr>
-<td>Eclair</td>
-<td>2.0</td>
-<td>API level 5</td>
-</tr>
-<tr>
-<td>Eclair</td>
-<td>2.0.1</td>
-<td>API level 6</td>
-</tr>
-<tr>
-<td>Eclair</td>
-<td>2.1</td>
-<td>API level 7, NDK 3</td>
-</tr>
-<tr>
-<td>Froyo</td>
-<td>2.2.x</td>
-<td>API level 8, NDK 4</td>
-</tr>
-<tr>
-<td>Gingerbread</td>
-<td>2.3 - 2.3.2</td>
-<td>API level 9, NDK 5</td>
-</tr>
-<tr>
-<td>Gingerbread</td>
-<td>2.3.3 - 2.3.7</td>
-<td>API level 10</td>
-</tr>
-<tr>
-<td>Honeycomb</td>
-<td>3.0</td>
-<td>API level 11</td>
-</tr>
-<tr>
-<td>Honeycomb</td>
-<td>3.1</td>
-<td>API level 12, NDK 6</td>
-</tr>
-<tr>
-<td>Honeycomb</td>
-<td>3.2.x</td>
-<td>API level 13</td>
-</tr>
-<tr>
-<td>Ice Cream Sandwich</td>
-<td>4.0.1 - 4.0.2</td>
-<td>API level 14, NDK 7</td>
-</tr>
-<tr>
-<td>Ice Cream Sandwich</td>
-<td>4.0.3 - 4.0.4</td>
-<td>API level 15, NDK 8</td>
+<td>KitKat</td>
+<td>4.4 - 4.4.4</td>
+<td>API level 19</td>
</tr>
<tr>
<td>Jelly Bean</td>
-<td>4.1.x</td>
-<td>API level 16</td>
+<td>4.3.x</td>
+<td>API level 18</td>
</tr>
<tr>
<td>Jelly Bean</td>
@@ -127,18 +67,83 @@
</tr>
<tr>
<td>Jelly Bean</td>
-<td>4.3.x</td>
-<td>API level 18</td>
+<td>4.1.x</td>
+<td>API level 16</td>
</tr>
<tr>
-<td>KitKat</td>
-<td>4.4 - 4.4.4</td>
-<td>API level 19</td>
+<td>Ice Cream Sandwich</td>
+<td>4.0.3 - 4.0.4</td>
+<td>API level 15, NDK 8</td>
</tr>
<tr>
-<td>Lollipop</td>
-<td>5.0</td>
-<td>API level 21</td>
+<td>Ice Cream Sandwich</td>
+<td>4.0.1 - 4.0.2</td>
+<td>API level 14, NDK 7</td>
+</tr>
+<tr>
+<td>Honeycomb</td>
+<td>3.2.x</td>
+<td>API level 13</td>
+</tr>
+<tr>
+<td>Honeycomb</td>
+<td>3.1</td>
+<td>API level 12, NDK 6</td>
+</tr>
+<tr>
+<td>Honeycomb</td>
+<td>3.0</td>
+<td>API level 11</td>
+</tr>
+<tr>
+<td>Gingerbread</td>
+<td>2.3.3 - 2.3.7</td>
+<td>API level 10</td>
+</tr>
+<tr>
+<td>Gingerbread</td>
+<td>2.3 - 2.3.2</td>
+<td>API level 9, NDK 5</td>
+</tr>
+<tr>
+<td>Froyo</td>
+<td>2.2.x</td>
+<td>API level 8, NDK 4</td>
+</tr>
+<tr>
+<td>Eclair</td>
+<td>2.1</td>
+<td>API level 7, NDK 3</td>
+</tr>
+<tr>
+<td>Eclair</td>
+<td>2.0.1</td>
+<td>API level 6</td>
+</tr>
+<tr>
+<td>Eclair</td>
+<td>2.0</td>
+<td>API level 5</td>
+</tr>
+<tr>
+<td>Donut</td>
+<td>1.6</td>
+<td>API level 4, NDK 2</td>
+</tr>
+<tr>
+<td>Cupcake</td>
+<td>1.5</td>
+<td>API level 3, NDK 1</td>
+</tr>
+<tr>
+<td>(no code name)</td>
+<td>1.1</td>
+<td>API level 2</td>
+</tr>
+<tr>
+<td>(no code name)</td>
+<td>1.0</td>
+<td>API level 1</td>
</tr>
</tbody>
</table>
@@ -173,14 +178,86 @@
<th>Supported devices</th>
</tr>
<tr>
+ <td>LMY47V</td>
+ <td>android-5.1.1_r1</td>
+ <td>Lollipop</td>
+ <td>Nexus Player</td>
+</tr>
+<tr>
+ <td>LMY47O</td>
+ <td>android-5.1.0_r5</td>
+ <td>Lollipop</td>
+ <td>Nexus 4, Nexus 7 (flo/deb)</td>
+</tr>
+<tr>
+ <td>LMY47I</td>
+ <td>android-5.1.0_r3</td>
+ <td>Lollipop</td>
+ <td>Nexus 5, Nexus 6</td>
+</tr>
+<tr>
+ <td>LMY47D</td>
+ <td>android-5.1.0_r1</td>
+ <td>Lollipop</td>
+ <td>Nexus 5, Nexus 6, Nexus 7 (grouper/tilapia), Nexus 10, Nexus Player</td>
+</tr>
+<tr>
+ <td>LRX22G</td>
+ <td>android-5.0.2_r1</td>
+ <td>Lollipop</td>
+ <td>Nexus 7 (flo/deb/grouper/tilapia), Nexus 10</td>
+</tr>
+<tr>
+ <td>LRX22C</td>
+ <td>android-5.0.1_r1</td>
+ <td>Lollipop</td>
+ <td>Nexus 4, Nexus 5, Nexus 6 (shamu), Nexus 7 (flo), Nexus 9 (volantis/volantisg), Nexus 10</td>
+</tr>
+<tr>
+ <td>LRX21V</td>
+ <td>android-5.0.0_r7.0.1</td>
+ <td>Lollipop</td>
+ <td>Nexus Player (fugu)</td>
+</tr>
+<tr>
+ <td>LRX21T</td>
+ <td>android-5.0.0_r6.0.1</td>
+ <td>Lollipop</td>
+ <td>Nexus 4</td>
+</tr>
+<tr>
+ <td>LRX21R</td>
+ <td>android-5.0.0_r5.1.0.1</td>
+ <td>Lollipop</td>
+ <td>Nexus 9 (volantis)</td>
+</tr>
+<tr>
+ <td>LRX21Q</td>
+ <td>android-5.0.0_r5.0.1</td>
+ <td>Lollipop</td>
+ <td>Nexus 9 (volantis)</td>
+</tr>
+<tr>
+ <td>LRX21P</td>
+ <td>android-5.0.0_r4.0.1</td>
+ <td>Lollipop</td>
+ <td>Nexus 7 (flo/grouper), Nexus 10</td>
+</tr>
+<tr>
+ <td>LRX21O</td>
+ <td>android-5.0.0_r3.0.1</td>
+ <td>Lollipop</td>
+ <td>Nexus 5 (hammerhead), Nexus 6 (shamu)</td>
+</tr>
+<tr>
<td>LRX21M</td>
- <td>android-5.0.0_r2</td>
+ <td>android-5.0.0_r2.0.1</td>
<td>Lollipop</td>
<td>Nexus Player (fugu)</td>
</tr>
<tr>
<td>LRX21L</td>
- <td>android-5.0.0_r1</td>
+ <td>android-5.0.0_r1.0.1</td>
<td>Lollipop</td>
<td>Nexus 9 (volantis)</td>
</tr>
diff --git a/src/source/building-devices.jd b/src/source/building-devices.jd
index 3c45168..06b4352 100644
--- a/src/source/building-devices.jd
+++ b/src/source/building-devices.jd
@@ -76,6 +76,18 @@
</thead>
<tbody>
<tr>
+<td>shamu</td>
+<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
+</tr>
+<tr>
+<td>fugu</td>
+<td>Press and hold <em>Power</em></td>
+</tr>
+<tr>
+<td>volantis</td>
+<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
+</tr>
+<tr>
<td>hammerhead</td>
<td>Press and hold both <em>Volume Up</em> and <em>Volume Down</em>, then press
and hold <em>Power</em></td>
@@ -204,6 +216,22 @@
</thead>
<tbody>
<tr>
+ <td>Nexus 6</td>
+<td>shamu</td>
+<td>aosp_shamu-userdebug</td>
+</tr>
+</tr>
+<tr>
+ <td>Nexus Player</td>
+<td>fugu</td>
+<td>aosp_fugu-userdebug</td>
+</tr>
+<tr>
+ <td>Nexus 9</td>
+<td>volantis (flounder)</td>
+<td>aosp_flounder-userdebug</td>
+</tr>
+<tr>
<td>Nexus 5 (GSM/LTE)</td>
<td>hammerhead</td>
<td>aosp_hammerhead-userdebug</td>
diff --git a/src/source/building-kernels.jd b/src/source/building-kernels.jd
index 8806d80..41e364b 100644
--- a/src/source/building-kernels.jd
+++ b/src/source/building-kernels.jd
@@ -40,6 +40,24 @@
<th>Build configuration</th>
</tr>
<tr>
+ <td>shamu</td>
+ <td>device/moto/shamu-kernel</td>
+ <td>kernel/msm</td>
+ <td>shamu_defconfig</td>
+ </tr>
+ <tr>
+ <td>fugu</td>
+ <td>device/asus/fugu-kernel</td>
+ <td>kernel/x86_64</td>
+ <td>fugu_defconfig</td>
+ </tr>
+ <tr>
+ <td>volantis</td>
+ <td>device/htc/flounder-kernel</td>
+ <td>kernel/tegra</td>
+ <td>flounder_defconfig</td>
+ </tr>
+ <tr>
<td>hammerhead</td>
<td>device/lge/hammerhead-kernel</td>
<td>kernel/msm</td>
@@ -148,13 +166,14 @@
</code></pre>
<p>For Nexus 5 (hammerhead), this can be accomplished with:</p>
<pre><code>
-$ bzgrep -a 'Linux version' vmlinux.bz2
+$ dd if=zImage-dtb bs=1 skip=$(LC_ALL=C od -Ad -x -w2 zImage-dtb | grep 8b1f | cut -d ' ' -f1 | head -1) | zgrep -a 'Linux version'
</code></pre>
<h2 id="downloading-sources">Downloading sources</h2>
<p>Depending on which kernel you want,</p>
<pre><code>$ git clone https://android.googlesource.com/kernel/common.git
+$ git clone https://android.googlesource.com/kernel/x86_64.git
$ git clone https://android.googlesource.com/kernel/exynos.git
$ git clone https://android.googlesource.com/kernel/goldfish.git
$ git clone https://android.googlesource.com/kernel/msm.git
@@ -165,16 +184,18 @@
<ul>
<li>The <code>goldfish</code> project contains the kernel sources for the emulated
platforms.</li>
-<li>The <code>msm</code> project has the sources for ADP1, ADP2, Nexus One, Nexus 4,
+<li>The <code>msm</code> project has the sources for ADP1, ADP2, Nexus One, Nexus 4, Nexus 5, Nexus 6,
and can be used as a starting point for work on Qualcomm MSM chipsets.</li>
<li>The <code>omap</code> project is used for PandaBoard and Galaxy Nexus,
and can be used as a starting point for work on TI OMAP chipsets.</li>
<li>The <code>samsung</code> project is used for Nexus S,
and can be used as a starting point for work on Samsung Hummingbird chipsets.</li>
-<li>The <code>tegra</code> project is for Xoom and Nexus 7,
+<li>The <code>tegra</code> project is for Xoom, Nexus 7, Nexus 9,
and can be used as a starting point for work on NVIDIA Tegra chipsets.</li>
<li>The <code>exynos</code> project has the kernel sources for Nexus 10,
and can be used as a starting point for work on Samsung Exynos chipsets.</li>
+<li>The <code>x86_64</code> project has the kernel sources for Nexus Player,
+and can be used as a starting point for work on Intel x86_64 chipsets.</li>
</ul>
<h2 id="downloading-a-prebuilt-gcc">Downloading a prebuilt gcc</h2>
<p>Ensure that the prebuilt toolchain is in your path.</p>
diff --git a/src/source/building-running.jd b/src/source/building-running.jd
index ed8c4b7..239ebe6 100644
--- a/src/source/building-running.jd
+++ b/src/source/building-running.jd
@@ -24,14 +24,14 @@
</div>
</div>
-The following instructions to build the Android source tree apply to all branches, including master.
+The following instructions to build the Android source tree apply to all branches, including <code>master</code>.
<h2 id="choosing-a-branch">Choosing a Branch</h2>
<p>Some of the requirements for your build environment are determined by which
version of the source code you plan to compile. See
<a href="build-numbers.html">Codenames, Tags, and Build Numbers</a> for a full listing of branches you may
choose from. You may also choose to download and build the latest source code
-(called "master"), in which case you will simply omit the branch specification
+(called <code>master</code>), in which case you will simply omit the branch specification
when you initialize the repository.</p>
<p>Once you have selected a branch, follow the appropriate instructions below to
set up your build environment.</p>
@@ -40,7 +40,7 @@
<p>The basic sequence of build commands is as follows:</p>
<h2 id="initialize">Initialize</h2>
<p>Initialize the environment with the <code>envsetup.sh</code> script. Note
-that replacing "source" with a single dot saves a few characters,
+that replacing <code>source</code> with <code>.</code> (a single dot) saves a few characters,
and the short form is more commonly used in documentation.</p>
<pre><code>$ source build/envsetup.sh
</code></pre>
@@ -49,12 +49,12 @@
</code></pre>
<h2 id="choose-a-target">Choose a Target</h2>
<p>Choose which target to build with <code>lunch</code>. The exact configuration can be passed as
-an argument, e.g. </p>
+an argument. For example, the following command:</p>
<pre><code>$ lunch aosp_arm-eng
</code></pre>
-<p>The example above refers to a complete build for the emulator, with all debugging enabled.</p>
+<p>refers to a complete build for the emulator, with all debugging enabled.</p>
<p>If run with no arguments <code>lunch</code> will prompt you to choose a target from the menu. </p>
-<p>All build targets take the form BUILD-BUILDTYPE, where the BUILD is a codename
+<p>All build targets take the form <code>BUILD-BUILDTYPE</code>, where the <code>BUILD</code> is a codename
referring to the particular feature combination. Here's a partial list:</p>
<table>
<thead>
@@ -111,7 +111,7 @@
<p>Build everything with <code>make</code>. GNU make can handle parallel
tasks with a <code>-jN</code> argument, and it's common to use a number of
tasks N that's between 1 and 2 times the number of hardware
-threads on the computer being used for the build. E.g. on a
+threads on the computer being used for the build. For example, on a
dual-E5520 machine (2 CPUs, 4 cores per CPU, 2 threads per core),
the fastest builds are made with commands between <code>make -j16</code> and
<code>make -j32</code>.</p>
@@ -126,7 +126,7 @@
<p>Once the device is in fastboot mode, run </p>
<pre><code>$ fastboot flashall -w
</code></pre>
-<p>The <code>-w</code> option wipes the <code>/data</code> partition on the device; this is useful for your first time flashing a particular device, but is otherwise unnecessary.</p>
+<p>The <code>-w</code> option wipes the <code>/data</code> partition on the device; this is useful for your first time flashing a particular device but is otherwise unnecessary.</p>
<p>For more information about building for and running on actual hardware, see
<a href="building-devices.html">Building for Devices.</a></p>
<h3 id="emulate-an-android-device">Emulate an Android Device</h3>
@@ -141,10 +141,10 @@
$ prebuilts/misc/linux-x86/ccache/ccache -M 50G
</code></pre>
<p>The suggested cache size is 50-100G.</p>
-<p>You can watch ccache being used by doing the following:</p>
+<p>On Linux, you can watch ccache being used by doing the following:</p>
<pre><code>$ watch -n1 -d prebuilts/misc/linux-x86/ccache/ccache -s
</code></pre>
-<p>On OSX, you should replace <code>linux-x86</code> with <code>darwin-x86</code>.</p>
+<p>On Mac OS, you should replace <code>linux-x86</code> with <code>darwin-x86</code>.</p>
<p>When using Ice Cream Sandwich (4.0.x) or older, you should replace
<code>prebuilts/misc</code> with <code>prebuilt</code>.</p>
<h2 id="troubleshooting-common-build-errors">Troubleshooting Common Build Errors</h2>
@@ -176,7 +176,7 @@
<pre><code>$ apt-get install python
</code></pre>
<h3 id="case-insensitive-filesystem">Case Insensitive Filesystem</h3>
-<p>If you are building on an HFS filesystem on Mac OS X, you may encounter an error such as</p>
+<p>If you are building on an HFS filesystem on Mac OS, you may encounter an error such as</p>
<pre><code>************************************************************
You are building on a case-insensitive filesystem.
Please move your source tree to a case-sensitive filesystem.
diff --git a/src/source/building.jd b/src/source/building.jd
index 8eec5a9..408ddb1 100644
--- a/src/source/building.jd
+++ b/src/source/building.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2014 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.
@@ -17,7 +17,7 @@
limitations under the License.
-->
<p>The Android build is routinely tested in-house on recent versions of
-Ubuntu LTS (12.04), but most distributions should have the required
+Ubuntu LTS (14.04), but most distributions should have the required
build tools available. We welcome reports of successes or failures on other
distributions.</p>
@@ -25,19 +25,20 @@
<ul>
- <li>A Linux or Mac system. It is also possible
+ <li>A Linux or Mac OS system. It is also possible
to build Android in a virtual machine on unsupported systems such as Windows.
If you are running Linux in a virtual machine, you need at
- least 16GB of RAM/swap and 30GB or more of disk space in order to
- build the Android tree.
+ least 16GB of RAM/swap and 50GB or more of disk space in order to
+ build the Android tree. See disk size requirements below.
</li>
<li>A 64-bit environment is required for Gingerbread (2.3.x) and newer versions, including the master
branch. You can compile older versions on 32-bit systems.
</li>
- <li>30GB of free disk space to complete a single build and
- up to 100GB or more for a full set of builds. The source download is approximately 8.5GB in size.</p>
+ <li>At least 50GB of free disk space for a checkout, 100GB for a single
+ build, and 150GB or more for multiple builds. If you employ ccache, you will
+ need even more space.</p>
</li>
<li>
diff --git a/src/source/code-lines.jd b/src/source/code-lines.jd
index f277019..2e82e7b 100644
--- a/src/source/code-lines.jd
+++ b/src/source/code-lines.jd
@@ -71,10 +71,10 @@
</p>
</li>
</ol>
-<p>
- <img src="{@docRoot}images/code-lines.png" alt="code-line diagram">
+ <img src="{@docRoot}images/code-lines.png" alt="code-line diagram" id="figure1" >
+<p class="img-caption">
+ <strong>Figure 1.</strong> AOSP code and releases
</p>
-
<h2 id="terms-and-caveats">
Terms and Caveats
</h2>
diff --git a/src/source/community/index.jd b/src/source/community/index.jd
index 31361ca..8845469 100644
--- a/src/source/community/index.jd
+++ b/src/source/community/index.jd
@@ -10,125 +10,213 @@
</div>
<p>Welcome to the Android community!</p>
-<p>The key to any community is, obviously, communication. Like most projects,
-Android communicates via mailing lists. Because Android is an extremely large
+<p>The key to any community is communication. Like most projects, Android
+communicates via mailing lists. Because Android is an extremely large
project with many components, we have many discussion forums, each focusing on
a different topic.</p>
-<p>Please check out the groups below, and join any that seem interesting to
+<p>Check out the groups below and join any that seem interesting to
you. Note that if you're a user looking for help with your Android device,
this page probably isn't for you; you should contact your carrier or retailer
for help with your phone.</p>
-<p>Please note that if you're looking for information about building
-applications for Android, you can find a separate set of groups for those at
-our sister site, developer.android.com: [https://developer.android.com/resources/community-groups.html]</p>
+<p>If you're looking for information about building applications for Android,
+you can find a separate set of groups at our sister site
+<a href="https://developer.android.com/resources/community-groups.html">
+developer.android.com</a>.</p>
<h2 id="open-source-project-discussions">Open Source Project discussions</h2>
<ul>
<li>
-<p><em>android-platform</em>:
- This list is for general discussion about the Android open-source project or the platform technologies.</p>
+<p><em>android-platform</em>:
+This list is for general discussion about the Android open-source project or
+the platform technologies.</p>
<ul>
-<li>Subscribe using Google Groups: <a href="https://groups.google.com/forum/?fromgroups#!forum/android-platform">android-platform</a></li>
-<li>Subscribe via email: <a href="mailto:android-platform+subscribe@googlegroups.com">android-platform</a></li>
+<li>Subscribe using Google Groups:
+<a href="https://groups.google.com/forum/?fromgroups#!forum/android-platform">
+android-platform</a></li>
+<li>Subscribe via email:
+<a href="mailto:android-platform+subscribe@googlegroups.com">android-platform
+</a></li>
</ul>
</li>
<li>
<p><em>android-building</em>:
- Subscribe to this list for discussion and help on building the Android source code, and on the build system. If you've just checked out the source code and have questions about how to turn it into binaries, start here.</p>
+Subscribe to this list for discussion and help on building the Android source
+code, and on the build system. If you've just checked out the source code and
+have questions about how to turn it into binaries, start here.</p>
<ul>
-<li>Subscribe using Google Groups: <a href="https://groups.google.com/forum/?fromgroups#!forum/android-building">android-building</a></li>
-<li>Subscribe via email: <a href="mailto:android-building+subscribe@googlegroups.com">android-building</a></li>
+<li>Subscribe using Google Groups:
+<a href="https://groups.google.com/forum/?fromgroups#!forum/android-building">
+android-building</a></li>
+<li>Subscribe via email:
+<a href="mailto:android-building+subscribe@googlegroups.com">android-building
+</a></li>
</ul>
</li>
<li>
<p><em>android-porting</em>:
- This list is for developers who want to port Android to a new device. If you're wondering how to combine the Android source code with your hardware, this is the right group for you. Discuss here the specifics of porting Android to individual devices, from obtaining toolchains and merging kernel drivers all the way to configuring or modifying applications for your specific
+This list is for developers who want to port Android to a new device. If
+you're wondering how to combine the Android source code with your hardware,
+this is the right group for you. Discuss here the specifics of porting Android
+to individual devices, from obtaining toolchains and merging kernel drivers
+all the way to configuring or modifying applications for your specific
configuration.</p>
<ul>
-<li>Subscribe using Google Groups: <a href="https://groups.google.com/forum/?fromgroups#!forum/android-porting">android-porting</a></li>
-<li>Subscribe via email: <a href="mailto:android-porting+subscribe@googlegroups.com">android-porting</a></li>
+<li>Subscribe using Google Groups:
+<a href="https://groups.google.com/forum/?fromgroups#!forum/android-porting">
+android-porting</a></li>
+<li>Subscribe via email:
+<a href="mailto:android-porting+subscribe@googlegroups.com">android-porting</a>
+</li>
</ul>
</li>
<li>
<p><em>android-contrib</em>:
- This list is for developers who want to contribute code to Android. This is a working list, and is not appropriate for general discussion. We ask that general discussion go to android-platform. Note: contributors to the Android kernel should go to the android-kernel list, below.</p>
+This list is for developers who want to contribute code to Android. This is a
+working list, and is not appropriate for general discussion. We ask that
+general discussion go to android-platform (and contributors to the Android
+kernel should go to android-kernel).</p>
<ul>
-<li>Subscribe using Google Groups: <a href="https://groups.google.com/forum/?fromgroups#!forum/android-contrib">android-contrib</a></li>
-<li>Subscribe via email: <a href="mailto:android-contrib+subscribe@googlegroups.com">android-contrib</a></li>
+<li>Subscribe using Google Groups:
+<a href="https://groups.google.com/forum/?fromgroups#!forum/android-contrib">
+android-contrib</a></li>
+<li>Subscribe via email:
+<a href="mailto:android-contrib+subscribe@googlegroups.com">android-contrib</a>
+</li>
</ul>
</li>
<li>
<p><em>android-kernel</em>:
- This list is for deveopers who want to contribute to the Linux kernel that Android devices use. If you've downloaded the kernel code, if you know how to compile it, if you want to write kernel code to specifically support Android,
-this is your place. This group isn't for user-space topics (see android-platform for that), and people will shake their fingers at you and call you naughty if you ask user-space questions here.</p>
+This list is for developers who want to contribute to the Linux kernel used by
+Android devices. If you've downloaded the kernel code, know how to compile it,
+and want to write kernel code to support Android, this is your place. This
+group is <em>not</em> for user-space topics (see android-platform); people
+will shake their fingers at you and call you naughty if you ask user-space
+questions here.</p>
<ul>
-<li>Subscribe using Google Groups: <a href="https://groups.google.com/forum/?fromgroups#!forum/android-kernel">android-kernel</a></li>
-<li>Subscribe via email: <a href="mailto:android-kernel+subscribe@googlegroups.com">android-kernel</a></li>
+<li>Subscribe using Google Groups:
+<a href="https://groups.google.com/forum/?fromgroups#!forum/android-kernel">
+android-kernel</a></li>
+<li>Subscribe via email:
+<a href="mailto:android-kernel+subscribe@googlegroups.com">android-kernel</a>
+</li>
+</ul>
+<li>
+<p><em>android-ota</em>:
+This list is for developers working on the Android OTA system (the recovery
+image and the scripts that generate OTAs).</p>
+<ul>
+<li>Subscribe using Google Groups:
+<a href="https://groups.google.com/forum/?fromgroups#!forum/android-ota">
+android-ota</a></li>
+<li>Subscribe via email:
+<a href="mailto:android-ota+subscribe@googlegroups.com">android-ota</a></li>
</ul>
</li>
</ul>
-
<h3 id="audience">Audience</h3>
-<p>
-These discussion groups are intended for developers working with the Android platform. Everyone is welcome to join in, provided you follow our community's policies described below. Our users help each other, and many experts post to these groups, including members of the Open Handset Alliance.
-</p>
-<p>
-No topic is off-limits, provided it relates to Android in some way. However, since these are very busy lists, search the archives before posting your question; you may find your question has already been answered.
-</p>
+<p>These discussion groups are intended for developers working with the Android
+platform. Everyone is welcome to join in, provided you follow the community
+policies described below. Our users help each other, and many experts post to
+these groups, including members of the Open Handset Alliance.</p>
+<p>No topic is off-limits, provided it relates to Android in some way. However,
+since these are very busy lists, search the archives before posting your
+question; you may find your question has already been answered.</p>
<h3 id="getting-the-most-from-our-lists">Getting the Most from Our Lists</h3>
<p>Please consider the following before you post to our lists.</p>
<ul>
<li>
-<p><em>Read the <a href="#mailing">Charter for our forums.</a></em> This explains the (few) rules and guidelines for our community.</p>
+<p><em>Read the <a href="#mailing">Charter for our forums.</a></em> This
+explains the (few) rules and guidelines for our community.</p>
</li>
<li>
-<p><em>Search the group archives to see whether your questions have already been discussed.</em> This avoids time-wasting redundant discussions.</p>
+<p><em>Search the group archives to see whether your questions have already
+been discussed.</em> This avoids time-wasting redundant discussions.</p>
</li>
<li>
-<p><em>Use a clear, relevant message subject.</em> This helps everyone, both those trying to answer your question as well as those who may be looking for information in the future.</p>
+<p><em>Use a clear, relevant message subject.</em> This helps everyone, both
+those trying to answer your question as well as those who may be looking for
+information in the future.</p>
</li>
<li>
-<p><em>Give plenty of details in your post.</em> Code or log snippets, pointers to screenshots, and similar details will get better results and make for better discussions. For a great guide to phrasing your questions, read <a href="http://www.catb.org/%7Eesr/faqs/smart-questions.html">How to Ask Questions the Smart Way</a>.</p>
+<p><em>Give plenty of details in your post.</em> Code or log snippets,
+pointers to screenshots, and similar details will get better results and make
+for better discussions. For a great guide to phrasing your questions, read
+<a href="http://www.catb.org/%7Eesr/faqs/smart-questions.html">How to Ask
+Questions the Smart Way</a>.</p>
</li>
</ul>
<h3 id="mailing">Mailing list rules</h3>
-<p>We love simplicity and hate restrictions, so we keep our policies minimal. The rules
-below describe what's expected of subscribers to the Android mailing lists.</h2>
+<p>We love simplicity and hate restrictions, so we keep our policies minimal.
+The rules below describe what's expected of subscribers to the Android mailing
+lists.</h2>
<ul>
- <li><em>Please be friendly</em>: Showing courtesy and respect to others is a vital part of the Android culture, and we expect everyone participating in the Android community to join us in accepting nothing less. Being courteous does not mean we can't constructively disagree with each other, but it does mean that we must be polite when we do so. There's never a reason to be antagonistic or dismissive toward anyone; if you think there is, think again before you post. Mobile development is serious business, but it's also a lot of fun. Let's keep it that way. Let's strive to be one of the friendliest communities in all of open source.
- </li>
- <li><em>Allowed discussion topics</em>: Most of our groups are for technical discussions of Android or users helping each other. Generally we don't put hard restrictions on the topics discussed in the group: as long as the topic is relevant to Android in some way, it's welcome on our groups. We welcome announcements and discussion of products, libraries, publications, and other interesting Android-related news, but please do not cross-post. Post only to the most relevant group for your message. We even welcome (polite!) discussion of articles and ideas critical of Android--after all, we can't improve if we don't listen.
- </li>
- <li><em>Working Lists</em>: Some of our groups are considered "working lists", by which we mean that the list is intended to be used in support of the completion of specific tasks. On these groups, we don't welcome off-topic conversations, and will generally ask you to take general discussions to a different list. Since these are lists where people are trying to get work done, we will be pretty aggressive about keeping the noise level low. We ask that you respect our contributors' time and keep general discussions to appropriate lists.
- </li>
- <li><em>Spam</em>: We hate spam almost as passionately as we love courtesy and respect, so we reserve the right to limit discussions that amount to spam. Outright spam will result in the spammer being immediately and permanently banned from the list.
- </li>
+<li><em>Please be friendly</em>: Showing courtesy and respect to others is a
+vital part of the Android culture, and we expect everyone participating in the
+Android community to join us in accepting nothing less. Being courteous does
+not mean we can't constructively disagree with each other, but it does mean
+that we must be polite when we do so. There's never a reason to be
+antagonistic or dismissive toward anyone; if you think there is, think again
+before you post. Mobile development is serious business, but it's also a lot
+of fun. Let's keep it that way. Let's strive to be one of the friendliest
+communities in all of open source.
+</li>
+<li><em>Allowed discussion topics</em>: Most of our groups are for technical
+discussions of Android or users helping each other. Generally we don't put
+hard restrictions on the topics discussed in the group: as long as the topic
+is relevant to Android in some way, it's welcome on our groups. We welcome
+announcements and discussion of products, libraries, publications, and other
+interesting Android-related news, but please do not cross-post. Post only to
+the most relevant group for your message. We even welcome (polite!) discussion
+of articles and ideas critical of Android—after all, we can't improve if
+we don't listen.
+</li>
+<li><em>Working Lists</em>: Some of our groups are considered "working lists",
+by which we mean that the list is intended to be used in support of the
+completion of specific tasks. On these groups, we don't welcome off-topic
+conversations, and will generally ask you to take general discussions to a
+different list. Since these are lists where people are trying to get work
+done, we will be pretty aggressive about keeping the noise level low. We ask
+that you respect our contributors' time and keep general discussions to
+appropriate lists.
+</li>
+<li><em>Spam</em>: We hate spam almost as passionately as we love courtesy and
+respect, so we reserve the right to limit discussions that amount to spam.
+Outright spam will result in the spammer being immediately and permanently
+banned from the list.
+</li>
</ul>
-<p>
-The most important rule is friendliness. Remember: disrespect and rudeness are not welcome in our community under any circumstances. We don't have a formal policy on dealing with troublemakers, and we hope we never need one. That said, we do pledge to do our best to be fair, and we will always try to warn someone before banning him or her.
-</p>
+<p>The most important rule is friendliness. Remember: disrespect and rudeness
+are not welcome in our community under any circumstances. We don't have a
+formal policy on dealing with troublemakers, and we hope we never need one.
+That said, we do pledge to do our best to be fair, and we will always try to
+warn someone before banning him or her.</p>
+
<h3 id="contacting">Contacting the moderators</h3>
-<p>
-If you see anyone being rude, call them out on it. This is your group too, and you don't have to accept someone else being disrespectful just because it wasn't directed at you. Just remember to be polite and courteous yourself! Don't add fuel to the fire.
-</p>
-<p>
-But if you see an outrageous violation, want to report spam, feel very strongly about something, or even if you just want to chat, then contact the mailing list's owners. It's what we're here for!
-</p>
-
-
+<p>If you see anyone being rude, call them out on it. This is your group too,
+and you don't have to accept someone else being disrespectful just because it
+wasn't directed at you. Just remember to be polite and courteous yourself!
+Don't add fuel to the fire.</p>
+<p>But if you see an outrageous violation, want to report spam, feel strongly
+about something, or just want to chat, then contact the mailing list owners.
+It's what we're here for!</p>
<h3 id="using-email-with-google-groups">Using email with Google Groups</h3>
-<p>Instead of using the <a href="https://groups.google.com/">Google groups</a> site, you can use your email client of choice to participate in the mailing lists.</p>
-<p>To subscribe to a group without using the Google Groups site, use the link under "subscribe via email" in the lists above.</p>
+<p>Instead of using the <a href="https://groups.google.com/">Google groups</a>
+site, you can use your email client of choice to participate in the mailing
+lists. To subscribe to a group without using the Google Groups site, use the link
+under "subscribe via email" in the lists above.</p>
<p>To set up how you receive mailing list postings by email:</p>
<ol>
<li>
-<p>Sign into the group via the Google Groups site. For example, for the android-platform group you would use [https://groups.google.com/forum/?fromgroups#!forum/android-platform].</p>
+<p>Sign into the group via the Google Groups site. For example, for the
+android-platform group you would use
+<a href="https://groups.google.com/forum/?fromgroups#!forum/android-platform">
+https://groups.google.com/forum/?fromgroups#!forum/android-platform</a>.</p>
</li>
<li>
<p>Click "My membership" on the right side.</p>
@@ -138,33 +226,36 @@
</li>
</ol>
<h2 id="android-on-irc">Android on IRC</h2>
-<p>We also have a presence on IRC via <a href="http://freenode.net/">freenode</a>.
-We maintain two official IRC channels on <a href="irc://irc.freenode.net/">irc.freenode.net</a> (access via the web
-at <a href="http://webchat.freenode.net/">freenode webchat</a>)</p>
+<p>Android has a presence on IRC via
+<a href="http://freenode.net/">freenode</a>. We maintain two official IRC
+channels on <a href="irc://irc.freenode.net/">irc.freenode.net</a> (access via
+the web at <a href="http://webchat.freenode.net/">freenode webchat</a>)</p>
<ul>
<li>
-<p><a href="irc://irc.freenode.net/android">#android</a> - dedicated to general Android discussion and porting concerns</p>
+<p><a href="irc://irc.freenode.net/android">#android</a> - dedicated to
+general Android discussion and porting concerns</p>
</li>
<li>
<p><a href="irc://irc.freenode.net/android-dev">#android-dev</a> - dedicated to discussion about writing Android applications</p>
</li>
</ul>
-<p>The channels above are official. There are a few other channels the
-community is using, but are not official. These aren't official or officially
-moderated/managed, so you use the channels below at your own risk. The Open
-Handset Alliance doesn't endorse these channels, there's no warranty express
-or implied, and so on. There may be more channels than just these listed.</p>
+<p>The community also uses several <em>unofficial</em> channels that are not not officially moderated or managed. The Open Handset Alliance does not endorse unofficial channels and there's no warranty express or implied, so use them at your own risk. Here's a list of a few unofficial channels (many more may exist):</p>
+
<ul>
<li>
-<p><a href="irc://irc.freenode.net/android-firehose">#android-firehose</a> - displays in real-time the commits to the Android Open Source Project</p>
+<p><a href="irc://irc.freenode.net/android-firehose">#android-firehose</a> -
+displays in real-time the commits to the Android Open Source Project</p>
</li>
<li>
-<p><a href="irc://irc.freenode.net/android-fr">#android-fr</a> - pour discuter d'Android en français</p>
+<p><a href="irc://irc.freenode.net/android-fr">#android-fr</a> - pour discuter
+d'Android en français</p>
</li>
<li>
-<p><a href="irc://irc.freenode.net/android-offtopic">#android-offtopic</a> - for, well, off-topic discussions</p>
+<p><a href="irc://irc.freenode.net/android-offtopic">#android-offtopic</a> -
+for, well, off-topic discussions</p>
</li>
<li>
-<p><a href="irc://irc.freenode.net/android-root">#android-root</a> - for discussion related to off-label uses of hardware</p>
+<p><a href="irc://irc.freenode.net/android-root">#android-root</a> - for
+discussion related to off-label uses of hardware</p>
</li>
-</ul>
+</ul>
\ No newline at end of file
diff --git a/src/source/developing.jd b/src/source/developing.jd
index e6a97b5..0bbafe2 100644
--- a/src/source/developing.jd
+++ b/src/source/developing.jd
@@ -41,6 +41,12 @@
<div style="float:right">
<img src="{@docRoot}images/submit-patches-0.png" alt="basic workflow diagram">
</div>
+<div class="figure" style="width:200px">
+ <img src="{@docRoot}images/submit-patches-0.png" alt="basic workflow diagram" height="153px" />
+ <p class="img-caption">
+ <strong>Figure 1.</strong> Basic Android workflow
+ </p>
+</div>
<p>The basic pattern of interacting with the repositories is as follows:</p>
<ol>
@@ -157,4 +163,7 @@
</code></pre>
<p>Deleting a client will <em>permanently delete</em> any changes you have not yet uploaded for review.</p>
<h2 id="git-and-repo-cheatsheet">Git and Repo cheatsheet</h2>
-<p><img src="{@docRoot}images/git-repo-1.png" alt="list of basic git and repo commands"></p>
+<img src="{@docRoot}images/git-repo-1.png" alt="list of basic git and repo commands" id="figure2" />
+<p class="img-caption">
+ <strong>Figure 2.</strong> Basic git and repo commands
+</p>
diff --git a/src/source/downloading.jd b/src/source/downloading.jd
index 10b8d0e..ee65cbb 100644
--- a/src/source/downloading.jd
+++ b/src/source/downloading.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2014 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.
@@ -100,7 +100,7 @@
$ repo init -u https://android.googlesource.com/platform/manifest
</pre>
<p>
- To check out a branch other than "master", specify it with -b:
+ To check out a branch other than "master", specify it with <code>-b</code>. For a list of branches, see <a href="build-numbers.html#source-code-tags-and-builds">Source Code Tags and Builds</a>.
</p>
<pre>
$ repo init -u https://android.googlesource.com/platform/manifest -b android-4.0.1_r1
@@ -151,9 +151,9 @@
for each user, regardless of the IP address.
</p>
<p>
- The first step is to create a password from <a href=
- "https://android.googlesource.com/new-password">the password generator</a> and to save it in
- <code>~/.netrc</code> according to the instructions on that page.
+ The first step is to create a password with <a href=
+ "https://android.googlesource.com/new-password">the password generator</a>
+ and follow the instructions on the password generator page.
</p>
<p>
The second step is to force authenticated access, by using the following manifest URI:
@@ -196,9 +196,8 @@
</p>
<p>
These instructions assume that the mirror is created in <code>/usr/local/aosp/mirror</code>.
- The first step is to create and sync the mirror itself, which uses close to 13GB of network
- bandwidth and a similar amount of disk space. Notice the <code>--mirror</code> flag, which
- can only be specified when creating a new client:
+ The first step is to create and sync the mirror itself. Notice the <code>--mirror</code> flag, which
+ can be specified only when creating a new client:
</p>
<pre>
$ mkdir -p /usr/local/aosp/mirror
diff --git a/src/source/index.jd b/src/source/index.jd
index c0a4a3e..34531f0 100644
--- a/src/source/index.jd
+++ b/src/source/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2014 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.
@@ -22,17 +22,23 @@
open software platform available for carriers, OEMs, and developers to make
their innovative ideas a reality and to introduce a successful,
real-world product that improves the mobile experience for users.
+</p>
+<p>
We also wanted to make sure there was
no central point of failure, where one industry player could restrict or
control the innovations of any other. The result is a full, production-quality
consumer product with source code open for customization and porting.
</p>
+<div class="figure" style="width:700px">
+ <img src="{@docRoot}images/android_framework_details.png" alt="Android framework details" height="483px" />
+ <p class="img-caption">
+ <strong>Figure 1.</strong> Android stack
+ </p>
+</div>
-
-
-<h2 id="governance-philosophy">Governance Philosophy</h2
+<h2 id="governance-philosophy">Governance Philosophy</h2>
<p>Android was originated by a group of companies known as the Open
Handset Alliance, led by Google. Today, many companies -- both original members
of the OHA and others -- have invested heavily in Android. These companies have
diff --git a/src/source/initializing.jd b/src/source/initializing.jd
index 3283575..829a975 100644
--- a/src/source/initializing.jd
+++ b/src/source/initializing.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -27,9 +27,6 @@
<p>This section describes how to set up your local work environment to build
the Android source files. You will need to use Linux or Mac OS. Building under
Windows is not currently supported.</p>
-<p><strong>Note</strong>: The source download is approximately 8.5GB in size.
-You will need over 30GB free to complete a single build, and
-up to 100GB (or more) for a full set of builds.</em></p>
<p>For an overview of the entire code-review and code-update process, see <a
href="life-of-a-patch.html">Life of a Patch</a>.</p>
<h2 id="choosing-a-branch">Choosing a Branch</h2>
@@ -37,29 +34,25 @@
version of the source code you plan to compile. See
<a href="build-numbers.html">Build Numbers</a> for a full listing of branches you may
choose from. You may also choose to download and build the latest source code
-(called "master"), in which case you will simply omit the branch specification
+(called <code>master</code>), in which case you will simply omit the branch specification
when you initialize the repository.</p>
<p>Once you have selected a branch, follow the appropriate instructions below to
set up your build environment.</p>
<h2 id="setting-up-a-linux-build-environment">Setting up a Linux build environment</h2>
-<p>These instructions apply to all branches, including master.</p>
+<p>These instructions apply to all branches, including <code>master</code>.</p>
<p>The Android build is routinely tested in house on recent versions of
-Ubuntu LTS (12.04), but most distributions should have the required
+Ubuntu LTS (14.04), but most distributions should have the required
build tools available. Reports of successes or failures on other
distributions are welcome.</p>
-<p>For Gingerbread (2.3.x) and newer versions, including the master
+<p>For Gingerbread (2.3.x) and newer versions, including the <code>master</code>
branch, a 64-bit environment is required. Older versions can be
compiled on 32-bit systems.</p>
-<p><strong>Note</strong>: 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.</p>
-<p>See the <a href="building.html">Downloading and Building</a> page for the
-list of hardware and software requirements. Then follow the detailed
-instructions for Ubuntu and MacOS below.</p>
+<p><strong>Note</strong>: See the <a href="building.html">Downloading and
+Building</a> page for the list of hardware and software requirements. Then
+follow the detailed instructions for Ubuntu and Mac OS below.</p>
<h3 id="installing-the-jdk">Installing the JDK</h3>
-<p>The master branch of Android in the <a
+<p>The <code>master</code> branch of Android in the <a
href="https://android.googlesource.com/">Android Open Source Project (AOSP)</a>
requires Java 7. On Ubuntu, use <a href="http://openjdk.java.net/install/">OpenJDK</a>.</p>
<p>Java 7: For the latest version of Android</p>
@@ -84,9 +77,12 @@
<p><strong>Note</strong>: The <code>lunch</code> command in the build step will ensure that the Sun JDK is
used instead of any previously installed JDK.</p>
+<h3 id="installing-required-packages-ubuntu-1404">Installing required packages (Ubuntu 14.04)</h3>
+<p>You will need a 64-bit version of Ubuntu. Ubuntu 14.04 is recommended.</p>
+<pre><code>$ sudo apt-get install bison g++-multilib git gperf libxml2-utils make zlib1g-dev:i386 zip</code></pre>
+
<h3 id="installing-required-packages-ubuntu-1204">Installing required packages (Ubuntu 12.04)</h3>
-<p>You will need a 64-bit version of Ubuntu. Ubuntu 12.04 is recommended.
-Building using an older version of Ubuntu is not supported on master or recent releases.</p>
+<p>You may use Ubuntu 12.04 to build older versions of Android. Version 12.04 is not supported on master or recent releases.</p>
<pre><code>$ sudo apt-get install git gnupg flex bison gperf build-essential \
zip curl libc6-dev libncurses5-dev:i386 x11proto-core-dev \
libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-glx:i386 \
@@ -95,15 +91,10 @@
$ sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so
</code></pre>
-<h3 id="installing-required-packages-ubuntu-1404">Installing required packages (Ubuntu 14.04)</h3>
-<p>Building on Ubuntu 14.04 is experimental at the moment but will eventually become the recommended
-environment.</p>
-<pre><code>$ sudo apt-get install bison g++-multilib git gperf libxml2-utils</code></pre>
-
<h3 id="installing-required-packages-ubuntu-1004-1110">Installing required packages (Ubuntu 10.04 -- 11.10)</h3>
<p>Building on Ubuntu 10.04-11.10 is no longer supported, but may be useful for building older
releases of AOSP.</p>
-<pre><code>$ sudo apt-get install git-core gnupg flex bison gperf build-essential \
+<pre><code>$ sudo apt-get install git 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 \
@@ -116,7 +107,7 @@
<pre><code>$ sudo apt-get install libx11-dev:i386
</code></pre>
<h3 id="configuring-usb-access">Configuring USB Access</h3>
-<p>Under GNU/linux systems (and specifically under Ubuntu systems),
+<p>Under GNU/Linux systems (and specifically under Ubuntu systems),
regular users can't directly access USB devices by default. The
system needs to be configured to allow such access.</p>
<p>The recommended approach is to create a file
@@ -164,33 +155,9 @@
back into the computer.</p>
<p>This is known to work on both Ubuntu Hardy Heron (8.04.x LTS) and
Lucid Lynx (10.04.x LTS). Other versions of Ubuntu or other
-variants of GNU/linux might require different configurations.</p>
-<p><a name="ccache"></a></p>
-<h3 id="setting-up-ccache">Setting up ccache</h3>
-<p>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.</p>
-<p>Put the following in your .bashrc or equivalent.</p>
-<pre><code>export USE_CCACHE=1
-</code></pre>
-<p>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.</p>
-<pre><code>export CCACHE_DIR=<path-to-your-cache-directory>
-</code></pre>
-<p>The suggested cache size is 50-100GB.
-You will need to run the following command once you have downloaded
-the source code:</p>
-<pre><code>prebuilts/misc/linux-x86/ccache/ccache -M 50G
-</code></pre>
-<p>When building Ice Cream Sandwich (4.0.x) or older, ccache is in
-a different location:</p>
-<pre><code>prebuilt/linux-x86/ccache/ccache -M 50G
-</code></pre>
-<p>This setting is stored in the CCACHE_DIR and is persistent.</p>
+variants of GNU/Linux might require different configurations.</p>
<h3 id="using-a-separate-output-directory">Using a separate output directory</h3>
-<p>By default, the output of each build is stored in the out/
+<p>By default, the output of each build is stored in the <code>out/</code>
subdirectory of the matching source tree.</p>
<p>On some machines with multiple storage devices, builds are
faster when storing the source files and the output on
@@ -214,59 +181,85 @@
as those would end up sharing an output directory, with
unpredictable results.</p>
<p>This is only supported on Jelly Bean (4.1) and newer,
-including the master branch.</p>
-<h2 id="setting-up-a-mac-os-x-build-environment">Setting up a Mac OS X build environment</h2>
-<p>In a default installation, OS X runs on a case-preserving but case-insensitive
+including the <code>master</code> branch.</p>
+<h2 id="setting-up-a-mac-os-x-build-environment">Setting up a Mac OS build environment</h2>
+<p>In a default installation, Mac OS runs on a case-preserving but case-insensitive
filesystem. This type of filesystem is not supported by git and will cause some
-git commands (such as "git status") to behave abnormally. Because of this, we
+git commands (such as <code>git status</code>) to behave abnormally. Because of this, we
recommend that you always work with the AOSP source files on a case-sensitive
filesystem. This can be done fairly easily using a disk image, discussed below.</p>
-<p>Once the proper filesystem is available, building the master branch in a modern
-OS X environment is very straightforward. Earlier branches, including ICS,
+<p>Once the proper filesystem is available, building the <code>master</code> branch in a modern
+Mac OS environment is very straightforward. Earlier branches, including ICS,
require some additional tools and SDKs.</p>
<h3 id="creating-a-case-sensitive-disk-image">Creating a case-sensitive disk image</h3>
-<p>You can create a case-sensitive filesystem within your existing OS X environment
+<p>You can create a case-sensitive filesystem within your existing Mac OS environment
using a disk image. To create the image, launch Disk
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
+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.</p>
<p>You can also create it from a shell with the following command:</p>
<pre><code># hdiutil create -type SPARSE -fs 'Case-sensitive Journaled HFS+' -size 40g ~/android.dmg
</code></pre>
-<p>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 <code>~/.bash_profile</code> to mount the image when you execute "mountAndroid":</p>
+<p>This will create a <code>.dmg</code> (or possibly a <code>.dmg.sparsefile</code>) file which, once mounted, acts as a drive with the required formatting for Android development.
+<p>If you need a larger volume later, you can also resize the sparse image with the following command:</p>
+<pre><code># hdiutil resize -size <new-size-you-want>g ~/android.dmg.sparseimage
+</code></pre>
+For a disk image named <code>android.dmg</code> stored in your home directory, you can add helper functions to your <code>~/.bash_profile</code>:
+<ul>
+<li>
+To mount the image when you execute <code>mountAndroid</code>:</p>
<pre><code># mount the android file image
function mountAndroid { hdiutil attach ~/android.dmg -mountpoint /Volumes/android; }
</code></pre>
-<p>Once mounted, you'll do all your work in the "android" volume. You can eject it (unmount it) just like you would with an external drive.</p>
-<h3 id="master-branch">Master branch</h3>
-<p>To build the latest source in a Mac OS environment, you will need an Intel/x86
-machine running MacOS 10.8 (Mountain Lion), along with Xcode
-4.5.2 and Command Line Tools.</p>
-<p>You will also need the <a
-href="http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html">Java 7 JDK</a>.
-Select the file: jdk-7u51-macosx-x64.dmg</p>
+<p><strong>Note</strong>: If your system created a <code>.dmg.sparsefile</code> file, replace <code>~/android.dmg</code> with <code>~/android.dmg.sparsefile</code>.</p>
+</li>
+<li>
+<p>To unmount it when you execute <code>umountAndroid</code>:</p>
+<pre><code># unmount the android file image
+function umountAndroid() { hdiutil detach /Volumes/android; }
+</code></pre>
+</li>
+</ul>
+<p>Once you've mounted the <code>android</code> volume, you'll do all your work there. You can eject it (unmount it) just like you would with an external drive.</p>
+
+<h3 id="installing-the-mac-jdk">Installing the JDK</h3>
+<p>The <code>master</code> and <code>5.0.x</code> branches of Android in the <a
+href="https://android.googlesource.com/">Android Open Source Project (AOSP)</a>
+require Java 7. On Mac OS, use <a
+href="https://www.oracle.com/technetwork/java/javase/downloads/java-archive-downloads-javase7-521261.html#jdk-7u71-oth-JPR">jdk-7u71-macosx-x64.dmg</a>.</p>
<p>To develop for versions of Android Gingerbread through KitKat, download and
install the Java 6 version of the <a
href="http://support.apple.com/kb/dl1572">Java JDK</a>.</p>
-<h3 id="branch-40x-and-all-earlier-branches">Branch 4.2.x and earlier branches</h3>
+<h3 id="master-branch">Master branch</h3>
+<p>To build the latest source in a Mac OS environment, you will need an Intel/x86
+machine running Mac OS X v10.8 (Mountain Lion) or later, along with Xcode
+4.5.2 or later including the Command Line Tools.</p>
+
+<h3 id="branch-50x-and-all-earlier-branches">Branch 5.0.x and earlier branches</h3>
+<p>To build 5.0.x and earlier source in a Mac OS environment, you will need an Intel/x86
+machine running Mac OS X v10.8 (Mountain Lion), along with Xcode
+4.5.2 and Command Line Tools.</p>
+
+<h3 id="branch-44x-and-all-earlier-branches">Branch 4.4.x and earlier branches</h3>
<p>To build 4.2.x and earlier source in a Mac OS environment, you will need an Intel/x86
-machine running MacOS 10.6 (Snow Leopard) or MacOS 10.7 (Lion), along with Xcode
+machine running Mac OS X v10.6 (Snow Leopard) or Mac OS X v10.7 (Lion), along with Xcode
4.2 (Apple's Developer Tools). Although Lion does not come with a JDK, it should
install automatically when you attempt to build the source.</p>
-<p>The remaining sections for Mac OS X only apply to those who wish to build
+<p>The remaining sections for Mac OS apply only to those who wish to build
earlier branches.</p>
+
<h3 id="branch-40x-and-all-earlier-branches">Branch 4.0.x and all earlier branches</h3>
<p>To build android-4.0.x and earlier branches in a Mac OS environment, you need an
-Intel/x86 machine running MacOS 10.5 (Leopard) or MacOS 10.6 (Snow Leopard). You
-will need the MacOS 10.5 SDK.</p>
+Intel/x86 machine running Mac OS X v10.5 (Leopard) or Mac OS X v10.6 (Snow Leopard). You
+will need the Mac OS X v10.5 SDK.</p>
<h4 id="installing-required-packages">Installing required packages</h4>
<ul>
<li>
<p>Install Xcode from <a href="http://developer.apple.com/">the Apple developer site</a>.
-We recommend version 3.1.4 or newer, i.e. gcc 4.2.
+We recommend version 3.1.4 or newer (e.g., 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.</p>
@@ -277,12 +270,15 @@
<pre><code>export PATH=/opt/local/bin:$PATH
</code></pre>
<p><em>to your <code>~/.bash_profile</code>.</em></p>
+
+<p><strong>Note</strong>: If you do not have a <code>.bash_profile</code> file in your home directory, create one.</p>
+
</li>
<li>
<p>Get make, git, and GPG packages from MacPorts: </p>
-<pre><code>$ POSIXLY_CORRECT=1 sudo port install gmake libsdl git-core gnupg
+<pre><code>$ POSIXLY_CORRECT=1 sudo port install gmake libsdl git gnupg
</code></pre>
-<p>If using Mac OS 10.4, also install bison:</p>
+<p>If using Mac OS X v10.4, also install bison:</p>
<pre><code>$ POSIXLY_CORRECT=1 sudo port install bison
</code></pre>
</li>
@@ -315,11 +311,39 @@
</li>
</ul>
<h4 id="setting-a-file-descriptor-limit">Setting a file descriptor limit</h4>
-<p>On MacOS the default limit on the number of simultaneous file descriptors open is too low and a highly parallel build process may exceed this limit.<br />
+<p>On Mac OS, the default limit on the number of simultaneous file descriptors open is too low and a highly parallel build process may exceed this limit.<br />
</p>
<p>To increase the cap, add the following lines to your <code>~/.bash_profile</code>: </p>
<pre><code># set the number of open files to be 1024
ulimit -S -n 1024
</code></pre>
+<h2 id="optimizing-a-build-environment">Optimizing a build environment (optional)</h2>
+<p><a name="ccache"></a></p>
+<h3 id="setting-up-ccache">Setting up ccache</h3>
+<p>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 use <code>make clean</code> often, or if you frequently
+switch between different build products.</p>
+<p>Put the following in your <code>.bashrc</code> (or equivalent):</p>
+<pre><code>export USE_CCACHE=1
+</code></pre>
+<p>By default the cache will be stored in <code>~/.ccache</code>.
+If your home directory is on NFS or some other non-local filesystem,
+you will want to specify the directory in your <code>.bashrc</code> file as well:</p>
+<pre><code>export CCACHE_DIR=<path-to-your-cache-directory>
+</code></pre>
+<p>The suggested cache size is 50-100GB.
+You will need to run the following command once you have downloaded
+the source code:</p>
+<pre><code>prebuilts/misc/linux-x86/ccache/ccache -M 50G
+</code></pre>
+<p>On Mac OS, you should replace <code>linux-x86</code> with <code>darwin-x86</code>:</p>
+<pre><code>prebuilts/misc/darwin-x86/ccache/ccache -M 50G
+</code></pre>
+<p>When building Ice Cream Sandwich (4.0.x) or older, ccache is in
+a different location:</p>
+<pre><code>prebuilt/linux-x86/ccache/ccache -M 50G
+</code></pre>
+<p>This setting is stored in the CCACHE_DIR and is persistent.</p>
<h2 id="next-download-the-source">Next: Download the source</h2>
<p>Your build environment is good to go! Proceed to <a href="downloading.html">downloading the source</a>.</p>
diff --git a/src/source/life-of-a-patch.jd b/src/source/life-of-a-patch.jd
index b0c821c..c16e63f 100644
--- a/src/source/life-of-a-patch.jd
+++ b/src/source/life-of-a-patch.jd
@@ -23,4 +23,7 @@
the steps below are performed in the web application.</p>
<p>For full instructions on how to get set up to use gerrit and git, please
see the <a href="submit-patches.html">Submitting Patches</a> page.</p>
-<p><img src="{@docRoot}images/workflow-0.png" alt="workflow diagram"/></p>
+<img src="{@docRoot}images/workflow-0.png" alt="workflow diagram" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> Patch workflow
+</p>
diff --git a/src/source/report-bugs.jd b/src/source/report-bugs.jd
index e0fcae9..fc5653e 100644
--- a/src/source/report-bugs.jd
+++ b/src/source/report-bugs.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -23,38 +23,41 @@
</ol>
</div>
</div>
-<p>Thanks for your interest in Android! One of the best ways you can help us
+
+<p>Thank you for your interest in Android! One of the best ways you can help us
improve Android is to let us know about any problems you find with it.</p>
-<p>First, though: if you think you've found a security vulnerability,
-<em>please don't use the forms below</em>. Using the public forms below may
+<h2 id="report-issues">Report Issues</h2>
+<p class="note"><strong>Note:</strong> For security vulnerabilities, please see
+<a href="{@docRoot}devices/tech/security/overview/updates-resources.html#reporting-security-issues">Reporting Security Issues</a>. If you think you've found
+a security vulnerability, <em>please don't use the forms below</em>. Using a public form may
allow anyone to see your report, which may put users at risk until the bug is
-fixed. Please visit
-<a href="{@docRoot}source/faqs.html">our
-security faq</a> for more information on reporting security vulnerabilities
-to the Android security team.</p>
-<p>Here's how to report non-security bugs:</p>
+fixed. Instead, please send an email detailing the issue to security@android.com.</p>
+<p>Here's how to report <strong>non-security</strong> bugs:</p>
<ul>
-<li>
+<li>
<p><a href="https://code.google.com/p/android/issues/advsearch">Search for
your bug</a> to see if anyone has already reported it. Don't forget to
search for all issues, not just open ones, as your issue might already
-have been reported and closed. To help find the most popular results,
+have been reported and closed. To help you find the most popular results,
sort the result by number of stars.</p>
</li>
<li>
<p>If you find your issue and it's important to you, star it! That's how we know which bugs are most important to fix.</p>
</li>
<li>
-<p>If no one's reported your bug, file the bug. You can use one of these templates:</p>
+<p>If no one has reported your bug, file the bug. You can use one of these templates:</p>
<ul>
<li>
-<p><a href="https://code.google.com/p/android/issues/entry?template=User%20bug%20report">Bug in your Device</a> - use this if you are a user reporting a bug in a device you own</p>
+<p><a href="https://code.google.com/p/android/issues/entry?template=User%20bug%20report">Bug in your Device</a> -
+use this if you are a user reporting a bug in a device you own</p>
</li>
<li>
-<p><a href="https://code.google.com/p/android/issues/entry?template=Developer%20bug%20report">Bug in the Software</a> - use this if you found a bug in the course of developing an app</p>
+<p><a href="https://code.google.com/p/android/issues/entry?template=Developer%20bug%20report">Bug in the Software</a> -
+use this if you found a bug in the course of developing an app</p>
</li>
<li>
-<p><a href="https://code.google.com/p/android/issues/entry?template=Feature%20request">Feature Request</a> - use this for a feature you'd like to see in a future verison</p>
+<p><a href="https://code.google.com/p/android/issues/entry?template=Feature%20request">Feature Request</a> -
+use this for a feature you'd like to see in a future verison</p>
</li>
</ul>
</li>
diff --git a/src/source/source_toc.cs b/src/source/source_toc.cs
index f1b54b6..84897f1 100644
--- a/src/source/source_toc.cs
+++ b/src/source/source_toc.cs
@@ -43,6 +43,7 @@
<li><a href="<?cs var:toroot ?>source/building-running.html">Building and Running</a></li>
<li><a href="<?cs var:toroot ?>source/building-devices.html">Building for Devices</a></li>
<li><a href="<?cs var:toroot ?>source/building-kernels.html">Building Kernels</a></li>
+ <li><a href="<?cs var:toroot ?>source/64-bit-builds.html">64-bit Build Instructions</a></li>
<li><a href="<?cs var:toroot ?>source/known-issues.html">Known Issues</a></li>
</ul>
</li>
diff --git a/src/source/submit-patches.jd b/src/source/submit-patches.jd
index c41de25..d78aabc 100644
--- a/src/source/submit-patches.jd
+++ b/src/source/submit-patches.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -30,7 +30,10 @@
<ul>
<li>
<p>Before you follow the instructions on this page, you need to <a href="{@docRoot}source/initializing.html">
-initialize your build environment</a> and <a href="{@docRoot}source/downloading.html">download the source</a>.</p>
+initialize your build environment</a>, <a
+href="{@docRoot}source/downloading.html">download the source</a>, <a
+href="https://android.googlesource.com/new-password">create a
+password</a>, and follow the instructions on the password generator page.</p>
</li>
<li>
<p>For details about Repo and Git, see the <a href="{@docRoot}source/developing.html">Developing</a> section.</p>
@@ -50,20 +53,12 @@
</ul>
<h1 id="for-contributors">For contributors</h1>
<h2 id="authenticate-with-the-server">Authenticate with the server</h2>
-<p>Before you can upload to Gerrit, you need to establish a password that
-will identify you with the server. You only need to do this once.</p>
-<ul>
-<li>
-<p>Sign in on the <a href="https://android-review.googlesource.com/">AOSP Gerrit Server</a>.</p>
-</li>
-<li>
-<p>Go to Settings -> HTTP Password -> Obtain Password</p>
-</li>
-<li>
-<p>Follow the instructions on the subsquent pages, and copy-paste your
-password in <code>~/.netrc</code>. If there are two password lines, copy both.</p>
-</li>
-</ul>
+<p>Before you can upload to Gerrit, you need to <a
+href="https://android.googlesource.com/new-password">establish a password</a>
+that will identify you with the server. Follow the instructions on the password
+generator page. You need to do this only once. See <a
+href="{@docRoot}source/downloading.html#using-authentication">Using
+Authentication</a> for additional details.</p>
<h2 id="start-a-repo-branch">Start a repo branch</h2>
<p>For each change you intend to make, start a new branch within the relevant git repository:</p>
<pre><code>$ repo start NAME .
@@ -120,7 +115,7 @@
</code></pre>
<p>This command first fetches the updates from the source server, then attempts to automatically rebase your HEAD onto the new remote HEAD.</p>
<p>If the automatic rebase is unsuccessful, you will have to perform a manual rebase.</p>
-<pre><code>$ git rebase master
+<pre><code>$ repo rebase
</code></pre>
<p>Using <code>git mergetool</code> may help you deal with the rebase conflict. Once you have successfully merged the conflicting files,</p>
<pre><code>$ git rebase --continue
diff --git a/src/source/using-eclipse.jd b/src/source/using-eclipse.jd
index 8f7a61b..4d78c42 100644
--- a/src/source/using-eclipse.jd
+++ b/src/source/using-eclipse.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2015 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.
@@ -40,7 +40,7 @@
chmod u+w .classpath
</code></pre>
<p>Now edit that copy of <code>.classpath</code>, if necessary.</p>
-<h3 id="increase-eclipses-memory-settings">Increase Eclipse's Memory Settings</h3>
+<h3 id="increase-eclipses-memory-settings">Increasing Eclipse's Memory Settings</h3>
<p>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 <code>eclipse.ini</code> file. On Apple OSX the eclipse.ini file is located at</p>
<pre><code>/Applications/eclipse/Eclipse.app/Contents/MacOS/eclipse.ini
</code></pre>
@@ -58,6 +58,7 @@
<p>Now start Eclipse:</p>
<pre><code>eclipse
</code></pre>
+<h3 id="create-project">Creating a project</h3>
<p>Now create a project for Android development:</p>
<ol>
<li>
@@ -73,7 +74,7 @@
<p>Pick a project name, "android" or anything you like.</p>
</li>
<li>
-<p>Select "Create project from existing source", enter the path to your Android root directory, and click Finish.</p>
+<p>Uncheck use default location, enter the path to your Android root directory, and click Finish.</p>
</li>
<li>
<p>Wait while it sets up the project. (You'll see a subtle progress meter in the lower right corner.)</p>
@@ -122,7 +123,7 @@
<p>Depending on which app(s) you include, you may also need to include <code>othersrc/main/java</code> directories under <code>android/dalvik/libcore</code>. Do this if you find you cannot build with the default set.</p>
<h2 id="eclipse-formatting">Eclipse formatting</h2>
<p>You can import files in <code>development/ide/eclipse</code> to make Eclipse
-follow the Android style rules. </p>
+follow the Android style rules.</p>
<ol>
<li>
<p>Select Window > Preferences > Java > Code Style.</p>
@@ -228,4 +229,6 @@
<p>Your application respects the package/directory structure.</p>
</li>
</ul>
-<p>If you're still having problems, please contact one of the Android mailing lists or IRC channels.</p>
+<p>If you're still having problems, please contact one of the <a
+href="{@docRoot}source/community/index.html">Android community mailing lists or
+IRC channels</a>.</p>
diff --git a/src/source/using-repo.jd b/src/source/using-repo.jd
index ce86c43..57a93c9 100644
--- a/src/source/using-repo.jd
+++ b/src/source/using-repo.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2014 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.
@@ -25,18 +25,25 @@
</div>
</div>
<p>Repo usage takes the following form: </p>
-<pre><code>repo COMMAND OPTIONS
+<pre><code>repo <em><COMMAND></em> <em><OPTIONS></em>
</code></pre>
-<p>Optional elements are shown in brackets [ ]. Once Repo is installed, you can get information about any command by running </p>
-<pre><code>repo help COMMAND
+<p>Optional elements are shown in brackets [ ]. For example, many commands take
+a project list as an argument. You can specify project-list as a list of names
+or a list of paths to local source directories for the projects:</p>
+<pre><code>repo sync [<em><PROJECT0></em> <em><PROJECT1></em> <em><PROJECTN></em>]
+repo sync [<em></PATH/TO/PROJECT0></em> ... <em></PATH/TO/PROJECTN></em>]
</code></pre>
-<p>Many commands take a project list as an argument. You can specify project-list as a list of names or a list of paths to local source directories for the projects:</p>
-<pre><code>repo sync [PROJECT0 PROJECT1 ... PROJECTN]
-repo sync [/PATH/TO/PROJECT0 ... /PATH/TO/PROJECTN]
+
+<h2 id="help">help</h2>
+<p>Once Repo is installed, you can find the latest documentation starting with a summary of all commands by running:</p>
+<pre><code>repo help
+</code></pre>
+<p>You can get information about any command by running this within a Repo tree:</p>
+<pre><code>repo help <em><COMMAND></em>
</code></pre>
<h2 id="init">init</h2>
-<pre><code>$ repo init -u URL [OPTIONS]
+<pre><code>$ repo init -u <em><URL></em> [<em><OPTIONS></em>]
</code></pre>
<p>Installs Repo in the current directory. This creates a <code>.repo/</code> directory that contains Git repositories for the Repo source code and the standard Android manifest files. The <code>.repo/</code> directory also contains <code>manifest.xml</code>, which is a symlink to the selected manifest in the <code>.repo/manifests/</code> directory.</p>
<p>Options:</p>
@@ -53,7 +60,7 @@
</ul>
<p><em>Note: For all remaining Repo commands, the current working directory must either be the parent directory of <code>.repo/</code> or a subdirectory of the parent directory.</em></p>
<h2 id="sync">sync</h2>
-<pre><code>repo sync [PROJECT_LIST]
+<pre><code>repo sync [<em><PROJECT_LIST></em>]
</code></pre>
<p>Downloads new changes and updates the working files in your local environment. If you run <code>repo sync</code> without any arguments, it will synchronize the files for all the projects.</p>
<p>When you run <code>repo sync</code>, this is what happens:</p>
@@ -64,9 +71,9 @@
<li>
<p>If the project has already been synchronized once, then <code>repo sync</code> is equivalent to:</p>
<pre><code>git remote update
-git rebase origin/BRANCH
+git rebase origin/<em><BRANCH></em>
</code></pre>
-<p>where <code>BRANCH</code> is the currently checked-out branch in the local project directory. If the local branch is not tracking a branch in the remote repository, then no synchronization will occur for the project.</p>
+<p>where <code><em><BRANCH></em></code> is the currently checked-out branch in the local project directory. If the local branch is not tracking a branch in the remote repository, then no synchronization will occur for the project.</p>
</li>
<li>
<p>If the git rebase operation results in merge conflicts, you will need to use the normal Git commands (for example, <code>git rebase --continue</code>) to resolve the conflicts.</p>
@@ -86,7 +93,7 @@
</li>
</ul>
<h2 id="upload">upload</h2>
-<pre><code>repo upload [PROJECT_LIST]
+<pre><code>repo upload [<em><PROJECT_LIST></em>]
</code></pre>
<p>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.</p>
<p>After you select one or more branches, all commits on the selected branches
@@ -105,14 +112,10 @@
<p>Make sure the updated branch is the currently checked out branch.</p>
</li>
<li>
-<p>Use <code>repo upload --replace PROJECT</code> to open the change matching editor.</p>
-</li>
-<li>
<p>For each commit in the series, enter the Gerrit change ID inside the brackets:</p>
<pre><code># Replacing from branch foo
[ 3021 ] 35f2596c Refactor part of GetUploadableBranches to lookup one specific...
[ 2829 ] ec18b4ba Update proto client to support patch set replacments
-[ 3022 ] c99883fe Teach 'repo upload --replace' how to add replacement patch se...
# Insert change numbers in the brackets to add a new patch set.
# To create a new change record, leave the brackets empty.
</code></pre>
@@ -120,11 +123,11 @@
</ul>
<p>After the upload is complete the changes will have an additional Patch Set.</p>
<h2 id="diff">diff</h2>
-<pre><code>repo diff [PROJECT_LIST]
+<pre><code>repo diff [<em><PROJECT_LIST></em>]
</code></pre>
<p>Shows outstanding changes between commit and working tree using <code>git diff</code>. </p>
<h2 id="download">download</h2>
-<pre><code>repo download TARGET CHANGE
+<pre><code>repo download <em><TARGET></em> <em><CHANGE></em>
</code></pre>
<p>Downloads the specified change from the review system and makes it available in your project's local working directory.</p>
<p>For example, to download <a href="https://android-review.googlesource.com/23823">change 23823</a> into your platform/frameworks/base directory:</p>
@@ -136,7 +139,7 @@
<code>repo download</code> will be able to find it for all users, because of replication
delays to all servers worldwide.</p>
<h2 id="forall">forall</h2>
-<pre><code>repo forall [PROJECT_LIST] -c COMMAND
+<pre><code>repo forall [<em><PROJECT_LIST></em>] -c <em><COMMAND></em>
</code></pre>
<p>Executes the given shell command in each project. The following additional environment variables are made available by <code>repo forall</code>:</p>
<ul>
@@ -169,18 +172,18 @@
</li>
</ul>
<h2 id="prune">prune</h2>
-<pre><code>repo prune [PROJECT_LIST]
+<pre><code>repo prune [<em><PROJECT_LIST></em>]
</code></pre>
<p>Prunes (deletes) topics that are already merged.</p>
<h2 id="start">start</h2>
-<pre><code>repo start BRANCH_NAME [PROJECT_LIST]
+<pre><code>repo start <em><BRANCH_NAME></em> [<em><PROJECT_LIST></em>]
</code></pre>
<p>Begins a new branch for development, starting from the revision specified in the manifest.</p>
-<p>The <code>BRANCH_NAME</code> argument should provide a short description of the change you are trying to make to the projects.If you don't know, consider using the name default.</p>
-<p>The <code>PROJECT_LIST</code> specifies which projects will participate in this topic branch. </p>
+<p>The <code><em><BRANCH_NAME></em></code> argument should provide a short description of the change you are trying to make to the projects.If you don't know, consider using the name default.</p>
+<p>The <code><em><PROJECT_LIST></em></code> specifies which projects will participate in this topic branch. </p>
<p><em>Note: "." is a useful shorthand for the project in the current working directory.</em></p>
<h2 id="status">status</h2>
-<pre><code>repo status [PROJECT_LIST]
+<pre><code>repo status [<em><PROJECT_LIST></em>]
</code></pre>
<p>Compares the working tree to the staging area (index) and the most recent commit on this branch (HEAD) in each project specified. Displays a summary line for each file where there is a difference between these three states.</p>
<p>To see the status for only the current branch, run <code>repo status</code>. The status information will be listed by project. For each file in the project, a two-letter code is used:</p>
