Merge L into AOSP
diff --git a/Doxyfile b/Doxyfile
index c01ff14..04f62f1 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -925,7 +925,7 @@
# If a relative path is entered the value of OUTPUT_DIRECTORY will be
# put in front of it. If left blank `html' will be used as the default path.
-HTML_OUTPUT = reference
+HTML_OUTPUT = halref
# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
@@ -944,13 +944,13 @@
# have to redo this when upgrading to a newer version of doxygen or when
# changing the value of configuration settings such as GENERATE_TREEVIEW!
-HTML_HEADER =
+HTML_HEADER = ./docs/source.android.com/hal_header.html
# The HTML_FOOTER tag can be used to specify a personal HTML footer for
# each generated HTML page. If it is left blank doxygen will generate a
# standard footer.
-HTML_FOOTER =
+HTML_FOOTER = ./docs/source.android.com/hal_footer.html
# The HTML_STYLESHEET tag can be used to specify a user-defined cascading
# style sheet that is used by each HTML page. It can be used to
@@ -969,7 +969,7 @@
# robust against future updates. Doxygen will copy the style sheet file to
# the output directory.
-HTML_EXTRA_STYLESHEET =
+HTML_EXTRA_STYLESHEET = ./docs/source.android.com/hal_doxygen.css
# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
# other source files which should be copied to the HTML output directory. Note
@@ -994,7 +994,7 @@
# the colors in the HTML output. For a value of 0 the output will use
# grayscales only. A value of 255 will produce the most vivid colors.
-HTML_COLORSTYLE_SAT = 100
+HTML_COLORSTYLE_SAT = 0
# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to
# the luminance component of the colors in the HTML output. Values below
@@ -1185,7 +1185,7 @@
# navigation tree you can set this option to NO if you already set
# GENERATE_TREEVIEW to YES.
-DISABLE_INDEX = NO
+DISABLE_INDEX = YES
# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
# structure should be generated to display hierarchical information.
@@ -1197,7 +1197,7 @@
# Since the tree basically has the same information as the tab index you
# could consider to set DISABLE_INDEX to NO when enabling this option.
-GENERATE_TREEVIEW = NO
+GENERATE_TREEVIEW = YES
# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values
# (range [0,1..20]) that doxygen will group on one line in the generated HTML
diff --git a/DoxygenLayout.xml b/DoxygenLayout.xml
index f264386..4b6ad40 100644
--- a/DoxygenLayout.xml
+++ b/DoxygenLayout.xml
@@ -2,7 +2,7 @@
<!-- Generated by doxygen 1.8.3.1 -->
<!-- Navigation index tabs for HTML output -->
<navindex>
- <tab type="mainpage" visible="yes" title="" intro="fdsfds"/>
+ <tab type="mainpage" visible="yes" title="" intro=""/>
<tab type="pages" visible="yes" title="" intro=""/>
<tab type="modules" visible="yes" title="" intro=""/>
<tab type="namespaces" visible="yes" title="">
@@ -18,7 +18,7 @@
<tab type="filelist" visible="yes" title="" intro=""/>
<tab type="globals" visible="yes" title="" intro=""/>
</tab>
- <tab type="user" url="/devices/index.html" title="Back to source.android.com">
+ <tab type="user" url="/devices/tech/index.html" title="Devices on source.android.com">
</tab>
</navindex>
diff --git a/hal_doxygen.css b/hal_doxygen.css
new file mode 100644
index 0000000..a3e7d9c
--- /dev/null
+++ b/hal_doxygen.css
@@ -0,0 +1,43 @@
+.title {
+ color:#333;
+ font-size: 34px;
+ margin: 36px 0 27px;
+ padding:0 0 10px;
+ font-weight:300;
+}
+
+#header {
+ padding: 1.2em 0 0.2em 0;
+ margin: 10px 120px;
+}
+
+a:hover,
+acronym:hover {
+ color: #7aa1b0 !important; }
+
+a:link, a:visited {
+ color: #258aaf;
+ text-decoration: none;
+}
+
+a:focus, a:hover, a:active {
+ color: #33b5e5;
+ text-decoration: none;
+}
+
+a.toptab {
+ color: #333;
+ font-size: 16px;
+}
+
+a.devices {
+ color: #F80;
+ font-size: 16px;
+}
+
+hr.light {
+ border: 0;
+ height: 0;
+ border-top: 1px solid rgba(0, 0, 0, 0.1);
+ border-bottom: 1px solid rgba(255, 255, 255, 0.3);
+}
diff --git a/hal_footer.html b/hal_footer.html
new file mode 100644
index 0000000..2ad5ca3
--- /dev/null
+++ b/hal_footer.html
@@ -0,0 +1,22 @@
+<!-- HTML footer for doxygen 1.8.4-->
+<!-- start footer part -->
+<!--BEGIN GENERATE_TREEVIEW-->
+<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
+ <ul>
+ $navpath
+ <li class="footer">$generatedby
+ <a href="/index.html">
+ <img class="footer" src="/images/Android_Robot_100.png" alt="Android"/></a> $doxygenversion </li>
+ </ul>
+</div>
+<!--END GENERATE_TREEVIEW-->
+<!--BEGIN !GENERATE_TREEVIEW-->
+<hr class="footer"/><address class="footer"><small>
+$generatedby  <a href="/index.html">
+<img class="footer"
+src="/images/Android_Robot_100.png" alt="Android"/>
+</a> $doxygenversion
+</small></address>
+<!--END !GENERATE_TREEVIEW-->
+</body>
+</html>
diff --git a/hal_header.html b/hal_header.html
new file mode 100644
index 0000000..dc4e671
--- /dev/null
+++ b/hal_header.html
@@ -0,0 +1,46 @@
+<!-- HTML header for doxygen 1.8.4-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
+<meta http-equiv="X-UA-Compatible" content="IE=9"/>
+<meta name="generator" content="Doxygen $doxygenversion"/>
+<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
+<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
+<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
+<script type="text/javascript" src="//www.gstatic.com/external_hosted/source_android_com/sac_doxygen_jquery.js"></script>
+<script type="text/javascript" src="$relpath^dynsections.js"></script>
+$treeview
+$search
+$mathjax
+<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
+$extrastylesheet
+<script type="text/javascript">
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-45455297-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+</script>
+</head>
+<body>
+<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
+
+ <div id="header">
+ <table width=80%>
+ <tr>
+ <td><a href="/index.html"><img src="/assets/images/sac_logo.png" width="123" height="25" alt="Android Developers" /></td>
+ <td><a class=toptab href="/source/index.html">Source</a></td>
+ <td><a class=devices href="/devices/index.html">Devices</a></td>
+ <td><a class=toptab href="/accessories/index.html">Accessories</a></td>
+ <td><a class=toptab href="/compatibility/index.html">Compatibility</a></td>
+ <td width=20%>$searchbox</td>
+ </tr>
+ </table>
+ </div>
+<hr class=light>
+<!-- end header part -->
diff --git a/src/accessories/accessories_toc.cs b/src/accessories/accessories_toc.cs
index d1badbe..654ff7b 100644
--- a/src/accessories/accessories_toc.cs
+++ b/src/accessories/accessories_toc.cs
@@ -1,5 +1,5 @@
<!--
- 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 @@
<ul id="nav">
<!-- Accessories -->
<li class="nav-section">
- <div class="nav-section-header">
+<div class="nav-section-header">
<a href="<?cs var:toroot ?>accessories/index.html">
<span class="en">Overview</span>
</a>
@@ -25,17 +25,32 @@
<ul>
<li class="nav-section">
<div class="nav-section-header">
- <a href="<?cs var:toroot ?>accessories/protocol.html">
- <span class="en">Open Accessory Protocol</span>
+ <a href="<?cs var:toroot ?>accessories/audio.html">
+ <span class="en">Audio Accessories</span>
</a>
</div>
<ul>
+ <li><a href="<?cs var:toroot ?>accessories/headset-spec.html">Headset specification</a></li>
+ </ul>
+ </li>
+ <li class="nav-section">
+<div class="nav-section-header">
+ <a href="<?cs var:toroot ?>accessories/custom.html">
+ <span class="en">Custom Accessories</span>
+ </a>
+ </div>
+ <ul>
+ <li class="nav-section">
+ <div class="nav-section-header"><a href="<?cs var:toroot ?>accessories/protocol.html"><span class="en">Open Accessory Protocol</span>
+ </a>
+ </div>
+ <ul>
<li><a href="<?cs var:toroot ?>accessories/aoa2.html">Version 2.0</a></li>
<li><a href="<?cs var:toroot ?>accessories/aoa.html">Version 1.0</a></li>
</ul>
- </li>
- <li><a href="<?cs var:toroot ?>accessories/audio.html">Building Audio Accessories</a></li>
- <li><a href="<?cs var:toroot ?>accessories/custom.html">Building Custom Accessories</a></li>
+ </li>
+ </ul>
+ </li>
</li>
<!-- End Accessories -->
</ul>
diff --git a/src/accessories/audio.jd b/src/accessories/audio.jd
index 240f4ea..1674710 100644
--- a/src/accessories/audio.jd
+++ b/src/accessories/audio.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.
@@ -16,33 +16,40 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<p>In building an audio accessory, such as an audio dock or other playback device, you should
-consider how your accessory will connect with Android devices. In particular, you should decide
-if your accessory will use Universal Serial Bus (USB) or a Bluetooth connection to stream music or
-other audio content.</p>
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>In implementing an audio accessory, such as a headset, headphone amplifier,
+microphone, DAC/ADC, or dock, you should consider how your accessory will
+connect with Android devices. In particular, you should decide
+if your accessory will use wired a 3.5 mm headset connector, Universal Serial
+Bus (USB), or a Bluetooth connection to stream music or other audio content.</p>
+<h2 id="audio-over-35mm">Audio over 3.5 mm headset connector</h2>
+<p>Many Android-based devices include a 3.5 mm (“mini”) headset connector. In
+addition to the traditional stereo output and mono input features, the <a
+href="headset-spec.html">Wired audio headset specification</a> defines standard
+impedances and functions so a range of Android devices and headsets can inter-operate.</p>
+
<h2 id="audio-over-usb">Audio over USB</h2>
-<p>An accessory that connects with Android over USB connection must use the Android Open
-Accessory (AOA) protocol version 2.0. This version of the AOA protocol is supported on Android 4.1
-(API Level 16) and higher. Once an Android device connects to an accessory that supports this
-protocol, the Android system treats it as a standard audio output device and routes all audio to
-that accessory. No secondary software application is required on the Android device.</p>
-<p><strong>Note:</strong> Due to the low power output of Android devices, the Android Open Accessory
-Protocol requires that accessories act as a USB host, which means that the connecting accessory
-must power the bus.</p>
-<h3 id="next-steps">Next steps</h3>
-<p>To get started on building an audio accessory that uses a USB connection:</p>
-<ul>
-<li>Select a hardware platform or build a hardware device that can support USB host mode.</li>
-<li>Review the <a href="{@docRoot}accessories/aoa2.html">AOA 2.0 protocol</a> specification to understand
- how to implement this protocol on your accessory hardware.</li>
-<li>Review the ADK 2012 <a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware source code</a>
- (<code><adk-src>/adk2012/board/library/ADK2/</code>), which includes an example implementation
- of an audio playback accessory using a USB connection.</li>
-</ul>
-<p><strong>Note:</strong> The AOA 2.0 protocol also supports the
-<a href="{@docRoot}accessories/aoa2.html#hid-support">human interface device</a> (HID) protocol through a USB
-connection, enabling accessories such as audio docks to provide hardware play back controls such
-as pause, fast-forward or volume buttons.</p>
+<p>Android can use USB in several modes:</p>
+ <ul>
+ <li>debug
+ <li>accessory
+ <li>host
+ </ul>
+<p>In the traditional debug 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>
+
<h2 id="audio-over-bluetooth">Audio over Bluetooth</h2>
<p>An accessory that connects with Android over Bluetooth can use an Advanced Audio Distribution
Profile (A2DP) connection stream music for playback. Playing audio over a Bluetooth with A2DP is
@@ -67,4 +74,3 @@
<p><strong>Note:</strong> The ADK 2012 source code includes an open source Bluetooth stack that
is built for the Texas Instruments CC2564 chip, but can work with any Bluetooth chip that
implements a standard Host/Controller Interface (HCI).</p>
-
diff --git a/src/accessories/custom.jd b/src/accessories/custom.jd
index 3f84d50..560f182 100644
--- a/src/accessories/custom.jd
+++ b/src/accessories/custom.jd
@@ -1,8 +1,8 @@
-page.title=Building Custom Accessories
+page.title=Custom Accessories
@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.
@@ -16,6 +16,14 @@
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>An accessory for Android can be anything: keyboard, thermometer, robot, lighting control or
anything else you can imagine. Accessories for Android all have one thing in common; they all
connect to an Android device in some way. When starting out to build an accessory, you should
@@ -77,3 +85,27 @@
<p><strong>Note:</strong> The ADK 2012 source code includes an open source Bluetooth stack which
is built for the Texas Instruments CC2564 chip, but can work with any Bluetooth chip that
supports a standard Host/Controller Interface (HCI).</p>
+
+<h2 id="audio-over-usb">Connecting audio over USB</h2>
+<p>An accessory that connects with Android over USB connection may use the Android Open
+Accessory (AOA) protocol version 2.0. This version of the AOA protocol is supported on Android 4.1
+(API Level 16) and higher. Once an Android device connects to an accessory that supports this
+protocol, the Android system treats it as a standard audio output device and routes all audio to
+that accessory. No secondary software application is required on the Android device.</p>
+<p><strong>Note:</strong> Due to the low power output of Android devices, the Android Open Accessory
+Protocol requires that accessories act as a USB host, which means that the connecting accessory
+must power the bus.</p>
+<h3 id="next-steps">Next steps</h3>
+<p>To get started on building an audio accessory that uses a USB connection:</p>
+<ul>
+<li>Select a hardware platform or build a hardware device that can support USB host mode.</li>
+<li>Review the <a href="{@docRoot}accessories/aoa2.html">AOA 2.0 protocol</a> specification to understand
+ how to implement this protocol on your accessory hardware.</li>
+<li>Review the ADK 2012 <a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware source code</a>
+ (<code><adk-src>/adk2012/board/library/ADK2/</code>), which includes an example implementation
+ of an audio playback accessory using a USB connection.</li>
+</ul>
+<p><strong>Note:</strong> The AOA 2.0 protocol also supports the
+<a href="{@docRoot}accessories/aoa2.html#hid-support">human interface device</a> (HID) protocol through a USB
+connection, enabling accessories such as audio docks to provide hardware play back controls such
+as pause, fast-forward or volume buttons.</p>
diff --git a/src/accessories/headset-spec.jd b/src/accessories/headset-spec.jd
new file mode 100644
index 0000000..d87c19a
--- /dev/null
+++ b/src/accessories/headset-spec.jd
@@ -0,0 +1,682 @@
+page.title=Wired audio headset specification
+@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><em>Version 1.0</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
+sections beginning with the specifications for the headset
+accessory followed by the specifications for the mobile device.</p>
+
+<h2 id=headset_accessory_plug_specifications>Headset Accessory (Plug) Specifications</h2>
+
+<p>The requirements in the following section apply to the headset accessory.</p>
+
+<h3 id=functions>Functions</h3>
+
+<table>
+ <tr>
+ <th>
+<p><strong>Function</strong></p>
+</th>
+ <th>
+<p><strong>Accessory Support</strong></p>
+</th>
+ </tr>
+ <tr>
+ <td>
+<p>Stereo Audio Out</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Audio in (Mic)</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Ground</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ </tr>
+</table>
+
+<h3 id=control-function_mapping>Control-Function Mapping</h3>
+
+<table>
+ <tr>
+ <th>
+<p><strong>Control Function</strong></p>
+</th>
+ <th>
+<p><strong>Accessory Support</strong></p>
+</th>
+ <th>
+<p><strong>Description</strong></p>
+</th>
+ </tr>
+ <tr>
+ <td>
+<p>Function A</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>Play/pause/hook (Short Press), Trigger Assist (Long Press), Next (double press)</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Function B</p>
+</td>
+ <td>
+<p>Optional</p>
+</td>
+ <td>
+<p>Vol+</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Function C</p>
+</td>
+ <td>
+<p>Optional</p>
+</td>
+ <td>
+<p>Vol-</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Function D</p>
+</td>
+ <td>
+<p>Optional</p>
+</td>
+ <td>
+<p>Reserved (Nexus devices will use this reserved function to launch Google Now
+voice search)</p>
+</td>
+ </tr>
+</table>
+
+<p><strong>Assign functions to buttons as follows</strong>:</p>
+
+<ul>
+ <li> All one-button headsets must implement Function A.
+ <li> Headsets with multiple buttons must implement functions according to the
+following pattern:
+ <ul>
+ <li> 2 functions: A and D
+ <li> 3 functions: A, B, C
+ <li> 4 functions: A, B, C, D
+ </ul>
+</ul>
+
+<h3 id=mechanical>Mechanical</h3>
+
+<table>
+ <tr>
+ <th>
+<p><strong>Function</strong></p>
+</th>
+ <th>
+<p><strong>Accessory Support</strong></p>
+</th>
+ <th>
+<p><strong>Notes</strong></p>
+</th>
+ </tr>
+ <tr>
+ <td>
+<p>4 conductor 3.5mm plug</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>Ref: EIAJ-RC5325A standard</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>CTIA pinout order (LRGM)</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>Except in regions with legal requirements for OMTP pinout</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>OMTP pinout order (LRMG)</p>
+</td>
+ <td>
+<p>Optional</p>
+</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>
+<p>Microphone</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>Must not be obstructed when operating headset controls</p>
+</td>
+ </tr>
+</table>
+
+<h3 id=electrical>Electrical</h3>
+
+<table>
+ <tr>
+ <th>
+<p><strong>Function</strong></p>
+</th>
+ <th>
+<p><strong>Accessory Support</strong></p>
+</th>
+ <th>
+<p><strong>Description</strong></p>
+</th>
+ </tr>
+ <tr>
+ <td>
+<p>Ear speaker impedance</p>
+</td>
+ <td>
+<p><strong>16 ohms or higher</strong></p>
+</td>
+ <td>
+<p>Recommend 32 - 300 ohms</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Mic DC resistance</p>
+</td>
+ <td>
+<p><strong>1000 ohms or higher</strong></p>
+</td>
+ <td>
+<p>Mic characteristics must be compliant with section 5.4 “Audio Recording” of
+current Android Compatibility Definition Document (CDD)</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Control Function Equivalent impedance*</p>
+
+<p>*Total impedance from positive mic terminal to GND when button is pressed with
+2.2 V mic bias applied through 2.2 kOhm resistor</p>
+</td>
+ <td>
+<p><strong>0 ohm</strong></p>
+</td>
+ <td>
+<p>[Function A] Play/Pause/Hook</p>
+</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>
+<p><strong>240 ohm</strong> +/- 1% resistance</p>
+</td>
+ <td>
+<p>[Function B]</p>
+</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>
+<p><strong>470 ohm</strong> +/- 1% resistance</p>
+</td>
+ <td>
+<p>[Function C] </p>
+</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>
+<p><strong>135 ohm</strong> +/- 1% resistance</p>
+</td>
+ <td>
+<p>[Function D]</p>
+</td>
+ </tr>
+</table>
+
+<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>
+
+<h3 id=reference_headset_test_circuit_2>Reference Headset Test Circuit 2</h3>
+
+<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>
+
+<h2 id=mobile_device_jack_specifications>Mobile Device (Jack) Specifications</h2>
+
+<p class="caution"><strong>Caution:</strong> To achieve compatibility with the
+headset specification above, devices that include a 4 conductor 3.5mm audio
+jack must meet the following specifications. Please see the <em>Analog audio
+ports</em> section of the <a
+href="{@docRoot}compatibility/android-cdd.pdf">Android Compatibility Definition
+Document (CDD)</a> for Android compatibility requirements.</p>
+
+<p><strong>Headset Jack Functions</strong></p>
+<table>
+ <tr>
+ <th>
+<p><strong>Function</strong></p>
+</th>
+ <th>
+<p><strong>Device Support</strong></p>
+</th>
+ </tr>
+ <tr>
+ <td>
+<p>Stereo Audio Out</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Audio in (Mic)</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Ground</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ </tr>
+</table>
+
+<h3 id=software_mapping>Software mapping</h3>
+
+<table>
+ <tr>
+ <th>
+<p><strong>Function</strong></p>
+</th>
+ <th>
+<p><strong>Device Support</strong></p>
+</th>
+ <th>
+<p><strong>Description</strong></p>
+</th>
+ </tr>
+ <tr>
+ <td>
+<p>Function A control event </p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>input event KEY_MEDIA</p>
+
+<p>Android key KEYCODE_HEADSETHOOK</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Function D control event</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>input event KEY_VOICECOMMAND</p>
+
+<p>Android key KEYCODE_VOICE_ASSIST</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Function B control event</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>input event KEY_VOLUMEUP</p>
+
+<p>Android key VOLUME_UP</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Function C control event</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>input event KEY_VOLUMEDOWN</p>
+
+<p>Android key VOLUME_DOWN</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Headset insertion detection</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>input event SW_JACK_PHYSICAL_INSERT 7</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Headset type detection</p>
+</td>
+ <td>
+<p><strong>Mic</strong></p>
+</td>
+ <td>
+<p>input event SW_MICROPHONE_INSERT 4</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Headset type detection</p>
+</td>
+ <td>
+<p><strong>No Mic</strong></p>
+</td>
+ <td>
+<p>input event SW_HEADPHONE_INSERT 2</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Headset speaker impedance</p>
+</td>
+ <td>
+<p><strong>Required Headphone (low)</strong></p>
+</td>
+ <td>
+<p>Failure mode is to indicate headphones so that limitation would be on</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Headset speaker impedance</p>
+</td>
+ <td>
+<p><strong>Required Line In (high)</strong></p>
+</td>
+ <td>
+<p>input event SW_LINEOUT_INSERT 6</p>
+</td>
+ </tr>
+</table>
+
+<h3 id=mechanical11>Mechanical</h3>
+
+<table>
+ <tr>
+ <th>
+<p><strong>Function</strong></p>
+</th>
+ <th>
+<p><strong>Device Support</strong></p>
+</th>
+ <th>
+<p><strong>Description</strong></p>
+</th>
+ </tr>
+ <tr>
+ <td>
+<p>4 conductor 3.5mm jack</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>
+<p>CTIA pinout order (LRGM)</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>3 Pin & Mono Plug Compatible</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>OMTP pinout order (LRMG)</p>
+</td>
+ <td>
+<p>Optional but <strong>Strongly Recommended</strong></p>
+</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>
+<p>Headset detect sequence</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>Plug insert notification must only be triggered after all contacts on plug are
+touching their relevant segments. This will prevent unreliable headset
+detection due to slow insertion. </p>
+</td>
+ </tr>
+</table>
+
+<h3 id=electrical12>Electrical</h3>
+
+<h4 id=general>General</h4>
+
+<table>
+ <tr>
+ <th>
+<p><strong>Function</strong></p>
+</th>
+ <th>
+<p><strong>Device Support</strong></p>
+</th>
+ <th>
+<p><strong>Notes</strong></p>
+</th>
+ </tr>
+ <tr>
+ <td>
+<p>Minimum output voltage drive capacity </p>
+</td>
+ <td>
+<p>150mV </p>
+</td>
+ <td>
+<p>>= 150mV on 32 ohm</p>
+
+<p>Test conditions: EN50332-2</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Mic bias resistance </p>
+</td>
+ <td>
+<p>Required</p>
+</td>
+ <td>
+<p>Flexible on detection method used and microphone bias resistor selection.
+Require that all button resistance value ranges specified below be detected and
+related to their respective function</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Mic bias voltage</p>
+</td>
+ <td>
+<p>1.8V - 2.9V</p>
+</td>
+ <td>
+<p>To guarantee compatibility to common microphone capsules.</p>
+</td>
+ </tr>
+</table>
+
+<h4 id=function_impedance_and_threshold_detection>Function Impedance and Threshold Detection</h4>
+
+<p>Devices must detect the following resistor ladder on the accessories. The
+accessories will be tested to the standardized circuit diagram in the diagram
+illustrated earlier (Reference Headset Test Circuit) where the total impedance
+is measured from MIC terminal to GND when a button is pressed with 2.2V mic
+bias applied through 2.2 kOhm resistor. This is the same effective resistance
+as the button detection circuit with the microphone in parallel with the button
+resistor.</p>
+<table>
+ <tr>
+ <th>
+<p><strong>Button Impedance Level</strong></p>
+</th>
+ <th>
+<p><strong>Device Support</strong></p>
+</th>
+ <th>
+<p><strong>Notes</strong></p>
+</th>
+ </tr>
+ <tr>
+ <td>
+<p><strong>70 ohm or less</strong></p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>[Function A]</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p><strong>110 - 180 ohm </strong></p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>[Function D]</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p><strong>210 - 290 ohm</strong></p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>[Function B]</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p><strong>360 - 680 ohm </strong></p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>[Function C]</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p><strong>Headset speaker impedance level</strong></p>
+</td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>
+<p>Low Threshold Detection</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>Headphone (low) < 1 Kohm</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>High Threshold Detection</p>
+</td>
+ <td>
+<p><strong>Required</strong></p>
+</td>
+ <td>
+<p>Line In (high) > 5 Kohm</p>
+</td>
+ </tr>
+</table>
diff --git a/src/accessories/images/headset-circuit1.png b/src/accessories/images/headset-circuit1.png
new file mode 100644
index 0000000..c69df98
--- /dev/null
+++ 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
new file mode 100644
index 0000000..67bd5b4
--- /dev/null
+++ b/src/accessories/images/headset-circuit2.png
Binary files differ
diff --git a/src/accessories/index.jd b/src/accessories/index.jd
index adf3f5c..1157d5d 100644
--- a/src/accessories/index.jd
+++ b/src/accessories/index.jd
@@ -1,8 +1,8 @@
-page.title=Build Accessories for Android
+page.title=Accessories for Android
@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.
@@ -16,28 +16,27 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<p>Build compelling USB and Bluetooth Accessories to extend
- the capabilities of your user's Android-powered devices. Android defines an standard
- protocol that you can implement in your accessories and have it compatible with
- a wide range of Android-powered devices.
+<p>Implement compelling accessories to extend the capabilities of your users'
+Android-powered devices. Android relies on a suite of standard protocols you
+can implement in your accessories to be compatible with a wide range of
+Android-powered devices.
</p>
<div class="layout-content-row">
<div class="layout-content-col span-6">
<h4 id="audio-accessories">Audio Accessories</h4>
- <p>Android 4.1 and higher has support for audio output over a USB connection or Bluetooth. Find out
- how to build audio docks and other plug-in audio output hardware for Android.</p>
- <p><a href="{@docRoot}accessories/audio.html">» Build Audio Accessories</a></p>
+ <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>
</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 Android.</p>
- <p><a href="{@docRoot}accessories/custom.html">» Build Custom Accessories</a></p>
+ 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>
</div>
</div>
-
-
diff --git a/src/compatibility/4.4/versions.jd b/src/compatibility/4.4/versions.jd
index 75da784..f9c3ce7 100644
--- a/src/compatibility/4.4/versions.jd
+++ b/src/compatibility/4.4/versions.jd
@@ -11,7 +11,7 @@
<p>Because subsequent releases of the Android software may revise this string,
but not change any API behavior, such releases may not be accompanied by a new
Compatibility Definition Document. This page lists the versions that are
-allowable by an Android 4.3-based system. The only permitted values for
+allowable by an Android 4.4-based system. The only permitted values for
<code>android.os.Build.VERSION.RELEASE</code> for Android 4.4 are:</p>
<ul>
<li>4.4</li>
diff --git a/src/compatibility/5.0/versions.jd b/src/compatibility/5.0/versions.jd
new file mode 100644
index 0000000..78a11cb
--- /dev/null
+++ b/src/compatibility/5.0/versions.jd
@@ -0,0 +1,18 @@
+page.title=Permitted Version Strings for Android 5.0
+@jd:body
+
+<p>As described in Section 3.2.2 of the <a
+href="/compatibility/android-5.0-cdd.pdf">Android 5.0 Compatibility Definition</a>,
+only certain strings are allowable for the system property
+<code>android.os.Build.VERSION.RELEASE</code>. The reason for this is that
+applications and web sites may rely on predictable values for this string, and
+so that end users can easily and reliably identify the version of Android
+running on their devices.</p>
+<p>Because subsequent releases of the Android software may revise this string,
+but not change any API behavior, such releases may not be accompanied by a new
+Compatibility Definition Document. This page lists the versions that are
+allowable by an Android 5.0-based system. The only permitted values for
+<code>android.os.Build.VERSION.RELEASE</code> for Android 5.0 are:</p>
+<ul>
+<li>5.0</li>
+</ul>
diff --git a/src/compatibility/cts-intro.jd b/src/compatibility/cts-intro.jd
index 2813aef..f489fc6 100644
--- a/src/compatibility/cts-intro.jd
+++ b/src/compatibility/cts-intro.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.
@@ -140,7 +140,7 @@
</tr>
<tr>
<td>Dalvik VM Tests</td>
-<td>The tests focus on testing the Dalvik VM.</td>
+<td>The tests focus on testing the Dalvik Executable Format.</td>
</tr>
<tr>
<td>Platform Data Model</td>
diff --git a/src/devices/audio.jd b/src/devices/audio.jd
index 1b85d5e..660ec7e 100644
--- a/src/devices/audio.jd
+++ b/src/devices/audio.jd
@@ -78,7 +78,7 @@
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="http://source.android.com/devices/reference/audio_8h_source.html">audio.h</a> for additional details.
+href="{@docRoot}devices/halref/audio_8h_source.html">audio.h</a> for additional details.
</dd>
<dt>
Kernel Driver
diff --git a/src/devices/audio/images/ape_audio_tv_hdmi_tuner.png b/src/devices/audio/images/ape_audio_tv_hdmi_tuner.png
new file mode 100644
index 0000000..43a89ea
--- /dev/null
+++ 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
new file mode 100644
index 0000000..f013cfa
--- /dev/null
+++ 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
new file mode 100644
index 0000000..a25dcfb
--- /dev/null
+++ b/src/devices/audio/images/ape_audio_tv_tuner.png
Binary files differ
diff --git a/src/devices/audio/images/hub.jpg b/src/devices/audio/images/hub.jpg
index 59a9f3b..0dd44bd 100644
--- a/src/devices/audio/images/hub.jpg
+++ b/src/devices/audio/images/hub.jpg
Binary files differ
diff --git a/src/devices/audio_attributes.jd b/src/devices/audio_attributes.jd
new file mode 100644
index 0000000..473a04e
--- /dev/null
+++ b/src/devices/audio_attributes.jd
@@ -0,0 +1,257 @@
+page.title=Audio Attributes
+@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>Audio players support attributes that define how the audio system handles routing, volume, and
+focus decisions for the specified source. Applications can attach attributes to an audio playback
+(such as music played by a streaming service or a notification for a new email) then pass the audio
+source attributes to the framework, where the audio system uses the attributes to make mixing
+decisions and to notify applications about the state of the system.</p>
+
+<p class="note"><strong>Note:</strong> Applications can also attach attributes to an audio
+recording (such as audio captured in a video recording), but this functionality is not exposed in
+the public API.</p>
+
+<p>In Android 4.4 and earlier, the framework made mixing decisions using only the audio stream type.
+However, basing such decisions on stream type was too limiting to produce quality output across
+multiple applications and devices. For example, on a mobile device, some applications (i.e.
+Google Maps) played driving directions on the STREAM_MUSIC stream type; however, on mobile
+devices in projection mode (i.e. Android Auto), applications cannot mix driving directions with
+other media streams.</p>
+
+<p>Using the <a href="http://developer.android.com/reference/android/media/AudioAttributes.html">
+audio attribute API</a>, applications can now provide the audio system with detailed information
+about a specific audio source:</p>
+
+<ul>
+<li><b>Usage</b>. Specifies why the source is playing and controls routing, focus, and volume
+decisions.</li>
+<li><b>Content type</b>. Specifies what the source is playing (music, movie, speech,
+sonification, unknown).</li>
+<li><b>Flags</b>. Specifies how the source should be played. Includes support for audibility
+enforcement (camera shutter sounds required in some countries) and hardware audio/video
+synchronization.</li>
+</ul>
+
+<p>For dynamics processing, applications must distinguish between movie, music, and speech content.
+Information about the data itself may also matter, such as loudness and peak sample value.</p>
+
+<h2 id="using">Using attributes</h2>
+
+<p>Usage specifies the context in which the stream is used, providing information about why the
+sound is playing and what the sound is used for. Usage information is more expressive than a stream
+type and allows platforms or routing policies to refine volume or routing decisions.</p>
+
+<p>Supply one of the following usage values for any instance:</p>
+
+<ul>
+<li><code>USAGE_UNKNOWN</code></li>
+<li><code>USAGE_MEDIA</code></li>
+<li><code>USAGE_VOICE_COMMUNICATION</code></li>
+<li><code>USAGE_VOICE_COMMUNICATION_SIGNALLING</code></li>
+<li><code>USAGE_ALARM</code></li>
+<li><code>USAGE_NOTIFICATION</code></li>
+<li><code>USAGE_NOTIFICATION_RINGTONE</code></li>
+<li><code>USAGE_NOTIFICATION_COMMUNICATION_INSTANT</code></li>
+<li><code>USAGE_NOTIFICATION_COMMUNICATION_DELAYED</code></li>
+<li><code>USAGE_NOTIFICATION_EVENT</code></li>
+<li><code>USAGE_ASSISTANCE_ACCESSIBILITY</code></li>
+<li><code>USAGE_ASSISTANCE_NAVIGATION_GUIDANCE</code></li>
+<li><code>USAGE_ASSISTANCE_SONIFICATION</code></li>
+<li><code>USAGE_GAME</code></li>
+</ul>
+
+<p>Audio attribute usage values are mutually exclusive. For examples, refer to <code>
+<a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_MEDIA">
+USAGE_MEDIA</a></code> and <code>
+<a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_ALARM">
+USAGE_ALARM</a></code> definitions; for exceptions, refer to the <code>
+<a href="http://developer.android.com/reference/android/media/AudioAttributes.Builder.html">
+AudioAttributes.Builder</a></code> definition.</p>
+
+<h2 id="content-type">Content type</h2>
+
+<p>Content type defines what the sound is and expresses the general category of the content such as
+movie, speech, or beep/ringtone. The audio framework uses content type information to selectively
+configure audio post-processing blocks. While supplying the content type is optional, you should
+include type information whenever the content type is known, such as using
+<code>CONTENT_TYPE_MOVIE</code> for a movie streaming service or <code>CONTENT_TYPE_MUSIC</code>
+for a music playback application.</p>
+
+<p>Supply one of the following content type values for any instance:</p>
+
+<ul>
+<li><code>CONTENT_TYPE_UNKNOWN</code> (default)</li>
+<li><code>CONTENT_TYPE_MOVIE</code></li>
+<li><code>CONTENT_TYPE_MUSIC</code></li>
+<li><code>CONTENT_TYPE_SONIFICATION</code></li>
+<li><code>CONTENT_TYPE_SPEECH</code></li>
+</ul>
+
+<p>Audio attribute content type values are mutually exclusive. For details on content types,
+refer to the <a href="http://developer.android.com/reference/android/media/AudioAttributes.html">
+audio attribute API</a>.</p>
+
+<h2 id="flags">Flags</h2>
+
+<p>Flags specify how the audio framework applies effects to the audio playback. Supply one or more
+of the following flags for an instance:</p>
+
+<ul>
+<li><code>FLAG_AUDIBILITY_ENFORCED</code>. Requests the system ensure the audibility of the
+sound. Use to address the needs of legacy <code>STREAM_SYSTEM_ENFORCED</code> (such as forcing
+camera shutter sounds).</li>
+<li><code>HW_AV_SYNC</code>. Requests the system select an output stream that supports hardware A/V
+synchronization.</li>
+</ul>
+
+<p>Audio attribute flags are non-exclusive (can be combined). For details on these flags,
+refer to the <a href="http://developer.android.com/reference/android/media/AudioAttributes.html">
+audio attribute API</a>.</p>
+
+<h2 id="example">Example</h2>
+
+<p>In this example, AudioAttributes.Builder defines the AudioAttributes to be used by a new
+AudioTrack instance:</p>
+
+<pre>
+AudioTrack myTrack = new AudioTrack(
+ new AudioAttributes.Builder()
+ .setUsage(AudioAttributes.USAGE_MEDIA)
+ .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
+ .build(),
+ myFormat, myBuffSize, AudioTrack.MODE_STREAM, mySession);
+</pre>
+
+<h2 id="compatibility">Compatibility</h2>
+
+<p>Application developers should use audio attributes when creating or updating applications for
+Android 5.0. However, applications are not required to take advantage of attributes; they can
+handle legacy stream types only or remain unaware of attributes (i.e. a generic media player that
+doesn’t know anything about the content it’s playing).</p>
+
+<p>In such cases, the framework maintains backwards compatibility with older devices and Android
+releases by automatically translating legacy audio stream types to audio attributes. However, the
+framework does not enforce or guarantee this mapping across devices, manufacturers, or Android
+releases.</p>
+
+<p>Compatibility mappings:</p>
+
+<table>
+<tr>
+ <th>Android 5.0</th>
+ <th>Android 4.4 and earlier</th>
+</tr>
+<tr>
+ <td>
+ <code>CONTENT_TYPE_SPEECH</code><br>
+ <code>USAGE_VOICE_COMMUNICATION</code>
+ </td>
+ <td>
+ <code>STREAM_VOICE_CALL</code>
+ </td>
+</tr>
+<tr>
+ <td>
+ <code>CONTENT_TYPE_SONIFICATION</code><br>
+ <code>USAGE_ASSISTANCE_SONIFICATION</code>
+ </td>
+ <td>
+ <code>STREAM_SYSTEM</code>
+ </td>
+</tr>
+<tr>
+ <td>
+ <code>CONTENT_TYPE_SONIFICATION</code><br>
+ <code>USAGE_NOTIFICATION_RINGTONE</code>
+ </td>
+ <td>
+ <code>STREAM_RING</code>
+ </td>
+</tr>
+<tr>
+ <td>
+ <code>CONTENT_TYPE_MUSIC</code><br>
+ <code>USAGE_UNKNOWN</code><br>
+ <code>USAGE_MEDIA</code><br>
+ <code>USAGE_GAME</code><br>
+ <code>USAGE_ASSISTANCE_ACCESSIBILITY</code><br>
+ <code>USAGE_ASSISTANCE_NAVIGATION_GUIDANCE</code><br>
+ </td>
+ <td>
+ <code>STREAM_MUSIC</code>
+ </td>
+</tr>
+<tr>
+ <td>
+ <code>CONTENT_TYPE_SONIFICATION</code><br>
+ <code>USAGE_ALARM</code>
+ </td>
+ <td>
+ <code>STREAM_ALARM</code>
+ </td>
+</tr>
+<tr>
+ <td>
+ <code>CONTENT_TYPE_SONIFICATION</code><br>
+ <code>USAGE_NOTIFICATION</code><br>
+ <code>USAGE_NOTIFICATION_COMMUNICATION_REQUEST</code><br>
+ <code>USAGE_NOTIFICATION_COMMUNICATION_INSTANT</code><br>
+ <code>USAGE_NOTIFICATION_COMMUNICATION_DELAYED</code><br>
+ <code>USAGE_NOTIFICATION_EVENT</code><br>
+ </td>
+ <td>
+ <code>STREAM_NOTIFICATION</code>
+ </td>
+</tr>
+<tr>
+ <td>
+ <code>CONTENT_TYPE_SPEECH</code>
+ </td>
+ <td>
+ (@hide)<code> STREAM_BLUETOOTH_SCO</code>
+ </td>
+</tr>
+<tr>
+ <td>
+ <code>FLAG_AUDIBILITY_ENFORCED</code>
+ </td>
+ <td>
+ (@hide)<code> STREAM_SYSTEM_ENFORCED</code>
+ </td>
+</tr>
+<tr>
+ <td>
+ <code>CONTENT_TYPE_SONIFICATION</code><br>
+ <code>USAGE_VOICE_COMMUNICATION_SIGNALLING</code>
+ </td>
+ <td>
+ (@hide)<code> STREAM_DTMF</code>
+ </td>
+</tr>
+</table>
+
+<p class="note"><strong>Note:</strong> @hide streams are used internally by the framework but are
+not part of the public API.</p>
\ No newline at end of file
diff --git a/src/devices/audio_avoiding_pi.jd b/src/devices/audio_avoiding_pi.jd
index 80d0907..e884f8c 100644
--- a/src/devices/audio_avoiding_pi.jd
+++ b/src/devices/audio_avoiding_pi.jd
@@ -182,8 +182,13 @@
</p>
<p class="note"><strong>Note:</strong> Atomic operations and their interactions with memory barriers
+<<<<<<< HEAD
are notoriously badly misunderstood and used incorrectly. These methods are
included here for completeness but recommend you also read the article
+=======
+are notoriously badly misunderstood and used incorrectly. We include these methods
+here for completeness but recommend you also read the article
+>>>>>>> goog/lmp-dev
<a href="https://developer.android.com/training/articles/smp.html">
SMP Primer for Android</a>
for further information.
@@ -286,7 +291,7 @@
</p>
<p>
-For developers, some of the sample OpenSL ES application code may be updated to
+For developers, some of the sample OpenSL ES application code should be updated to
use non-blocking algorithms or reference a non-Android open source library.
</p>
diff --git a/src/devices/audio_implement.jd b/src/devices/audio_implement.jd
index 5d04074..4535640 100644
--- a/src/devices/audio_implement.jd
+++ b/src/devices/audio_implement.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.
@@ -24,63 +24,58 @@
</div>
</div>
-<p>
- This page exlains how to implement the audio Hardware Abstraction Layer (HAL)
-and configure the shared library.
-</p>
+<p>This page explains how to implement the audio Hardware Abstraction Layer (HAL) and configure the
+shared library.</p>
-<h2 id="implementing">
- Implementing the HAL
-</h2>
-<p>
- The audio HAL is composed of three different interfaces that you must implement:
-</p>
+<h2 id="implementing">Implementing the HAL</h2>
+
+<p>The audio HAL is composed of three different interfaces that you must implement:</p>
+
<ul>
- <li>
- <code>hardware/libhardware/include/hardware/audio.h</code> - represents the main functions of
- an audio device.
- </li>
- <li>
- <code>hardware/libhardware/include/hardware/audio_policy.h</code> - represents the audio policy
- manager, which handles things like audio routing and volume control policies.
- </li>
- <li>
- <code>hardware/libhardware/include/hardware/audio_effect.h</code> - represents effects that can
- be applied to audio such as downmixing, echo, or noise suppression.
- </li>
+<li><code>hardware/libhardware/include/hardware/audio.h</code> - represents the main functions
+of an audio device.</li>
+<li><code>hardware/libhardware/include/hardware/audio_policy.h</code> - represents the audio policy
+manager, which handles things like audio routing and volume control policies.</li>
+<li><code>hardware/libhardware/include/hardware/audio_effect.h</code> - represents effects that can
+be applied to audio such as downmixing, echo, or noise suppression.</li>
</ul>
-<p>See the implementation for the Galaxy Nexus at <code>device/samsung/tuna/audio</code> for an example.</p>
+
+<p>For an example, refer to the implementation for the Galaxy Nexus at
+<code>device/samsung/tuna/audio</code>.</p>
<p>In addition to implementing the HAL, you need to create a
- <code>device/<company_name>/<device_name>/audio/audio_policy.conf</code> file
- that declares the audio devices present on your product. For an example, see the file for
- the Galaxy Nexus audio hardware in <code>device/samsung/tuna/audio/audio_policy.conf</code>.
-Also, see
- the <code>system/core/include/system/audio.h</code> and <code>system/core/include/system/audio_policy.h</code>
- header files for a reference of the properties that you can define.
-</p>
-<h3 id="multichannel">Multi-channel support</h3>
-<p>If your hardware and driver supports multichannel audio via HDMI, you can output the audio stream
- directly to the audio hardware. This bypasses the AudioFlinger mixer so it doesn't get downmixed to two channels.
-
- <p>
- The audio HAL must expose whether an output stream profile supports multichannel audio capabilities.
- If the HAL exposes its capabilities, the default policy manager allows multichannel playback over
- HDMI.</p>
- <p>For more implementation details, see the
-<code>device/samsung/tuna/audio/audio_hw.c</code> in the Android 4.1 release.</p>
+<code>device/<company_name>/<device_name>/audio/audio_policy.conf</code> file that
+declares the audio devices present on your product. For an example, see the file for the Galaxy
+Nexus audio hardware in <code>device/samsung/tuna/audio/audio_policy.conf</code>. Also, see the
+<code>system/core/include/system/audio.h</code> and
+<code>system/core/include/system/audio_policy.h</code> header files for a reference of the
+properties that you can define.</p>
- <p>
- To specify that your product contains a multichannel audio output, edit the <code>audio_policy.conf</code> file to describe the multichannel
- output for your product. The following is an example from the Galaxy Nexus that shows a "dynamic" channel mask, which means the audio policy manager
- queries the actual channel masks supported by the HDMI sink after connection. You can also specify a static channel mask like <code>AUDIO_CHANNEL_OUT_5POINT1</code>
- </p>
+<h3 id="multichannel">Multi-channel support</h3>
+
+<p>If your hardware and driver supports multichannel audio via HDMI, you can output the audio
+stream directly to the audio hardware. This bypasses the AudioFlinger mixer so it doesn't get
+downmixed to two channels.</p>
+
+<p>The audio HAL must expose whether an output stream profile supports multichannel audio
+capabilities. If the HAL exposes its capabilities, the default policy manager allows multichannel
+playback over HDMI.</p>
+
+<p>For more implementation details, see the <code>device/samsung/tuna/audio/audio_hw.c</code> in
+the Android 4.1 release.</p>
+
+<p>To specify that your product contains a multichannel audio output, edit the
+<code>audio_policy.conf</code> file to describe the multichannel output for your product. The
+following is an example from the Galaxy Nexus that shows a "dynamic" channel mask, which means the
+audio policy manager queries the actual channel masks supported by the HDMI sink after connection.
+You can also specify a static channel mask like <code>AUDIO_CHANNEL_OUT_5POINT1</code>.</p>
+
<pre>
audio_hw_modules {
primary {
outputs {
...
- hdmi {
+ hdmi {
sampling_rates 44100|48000
channel_masks dynamic
formats AUDIO_FORMAT_PCM_16_BIT
@@ -95,42 +90,38 @@
}
</pre>
-
- <p>AudioFlinger's mixer downmixes the content to stereo
- automatically when sent to an audio device that does not support multichannel audio.</p>
+<p>AudioFlinger's mixer downmixes the content to stereo automatically when sent to an audio device
+that does not support multichannel audio.</p>
<h3 id="codecs">Media codecs</h3>
-<p>Ensure the audio codecs your hardware and drivers support are properly declared for your product. See
- <a href="media.html#expose"> Exposing Codecs to the Framework</a> for information on how to do this.
-</p>
+<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
+to the Framework</a>.</p>
-<h2 id="configuring">
- Configuring the shared library
-</h2>
-<p>
- You need to package the HAL implementation into a shared library and copy it to the
- appropriate location by creating an <code>Android.mk</code> file:
-</p>
+<h2 id="configuring">Configuring the shared library</h2>
+
+<p>You need to package the HAL implementation into a shared library and copy it to the appropriate
+location by creating an <code>Android.mk</code> file:</p>
+
<ol>
- <li>Create a <code>device/<company_name>/<device_name>/audio</code> directory
- to contain your library's source files.
- </li>
- <li>Create an <code>Android.mk</code> file to build the shared library. Ensure that the
- Makefile contains the following line:
+<li>Create a <code>device/<company_name>/<device_name>/audio</code> directory to
+contain your library's source files.</li>
+<li>Create an <code>Android.mk</code> file to build the shared library. Ensure that the Makefile
+contains the following line:
<pre>
LOCAL_MODULE := audio.primary.<device_name>
</pre>
- <p>
- Notice your library must be named <code>audio_primary.<device_name>.so</code> so
- that Android can correctly load the library. The "<code>primary</code>" portion of this
- filename indicates that this shared library is for the primary audio hardware located on the
- device. The module names <code>audio.a2dp.<device_name></code> and
- <code>audio.usb.<device_name></code> are also available for bluetooth and USB audio
- interfaces. Here is an example of an <code>Android.mk</code> from the Galaxy
- Nexus audio hardware:
- </p>
- <pre>
+
+<p>Notice your library must be named <code>audio_primary.<device_name>.so</code> so
+that Android can correctly load the library. The "<code>primary</code>" portion of this filename
+indicates that this shared library is for the primary audio hardware located on the device. The
+module names <code>audio.a2dp.<device_name></code> and
+<code>audio.usb.<device_name></code> are also available for bluetooth and USB audio
+interfaces. Here is an example of an <code>Android.mk</code> from the Galaxy Nexus audio hardware:
+</p>
+
+<pre>
LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
@@ -147,59 +138,73 @@
include $(BUILD_SHARED_LIBRARY)
</pre>
- </li>
- <li>If your product supports low latency audio as specified by the Android CDD, copy the
- corresponding XML feature file into your product. For example, in your product's
- <code>device/<company_name>/<device_name>/device.mk</code>
- Makefile:
- <pre>
+
+</li>
+
+<li>If your product supports low latency audio as specified by the Android CDD, copy the
+corresponding XML feature file into your product. For example, in your product's
+<code>device/<company_name>/<device_name>/device.mk</code> Makefile:
+
+<pre>
PRODUCT_COPY_FILES := ...
PRODUCT_COPY_FILES += \
frameworks/native/data/etc/android.android.hardware.audio.low_latency.xml:system/etc/permissions/android.hardware.audio.low_latency.xml \
</pre>
- </li>
-
- <li>Copy the <code>audio_policy.conf</code> file that you created earlier to the <code>system/etc/</code> directory
- in your product's <code>device/<company_name>/<device_name>/device.mk</code>
- Makefile. For example:
- <pre>
+
+</li>
+
+<li>Copy the <code>audio_policy.conf</code> file that you created earlier to the
+<code>system/etc/</code> directory in your product's
+<code>device/<company_name>/<device_name>/device.mk</code> Makefile. For example:
+
+<pre>
PRODUCT_COPY_FILES += \
device/samsung/tuna/audio/audio_policy.conf:system/etc/audio_policy.conf
</pre>
- </li>
- <li>Declare the shared modules of your audio HAL that are required by your product in the product's
- <code>device/<company_name>/<device_name>/device.mk</code> Makefile. For example, the
- Galaxy Nexus requires the primary and bluetooth audio HAL modules:
+
+</li>
+
+<li>Declare the shared modules of your audio HAL that are required by your product in the
+product's <code>device/<company_name>/<device_name>/device.mk</code> Makefile. For
+example, the Galaxy Nexus requires the primary and bluetooth audio HAL modules:
+
<pre>
PRODUCT_PACKAGES += \
audio.primary.tuna \
audio.a2dp.default
</pre>
- </li>
+
+</li>
</ol>
<h2 id="preprocessing">Audio pre-processing effects</h2>
-<p>
-The Android platform provides audio effects on supported devices in the
-<a href="http://developer.android.com/reference/android/media/audiofx/package-summary.html">audiofx</a>
-package, which is available for developers to access. For example, on the Nexus 10, the following pre-processing effects are supported: </p>
+
+<p>The Android platform provides audio effects on supported devices in the
+<a href="http://developer.android.com/reference/android/media/audiofx/package-summary.html">audiofx
+</a> package, which is available for developers to access. For example, on the Nexus 10, the
+following pre-processing effects are supported:</p>
+
<ul>
- <li><a
-href="http://developer.android.com/reference/android/media/audiofx/AcousticEchoCanceler.html">Acoustic Echo Cancellation</a></li>
- <li><a
-href="http://developer.android.com/reference/android/media/audiofx/AutomaticGainControl.html">Automatic Gain Control</a></li>
- <li><a
-href="http://developer.android.com/reference/android/media/audiofx/NoiseSuppressor.html">Noise Suppression</a></li>
+<li>
+<a href="http://developer.android.com/reference/android/media/audiofx/AcousticEchoCanceler.html">
+Acoustic Echo Cancellation</a></li>
+<li>
+<a href="http://developer.android.com/reference/android/media/audiofx/AutomaticGainControl.html">
+Automatic Gain Control</a></li>
+<li>
+<a href="http://developer.android.com/reference/android/media/audiofx/NoiseSuppressor.html">
+Noise Suppression</a></li>
</ul>
-<p>Pre-processing effects are always paired with the use case mode in which the pre-processing is requested. In Android
-app development, a use case is referred to as an <code>AudioSource</code>; and app developers
-request to use the <code>AudioSource</code> abstraction instead of the actual audio hardware device.
-The Android Audio Policy Manager maps an <code>AudioSource</code> to the actual hardware with <code>AudioPolicyManagerBase::getDeviceForInputSource(int
-inputSource)</code>. The following sources are exposed to developers:
-</p>
+<p>Pre-processing effects are paired with the use case mode in which the pre-processing is requested
+. In Android app development, a use case is referred to as an <code>AudioSource</code>; and app
+developers request to use the <code>AudioSource</code> abstraction instead of the actual audio
+hardware device. The Android Audio Policy Manager maps an <code>AudioSource</code> to the actual
+hardware with <code>AudioPolicyManagerBase::getDeviceForInputSource(int inputSource)</code>. The
+following sources are exposed to developers:</p>
+
<ul>
<li><code>android.media.MediaRecorder.AudioSource.CAMCORDER</code></li>
<li><code>android.media.MediaRecorder.AudioSource.VOICE_COMMUNICATION</code></li>
@@ -208,25 +213,26 @@
<li><code>android.media.MediaRecorder.AudioSource.VOICE_UPLINK</code></li>
<li><code>android.media.MediaRecorder.AudioSource.VOICE_RECOGNITION</code></li>
<li><code>android.media.MediaRecorder.AudioSource.MIC</code></li>
-<li><code>android.media.MediaRecorder.AudioSource.DEFAULT</code></li>
-</ul>
+<li><code>android.media.MediaRecorder.AudioSource.DEFAULT</code></li> </ul>
-<p>The default pre-processing effects that are applied for each <code>AudioSource</code> are
-specified in the <code>/system/etc/audio_effects.conf</code> file. To specify
-your own default effects for every <code>AudioSource</code>, create a <code>/system/vendor/etc/audio_effects.conf</code> file
-and specify any pre-processing effects that you need to turn on. For an example,
-see the implementation for the Nexus 10 in <code>device/samsung/manta/audio_effects.conf</code></p>
+<p>The default pre-processing effects applied for each <code>AudioSource</code> are specified in
+the <code>/system/etc/audio_effects.conf</code> file. To specify your own default effects for every
+<code>AudioSource</code>, create a <code>/system/vendor/etc/audio_effects.conf</code> file and
+specify the pre-processing effects to turn on. For an example, see the implementation for the Nexus
+10 in <code>device/samsung/manta/audio_effects.conf</code>. AudioEffect instances acquire and
+release a session when created and destroyed, enabling the effects (such as the Loudness Enhancer)
+to persist throughout the duration of the session. </p>
-<p class="warning"><strong>Warning:</strong> For the <code>VOICE_RECOGNITION</code> use case, do 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 default due to
-configuration file, or the audio HAL implementation's default behavior.</p>
+<p class="warning"><strong>Warning:</strong> For the <code>VOICE_RECOGNITION</code> use case, do
+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
+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 <code>AudioSource</code>.
-By declaring the <code>AudioSource</code> configuration in this manner, the
-framework will automatically request from the audio HAL the use of those
-effects.</p>
+<p>The following example enables pre-processing for the VoIP <code>AudioSource</code> and Camcorder
+<code>AudioSource</code>. By declaring the <code>AudioSource</code> configuration in this manner,
+the framework will automatically request from the audio HAL the use of those effects.</p>
<pre>
pre_processing {
@@ -241,8 +247,9 @@
</pre>
<h3 id="tuning">Source tuning</h3>
-<p>For <code>AudioSource</code> tuning, there are no explicit requirements on audio gain or audio processing
-with the exception of voice recognition (<code>VOICE_RECOGNITION</code>).</p>
+
+<p>For <code>AudioSource</code> tuning, there are no explicit requirements on audio gain or audio
+processing with the exception of voice recognition (<code>VOICE_RECOGNITION</code>).</p>
<p>The requirements for voice recognition are:</p>
@@ -252,32 +259,38 @@
<li>level tracks linearly from -18dB to +12dB relative to 90dB SPL</li>
<li>THD < 1% (90dB SPL in 100 to 4000Hz range)</li>
<li>8kHz sampling rate (anti-aliasing)</li>
-<li>Effects / pre-processing must be disabled by default</li>
+<li>Effects/pre-processing must be disabled by default</li>
</ul>
<p>Examples of tuning different effects for different sources are:</p>
<ul>
- <li>Noise Suppressor
- <ul>
- <li>Tuned for wind noise suppressor for <code>CAMCORDER</code></li>
- <li>Tuned for stationary noise suppressor for <code>VOICE_COMMUNICATION</code></li>
- </ul>
- </li>
- <li>Automatic Gain Control
- <ul>
- <li>Tuned for close-talk for <code>VOICE_COMMUNICATION</code> and main phone mic</li>
- <li>Tuned for far-talk for <code>CAMCORDER</code></li>
- </ul>
- </li>
+<li>Noise Suppressor
+<ul>
+<li>Tuned for wind noise suppressor for <code>CAMCORDER</code></li>
+<li>Tuned for stationary noise suppressor for <code>VOICE_COMMUNICATION</code></li>
+</ul>
+</li>
+<li>Automatic Gain Control
+<ul>
+<li>Tuned for close-talk for <code>VOICE_COMMUNICATION</code> and main phone mic</li>
+<li>Tuned for far-talk for <code>CAMCORDER</code></li>
+</ul>
+</li>
</ul>
<h3 id="more">More information</h3>
-<p>For more information, see:</p>
-<ul>
-<li>Android documentation for <a href="http://developer.android.com/reference/android/media/audiofx/package-summary.html">audiofx
-package</a>
-<li>Android documentation for <a href="http://developer.android.com/reference/android/media/audiofx/NoiseSuppressor.html">Noise Suppression audio effect</a></li>
+<p>For more information, see:</p>
+
+<ul>
+<li>Android documentation for
+<a href="http://developer.android.com/reference/android/media/audiofx/package-summary.html">
+audiofx package</a>
+
+<li>Android documentation for
+<a href="http://developer.android.com/reference/android/media/audiofx/NoiseSuppressor.html">
+Noise Suppression audio effect</a></li>
+
<li><code>device/samsung/manta/audio_effects.conf</code> file for the Nexus 10</li>
</ul>
diff --git a/src/devices/audio_terminology.jd b/src/devices/audio_terminology.jd
index 87baacb..e832153 100644
--- a/src/devices/audio_terminology.jd
+++ b/src/devices/audio_terminology.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.
@@ -372,6 +372,49 @@
</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>
@@ -647,4 +690,3 @@
<dd>To resample, where sink sample rate > source sample rate.</dd>
</dl>
-
diff --git a/src/devices/audio_tv.jd b/src/devices/audio_tv.jd
new file mode 100644
index 0000000..4bcb55e
--- /dev/null
+++ b/src/devices/audio_tv.jd
@@ -0,0 +1,296 @@
+page.title=TV Audio
+@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 TV Input Framework (TIF) manager works with the audio routing API to support flexible audio
+path changes. When a System on Chip (SoC) implements the TV hardware abstraction layer (HAL), each
+TV input (HDMI IN, Tuner, etc.) provides <code>TvInputHardwareInfo</code> that specifies AudioPort information for audio type and address.</p>
+
+<ul>
+<li><b>Physical</b> audio input/output devices have a corresponding AudioPort.</li>
+<li><b>Software</b> audio output/input streams are represented as AudioMixPort (child class of
+AudioPort).</li>
+</ul>
+
+<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 class="img-caption"><strong>Figure 1.</strong> TV Input Framework (TIF)</p>
+
+<h2 id="Requirements">Requirements</h2>
+
+<p>A SoC must implement the audio HAL with the following audio routing API support:</p>
+
+<table>
+<tbody>
+<tr>
+<th>Audio Ports</th>
+<td>
+<ul>
+<li>TV Audio Input has a corresponding audio source port implementation.</li>
+<li>TV Audio Output has a corresponding audio sink port implementation.</li>
+<li>Can create audio patch between any TV input audio port and any TV output audio port.</li>
+</ul>
+</td>
+</tr>
+<tr>
+<th>Default Input</th>
+<td>AudioRecord (created with DEFAULT input source) must seize <i>virtual null input source</i> for
+AUDIO_DEVICE_IN_DEFAULT acquisition on Android TV.</td>
+</tr>
+<tr>
+<th>Device Loopback</th>
+<td>Requires supporting an AUDIO_DEVICE_IN_LOOPBACK input that is a complete mix of all audio output
+of all the TV output (11Khz, 16bit mono or 48Khz, 16bit mono). Used only for audio capture.
+</td>
+</tr>
+</tbody>
+</table>
+
+
+<h2 id="Audio Devices">TV audio devices</h2>
+
+<p>Android supports the following audio devices for TV audio input/output.</p>
+
+<h4>system/core/include/system/audio.h</h4>
+
+<pre>
+/* output devices */
+AUDIO_DEVICE_OUT_AUX_DIGITAL = 0x400,
+AUDIO_DEVICE_OUT_HDMI = AUDIO_DEVICE_OUT_AUX_DIGITAL,
+/* HDMI Audio Return Channel */
+AUDIO_DEVICE_OUT_HDMI_ARC = 0x40000,
+/* S/PDIF out */
+AUDIO_DEVICE_OUT_SPDIF = 0x80000,
+/* input devices */
+AUDIO_DEVICE_IN_AUX_DIGITAL = AUDIO_DEVICE_BIT_IN | 0x20,
+AUDIO_DEVICE_IN_HDMI = AUDIO_DEVICE_IN_AUX_DIGITAL,
+/* TV tuner input */
+AUDIO_DEVICE_IN_TV_TUNER = AUDIO_DEVICE_BIT_IN | 0x4000,
+/* S/PDIF in */
+AUDIO_DEVICE_IN_SPDIF = AUDIO_DEVICE_BIT_IN | 0x10000,
+AUDIO_DEVICE_IN_LOOPBACK = AUDIO_DEVICE_BIT_IN | 0x40000,
+</pre>
+
+
+<h2 id="HAL extension">Audio HAL extension</h2>
+
+<p>The Audio HAL extension for the audio routing API is defined by following:</p>
+
+<h4>system/core/include/system/audio.h</h4>
+
+<pre>
+/* audio port configuration structure used to specify a particular configuration of an audio port */
+struct audio_port_config {
+ audio_port_handle_t id; /* port unique ID */
+ audio_port_role_t role; /* sink or source */
+ audio_port_type_t type; /* device, mix ... */
+ unsigned int config_mask; /* e.g AUDIO_PORT_CONFIG_ALL */
+ unsigned int sample_rate; /* sampling rate in Hz */
+ audio_channel_mask_t channel_mask; /* channel mask if applicable */
+ audio_format_t format; /* format if applicable */
+ struct audio_gain_config gain; /* gain to apply if applicable */
+ union {
+ struct audio_port_config_device_ext device; /* device specific info */
+ struct audio_port_config_mix_ext mix; /* mix specific info */
+ struct audio_port_config_session_ext session; /* session specific info */
+ } ext;
+};
+struct audio_port {
+ audio_port_handle_t id; /* port unique ID */
+ audio_port_role_t role; /* sink or source */
+ audio_port_type_t type; /* device, mix ... */
+ unsigned int num_sample_rates; /* number of sampling rates in following array */
+ unsigned int sample_rates[AUDIO_PORT_MAX_SAMPLING_RATES];
+ unsigned int num_channel_masks; /* number of channel masks in following array */
+ audio_channel_mask_t channel_masks[AUDIO_PORT_MAX_CHANNEL_MASKS];
+ unsigned int num_formats; /* number of formats in following array */
+ audio_format_t formats[AUDIO_PORT_MAX_FORMATS];
+ unsigned int num_gains; /* number of gains in following array */
+ struct audio_gain gains[AUDIO_PORT_MAX_GAINS];
+ struct audio_port_config active_config; /* current audio port configuration */
+ union {
+ struct audio_port_device_ext device;
+ struct audio_port_mix_ext mix;
+ struct audio_port_session_ext session;
+ } ext;
+};
+</pre>
+
+<h4>hardware/libhardware/include/hardware/audio.h</h4>
+
+<pre>
+struct audio_hw_device {
+ :
+ /**
+ * Routing control
+ */
+
+ /* Creates an audio patch between several source and sink ports.
+ * The handle is allocated by the HAL and should be unique for this
+ * audio HAL module. */
+ int (*create_audio_patch)(struct audio_hw_device *dev,
+ unsigned int num_sources,
+ const struct audio_port_config *sources,
+ unsigned int num_sinks,
+ const struct audio_port_config *sinks,
+ audio_patch_handle_t *handle);
+
+ /* Release an audio patch */
+ int (*release_audio_patch)(struct audio_hw_device *dev,
+ audio_patch_handle_t handle);
+
+ /* Fills the list of supported attributes for a given audio port.
+ * As input, "port" contains the information (type, role, address etc...)
+ * needed by the HAL to identify the port.
+ * As output, "port" contains possible attributes (sampling rates, formats,
+ * channel masks, gain controllers...) for this port.
+ */
+ int (*get_audio_port)(struct audio_hw_device *dev,
+ struct audio_port *port);
+
+ /* Set audio port configuration */
+ int (*set_audio_port_config)(struct audio_hw_device *dev,
+ const struct audio_port_config *config);
+</pre>
+
+<h2 id="Testing">Testing DEVICE_IN_LOOPBACK</h2>
+
+<p>To test DEVICE_IN_LOOPBACK for TV monitoring, use the following testing code. After running the
+test, the captured audio saves to <code>/sdcard/record_loopback.raw</code>, where you can listen to
+it using <code>ffmeg</code>.</p>
+
+<pre>
+<uses-permission android:name="android.permission.MODIFY_AUDIO_ROUTING" />
+<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+
+ AudioRecord mRecorder;
+ Handler mHandler = new Handler();
+ int mMinBufferSize = AudioRecord.getMinBufferSize(RECORD_SAMPLING_RATE,
+ AudioFormat.CHANNEL_IN_MONO,
+ AudioFormat.ENCODING_PCM_16BIT);;
+ static final int RECORD_SAMPLING_RATE = 48000;
+ public void doCapture() {
+ mRecorder = new AudioRecord(MediaRecorder.AudioSource.DEFAULT, RECORD_SAMPLING_RATE,
+ AudioFormat.CHANNEL_IN_MONO, AudioFormat.ENCODING_PCM_16BIT, mMinBufferSize * 10);
+ AudioManager am = (AudioManager) getSystemService(Context.AUDIO_SERVICE);
+ ArrayList<AudioPort> audioPorts = new ArrayList<AudioPort>();
+ am.listAudioPorts(audioPorts);
+ AudioPortConfig srcPortConfig = null;
+ AudioPortConfig sinkPortConfig = null;
+ for (AudioPort audioPort : audioPorts) {
+ if (srcPortConfig == null
+ && audioPort.role() == AudioPort.ROLE_SOURCE
+ && audioPort instanceof AudioDevicePort) {
+ AudioDevicePort audioDevicePort = (AudioDevicePort) audioPort;
+ if (audioDevicePort.type() == AudioManager.DEVICE_IN_LOOPBACK) {
+ srcPortConfig = audioPort.buildConfig(48000, AudioFormat.CHANNEL_IN_DEFAULT,
+ AudioFormat.ENCODING_DEFAULT, null);
+ Log.d(LOG_TAG, "Found loopback audio source port : " + audioPort);
+ }
+ }
+ else if (sinkPortConfig == null
+ && audioPort.role() == AudioPort.ROLE_SINK
+ && audioPort instanceof AudioMixPort) {
+ sinkPortConfig = audioPort.buildConfig(48000, AudioFormat.CHANNEL_OUT_DEFAULT,
+ AudioFormat.ENCODING_DEFAULT, null);
+ Log.d(LOG_TAG, "Found recorder audio mix port : " + audioPort);
+ }
+ }
+ if (srcPortConfig != null && sinkPortConfig != null) {
+ AudioPatch[] patches = new AudioPatch[] { null };
+ int status = am.createAudioPatch(
+ patches,
+ new AudioPortConfig[] { srcPortConfig },
+ new AudioPortConfig[] { sinkPortConfig });
+ Log.d(LOG_TAG, "Result of createAudioPatch(): " + status);
+ }
+ mRecorder.startRecording();
+ processAudioData();
+ mRecorder.stop();
+ mRecorder.release();
+ }
+ private void processAudioData() {
+ OutputStream rawFileStream = null;
+ byte data[] = new byte[mMinBufferSize];
+ try {
+ rawFileStream = new BufferedOutputStream(
+ new FileOutputStream(new File("/sdcard/record_loopback.raw")));
+ } catch (FileNotFoundException e) {
+ Log.d(LOG_TAG, "Can't open file.", e);
+ }
+ long startTimeMs = System.currentTimeMillis();
+ while (System.currentTimeMillis() - startTimeMs < 5000) {
+ int nbytes = mRecorder.read(data, 0, mMinBufferSize);
+ if (nbytes <= 0) {
+ continue;
+ }
+ try {
+ rawFileStream.write(data);
+ } catch (IOException e) {
+ Log.e(LOG_TAG, "Error on writing raw file.", e);
+ }
+ }
+ try {
+ rawFileStream.close();
+ } catch (IOException e) {
+ }
+ Log.d(LOG_TAG, "Exit audio recording.");
+ }
+</pre>
+
+<p>Locate the captured audio file in <code>/sdcard/record_loopback.raw</code> and listen to it using
+<code>ffmeg</code>:</p>
+
+<pre>
+adb pull /sdcard/record_loopback.raw
+ffmpeg -f s16le -ar 48k -ac 1 -i record_loopback.raw record_loopback.wav
+ffplay record_loopback.wav
+</pre>
+
+<h2 id="Use cases">Use cases</h2>
+
+<p>This section includes common use cases for TV audio.</p>
+
+<h3>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 class="img-caption">
+<strong>Figure 2.</strong> Audio Patch for TV tuner with speaker output.</p>
+
+
+<h3>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 class="img-caption">
+<strong>Figure 3.</strong> Audio Patch for HDMI OUT from live TV.</p>
\ No newline at end of file
diff --git a/src/devices/camera/camera.jd b/src/devices/camera/camera.jd
index 577224b..a1e837f 100644
--- a/src/devices/camera/camera.jd
+++ b/src/devices/camera/camera.jd
@@ -1,4 +1,4 @@
-page.title=Camera HAL overview
+page.title=Camera
@jd:body
<!--
diff --git a/src/devices/camera/camera3.jd b/src/devices/camera/camera3.jd
index 6fe9770..4d4d3a1 100644
--- a/src/devices/camera/camera3.jd
+++ b/src/devices/camera/camera3.jd
@@ -39,18 +39,19 @@
capable front-facing camera with version 1 of the HAL and a more advanced
back-facing camera with version 3 of the HAL. Version 2 was a stepping stone to
version 3 and is not supported.</p>
+
<p>
There is only one camera HAL module (with its own version number, currently 1, 2,
or 2.1), which lists multiple independent camera devices that each have
their own version. Camera module v2 or newer is required to support devices v2 or newer, and such
camera modules can have a mix of camera device versions. This is what we mean
-when we say we Android supports implementing both HALs.
+when we say Android supports implementing both HALs.
</p>
-<p><strong>Note:</strong> The new camera HAL is in active development and can change at any
- time. This document describes at a high level the design of the camera subsystem
- and omits many details. Stay tuned for more updates to the PDK repository and
- look out for updates to the Camera HAL and reference implementation for more
- information.</p>
+
+<p class="note"><strong>Note:</strong> The new camera HAL is in active
+development and can change at any time. This document describes at a high level
+the design of the camera subsystem and omits many details. See <a
+href="versioning.html">Camera version support</a> for our plans.</p>
<h2 id="overview">Overview</h2>
diff --git a/src/devices/camera/versioning.jd b/src/devices/camera/versioning.jd
new file mode 100644
index 0000000..9f97ce3
--- /dev/null
+++ b/src/devices/camera/versioning.jd
@@ -0,0 +1,132 @@
+page.title=Camera version support
+@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 Android 5.0 (Lollipop) platform release adds a new app-level camera framework. This
+document outlines some logistical details that OEMs and SoC vendors need to
+know.</p>
+
+<h2 id=glossary>Terms</h2>
+
+<p>The following terms are used in this document:</p>
+
+<ul>
+ <li><em>Camera API1</em>: The app-level camera framework on KitKat and earlier devices, exposed
+through the <code>android.hardware.Camera</code> class.
+ <li><em>Camera API2</em>: The app-level camera framework on 5.0 and later
+devices, exposed through the<code> android.hardware.camera2</code> package.
+ <li><em>Camera HAL</em>: The camera module layer that SoC vendors implement. The app-level public
+frameworks are built on top of the camera HAL.
+ <li><em>Camera HAL3.2</em>: The version of the camera device HAL that is
+being released with Lollipop. KitKat launched with an earlier version (Camera HAL3.1).
+ <li><em>Camera API1 CTS</em>: The set of camera Compatibility Test Suite (CTS) tests that run on top of
+Camera API1.
+ <li><em>Camera API2 CTS</em>: An additional set of camera CTS tests that run on top of Camera API2.
+</ul>
+
+<h2 id=camera_api2_overview>Camera API2 overview</h2>
+
+<p>The new camera frameworks expose lower-level camera control to the app,
+including efficient zero-copy burst/streaming flows and per-frame controls of
+exposure, gain, white balance gains, color conversion, denoising, sharpening,
+and more. See this <a
+href="https://www.youtube.com/watch?v=92fgcUNCHic&feature=youtu.be&t=29m50s">brief
+video overview from the Google I/O 2014 conference</a> for additional details.
+</p>
+
+<h2 id=camera_api1_availability_and_deprecation_in_l>Camera API1 availability and deprecation in Android 5.0</h2>
+
+<p>The Camera API1 interfaces are still available for apps to use on Android
+5.0 and later devices, and camera apps built on top of Camera API1 should work
+as before. Camera API1 is being marked as deprecated in Lollipop, indicating that it
+will be phased out over time and new platform development will focus on Camera
+API2. However, we expect this phase-out period to be lengthy, and Camera API1
+apps will continue to be supported in Android for some time to come.</p>
+
+<p>All earlier camera HAL versions, including Camera HAL1.0, will also continue to
+be supported.</p>
+
+<h2 id=camera_api2_capabilities_and_support_levels>Camera API2 capabilities and support levels</h2>
+
+<p>Android 5.0 and later devices feature Camera API2, however they may not fully support all of
+the new features of Camera API2. The
+<code>android.info.supportedHardwareLevel</code> property that apps can query
+through the Camera API2 interfaces report one of three support levels:
+<code>LEGACY</code>, <code>FULL</code>, and <code>LIMITED</code>.</p>
+
+<p><em>Legacy</em> devices expose a level of capabilities through the Camera API2 interfaces that
+are approximately the same as is exposed to apps through the Camera API1
+interfaces; the legacy frameworks code conceptually translates Camera API2
+calls into Camera API1 calls under the hood. Legacy devices do not support
+the new Camera API2 features including per-frame controls.</p>
+
+<p><em>Full</em> devices support all of the major capabilities of Camera API2. Full devices by
+necessity must have a Camera HAL version of 3.2 (shipping with Android 5.0) or later.</p>
+
+<p><em>Limited</em> devices are in between: They support some of the new Camera API2 capabilities,
+but not all of them, and must also comprise a Camera HAL version of 3.2 or later.</p>
+
+<p>Individual capabilities are exposed via the<code>
+android.request.availableCapabilities</code> property in the Camera API2
+interfaces. Full devices require both the <code>MANUAL_SENSOR</code> and
+<code>MANUAL_POST_PROCESSING</code> capabilities, among others. There is also a
+<code>RAW</code> capability that is optional even for full devices. Limited
+devices can advertise any subset of these capabilities, including none of them. However,
+the <code>BACKWARD_COMPATIBLE</code> capability must always be defined.</p>
+
+<p>The supported hardware level of the device, as well as the specific Camera API2
+capabilities it supports, are available as the following feature flags to allow
+Play Store filtering of Camera API2 camera apps; a device must define the
+feature flag if any of its attached camera devices supports the feature.</p>
+
+<ul>
+ <li><code>android.hardware.camera.hardware_level.full</code>
+ <li><code>android.hardware.camera.capability.raw</code>
+ <li><code>android.hardware.camera.capability.manual_sensor</code>
+ <li><code>android.hardware.camera.capability.manual_post_processing</code>
+</ul>
+
+<h2 id=cts_requirements>CTS requirements</h2>
+
+<p>Android 5.0 and later devices must pass both Camera API1 CTS and Camera API2
+CTS. And as always, devices are required to pass the CTS Verifier camera
+tests.</p>
+
+<p>To add some context: For devices that don’t feature a Camera HAL3.2
+implementation and are not capable of supporting the full Camera API2
+interfaces, the Camera API2 CTS tests must still be passed. However, in this
+case the device will be running in Camera API2 <em>legacy</em> mode (in which
+the Camera API2 calls are conceptually just mapped to Camera
+API1 calls); and any Camera API2 CTS tests that relate to features or
+capabilities beyond Camera API1 have logic that will skip them in the case of
+old (legacy) devices.</p>
+
+<p>On a legacy device, the Camera API2 CTS tests that are not skipped are purely
+using the existing public Camera API1 interfaces and capabilities (with no new
+requirements), and any bugs that are exposed (which will in turn cause a Camera
+API2 CTS failure) are bugs that were already present in the device’s existing
+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>
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index c46a418..8a5353f 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -20,7 +20,7 @@
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/index.html">
- <span class="en">Porting</span>
+ <span class="en">Interfaces</span>
</a>
</div>
<ul>
@@ -33,6 +33,7 @@
<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 class="nav-section">
<div class="nav-section-header">
@@ -50,6 +51,7 @@
<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>
@@ -67,6 +69,7 @@
<li><a href="<?cs var:toroot ?>devices/camera/camera3_crop_reprocess.html">Output and Cropping</a></li>
<li><a href="<?cs var:toroot ?>devices/camera/camera3_error_stream.html">Errors and Streams</a></li>
<li><a href="<?cs var:toroot ?>devices/camera/camera3_requests_methods.html">Request Creation</a></li>
+ <li><a href="<?cs var:toroot ?>devices/camera/versioning.html">Version Support</a></li>
</ul>
</li>
@@ -112,64 +115,9 @@
<li><a href="<?cs var:toroot ?>devices/tech/input/validate-keymaps.html">Validate Keymaps</a></li>
</ul>
</li>
- <li><a href="<?cs var:toroot ?>devices/low-ram.html">Low RAM</a></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/tech/security/index.html">
- <span class="en">Security</span>
- </a>
- </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>
- </div>
- <ul>
- <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>
- </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>
- </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 class="nav-section">
- <div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/sensors/index.html">
<span class="en">Sensors</span>
</a>
@@ -222,6 +170,17 @@
</li>
</ul>
</li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tv/index.html">
+ <span class="en">TV</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tv/HDMI-CEC.html">HDMI-CEC control service</a></li>
+ </ul>
+ </li>
+
</ul>
</li>
<!-- End Porting Android -->
@@ -231,7 +190,7 @@
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/index.html">
- <span class="en">Technical Information</span>
+ <span class="en">Core Technologies</span>
</a>
</div>
@@ -239,13 +198,12 @@
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/dalvik/index.html">
- <span class="en">Dalvik</span></a>
+ <span class="en">ART and Dalvik</span></a>
</div>
<ul>
<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/art.html">Introducing ART</a></li>
</ul>
</li>
@@ -279,7 +237,7 @@
<li class="nav-section">
<div class="nav-section-header empty">
- <a href="<?cs var:toroot ?>devices/reference/files.html">
+ <a href="<?cs var:toroot ?>devices/halref/index.html">
<span class="en">HAL File Reference</span>
</a>
</div>
@@ -292,15 +250,77 @@
</li>
<li>
+ <a href="<?cs var:toroot ?>devices/low-ram.html">
+ <span class="en">Low RAM</span>
+ </a>
+ </li>
+
+ <li>
<a href="<?cs var:toroot ?>devices/tech/power.html">
<span class="en">Power</span>
</a>
</li>
+ <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>
+ <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>
+ </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>
+ </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>
+ </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 class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/index.html">
- <span class="en">Trade Federation Testing Infrastructure</span>
+ <span class="en">Testing Infrastructure</span>
</a>
</div>
<ul>
diff --git a/src/devices/index.jd b/src/devices/index.jd
index da9438d..483c3b0 100644
--- a/src/devices/index.jd
+++ b/src/devices/index.jd
@@ -1,8 +1,8 @@
-page.title=Porting Android to Devices
+page.title=Android Interfaces
@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.
diff --git a/src/devices/low-ram.jd b/src/devices/low-ram.jd
index 19845a9..f0892a7 100644
--- a/src/devices/low-ram.jd
+++ b/src/devices/low-ram.jd
@@ -1,4 +1,4 @@
-page.title=Running Android with low RAM
+page.title=Low RAM
@jd:body
<!--
diff --git a/src/devices/sensors/hal-interface.jd b/src/devices/sensors/hal-interface.jd
index 5c232fa..7feadf2 100644
--- a/src/devices/sensors/hal-interface.jd
+++ b/src/devices/sensors/hal-interface.jd
@@ -24,7 +24,7 @@
</div>
</div>
-<p>The HAL interface, declared in <a href="{@docRoot}devices/reference/sensors_8h.html">sensors.h</a>, represents the interface between the Android <a href="sensor-stack.html#framework">framework</a> and the hardware-specific software. A HAL implementation must define each
+<p>The HAL interface, declared in <a href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a>, represents the interface between the Android <a href="sensor-stack.html#framework">framework</a> and the hardware-specific software. A HAL implementation must define each
function declared in sensors.h. The main functions are:</p>
<ul>
<li><code>get_sensors_list</code> - Returns the list of all sensors. </li>
@@ -47,7 +47,7 @@
<li><code>sensor_t</code></li>
<li><code>sensors_event_t</code></li>
</ul>
-<p>In addition to the sections below, see <a href="{@docRoot}devices/reference/sensors_8h.html">sensors.h</a> for more information on those types.</p>
+<p>In addition to the sections below, see <a href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a> for more information on those types.</p>
<h2 id="get_sensors_list_list">get_sensors_list(list)</h2>
<pre>int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t
const** list);</pre>
@@ -240,13 +240,13 @@
<code>HAL_MODULE_INFO_SYM</code> of this type to expose the <a
href="#get_sensors_list_list">get_sensors_list</a> function. See the definition
of <code>sensors_module_t</code> in <a
- href="{@docRoot}devices/reference/sensors_8h.html">sensors.h</a> and the
+ href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a> and the
definition of <code>hw_module_t</code> for more information.</p>
<h2 id="sensors_poll_device_t_sensors_poll_device_1_t">sensors_poll_device_t / sensors_poll_device_1_t</h2>
<p><code>sensors_poll_device_1_t</code> contains the rest of the methods defined above:
<code>activate</code>, <code>batch</code>, <code>flush</code> and
<code>poll</code>. Its <code>common</code> field (of type <a
- href="{@docRoot}devices/reference/structhw__device__t.html">hw_device_t</a>)
+ href="{@docRoot}devices/halref/structhw__device__t.html">hw_device_t</a>)
defines the version number of the HAL.</p>
<h2 id="sensor_t">sensor_t</h2>
<p><code>sensor_t</code> represents an <a href="index.html">Android sensor</a>. Here are some of its important fields:</p>
@@ -268,7 +268,7 @@
<em>Cool-product</em> team at Fictional-Company could use
<code>stringType=”com.fictional_company.cool_product.unicorn_detector”</code>.
The <code>stringType</code> is used to uniquely identify non-official sensors types. See <a
- href="{@docRoot}devices/reference/sensors_8h.html">sensors.h</a> for more
+ href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a> for more
information on types and string types.</p>
<p><strong>requiredPermission:</strong> A string representing the permission that applications must
possess to see the sensor, register to it and receive its data. An empty string
@@ -328,7 +328,7 @@
<p>Sensor events generated by Android sensors and reported through the <a
href="#poll">poll</a> function are of <code>type sensors_event_t</code>. Here are some
important fields of <code>sensors_event_t</code>:</p>
-<p>version: must be <code>sizeof(struct sensors_event_t)</code></p>
+<p><strong>version:</strong> Must be <code>sizeof(struct sensors_event_t)</code></p>
<p><strong>sensor:</strong> The handle of the sensor that generated the event, as defined by
<code>sensor_t.handle</code>.</p>
<p><strong>type:</strong> The sensor type of the sensor that generated the event, as defined by
@@ -342,9 +342,9 @@
causes too high jitter, and using only the sensor chip time to set the
timestamps can cause de-synchronization from the
<code>elapsedRealtimeNano</code> clock, as the sensor clock drifts.</p>
-<p>data and overlapping fields: The values measured by the sensor. The meaning and
+<p><strong>data and overlapping fields:</strong> The values measured by the sensor. The meaning and
units of those fields are specific to each sensor type. See <a
- href="{@docRoot}devices/reference/sensors_8h.html">sensors.h</a> and the
+ href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a> and the
definition of the different <a href="sensor-types.html">Sensor types</a> for a
description of the data fields. For some sensors, the accuracy of the
readings is also reported as part of the data, through a <code>status</code> field. This
@@ -355,10 +355,10 @@
<p>Metadata events have the same type as normal sensor events:
<code>sensors_event_meta_data_t = sensors_event_t</code>. They are returned together with
other sensor events through poll. They possess the following fields:</p>
-<p>version must be <code>META_DATA_VERSION</code></p>
-<p>type must be <code>SENSOR_TYPE_META_DATA</code></p>
-<p>sensor, reserved, and <strong>timestamp </strong>must be 0</p>
-<p>meta_data.what contains the metadata type for this event. There is currently a
+<p><strong>version:</strong> Must be <code>META_DATA_VERSION</code></p>
+<p><strong>type:</strong> Must be <code>SENSOR_TYPE_META_DATA</code></p>
+<p><strong>sensor, reserved, and timestamp</strong>: Must be 0</p>
+<p><strong>meta_data.what:</strong> Contains the metadata type for this event. There is currently a
single valid metadata type: <code>META_DATA_FLUSH_COMPLETE</code>.</p>
<p><code>META_DATA_FLUSH_COMPLETE</code> events represent the completion of the flush of a
sensor FIFO. When <code>meta_data.what=META_DATA_FLUSH_COMPLETE</code>, <code>meta_data.sensor</code>
diff --git a/src/devices/sensors/index.jd b/src/devices/sensors/index.jd
index 6f21488..dea285b 100644
--- a/src/devices/sensors/index.jd
+++ b/src/devices/sensors/index.jd
@@ -28,19 +28,19 @@
<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/reference/sensors_8h.html">sensors.h</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>
+ 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>
+ 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>
+ microphone.</li>
</ul>
<p>How the different physical sensors are connected to the system on chip
(SoC) is not defined by Android.</p>
@@ -62,7 +62,7 @@
<p>Each Android sensor has a “type” representing how the sensor behaves and what
data it provides.</p>
<ul>
- <li> The official Android <a href="sensor-types.html">Sensor types</a> are defined in <a href="{@docRoot}devices/reference/sensors_8h.html">sensors.h</a> under the names SENSOR_TYPE_…
+ <li> The official Android <a href="sensor-types.html">Sensor types</a> are defined in <a href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a> under the names SENSOR_TYPE_…
<ul>
<li> The vast majority of sensors have an official sensor type. </li>
<li> Those types are documented in the Android SDK. </li>
@@ -144,7 +144,7 @@
</li>
<li> Hardware abstraction layer (HAL)
<ul>
- <li> <a href="{@docRoot}devices/reference/sensors_8h_source.html">https://source.android.com/devices/reference/sensors_8h_source.html</a></li>
+ <li> <a href="{@docRoot}devices/halref/sensors_8h_source.html">https://source.android.com/devices/halref/sensors_8h_source.html</a></li>
<li> Also known as “sensors.h” </li>
<li> The source of truth. First document to be updated when new features are
developed. </li>
diff --git a/src/devices/sensors/sensor-stack.jd b/src/devices/sensors/sensor-stack.jd
index 9776c44..5ffcce8 100644
--- a/src/devices/sensors/sensor-stack.jd
+++ b/src/devices/sensors/sensor-stack.jd
@@ -128,7 +128,7 @@
<p>The interface is defined by Android and AOSP contributors, and the
implementation is provided by the manufacturer of the device.</p>
<p>The sensor HAL interface is located in <code>hardware/libhardware/include/hardware</code>.
- See <a href="{@docRoot}devices/reference/sensors_8h.html">sensors.h</a> for additional details.</p>
+ See <a href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a> for additional details.</p>
<h3 id="release_cycle">Release cycle</h3>
<p>The HAL implementation specifies what version of the HAL interface it
implements by setting <code>your_poll_device.common.version</code>. The existing HAL
diff --git a/src/devices/sensors/sensor-types.jd b/src/devices/sensors/sensor-types.jd
index 824680f..7ebac25 100644
--- a/src/devices/sensors/sensor-types.jd
+++ b/src/devices/sensors/sensor-types.jd
@@ -274,15 +274,17 @@
<td><p>Continuous</p></td>
</tr>
<tr>
- <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" />
- <p>i<a href="#geomagnetic_rotation_vector"Geomagnetic rotation vector</a></p></td>
+ <td><p><a href="#geomagnetic_rotation_vector">Geomagnetic rotation
+ vector</a> <img src="images/battery_icon.png" width="20" height="20" alt="Low
+ power sensor" /></p></td>
<td><p>Attitude</p></td>
<td><p>Accelerometer, Magnetometer, MUST NOT USE Gyroscope</p></td>
<td><p>Continuous</p></td>
</tr>
<tr>
- <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" />
- <p><a href="#glance_gesture">Glance gesture</a></p></td>
+ <td><a href="#glance_gesture">Glance gesture</a> <img
+ src="images/battery_icon.png" width="20" height="20" alt="Low power sensor"
+ /></p></td>
<td><p>Interaction</p></td>
<td><p>Undefined</p></td>
<td><p>One-shot</p></td>
@@ -318,8 +320,9 @@
<td><p>Continuous</p></td>
</tr>
<tr>
- <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" />
- <p><a href="#pick_up_gesture">Pick up gesture</a></p></td>
+ <td><p><a href="#pick_up_gesture">Pick up gesture</a> <img
+ src="images/battery_icon.png" width="20" height="20" alt="Low power sensor"
+ /></p></td>
<td><p>Interaction</p></td>
<td><p>Undefined</p></td>
<td><p>One-shot</p></td>
@@ -331,43 +334,46 @@
<td><p>Continuous</p></td>
</tr>
<tr>
- <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" />
- <p><a href="#significant_motion">Significant motion</a></p></td>
+ <td><p><a href="#significant_motion">Significant motion</a> <img
+ src="images/battery_icon.png" width="20" height="20" alt="Low power sensor"
+ /></p></td>
<td><p>Activity</p></td>
<td><p>Accelerometer (or another as long as very low power)</p></td>
<td><p>One-shot</p></td>
</tr>
<tr>
- <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" />
- <p><a href="#step_counter">Step counter</a></p></td>
+ <td><p><a href="#step_counter">Step counter</a> <img
+ src="images/battery_icon.png" width="20" height="20" alt="Low power sensor"
+ /></p></td>
<td><p>Activity</p></td>
<td><p>Accelerometer</p></td>
<td><p>On-change</p></td>
</tr>
<tr>
- <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" />
- <p><a href="#step_detector">Step detector</a></p></td>
+ <td><p><a href="#step_detector">Step detector</a> <img
+ src="images/battery_icon.png" width="20" height="20" alt="Low power sensor"
+ /></p></td> <td><p>Activity</p></td>
+ <td><p>Accelerometer</p></td>
+ <td><p>Special</p></td>
+ </tr>
+ <tr>
+ <td><p><a href="#tilt_detector">Tilt detector</a> <img
+ src="images/battery_icon.png" width="20" height="20" alt="Low power sensor"
+ /></p></td>
<td><p>Activity</p></td>
<td><p>Accelerometer</p></td>
<td><p>Special</p></td>
</tr>
<tr>
- <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" />
- <p><a href="#tilt_detector">Tilt detector</a></p></td>
- <td><p>Activity</p></td>
- <td><p>Accelerometer</p></td>
- <td><p>Special</p></td>
- </tr>
- <tr>
- <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" />
- <p><a href="#wake_up_gesture">Wake up gesture</a></p></td>
+ <td><p><a href="#wake_up_gesture">Wake up gesture</a> <img
+ src="images/battery_icon.png" width="20" height="20" alt="Low power sensor"
+ /></p></td>
<td><p>Interaction</p></td>
<td><p>Undefined</p></td>
<td><p>One-shot</p></td>
</tr>
</table>
-<img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" />
-<p> = Low power sensor</p>
+<p><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /> = Low power sensor</p>
<h2 id="activity_composite_sensors">Activity composite sensors</h2>
<h3 id="linear_acceleration">Linear acceleration</h3>
<p>Underlying physical sensors: Accelerometer and (if present) Gyroscope (or
@@ -622,7 +628,7 @@
direction. (Mathematically speaking, it should be positive in the
counter-clockwise direction):</p>
<div class="figure" style="width:264px">
- <imgsrc="images/axis_positive_roll.png" alt="Depiction of orientation
+ <img src="images/axis_positive_roll.png" alt="Depiction of orientation
relative to a device" height="253" />
<p class="img-caption">
<strong>Figure 2.</strong> Orientation relative to a device.
diff --git a/src/devices/tech/dalvik/art.jd b/src/devices/tech/dalvik/art.jd
deleted file mode 100644
index 33a82ed..0000000
--- a/src/devices/tech/dalvik/art.jd
+++ /dev/null
@@ -1,244 +0,0 @@
-page.title=Introducing ART
-@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 id="Contents">In this document</h2>
- <ol id="auto-toc">
- </ol>
- <strong>See also</strong>
- <ol>
- <li><a
- href="http://developer.android.com/guide/practices/verifying-apps-art.html">Verifying
- App Behavior on the Android Runtime (ART)</a></li>
- </ol>
-</div>
-</div>
-
-<p>
-ART is a new Android runtime being introduced experimentally in the 4.4
-release. This is a preview of work in progress in KitKat that can be turned on
-in <strong>Settings</strong> > <strong>developer options</strong>. This is
-available for the purpose of obtaining early developer and partner feedback.</p>
-
-<p class="caution"><strong>Important:</strong> Dalvik must remain the default
-runtime or you risk breaking your Android implementations and third-party
-applications.</p>
-
-<p>Most existing apps should just work when running with ART. However, some
-techniques that work on Dalvik do not work on ART. For information about the
-most important issues, see <a
-href="http://developer.android.com/guide/practices/verifying-apps-art.html">Verifying
-App Behavior on the Android Runtime (ART)</a>.</p>
-
-<h2 id="features">ART Features</h2>
-
-<p>Here are some of the major new features implemented by ART.</p>
-
-<h3 id="AOT_compilation">Ahead-of-time (AOT) compilation</h3>
-
-<p>ART introduces ahead-of-time (AOT) compilation, which can improve app
-performance. ART also has tighter install-time verification than Dalvik.</p>
-
-<p>At install time, ART compiles apps using the on-device
-<strong>dex2oat</strong> tool. This utility accepts <a
-href="http://source.android.com/devices/tech/dalvik/dex-format.html">DEX</a> files as input and
-generates a compiled app executable for the target device. The utility should be
-able to compile all valid DEX files without difficulty. However, some
-post-processing tools produce invalid files that may be tolerated by Dalvik but
-cannot be compiled by ART. For more information, see <a
-href="http://developer.android.com/guide/practices/verifying-apps-art.html#GC_Migration">Addressing
-Garbage Collection Issues</a>.</p>
-
-<h3 id="Improved_GC">Improved garbage collection</h3>
-
-<p>Garbage collection (GC) can impair an app's performance, resulting in choppy
-display, poor UI responsiveness, and other problems. ART improves garbage
-collection in several ways:</p>
-
-<ul>
- <li>One GC pause instead of two</li>
- <li>Parallelized processing during the remaining GC pause</li>
- <li>Collector with lower pause time for the special case of cleaning up
- recently-allocated, short-lived objects</li>
- <li>Improved garbage collection ergonomics, making concurrent garbage
- collections more timely, which makes <a
- href="http://developer.android.com/tools/debugging/debugging-memory.html#LogMessages"><code>GC_FOR_ALLOC</code></a>
- events extremely rare in typical use cases</li>
-</ul>
-
-<p>ART currently does not use compacting GC, but this feature is under
-development in the <a href="https://source.android.com">Android Open Source
-Project (AOSP)</a>. In the meantime, don't perform operations that are
-incompatible with compacting GC, such as storing pointers to object fields. For
-more information, see <a
-href="http://developer.android.com/guide/practices/verifying-apps-art.html#GC_Migration">Addressing
-Garbage Collection Issues</a>.</p>
-
-<h3 id="Debugging_Imp">Development and debugging improvements</h3>
-
-<p>ART offers a number of features to improve app development and debugging.</p>
-
-<h4 id="Sampling_Profiler">Support for sampling profiler</h4>
-
-<p>Historically, developers have used the <a
-href=" http://developer.android.com/tools/help/traceview.html">Traceview</a>
-tool (designed for tracing
-application execution) as a profiler. While Traceview gives useful information,
-its results on Dalvik have been skewed by the per-method-call overhead, and use
-of the tool noticeably affects run time performance.</p>
-
-<p>ART adds support for a dedicated sampling profiler that does not have these
-limitations. This gives a more accurate view of app execution without
-significant slowdown. Sampling support has also been added to Traceview for
-Dalvik.</p>
-
-<h4 id="Debugging_Features">Support for more debugging features</h4>
-
-<p>ART supports a number of new debugging options, particularly in monitor- and
-garbage collection-related functionality. For example, you can:</p>
-
-<ul>
- <li>See what locks are held in stack traces, then jump to the thread that
- holds a lock.</li>
- <li>Ask how many live instances there are of a given class, ask to see the
- instances, and see what references are keeping an object live.</li>
- <li>Filter events (like breakpoint) for a specific instance.</li>
- <li>See the value returned by a method when it exits (using “method-exit”
- events).</li>
- <li>Set field watchpoint to suspend the execution of a program when a specific
- field is accessed and/or modified.</li>
-</ul>
-
-<h4 id="Crash_Reports">Improved diagnostic detail in exceptions and crash reports</h4>
-
-<p>ART gives you as much context and detail as possible when runtime exceptions
-occur. ART provides expanded exception detail for <code><a
-href="http://developer.android.com/reference/java/lang/ClassCastException.html">java.lang.ClassCastException</a></code>,
-<code><a
-href="http://developer.android.com/reference/java/lang/ClassNotFoundException.html">java.lang.ClassNotFoundException</a></code>,
-and <code><a
-href="http://developer.android.com/reference/java/lang/NullPointerException.html">java.lang.NullPointerException</a></code>.
-(Later versions of Dalvik provided expanded exception detail for <code><a
-href="http://developer.android.com/reference/java/lang/ArrayIndexOutOfBoundsException.html">java.lang.ArrayIndexOutOfBoundsException</a></code>
-and <code><a
-href="http://developer.android.com/reference/java/lang/ArrayStoreException.html">java.lang.ArrayStoreException</a></code>,
-which now include the size of the array and the out-of-bounds offset, and ART
-does this as well.)</p>
-
-<p>For example, <code><a
-href="http://developer.android.com/reference/java/lang/NullPointerException.html">java.lang.NullPointerException</a></code>
-now shows information about what the app was trying to do with the null pointer,
-such as the field the app was trying to write to, or the method it was trying to
-call. Here are some typical examples:</p>
-
-<pre class="no-pretty-print">
-java.lang.NullPointerException: Attempt to write to field 'int
-android.accessibilityservice.AccessibilityServiceInfo.flags' on a null object
-reference</pre>
-
-<pre class="no-pretty-print">
-java.lang.NullPointerException: Attempt to invoke virtual method
-'java.lang.String java.lang.Object.toString()' on a null object reference</pre>
-
-<p>ART also provides improved context information in app native crash reports,
-by including both Java and native stack information. </p>
-
-<h2 id="Known_Issues">Known Issues</h2>
-
-<p>The following known issues are present in the 4.4.1 implementation of ART.</p>
-
-<ul>
-
- <li><em>Compile-time issue:</em> As noted above, ART flags unbalanced
- <code>monitorenter</code>/<code>moniterexit</code> instructions. We relaxed
- this check in 4.4.1 but intend to restore this verification in the future once
- tools are fixed, as this check is necessary for certain compiler
- optimizations. <a
- href="https://code.google.com/p/android/issues/detail?id=61916">https://code.google.com/p/android/issues/detail?id=61916</a></li>
-
- <li><em>Run-time issue:</em> There was an issue where JNI
- <code>GetFieldID</code> and <code>GetStaticFieldID</code> were using the wrong
- class loader on unattached threads, often leading to later CheckJNI errors or
- NoSuchFieldError exceptions. <a
- href="http://code.google.com/p/android/issues/detail?id=63970">http://code.google.com/p/android/issues/detail?id=63970</a></li>
-
- <li><em>Run-time issue:</em> Calling JNI <code>NewDirectByteBuffer()</code>
- with byte size of <code>0</code> led to the following CheckJNI error: <pre
- class="no-pretty-print"> JNI DETECTED ERROR IN APPLICATION: capacity must be
- greater than 0: 0</pre> <a
- href="http://code.google.com/p/android/issues/detail?id=63055">http://code.google.com/p/android/issues/detail?id=63055</a></li>
-
-</ul>
-
-<h3 id="Fixed_Issues">Fixed issues</h3>
-
-<ul>
-
- <li><em>Compile-time issue:</em> Overly aggressive verification and
- compilation of unused portions of dex files lead to corrupt package messages.
- This was addressed in AOSP with: <a
- href="https://android-review.googlesource.com/#/c/72374/">https://android-review.googlesource.com/#/c/72374/</a></li>
-
- <li><em>Debug-time issue:</em> Interactive debugging performance was slow,
- even in code without breakpoints. This has been addressed in the latest AOSP
- code.</li>
-
-</ul>
-
-<h2 id="building">Enabling ART in Android Build</h2>
-
-<p> Two runtimes are now available, the existing Dalvik runtime
-(<code>libdvm.so</code>) and the ART runtime (<code>libart.so</code>). A device
-can be built using either or both runtimes. (You can dual boot from
-<strong>Developer options</strong> if both runtimes are installed.) See
-runtime_common.mk. That is included from build/target/product/runtime_libdvm.mk
-or build/target/product/runtime_libart.mk or both.</p>
-
-<p> The <code>dalvikvm</code> command line tool can run with either runtime now.
-It will default to using the runtime specified in <strong>developer
-options</strong>. The default can be overridden by specifying the desired
-runtime library, for example with <code>-XXlib:libart.so</code> </p>
-
-<p>
-A new <code>PRODUCT_RUNTIMES</code> variable controls which runtimes
-are included in a build. Include it within either
-<code>build/target/product/core_minimal.mk</code> or
-<code>build/target/product/core_base.mk</code>.
-</p>
-
-<p>
-Add this to the device makefile to have both runtimes
-built and installed, with Dalvik as the default:
-</br>
-<code>PRODUCT_RUNTIMES := runtime_libdvm_default</code>
-</br>
-<code>PRODUCT_RUNTIMES += runtime_libart</code>
-</p>
-
-<h2 id="Reporting_Problems">Reporting Problems</h2>
-
-<p>If you run into any issues that aren’t due to app JNI issues, please report
-them via the Android Open Source Project Issue Tracker at <a
-href="https://code.google.com/p/android/issues/list">https://code.google.com/p/android/issues/list</a>.
-Please include an <code>"adb bugreport"</code> and link to the app in Google
-Play store if available. Otherwise, if possible, attach an APK that reproduces
-the issue. Please note that issues (including attachments) are publicly
-visible.</p>
diff --git a/src/devices/tech/dalvik/dalvik-bytecode.jd b/src/devices/tech/dalvik/dalvik-bytecode.jd
index 8d4f52b..1b9b9e3 100644
--- a/src/devices/tech/dalvik/dalvik-bytecode.jd
+++ b/src/devices/tech/dalvik/dalvik-bytecode.jd
@@ -1,8 +1,8 @@
-page.title=Bytecode for the Dalvik VM
+page.title=Dalvik bytecode
@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.
@@ -16,13 +16,21 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<h2>General Design</h2>
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<h2 id="design">General design</h2>
<ul>
<li>The machine model and calling conventions are meant to approximately
imitate common real architectures and C-style calling conventions:
<ul>
- <li>The VM is register-based, and frames are fixed in size upon creation.
+ <li>The machine is register-based, and frames are fixed in size upon creation.
Each frame consists of a particular number of registers (specified by
the method) as well as any adjunct data needed to execute the method,
such as (but not limited to) the program counter and a reference to the
@@ -149,7 +157,7 @@
</li>
</ul>
-<h2>Summary of Instruction Set</h2>
+<h2 id="instructions">Summary of bytecode set</h2>
<table class="instruc">
<thead>
@@ -987,7 +995,7 @@
</tbody>
</table>
-<h2>packed-switch-payload Format</h2>
+<h2 id="packed-switch">packed-switch-payload format</h2>
<table class="supplement">
<thead>
@@ -1026,7 +1034,7 @@
<p><b>Note:</b> The total number of code units for an instance of this
table is <code>(size * 2) + 4</code>.</p>
-<h2>sparse-switch-payload Format</h2>
+<h2 id="sparse-switch">sparse-switch-payload format</h2>
<table class="supplement">
<thead>
@@ -1066,7 +1074,7 @@
<p><b>Note:</b> The total number of code units for an instance of this
table is <code>(size * 4) + 2</code>.</p>
-<h2>fill-array-data-payload Format</h2>
+<h2 id="fill-array">fill-array-data-payload format</h2>
<table class="supplement">
<thead>
@@ -1104,7 +1112,7 @@
table is <code>(size * element_width + 1) / 2 + 4</code>.</p>
-<h2>Mathematical Operation Details</h2>
+<h2 id="math">Mathematical operation details</h2>
<p><b>Note:</b> Floating point operations must follow IEEE 754 rules, using
round-to-nearest and gradual underflow, except where stated otherwise.</p>
diff --git a/src/devices/tech/dalvik/dex-format.jd b/src/devices/tech/dalvik/dex-format.jd
index 744eb86..bd167fb 100644
--- a/src/devices/tech/dalvik/dex-format.jd
+++ b/src/devices/tech/dalvik/dex-format.jd
@@ -1,4 +1,4 @@
-page.title=Dalvik Executable Format
+page.title=Dalvik Executable format
@jd:body
<!--
@@ -20,7 +20,7 @@
files, which are used to hold a set of class definitions and their associated
adjunct data.</p>
-<h2>Guide To Types</h2>
+<h2 id="types">Guide to types</h2>
<table class="guide">
<thead>
@@ -77,7 +77,7 @@
</tbody>
</table>
-<h3>LEB128</h3>
+<h3 id="leb128">LEB128</h3>
<p>LEB128 ("<b>L</b>ittle-<b>E</b>ndian <b>B</b>ase <b>128</b>") is a
variable-length encoding for
@@ -157,7 +157,7 @@
</tbody>
</table>
-<h2>Overall File Layout</h2>
+<h2 id="file-layout">File layout</h2>
<table class="format">
<thead>
@@ -256,9 +256,9 @@
</tbody>
</table>
-<h2>Bitfield, String, and Constant Definitions</h2>
+<h2 id="definitions">Bitfield, string and constant definitions</h2>
-<h3>DEX_FILE_MAGIC</h3>
+<h3 id="dex-file-magic">DEX_FILE_MAGIC</h3>
<h4>embedded in header_item</h4>
<p>The constant array/string <code>DEX_FILE_MAGIC</code> is the list of
@@ -284,7 +284,7 @@
versions of the format differ significantly from the version described in this
document.</p>
-<h3>ENDIAN_CONSTANT and REVERSE_ENDIAN_CONSTANT</h3>
+<h3 id="endian-constant">ENDIAN_CONSTANT and REVERSE_ENDIAN_CONSTANT</h3>
<h4>embedded in header_item</h4>
<p>The constant <code>ENDIAN_CONSTANT</code> is used to indicate the
@@ -300,7 +300,7 @@
uint REVERSE_ENDIAN_CONSTANT = 0x78563412;
</pre>
-<h3>NO_INDEX</h3>
+<h3 id="no-index">NO_INDEX</h3>
<h4>embedded in class_def_item and debug_info_item</h4>
<p>The constant <code>NO_INDEX</code> is used to indicate that
@@ -316,7 +316,7 @@
uint NO_INDEX = 0xffffffff; // == -1 if treated as a signed int
</pre>
-<h3>access_flags Definitions</h3>
+<h3 id="access-flags">access_flags definitions</h3>
<h4>embedded in class_def_item, encoded_field, encoded_method, and
InnerClass</h4>
@@ -492,7 +492,7 @@
<p><super>*</super> Only allowed on for <code>InnerClass</code> annotations,
and must not ever be on in a <code>class_def_item</code>.</p>
-<h3>MUTF-8 (Modified UTF-8) Encoding</h3>
+<h3 id="mutf-8">MUTF-8 (Modified UTF-8) Encoding</h3>
<p>As a concession to easier legacy support, the <code>.dex</code> format
encodes its string data in a de facto standard modified UTF-8 form, hereafter
@@ -531,7 +531,7 @@
<a href="http://www.unicode.org/reports/tr26/">CESU-8</a> than to UTF-8
per se.</p>
-<h3>encoded_value Encoding</h3>
+<h3 id="encoding">encoded_value encoding</h3>
<h4>embedded in annotation_element and encoded_array_item </h4>
<p>An <code>encoded_value</code> is an encoded piece of (nearly)
@@ -573,7 +573,7 @@
</tbody>
</table>
-<h3>Value Formats</h3>
+<h3 id="value-formats">Value formats</h3>
<table class="encodedValue">
<thead>
@@ -699,7 +699,7 @@
<td><i>(none; must be <code>0</code>)</i></td>
<td>encoded_array</td>
<td>an array of values, in the format specified by
- "<code>encoded_array</code> Format" below. The size
+ "<code>encoded_array</code> format" below. The size
of the <code>value</code> is implicit in the encoding.
</td>
</tr>
@@ -709,7 +709,7 @@
<td><i>(none; must be <code>0</code>)</i></td>
<td>encoded_annotation</td>
<td>a sub-annotation, in the format specified by
- "<code>encoded_annotation</code> Format" below. The size
+ "<code>encoded_annotation</code> format" below. The size
of the <code>value</code> is implicit in the encoding.
</td>
</tr>
@@ -733,7 +733,7 @@
</tbody>
</table>
-<h3>encoded_array Format</h3>
+<h3 id="encoded-array">encoded_array format</h3>
<table class="format">
<thead>
@@ -760,7 +760,7 @@
</tbody>
</table>
-<h3>encoded_annotation Format</h3>
+<h3 id="encoded-annotation">encoded_annotation format</h3>
<table class="format">
<thead>
@@ -794,7 +794,7 @@
</tbody>
</table>
-<h3>annotation_element Format</h3>
+<h3 id="annotation-element">annotation_element format</h3>
<table class="format">
<thead>
@@ -821,13 +821,13 @@
</tbody>
</table>
-<h2>String Syntax</h2>
+<h2 id="string-syntax">String syntax</h2>
<p>There are several kinds of item in a <code>.dex</code> file which
ultimately refer to a string. The following BNF-style definitions
indicate the acceptable syntax for these strings.</p>
-<h3><i>SimpleName</i></h3>
+<h3 id="simplename"><i>SimpleName</i></h3>
<p>A <i>SimpleName</i> is the basis for the syntax of the names of other
things. The <code>.dex</code> format allows a fair amount of latitude
@@ -896,7 +896,7 @@
</tr>
</table>
-<h3><i>MemberName</i></h3>
+<h3 id="membername"><i>MemberName</i></h3>
<h4>used by field_id_item and method_id_item</h4>
<p>A <i>MemberName</i> is the name of a member of a class, members being
@@ -914,7 +914,7 @@
</tr>
</table>
-<h3><i>FullClassName</i></h3>
+<h3 id="fullclassname"><i>FullClassName</i></h3>
<p>A <i>FullClassName</i> is a fully-qualified class name, including an
optional package specifier followed by a required name.</p>
@@ -933,7 +933,7 @@
</tr>
</table>
-<h3><i>TypeDescriptor</i></h3>
+<h3 id="typedescriptor"><i>TypeDescriptor</i></h3>
<h4>used by type_id_item</h4>
<p>A <i>TypeDescriptor</i> is the representation of any type, including
@@ -1003,7 +1003,7 @@
</tr>
</table>
-<h3><i>ShortyDescriptor</i></h3>
+<h3 id="shortydescriptor"><i>ShortyDescriptor</i></h3>
<h4>used by proto_id_item</h4>
<p>A <i>ShortyDescriptor</i> is the short form representation of a method
@@ -1067,7 +1067,7 @@
</tr>
</table>
-<h3><i>TypeDescriptor</i> Semantics</h3>
+<h3 id="typedescriptor"><i>TypeDescriptor</i> Semantics</h3>
<p>This is the meaning of each of the variants of <i>TypeDescriptor</i>.</p>
@@ -1129,12 +1129,12 @@
</tbody>
</table>
-<h2>Items and Related Structures</h2>
+<h2 id="items">Items and related structures</h2>
<p>This section includes definitions for each of the top-level items that
may appear in a <code>.dex</code> file.
-<h3>header_item</h3>
+<h3 id="header-item">header_item</h3>
<h4>appears in the header section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1317,7 +1317,7 @@
</tbody>
</table>
-<h3>map_list</h3>
+<h3 id="map-list">map_list</h3>
<h4>appears in the data section</h4>
<h4>referenced from header_item</h4>
<h4>alignment: 4 bytes</h4>
@@ -1354,7 +1354,7 @@
</tbody>
</table>
-<h3>map_item Format</h3>
+<h3 id="map-item">map_item format</h3>
<table class="format">
<thead>
@@ -1389,7 +1389,7 @@
</table>
-<h3>Type Codes</h3>
+<h3 id="type-codes">Type Codes</h3>
<table class="typeCodes">
<thead>
@@ -1513,7 +1513,7 @@
</table>
-<h3>string_id_item</h3>
+<h3 id="string-item">string_id_item</h3>
<h4>appears in the string_ids section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1539,7 +1539,7 @@
</tbody>
</table>
-<h3>string_data_item</h3>
+<h3 id="string-data-item">string_data_item</h3>
<h4>appears in the data section</h4>
<h4>alignment: none (byte-aligned)</h4>
@@ -1578,7 +1578,7 @@
</tbody>
</table>
-<h3>type_id_item</h3>
+<h3 id="type-id-item">type_id_item</h3>
<h4>appears in the type_ids section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1602,7 +1602,7 @@
</tbody>
</table>
-<h3>proto_id_item</h3>
+<h3 id="proto-id-item">proto_id_item</h3>
<h4>appears in the proto_ids section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1645,7 +1645,7 @@
</tbody>
</table>
-<h3>field_id_item</h3>
+<h3 id="field-id-item">field_id_item</h3>
<h4>appears in the field_ids section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1683,7 +1683,7 @@
</tbody>
</table>
-<h3>method_id_item</h3>
+<h3 id="method-id-item">method_id_item</h3>
<h4>appears in the method_ids section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1721,7 +1721,7 @@
</tbody>
</table>
-<h3>class_def_item</h3>
+<h3 id="class-def-item">class_def_item</h3>
<h4>appears in the class_defs section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1825,7 +1825,7 @@
</tbody>
</table>
-<h3>class_data_item</h3>
+<h3 id="class-data-item">class_data_item</h3>
<h4>referenced from class_def_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: none (byte-aligned)</h4>
@@ -1900,7 +1900,7 @@
<p><b>Note:</b> All elements' <code>field_id</code>s and
<code>method_id</code>s must refer to the same defining class.</p>
-<h3>encoded_field Format</h3>
+<h3 id="encoded-field-format">encoded_field format</h3>
<table class="format">
<thead>
@@ -1930,7 +1930,7 @@
</tbody>
</table>
-<h3>encoded_method Format</h3>
+<h3 id="encoded-method">encoded_method format</h3>
<table class="format">
<thead>
@@ -1970,7 +1970,7 @@
</tbody>
</table>
-<h3>type_list</h3>
+<h3 id="type-list">type_list</h3>
<h4>referenced from class_def_item and proto_id_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: 4 bytes</h4>
@@ -1997,7 +1997,7 @@
</tbody>
</table>
-<h3>type_item Format</h3>
+<h3 id="type-item-format">type_item format</h3>
<table class="format">
<thead>
@@ -2016,7 +2016,7 @@
</tbody>
</table>
-<h3>code_item</h3>
+<h3 id="code-item">code_item</h3>
<h4>referenced from encoded_method</h4>
<h4>appears in the data section</h4>
<h4>alignment: 4 bytes</h4>
@@ -2076,7 +2076,7 @@
<td>ushort[insns_size]</td>
<td>actual array of bytecode. The format of code in an <code>insns</code>
array is specified by the companion document
- <a href="dalvik-bytecode.html">"Bytecode for the Dalvik VM"</a>. Note
+ <a href="dalvik-bytecode.html">Dalvik bytecode</a>. Note
that though this is defined as an array of <code>ushort</code>, there
are some internal structures that prefer four-byte alignment. Also,
if this happens to be in an endian-swapped file, then the swapping is
@@ -2113,7 +2113,7 @@
</tbody>
</table>
-<h3>try_item Format</h3>
+<h3 id="type-item">try_item format</h3>
<table class="format">
<thead>
@@ -2151,7 +2151,7 @@
</tbody>
</table>
-<h3>encoded_catch_handler_list Format</h3>
+<h3 id="encoded-catch-handlerlist">encoded_catch_handler_list format</h3>
<table class="format">
<thead>
@@ -2176,7 +2176,7 @@
</tbody>
</table>
-<h3>encoded_catch_handler Format</h3>
+<h3 id="encoded-catch-handler">encoded_catch_handler format</h3>
<table class="format">
<thead>
@@ -2216,7 +2216,7 @@
</tbody>
</table>
-<h3>encoded_type_addr_pair Format</h3>
+<h3 id="encoded-type-addr-pair">encoded_type_addr_pair format</h3>
<table class="format">
<thead>
@@ -2242,7 +2242,7 @@
</tbody>
</table>
-<h3>debug_info_item</h3>
+<h3 id="debug-info-item">debug_info_item</h3>
<h4>referenced from code_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: none (byte-aligned)</h4>
@@ -2457,7 +2457,7 @@
</tbody>
</table>
-<h3>Special Opcodes</h3>
+<h3 id="opcodes">Special opcodes</h3>
<p>Opcodes with values between <code>0x0a</code> and <code>0xff</code>
(inclusive) move both the <code>line</code> and <code>address</code>
@@ -2475,7 +2475,7 @@
address += (adjusted_opcode / DBG_LINE_RANGE)
</pre>
-<h3>annotations_directory_item</h3>
+<h3 id="annotations-directory">annotations_directory_item</h3>
<h4>referenced from class_def_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: 4 bytes</h4>
@@ -2541,7 +2541,7 @@
<p><b>Note:</b> All elements' <code>field_id</code>s and
<code>method_id</code>s must refer to the same defining class.</p>
-<h3>field_annotation Format</h3>
+<h3 id="field-annotation">field_annotation format</h3>
<table class="format">
<thead>
@@ -2571,7 +2571,7 @@
</tbody>
</table>
-<h3>method_annotation Format</h3>
+<h3 id="method-annotation">method_annotation format</h3>
<table class="format">
<thead>
@@ -2601,7 +2601,7 @@
</tbody>
</table>
-<h3>parameter_annotation Format</h3>
+<h3 id="parameter-annotation">parameter_annotation format</h3>
<table class="format">
<thead>
@@ -2631,7 +2631,7 @@
</tbody>
</table>
-<h3>annotation_set_ref_list</h3>
+<h3 id="set-ref-list">annotation_set_ref_list</h3>
<h4>referenced from parameter_annotations_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: 4 bytes</h4>
@@ -2658,7 +2658,7 @@
</tbody>
</table>
-<h3>annotation_set_ref_item Format</h3>
+<h3 id="set-ref-item">annotation_set_ref_item format</h3>
<table class="format">
<thead>
@@ -2682,7 +2682,7 @@
</tbody>
</table>
-<h3>annotation_set_item</h3>
+<h3 id="annotation-set-item">annotation_set_item</h3>
<h4>referenced from annotations_directory_item, field_annotations_item,
method_annotations_item, and annotation_set_ref_item</h4>
<h4>appears in the data section</h4>
@@ -2712,7 +2712,7 @@
</tbody>
</table>
-<h3>annotation_off_item Format</h3>
+<h3 id="off-item">annotation_off_item format</h3>
<table class="format">
<thead>
@@ -2736,7 +2736,7 @@
</table>
-<h3>annotation_item</h3>
+<h3 id="annotation-item">annotation_item</h3>
<h4>referenced from annotation_set_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: none (byte-aligned)</h4>
@@ -2759,14 +2759,14 @@
<td>annotation</td>
<td>encoded_annotation</td>
<td>encoded annotation contents, in the format described by
- "<code>encoded_annotation</code> Format" under
- "<code>encoded_value</code> Encoding" above.
+ "<code>encoded_annotation</code> format" under
+ "<code>encoded_value</code> encoding" above.
</td>
</tr>
</tbody>
</table>
-<h3>Visibility values</h3>
+<h3 id="visibility">Visibility values</h3>
<p>These are the options for the <code>visibility</code> field in an
<code>annotation_item</code>:</p>
@@ -2802,7 +2802,7 @@
</tbody>
</table>
-<h3>encoded_array_item</h3>
+<h3 id="encoded-array-item">encoded_array_item</h3>
<h4>referenced from class_def_item</h4>
<h4>appears in the data section</h4>
<h4>alignment: none (byte-aligned)</h4>
@@ -2827,7 +2827,7 @@
</tbody>
</table>
-<h2>System Annotations</h2>
+<h2 id="system-annotation">System annotations</h2>
<p>System annotations are used to represent various pieces of reflective
information about classes (and methods and fields). This information is
@@ -2836,7 +2836,7 @@
<p>System annotations are represented in <code>.dex</code> files as
annotations with visibility set to <code>VISIBILITY_SYSTEM</code>.
-<h3>dalvik.annotation.AnnotationDefault</h3>
+<h3 id="dalvik-annotation-default">dalvik.annotation.AnnotationDefault</h3>
<h4>appears on methods in annotation interfaces</h4>
<p>An <code>AnnotationDefault</code> annotation is attached to each
@@ -2862,7 +2862,7 @@
</tbody>
</table>
-<h3>dalvik.annotation.EnclosingClass</h3>
+<h3 id="dalvik-enclosingclass">dalvik.annotation.EnclosingClass</h3>
<h4>appears on classes</h4>
<p>An <code>EnclosingClass</code> annotation is attached to each class
@@ -2890,7 +2890,7 @@
</tbody>
</table>
-<h3>dalvik.annotation.EnclosingMethod</h3>
+<h3 id="dalvik-enclosingmethod">dalvik.annotation.EnclosingMethod</h3>
<h4>appears on classes</h4>
<p>An <code>EnclosingMethod</code> annotation is attached to each class
@@ -2916,7 +2916,7 @@
</tbody>
</table>
-<h3>dalvik.annotation.InnerClass</h3>
+<h3 id="dalvik-innerclass">dalvik.annotation.InnerClass</h3>
<h4>appears on classes</h4>
<p>An <code>InnerClass</code> annotation is attached to each class
@@ -2953,7 +2953,7 @@
</tbody>
</table>
-<h3>dalvik.annotation.MemberClasses</h3>
+<h3 id="dalvik-memberclasses">dalvik.annotation.MemberClasses</h3>
<h4>appears on classes</h4>
<p>A <code>MemberClasses</code> annotation is attached to each class
@@ -2977,7 +2977,7 @@
</tbody>
</table>
-<h3>dalvik.annotation.Signature</h3>
+<h3 id="dalvik-signature">dalvik.annotation.Signature</h3>
<h4>appears on classes, fields, and methods</h4>
<p>A <code>Signature</code> annotation is attached to each class,
@@ -3020,7 +3020,7 @@
</tbody>
</table>
-<h3>dalvik.annotation.Throws</h3>
+<h3 id="dalvik-throws">dalvik.annotation.Throws</h3>
<h4>appears on methods</h4>
<p>A <code>Throws</code> annotation is attached to each method which is
diff --git a/src/devices/tech/dalvik/index.jd b/src/devices/tech/dalvik/index.jd
index 71324d8..ed1bad1 100644
--- a/src/devices/tech/dalvik/index.jd
+++ b/src/devices/tech/dalvik/index.jd
@@ -1,8 +1,8 @@
-page.title=Dalvik Technical Information
+page.title=ART and Dalvik
@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.
@@ -16,14 +16,140 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<p>Dalvik is the managed runtime used by applications and some system
-services on Android. Dalvik was originally created specifically for
-the Android project.</p>
-<p>Much of the documentation in this directory is intended to help
-with the ongoing development of Dalvik, as opposed to most of the
-other documentation on this site, which is geared more towards
-application development.</p>
-<p>Please note, in Android 4.4 a new virtual machine - ART - is being introduced
-experimentally that will eventually replace Dalvik. Please see <a
-href="{@docRoot}devices/tech/dalvik/art.html">Introducing ART</a> for details.
+
+<div id="qv-wrapper">
+<div id="qv">
+ <h2 id="Contents">In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+</div>
+</div>
+
+<p>Android runtime (ART) is the managed runtime used by applications and some system
+services on Android. ART and its predecessor Dalvik were originally created
+specifically for the Android project. ART as the runtime executes the Dalvik
+Executable format and Dex bytecode specification.</p>
+
+<p>ART and Dalvik are compatible runtimes running Dex bytecode, so apps
+developed for Dalvik should work when running with ART. However, some
+techniques that work on Dalvik do not work on ART. For information about the
+most important issues, see <a
+href="http://developer.android.com/guide/practices/verifying-apps-art.html">Verifying
+App Behavior on the Android Runtime (ART)</a>.</p>
+
+<h2 id="features">ART Features</h2>
+
+<p>Here are some of the major features implemented by ART.</p>
+
+<h3 id="AOT_compilation">Ahead-of-time (AOT) compilation</h3>
+
+<p>ART introduces ahead-of-time (AOT) compilation, which can improve app
+performance. ART also has tighter install-time verification than Dalvik.</p>
+
+<p>At install time, ART compiles apps using the on-device
+<strong>dex2oat</strong> tool. This utility accepts <a
+href="http://source.android.com/devices/tech/dalvik/dex-format.html">DEX</a> files as input and
+generates a compiled app executable for the target device. The utility should be
+able to compile all valid DEX files without difficulty. However, some
+post-processing tools produce invalid files that may be tolerated by Dalvik but
+cannot be compiled by ART. For more information, see <a
+href="http://developer.android.com/guide/practices/verifying-apps-art.html#GC_Migration">Addressing
+Garbage Collection Issues</a>.</p>
+
+<h3 id="Improved_GC">Improved garbage collection</h3>
+
+<p>Garbage collection (GC) can impair an app's performance, resulting in choppy
+display, poor UI responsiveness, and other problems. ART improves garbage
+collection in several ways:</p>
+
+<ul>
+ <li>One GC pause instead of two</li>
+ <li>Parallelized processing during the remaining GC pause</li>
+ <li>Collector with lower total GC time for the special case of cleaning up
+ recently-allocated, short-lived objects</li>
+ <li>Improved garbage collection ergonomics, making concurrent garbage
+ collections more timely, which makes <a
+ href="http://developer.android.com/tools/debugging/debugging-memory.html#LogMessages"><code>GC_FOR_ALLOC</code></a>
+ events extremely rare in typical use cases</li>
+ <li>Compacting GC to reduce background memory usage and fragmentation</li>
+</ul>
+
+<h3 id="Debugging_Imp">Development and debugging improvements</h3>
+
+<p>ART offers a number of features to improve app development and debugging.</p>
+
+<h4 id="Sampling_Profiler">Support for sampling profiler</h4>
+
+<p>Historically, developers have used the <a
+href=" http://developer.android.com/tools/help/traceview.html">Traceview</a>
+tool (designed for tracing
+application execution) as a profiler. While Traceview gives useful information,
+its results on Dalvik have been skewed by the per-method-call overhead, and use
+of the tool noticeably affects run time performance.</p>
+
+<p>ART adds support for a dedicated sampling profiler that does not have these
+limitations. This gives a more accurate view of app execution without
+significant slowdown. Sampling support was added to Traceview for
+Dalvik in the KitKat release.</p>
+
+<h4 id="Debugging_Features">Support for more debugging features</h4>
+
+<p>ART supports a number of new debugging options, particularly in monitor- and
+garbage collection-related functionality. For example, you can:</p>
+
+<ul>
+ <li>See what locks are held in stack traces, then jump to the thread that
+ holds a lock.</li>
+ <li>Ask how many live instances there are of a given class, ask to see the
+ instances, and see what references are keeping an object live.</li>
+ <li>Filter events (like breakpoint) for a specific instance.</li>
+ <li>See the value returned by a method when it exits (using “method-exit”
+ events).</li>
+ <li>Set field watchpoint to suspend the execution of a program when a specific
+ field is accessed and/or modified.</li>
+</ul>
+
+<h4 id="Crash_Reports">Improved diagnostic detail in exceptions and crash reports</h4>
+
+<p>ART gives you as much context and detail as possible when runtime exceptions
+occur. ART provides expanded exception detail for <code><a
+href="http://developer.android.com/reference/java/lang/ClassCastException.html">java.lang.ClassCastException</a></code>,
+<code><a
+href="http://developer.android.com/reference/java/lang/ClassNotFoundException.html">java.lang.ClassNotFoundException</a></code>,
+and <code><a
+href="http://developer.android.com/reference/java/lang/NullPointerException.html">java.lang.NullPointerException</a></code>.
+(Later versions of Dalvik provided expanded exception detail for <code><a
+href="http://developer.android.com/reference/java/lang/ArrayIndexOutOfBoundsException.html">java.lang.ArrayIndexOutOfBoundsException</a></code>
+and <code><a
+href="http://developer.android.com/reference/java/lang/ArrayStoreException.html">java.lang.ArrayStoreException</a></code>,
+which now include the size of the array and the out-of-bounds offset, and ART
+does this as well.)</p>
+
+<p>For example, <code><a
+href="http://developer.android.com/reference/java/lang/NullPointerException.html">java.lang.NullPointerException</a></code>
+now shows information about what the app was trying to do with the null pointer,
+such as the field the app was trying to write to, or the method it was trying to
+call. Here are some typical examples:</p>
+
+<pre class="no-pretty-print">
+java.lang.NullPointerException: Attempt to write to field 'int
+android.accessibilityservice.AccessibilityServiceInfo.flags' on a null object
+reference</pre>
+
+<pre class="no-pretty-print">
+java.lang.NullPointerException: Attempt to invoke virtual method
+'java.lang.String java.lang.Object.toString()' on a null object reference</pre>
+
+<p>ART also provides improved context information in app native crash reports,
+by including both Java and native stack information. </p>
+
+<h2 id="Reporting_Problems">Reporting Problems</h2>
+
+<p>If you run into any issues that aren’t due to app JNI issues, please report
+them via the Android Open Source Project Issue Tracker at <a
+href="http://b.android.com">http://b.android.com</a>.
+Please include an <code>"adb bugreport"</code> and link to the app in Google
+Play store if available. Otherwise, if possible, attach an APK that reproduces
+the issue. Please note that issues (including attachments) are publicly
+visible.</p>
diff --git a/src/devices/tech/dalvik/instruction-formats.jd b/src/devices/tech/dalvik/instruction-formats.jd
index 37640da..91d876a 100644
--- a/src/devices/tech/dalvik/instruction-formats.jd
+++ b/src/devices/tech/dalvik/instruction-formats.jd
@@ -1,8 +1,8 @@
-page.title=Dalvik VM Instruction Formats
+page.title=Dalvik Executable instruction formats
@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.
@@ -16,13 +16,21 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<h2>Introduction and Overview</h2>
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
-<p>This document lists the instruction formats used by Dalvik bytecode
-and is meant to be used in conjunction with the
+<h2 id="intro">Introduction</h2>
+
+<p>This document lists the instruction formats used by the Dalvik Executable
+format and Dalvik bytecode. It is meant to be used in conjunction with the
<a href="dalvik-bytecode.html">bytecode reference document</a>.</p>
-<h3>Bitwise descriptions</h3>
+<h2 id="bitwise">Bitwise descriptions</h2>
<p>The first column in the format table lists the bitwise layout of
the format. It consists of one or more space-separated "words" each of
@@ -49,7 +57,7 @@
values in the high eight bits; and the second word consists of a single
16-bit value.</p>
-<h3>Format IDs</h3>
+<h2 id="format-ids">Format IDs</h2>
<p>The second column in the format table indicates the short identifier
for the format, which is used in other documents and in code to identify
@@ -69,7 +77,7 @@
"<code>s</code>" suffix, making them four characters total. Similarly,
suggested "inline" linking formats have an additional "<code>i</code>"
suffix. (In this context, inline linking is like static linking,
-except with more direct ties into a virtual machine's implementation.)
+except with more direct ties into a machine's implementation.)
Finally, a couple oddball suggested formats (e.g.,
"<code>20bc</code>") include two pieces of data which are both
represented in its format ID.</p>
@@ -147,7 +155,7 @@
</tbody>
</table>
-<h3>Syntax</h3>
+<h2 id="syntax">Syntax</h2>
<p>The third column of the format table indicates the human-oriented
syntax for instructions which use the indicated format. Each instruction
@@ -163,7 +171,7 @@
<p>Arguments which name a register have the form "<code>v<i>X</i></code>".
The prefix "<code>v</code>" was chosen instead of the more common
"<code>r</code>" exactly to avoid conflicting with (non-virtual) architectures
-on which a Dalvik virtual machine might be implemented which themselves
+on which the Dalvik Executable format might be implemented which themselves
use the prefix "<code>r</code>" for their registers. (That is, this
decision makes it possible to talk about both virtual and real registers
together without the need for circumlocution.)</p>
@@ -197,7 +205,7 @@
"<code>[<i>X</i>=<i>N</i>]</code>" (e.g., "<code>[A=2]</code>") to indicate
the correspondence.</p>
-<h2>The Formats</h2>
+<h2 id="formats">The formats</h2>
<table class="format">
<thead>
diff --git a/src/devices/tech/encryption/index.jd b/src/devices/tech/encryption/index.jd
index e3038d4..d7e9328 100644
--- a/src/devices/tech/encryption/index.jd
+++ b/src/devices/tech/encryption/index.jd
@@ -32,7 +32,7 @@
automatically encrypted before committing it to disk and all reads
automatically decrypt data before returning it to the calling process.</p>
-<h2 id=what_we’ve_added_for_android_l>What we’ve added for Android L</h2>
+<h2 id=what_we’ve_added_for_android_l>What we’ve added for Android 5.0</h2>
<ul>
<li>Created fast encryption, which only encrypts used blocks on the data partition
@@ -44,6 +44,10 @@
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
+encrypted may be returned to an unencrypted state by factory data reset. New Android 5.0
+devices encrypted at first boot cannot be returned to an unencrypted state.</p>
+
<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
@@ -58,7 +62,7 @@
<p class="note"><strong>Note:</strong> OEMs can use 128-bit or higher to encrypt the master key.</p>
-<p>In the L release, there are four kinds of encryption states: </p>
+<p>In the Android 5.0 release, there are four kinds of encryption states: </p>
<ul>
<li>default
@@ -115,7 +119,7 @@
<li>Boot an encrypted device:
<ul>
<li>Starting an encrypted device with no password: Booting an encrypted device that
-has no set password (relevant for devices running Android L and later).
+has no set password (relevant for devices running Android 5.0 and later).
<li> Starting an encrypted device with a password: Booting an encrypted device that
has a set password.
</ul>
@@ -123,9 +127,9 @@
<p>In addition to these flows, the device can also fail to encrypt <code>/data</code>. Each of the flows are explained in detail below.</p>
-<h3 id=encrypt_a_new_device_with_forceencrypt>Encrypt a new device with <code>/forceencrypt</code></h3>
+<h3 id=encrypt_a_new_device_with_forceencrypt>Encrypt a new device with /forceencrypt</h3>
-<p>This is the normal first boot for an Android L device. </p>
+<p>This is the normal first boot for an Android 5.0 device. </p>
<ol>
<li><strong>Detect unencrypted filesystem with <code>/forceencrypt</code> flag</strong>
@@ -156,10 +160,13 @@
<li><strong>When <code>/data</code> is encrypted, take down the framework</strong>
-<p><code>vold</code> sets <code>vold.decrypt</code> to <code>trigger_default_encryption</code> which starts the <code>defaultcrypto</code> service. (This starts the flow below for mounting a default encrypted
-userdata.) <code>trigger_default_encryption</code> checks the encryption type to see if <code>/data</code> is encrypted with or without a password. Because Android L devices are
-encrypted on first boot, there should be no password set; therefore we decrypt
-and mount <code>/data</code>.</p>
+<p><code>vold</code> sets <code>vold.decrypt</code> to
+<code>trigger_default_encryption</code> which starts the
+<code>defaultcrypto</code> service. (This starts the flow below for mounting a
+default encrypted userdata.) <code>trigger_default_encryption</code> checks the
+encryption type to see if <code>/data</code> is encrypted with or without a
+password. Because Android 5.0 devices are encrypted on first boot, there should
+be no password set; therefore we decrypt and mount <code>/data</code>.</p>
<li><strong>Mount <code>/data</code></strong>
@@ -231,7 +238,7 @@
<h3 id=starting_an_encrypted_device_with_default_encryption>Starting an encrypted device with default encryption</h3>
<p>This is what happens when you boot up an encrypted device with no password.
-Because Android L devices are encrypted on first boot, there should be no set
+Because Android 5.0 devices are encrypted on first boot, there should be no set
password and therefore this is the <em>default encryption</em> state.</p>
<ol>
@@ -351,13 +358,13 @@
<ol>
<li>Generate random 16-byte disk encryption key (DEK) and 16-byte salt.
- <li>Apply scrypt to the user password and the salt to produce 16-byte intermediate
+ <li>Apply scrypt to the user password and the salt to produce 32-byte intermediate
key 1 (IK1).
<li>Pad IK1 with zero bytes to the size of the hardware-bound private key (HBK).
Specifically, we pad as: 00 || IK1 || 00..00; one zero byte, 32 IK1 bytes, 223
zero bytes.
<li>Sign padded IK1 with HBK to produce 256-byte IK2.
- <li>Apply scrypt to IK2 and salt (same salt as step 2) to produce 16-byte IK3.
+ <li>Apply scrypt to IK2 and salt (same salt as step 2) to produce 32-byte IK3.
<li>Use the first 16 bytes of IK3 as KEK and the last 16 bytes as IV.
<li>Encrypt DEK with AES_CBC, with key KEK, and initialization vector IV.
</ol>
diff --git a/src/devices/tech/index.jd b/src/devices/tech/index.jd
index fbb4cc7..3eed8e9 100644
--- a/src/devices/tech/index.jd
+++ b/src/devices/tech/index.jd
@@ -1,4 +1,4 @@
-page.title=Android Technical Information
+page.title=Android Core Technologies
@jd:body
<!--
@@ -25,26 +25,26 @@
</div>
-<p>Welcome to the Android technical documentation section of the site. Here you
-can find technical information useful to people and organizations who are
+<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>
-<h2 id="accessory-protocol-information">Accessory Protocol Information</h2>
+<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>
-<h2 id="dalvik-technical-information">Dalvik Technical Information</h2>
-<p>The Dalvik Virtual Machine is the heart of Android. It's a fast, just-in-time
-compiled, optimized bytecode virtual machine. Android applications are
-compiled to Dalvik bytecode and run on the Dalvik VM. This section includes
-detailed information such as the Dalvik bytecode format specification,
-design information on the VM itself, and so on.</p>
-<p><a href="{@docRoot}devices/tech/dalvik/index.html">» Dalvik 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>
-<h2 id="data-usage-technical-information">Data Usage Technical Information</h2>
+<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
@@ -60,19 +60,30 @@
<p>Android's Hardware Abstraction Layer (HAL) provides the interface between
software APIs and hardware drivers. This section contains the commented code
files of the HAL.</p>
-<p><a href="{@docRoot}devices/reference/files.html">» HAL Reference</a></p>
+<p><a href="{@docRoot}devices/halref/files.html">» HAL Reference</a></p>
-<h2 id="kernel-technical-information">Kernel Technical Information</h2>
+<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>
-<h2 id="power-technical-information">Power Technical Information</h2>
+<h2 id="lowram-technical-information">Low RAM</h2>
+<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>
+
+<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>
+<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>
+
<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,
diff --git a/src/devices/tech/input/keyboard-devices.jd b/src/devices/tech/input/keyboard-devices.jd
index 0c6ba08..74bafaa 100644
--- a/src/devices/tech/input/keyboard-devices.jd
+++ b/src/devices/tech/input/keyboard-devices.jd
@@ -6430,7 +6430,7 @@
</ol>
<h3 id="sources">Sources</h3>
<ol>
-<li><a href="http://www.usb.org/developers/devclass_docs/Hut1_12v2.pdf">USB HID Usage Tables v1.12</a></li>
+<li><a href="http://www.usb.org/developers/hidpage/Hut1_12v2.pdf">USB HID Usage Tables v1.12</a></li>
<li>Linux 2.6.39 kernel: include/linux/input.h, drivers/hid/hid-input.c</li>
<li>Android ICS: qwerty.kl, Generic.kl, KeyEvent.java</li>
</ol>
diff --git a/src/devices/tech/power.jd b/src/devices/tech/power.jd
index 0367f26..38e1e6a 100644
--- a/src/devices/tech/power.jd
+++ b/src/devices/tech/power.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.
@@ -23,268 +23,203 @@
</div>
</div>
-<p>
-Battery usage information is derived from battery usage statistics and power profile
-values.
-</p>
+<p>Battery usage information is derived from battery usage statistics and power profile values.</p>
-<h2>
-Battery Usage Statistics
-</h2>
+<h2 id="usage-statistics">Battery Usage Statistics</h2>
-<p>
-Battery usage statistics are tracked by the framework. This involves keeping track of time
-spent by different device components in different states. This includes components such as
-WiFi chipset, Cellular Radio, Bluetooth, GPS, Display and CPU. When these components change
-state from off to on, or from idle to full power, low brightness to high brightness, etc.,
-their controlling service reports to the framework’s BatteryStats service, which collects
-such information over time and persists to storage so that it is available across reboots.
-</p>
+<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
+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>
-<p>
-The service isn’t keeping track of battery current draw information directly. It’s collecting
-mostly timing information so that it can be used to approximate battery consumption by
-different components.
-</p>
+<p>The framework gathers statistics using the following methods:</p>
-<p>
-Consumption of these resources is also (where possible) attributed to the applications using
-the resources, sometimes sharing the blame across multiple applications using a resource
-simultaneously. For instance, multiple apps could be holding wakelocks, keeping the system
-from going into suspend state. Blame is shared across these apps (not necessarily equally).
-</p>
+<ul>
+<li><strong>Push</strong>. Services aware of component changes push state changes to the
+BatteryStats service.</li>
+<li><strong>Pull</strong>. For components such as the CPU usage by apps, the framework automatically
+pulls the data at transition points (such as starting or stopping an activity) to take a
+snapshot.</li>
+</ul>
-<p>
-Statistics are persisted to flash periodically (approximately every half hour or so) to avoid
-losing the information on a shutdown (such as due to battery reaching zero remaining
-capacity, which may indicate a battery power consumption problem).
-</p>
+<p>Resource consumption is associated with the application using the resource. When multiple
+applications simultaneously use a resource (such as wakelocks that prevent the system from
+suspending), the framework spreads consumption across those applications, although not necessarily
+equally.</p>
-<p>
-Statistics gathering can happen in two ways - push or pull. When services are aware of
-changes happening to a component, they will push state changes to the BatteryStats service.
-With components such as the CPU usage by apps, we pull the data periodically (at certain
-transition points such as starting or stopping an activity, etc) to take a snapshot.
-</p>
+<p>To avoid losing usage statistics for a shutdown event, which may indicate battery power
+consumption problems (i.e. shutdown occurs because the battery reached zero remaining capacity), the
+framework flashes statistics approximately every 30 minutes.</p>
-<p>
-All of the above is automatically done by the framework, and OEMs don’t need to do anything
-in addition to that.
-</p>
+<p>Battery usage statistics are handled entirely by the framework and do not require OEM
+modifications.</p>
-<h2>
-Power Profile Values
-</h2>
+<h2 id="profile-values">Power Profile Values</h2>
-<p>
-The power profile is where the device manufacturer needs to provide current consumption
-values for various components and their states in order to approximate the actual battery
-drain caused by these components over time. The power consumption of a component is specified
-in units of milliamps (mA) of current draw (at a nominal voltage) in the power profile, and
-can be a fractional value specifying microamps. The value specified 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>
+<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
+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>
-<p>
-For instance, to attribute the cost of keeping the display on for a duration of time, the
-framework gathers brightness levels and times spent at each level (quantized to some number
-of bins). The power profile values specify how many milliamps of current are required to keep
-the display on at minimum brightness and at maximum brightness. The time spent at each
-brightness level can then be multiplied by an interpolated display brightness cost to compute
-an approximation of how much battery was drained by the display component.
-</p>
+<p>For example, a display power profile specifies the mA of current required to keep the display on
+at minimum brightness and at maximum brightness. To determine the power cost (i.e the battery
+drained by the display component) of keeping the display on, the framework tracks the time spent at
+each brightness level, then multiplies those time intervals by an interpolated display brightness
+cost.</p>
-<p>
-Similarly, CPU time for each application is multiplied by the mA to keep the CPU running at a
-certain speed to get a comparative ranking of how much battery each app is consuming due to
-executing CPU code (time as the foreground app and total time including background activity
-are reported separately).
-</p>
+<p>The framework also multiplies the CPU time for each application by the mA required to run the CPU
+at a specific speed. This calculation establishes a comparative ranking of how much battery an
+application consumes by executing CPU code (time as the foreground app and total time including
+background activity are reported separately).</p>
-<h2>
-Computing power consumption for individual components
-</h2>
+<h2 id="component-power">Measuring Component Power</h2>
+
+<p>You can determine individual component power consumption by comparing the current drawn by the
+device when the component is in the desired state (on, active, scanning, etc.) and when the
+component is off. Measure the average instantaneous current drawn on the device at a
+nominal voltage using an external power monitor, such as a bench power supply or specialized
+battery-monitoring tools (such as Monsoon Solution Inc. Power Monitor and Power Tool software).</p>
<p class="note">
-<strong>Note:</strong> manufacturers usually supply information about how much current an
-individual component consumes. It may be possible to use these values if they are an accurate
-representation of the the current drawn from the device’s battery in practice. However, we
-encourage you validate manufacturer-provided values before entering them in your device’s
-power profile.
-</p>
+<strong>Note:</strong> Manufacturers often supply information about the current consumed by an
+individual component. Use this information if it accurately represents the current drawn from the
+device battery in practice. However, validate manufacturer-provided values before
+using those values in your device power profile.</p>
-<p>
-Current consumption for an individual component is calculated by:
-</p>
+<p>When measuring, ensure the device does not have a connection to an external charge source, such
+as a USB connection to a development host used when running Android Debug Bridge (adb). The device
+under test might draw current from the host, thus lowering measurements at the battery. Avoid USB
+On-The-Go (OTG) connections, as the OTG device might draw current from the device under test.</p>
+
+<p>Excluding the component being measured, the system should run at a constant level of power
+consumption to avoid inaccurate measurements caused by changes in other components. System
+activities that can introduce unwanted changes to power measurements include:</p>
<ul>
-<li>
-Measuring the current drawn by the device when the component is in the desired state (e.g.,
-on, active, or scanning)
-</li>
-<li>
-Measuring the current drawn by the device when the component is
-off
-</li>
-<li>subtracting (2) from (1).</li>
+<li><strong>Cellular, Wi-Fi, and Bluetooth receive, transmit, or scanning activity</strong>. When
+not measuring cell radio power, set the device to airplane mode and enable Wi-Fi or Bluetooth as
+appropriate.</li>
+<li><strong>Screen on/off</strong>. Colors displayed while the screen is on can affect power draw on
+some screen technologies. Turn the screen off when measuring values for non-screen components.</li>
+<li><strong>System suspend/resume</strong>. A screen off state can trigger a system suspension,
+placing parts of the device in a low-power or off state. This can affect power consumption of the
+component being measured and introduce large variances in power readings as the system periodically
+resumes to send alarms, etc. For details, see <a href="#control-suspend">Controlling System
+Suspend</a>.</li>
+<li><strong>CPUs changing speed and entering/exiting low-power scheduler idle state</strong>. During
+normal operation, the system makes frequent adjustments to CPU speeds, the number of online CPU
+cores, and other system core states such as memory bus speed and voltages of power rails associated
+with CPUs and memory. During testing, these adjustments affect power measurements:
-
-<img></img><p class="img-caption"></p>
-<p>
-We recommend that you measure the current (usually the average instantaneous current) drawn
-on the device at a nominal voltage. This can be accomplished using a bench power supply or
-using specialized battery-monitoring tools (such as Monsoon Solution Inc.’s Power Monitor and
-Power Tool software).
-</p>
-<p>
-Take the measurements with no external charger connected to the device, including no USB
-connection to a host (as used for connecting to development hosts via the adb Android Debug
-Bridge), which may draw current from the host and lower the measurements at the battery. If
-the device supports USB On The Go (OTG) then having an OTG device connected may draw
-additional power from the device being measured, so disconnect any such OTG device.
-</p>
-<p>
-While taking measurements, you’ll want to try to keep the rest of the system other than the
-component being measured running at a constant level of power consumption, to avoid
-introducing inaccuracies in the measurements due to changes in other components. System
-activities that may introduce unwanted changes to power measurements include:
-</p>
<ul>
-<li>
-Cellular, Wi-Fi, and Bluetooth receive, transmit, or scanning activity. You may want to put
-the device into airplane mode when not measuring cell radio power, and individually enable
-Wi-Fi or Bluetooth when appropriate.
-</li>
-<li>
-Screen/backlight on or off. The colors displayed while screen is on can also affect power
-draw on certain screen technologies. Measurements for components other than the screen on
-values should be made with screen turned off. But see the next item for an important
-consideration when the screen is off.
-</p>
-<li>
-System suspended/resumed state. When the screen is off the system may enter a suspend state
-where much of the device may be powered off or placed in a low-power state, probably
-affecting power consumption of the component being measured and possibly introducing large
-variances in power readings as the system periodically resumes to service alarms and such.
-See Controlling and Measuring System Suspend State for more instructions.
-</li>
-<li>
-CPUs changing speed and entering/exiting low-power scheduler idle state. The system may make
-frequent adjustments to the speeds of CPUs, how many CPU cores are online, and other system
-core state such as memory bus speed and voltages of power rails associated with CPUs and
-memory. If these are changing during your measurements then you may want to prevent CPU speed
-scaling operations, which may also reduce the amount of clock and voltage scaling of memory
-busses and other system core components. Scheduling activity may also affect what percentage
-of the time the CPUs spend in low-power idle states. See Controlling and Measuring CPU Speeds
-for more instructions.
+<li>CPU speed scaling operations can reduce the amount of clock and voltage scaling of memory buses
+and other system core components.</li>
+<li>Scheduling activity can affect the percentage of the time CPUs spend in low-power idle states.
+For details on preventing these adjustments from occurring during testing, see
+<a href="#control-cpu">Controlling CPU Speeds</a>.</li>
+</ul>
+
</li>
</ul>
-<p>
-For instance, to compute the value for <code>screen.on</code>, you would run the device in a stable state,
-with CPU speed held constant, device in airplane mode, with a partial wakelock held to
-prevent system suspend. The current readings in this state should be stable. Take the reading
-- say 200mA. Now turn on the screen at minimum brightness. If the power monitor shows 300mA,
-then <code>screen.on</code> = (300 - 200) = 100mA.
-</p>
-<p>
-For components that don’t have a flat waveform of current consumption when active (such as
-the cellular radio or wifi), you may need to measure an average current over a period of
-time. Your power monitoring tool may be able to compute this average for you.
-</p>
-<p>
-Replacing the battery with an external power source may require working around problems that
-can occur due to not connecting battery thermistor or integrated fuel gauge pins. For
-example, the system might take an invalid battery temperature reading or remaining battery
-capacity reading that could cause the kernel or Android system to shut down. Sometimes these
-problems are avoided through the use of “fake batteries” that replace normal batteries for
-power measurement purposes, constructed to match the dimensions and electrical properties of
-the batteries for the product being measured. Fake batteries can provide signals on
-thermistor or fuel gauge pins that mimic temperature and state of charge readings for a
-normally running system, and may also provide convenient leads for connecting to external
-power supplies. In other cases it may be easier to modify the system to ignore the invalid
-data from the missing battery.
-</p>
-<h3>
-Controlling and Measuring System Suspend State
-</h3>
-<p>
-As mentioned above, system suspend can introduce unwanted variance in power measurements and
-place system components in low power states not appropriate for measuring active power use.
-But at some point you’ll also need to measure the power draw of system suspend state. 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 measure it.
-</p>
-<p>
-To avoid system suspend you can temporarily connect the device to a development host and
-issue the following command to hold a “partial wakelock”:
-</p>
+
+<p>For example, Joe Droid wants to compute the <code>screen.on</code> value for a device. He enables
+airplane mode on the device, runs the device at a stable current state, holds the CPU speed constant
+, and uses a partial wakelock to prevent system suspend. Joe then turns the device screen off and
+takes a measurement (200mA). Next, Joe turns the device screen on at minimum brightness and takes
+another measurement (300mA). The <code>screen.on</code> value is 100mA (300 - 200).</p>
+
+<p>For components that don’t have a flat waveform of current consumption when active (such as
+cellular radio or Wi-Fi), measure the average current over time using a power monitoring tool.</p>
+
+<p>When using an external power source in place of the device battery, the system might experience
+problems due to an unconnected battery thermistor or integrated fuel gauge pins (i.e. an invalid
+reading for battery temperature or remaining battery capacity could shut down the kernel or Android
+system). Fake batteries can provide signals on thermistor or fuel gauge pins that mimic temperature
+and state of charge readings for a normal system, and may also provide convenient leads for
+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>
+
+<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
+measure it.</p>
+
+<h4>Preventing System Suspend</h4>
+
+<p>System suspend can introduce unwanted variance in power measurements and place system components
+in low-power states inappropriate for measuring active power use. To prevent the system from
+suspending while the screen is off, use a temporary partial wakelock. Using a USB cable, connect the
+device to a development host, then issue the following command:</p>
+
<pre>
$ adb shell "echo temporary > /sys/power/wake_lock"
</pre>
-<p>
-which will prevent the system from suspending while the screen is off. Disconnect the USB
-cable before making measurements.
-</p>
-<p>
-You can undo the effect of this later with:
-</p>
+
+<p>While in wake_lock, the screen off state does not trigger a system suspend. (Remember to
+disconnect the USB cable from the device before measuring power consumption.)</p>
+
+<p>To remove the wakelock:</p>
+
<pre>
$ adb shell "echo temporary > /sys/power/wake_unlock"
</pre>
-<p>
-The power consumption of the system suspend state is measured for the value of cpu.idle in
-the power profile. For this measurement it may be best to place the device in airplane mode
-to avoid any concurrent activity by the cellular radio, which may run on a processor separate
-from the portions of the SoC controlled by the system suspend. To ensure the measurement is
-made while the system is in the correct state, it may be necessary to first confirm the
-current readings settle to a steady value within the expected range for the consumption of
-the suspend state of the SoC entered plus the consumption of additional system components
-that remain powered (such as the USB PHY). A system console or other external indication of
-system status (such as turning off an LED when not in suspend) may also be observed during
-the measurement.
-</p>
-<h3>
-Controlling and Measuring CPU Speeds
-</h3>
-<p>
-While active, CPUs can be brought online or put offline, change clock speeds and associated
-voltages (possibly also affecting memory bus speeds and other system core power state), and
-can enter lower power idle states while in the kernel idle loop. Not only are these different
-CPU power states measured for the power profile, it may be necessary to avoid the power draw
-variance when measuring other parameters.
-</p>
-<p>
-The power profile currently assumes all CPUs have the same available speeds and power
-characteristics.
-</p>
-<p>
-While measuring CPU power, or holding CPU power constant in order to make other measurements,
-it may be best to hold the number of CPUs brought online constant, such as to have one CPU
-online and the rest offline / hotplugged out. Keeping all CPUs but one in scheduling idle may
-deliver acceptable results. Stopping the Android framework with adb shell stop can help
-reduce system scheduling activity.
-</p>
-<p>
-You’ll specify the available CPU speeds for your device in the power profile cpu.speeds
-entry. You can get a list of these using
-</p>
+
+<h4>Measuring System Suspend</h4>
+
+<p>To measure the power draw during the system suspend state, measure the value of cpu.idle in the
+power profile. Before measuring:
+
+<ul>
+<li>Remove existing wakelocks (as described above).</li>
+<li>Place the device in airplane mode to avoid concurrent activity by the cellular radio, which
+might run on a processor separate from the SoC portions controlled by the system suspend.</li>
+<li>Ensure the system is in suspend state by:
+<ul>
+<li>Confirming current readings settle to a steady value. Readings should be within the expected
+range for the power consumption of the SoC suspend state plus the power consumption of system
+components that remain powered (such as the USB PHY).</li>
+<li>Checking the system console output.</li>
+<li>Watching for external indications of system status (such as an LED turning off when not in
+suspend).</li>
+</ul>
+</li>
+</ul>
+
+<a name="control-cpu"><h3 id="control-cpu">Controlling CPU Speeds</h3></a>
+
+<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
+can enter lower power idle states while in the kernel idle loop. When measuring different CPU power
+states for the power profile, avoid the power draw variance when measuring other parameters. The
+power profile assumes all CPUs have the same available speeds and power characteristics.</p>
+
+<p>While measuring CPU power, or while holding CPU power constant to make other measurements, keep
+the number of CPUs brought online constant (such as having one CPU online and the rest
+offline/hotplugged out). Keeping all CPUs except one in scheduling idle may product acceptable
+results. Stopping the Android framework with <code>adb shell stop</code> can reduce system
+scheduling activity.</p>
+
+<p>You must specify the available CPU speeds for your device in the power profile cpu.speeds
+entry. To get a list of available CPU speeds, run:</p>
+
<pre>
adb shell cat /sys/devices/system/cpu/cpu0/cpufreq/stats/time_in_state
</pre>
-<p>
-These speeds are matched with their corresponding power measurements in value <code>cpu.active</code>.
-</p>
-<p>
-If your platform’s power consumption is significantly affected by how many cores are brought
-online then you may need to modify the cpufreq driver or governor for your platform to
-control this. For many platforms, the easiest way to control CPU speed is to use the
-“userspace” cpufreq governor and use sysfs interfaces to set the speed. The exact commands
-differ depending on your platform’s cpufreq implementation. The following commands from the
-system console or adb shell could be used to set a speed for 200MHz on a system with only 1
-CPU, or all CPUs sharing a common cpufreq policy:
-</p>
+
+<p>These speeds match the corresponding power measurements in value <code>cpu.active</code>.</p>
+
+<p>For platforms where number of cores brought online significantly affects power consumption, you
+might need to modify the cpufreq driver or governor for the platform. Most platforms support
+controlling CPU speed using the “userspace” cpufreq governor and using sysfs interfaces to
+set the speed. For example, to set speed for 200MHz on a system with only 1 CPU or all CPUs sharing
+a common cpufreq policy, use the system console or adb shell to run the following commands:</p>
+
<pre>
echo userspace > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq
@@ -292,105 +227,347 @@
echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq
</pre>
-<p>
-which makes sure the new speed is not outside the allowed bounds, sets the new speed, and
-then prints which speed the CPU is actually running at for verification. (If the current
-minimum speed prior to executing the above is above 200000, you may have to reverse the order
-of the first two lines, or execute the first line again, to drop the minimum speed prior to
-setting the maximum speed.)
+
+<p class="note">
+<strong>Note</strong>: The exact commands differ depending on the platform cpufreq implementation.
</p>
-<p>
-To measure current consumed by a CPU while running at various speeds, you may need to place a
-CPU in a CPU-bound loop such as:
-</p>
+
+<p>These commands ensure the new speed is not outside the allowed bounds, set the new speed, then
+print the speed at which the CPU is actually running (for verification). If the current
+minimum speed prior to execution is higher than 200000, you might need to reverse the order
+of the first two lines, or execute the first line again to drop the minimum speed prior to
+setting the maximum speed.</p>
+
+<p>To measure current consumed by a CPU running at various speeds, use the system console place the
+CPU in a CPU-bound loop using the command:</p>
<pre>
# while true; do true; done
</pre>
-<p>
-on the system console and take the measurement while the above runs.
-</p>
-<p>
-If your device may limit maximum CPU speed while thermal throttling due to a high temperature
-measurement, possibly as a result of running CPUs at high speeds for sustained periods, then
-watch out for this while taking measurements. You may need to watch system console output, or
-check the kernel log after measuring.
-</p>
-<p>
-For the <code>cpu.active</code> value you can measure the power consumed when the system is not in suspend
-but not executing tasks. The CPU should be in a low-power scheduler “idle loop”, 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. There may be more than one idle state in use on your
-platform with differing levels of power consumption; choose a representative idle state for
-longer periods of scheduler idle (several milliseconds). You may need to 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>
-<h3>
-Measuring Screen Power
-</h3>
-<p>
-Screen on power is typically measured with all other devices that are turned on with the
-screen also enabled. For example, the touchscreen and any display backlight would normally
-also be turned on during the measurement, to get a more realistic example of screen on power
-usage.
-</p>
-<p>
-Some display technologies vary in power consumption according to the colors displayed, and so
-power measurements may vary considerably depending on what is on the screen at the time. It’s
-best to choose to display something that has power characteristics of a realistic screen,
-somewhere between the extremes of an all-black screen (which consumes the lowest power for
-some technologies) and an all-white screen. A common choice is a view of a schedule in the
-calendar app, which has a mix of white background and non-white elements.
-</p>
-<p>
-The cost of having the screen on is measured at two points: at minimum display/backlight
-brightness, and at maximum brightness. Setting the display brightness to minimum using the
-Settings app Display Brightness slider might not produce accurate results. The Android UI
-will typically only allow you to set the brightness to a minimum of about 10-20% of the
-possible panel/backlight brightness -- it doesn't allow the user to set brightness so low
-that the screen might not be visible without great effort. If you have a sysfs file that
-controls panel brightness all the way down to the minimum brightness supported by the
-hardware then that's even better.
-</p>
-<p>
-If your platform provides sysfs files that turns the LCD panel, backlight, and touchscreen on
-and off then that’s a good way to take measurements with the screen on and off. Otherwise,
-holding a partial wakelock so the system doesn't go to suspend, and turning on and off the
-screen with the power button, should be fine.
-</p>
-<h3>
-Measuring Wi-Fi Power
-</h3>
-<p>
-It’s recommended to perform Wi-Fi measurements on a relatively quiet network, without
-introducing a lot of additional work processing high volumes of broadcast traffic unrelated
-to the activity being measured.
-</p>
-<p>
-The <code>wifi.on</code> value measures the power consumed when Wi-Fi is enabled but not actively
+
+<p>Take the measurement while the loop executes.</p>
+
+<p>Some devices can limit maximum CPU speed while performing thermal throttling due to a high
+temperature measurement (i.e. after running CPUs at high speeds for sustained periods). Watch for
+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
+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>
+
+<h3 id="screen-power">Measuring Screen Power</h3>
+
+<p>When measuring screen on power, ensure that other devices normally turned on when the screen is
+enabled are also on. For example, if the touchscreen and display backlight would normally be on when
+the screen is on, ensure these devices are on when you measure to get a realistic example of screen
+on power usage.</p>
+
+<p>Some display technologies vary in power consumption according to the colors displayed, causing
+power measurements to vary considerably depending on what is displayed on the screen at the time of
+measurement. When measuring, ensure the screen is displaying something that has power
+characteristics of a realistic screen. Aim between the extremes of an all-black screen (which
+consumes the lowest power for some technologies) and an all-white screen. A common choice is a view
+of a schedule in the calendar app, which has a mix of white background and non-white elements.</p>
+
+<p>Measure screen on power at <em>minimum</em> and <em>maximum</em> display/backlight brightness.
+To set minimum brightness:</p>
+
+<ul>
+<li><strong>Use the Android UI</strong> (not recommended). Set the Settings > Display Brightness
+slider to the minimum display brightness. However, the Android UI allows setting brightness only to
+a minimum of 10-20% of the possible panel/backlight brightness, and does not allow setting
+brightness so low that the screen might not be visible without great effort.</li>
+<li><strong>Use a sysfs file</strong> (recommended). If available, use a sysfs file to control panel
+brightness all the way down to the minimum brightness supported by the hardware.</li>
+</ul>
+
+<p>Additionally, if the platform sysfs file enables turning the LCD panel, backlight, and
+touchscreen on and off, use the file to take measurements with the screen on and off. Otherwise,
+set a partial wakelock so the system does not suspend, then turn on and off the
+screen with the power button.</p>
+
+<h3 id="wifi-power">Measuring Wi-Fi Power</h3>
+
+<p>Perform Wi-Fi measurements on a relatively quiet network. Avoid introducing additional work
+processing high volumes of broadcast traffic that is unrelated to the activity being measured.</p>
+
+<p>The <code>wifi.on</code> value measures the power consumed when Wi-Fi is enabled but not actively
transmitting or receiving. This is often measured as the delta between the current draw in
-system suspend (sleep) state with Wi-Fi enabled vs. disabled.
-</p>
-<p>
-The <code>wifi.scan</code> value measures the power consumed during a Wi-Fi scan for access points. Wi-Fi
-scans can be triggered by an app using the WifiManager class <code>startScan()</code> API, which is
-documented at http://developer.android.com/reference/android/net/wifi/WifiManager.html . You
-can also open Settings > Wi-Fi, which will perform scans for access points every few
-seconds with an apparent jump in power consumption, but the screen power must be subtracted
-from these measurements.
-</p>
-<p>
-Network receive and transmit traffic can be generated using controlled setup such as
-<a href="http://en.wikipedia.org/wiki/Iperf">iperf</a> if desired.
-</p>
-<h2>
-List of values and their meaning
-</h2>
+system suspend (sleep) state with Wi-Fi enabled vs. disabled.</p>
+
+<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">
+<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>
+
+<p class="note">
+<strong>Note</strong>: Use a controlled setup (such as
+<a href="http://en.wikipedia.org/wiki/Iperf">iperf</a>) to generate network receive and transmit
+traffic.</p>
+
+<h2 id="device-power">Measuring Device Power</h2>
+
+<p>You can determine device power consumption for Android devices that include a battery fuel gauge
+such as a Summit SMB347 or Maxim MAX17050 (available on many Nexus devices). Use the in-system
+battery fuel gauge when external measurement equipment is not available or is inconvenient to
+connect to a device (such as in mobile usage).</p>
+
+<p>Measurements can include instantaneous current, remaining charge, battery capacity at test start
+and end, and more depending on the supported properties of the device (see below). For best results,
+perform device power measurements during long-running A/B tests that use the same device type with
+the same fuel gauge and same current sense resistor. Ensure the starting battery charge is the same
+for each device to avoid differing fuel gauge behavior at different points in the battery discharge
+curve.</p>
+
+<p>Even with identical test environments, measurements are not guaranteed to be of high absolute
+accuracy. However, most inaccuracies specific to the fuel gauge and sense resistor are consistent
+between test runs, making comparisons between identical devices useful. We recommend running
+multiple tests in different configurations to identify significant differences and relative power
+consumption between configurations.</p>
+
+<h3 id="power-consumption">Reading Power Consumption</h3>
+
+<p>To read power consumption data, insert calls to the API in your testing code.</p>
+
+<pre>
+import android.os.BatteryManager;
+import android.os.ServiceManager;
+import android.content.Context;
+BatteryManager mBatteryManager =
+(BatteryManager)Context.getSystemService(Context.BATTERY_SERVICE);
+Long energy =
+mBatteryManager.getLongProperty(BatteryManager.BATTERY_PROPERTY_ENERGY_COUNTER);
+Slog.i(TAG, "Remaining energy = " + energy + "nWh");
+</pre>
+
+<h3 id="avail-props">Available Properties</h3>
+
+<p>Android supports the following battery fuel gauge properties:</p>
+
+<pre>
+BATTERY_PROPERTY_CHARGE_COUNTER Remaining battery capacity in microampere-hours
+BATTERY_PROPERTY_CURRENT_NOW Instantaneous battery current in microamperes
+BATTERY_PROPERTY_CURRENT_AVERAGE Average battery current in microamperes
+BATTERY_PROPERTY_CAPACITY Remaining battery capacity as an integer percentage
+BATTERY_PROPERTY_ENERGY_COUNTER Remaining energy in nanowatt-hours
+</pre>
+
+<p>Most properties are read from kernel power_supply subsystem attributes of similar names.
+However, the exact properties, resolution of property values, and update frequency
+available for a specific device depend on:</p>
+
+<ul>
+<li>Fuel gauge hardware, such as a Summit SMB347 or Maxim MAX17050.</li>
+<li>Fuel gauge-to-system connection, such as the value of external current sense resistors.</li>
+<li>Fuel gauge chip software configuration, such as values chosen for average current computation
+intervals in the kernel driver.</li>
+</ul>
+
+<p>For details, see the properties available for <a href="#nexus-devices">Nexus devices</a>.</p>
+
+<h3 id="maxim-fuel">Maxim Fuel Gauge</h3>
+
+<p>When determining battery state-of-charge over a long period of time, the Maxim fuel gauge
+(MAX17050, BC15) corrects for coulomb-counter offset measurements. For measurements made over a
+short period of time (such as power consumption metering tests), the fuel gauge does not make
+corrections, making the offset the primary source of error when current measurements are too small
+(although no amount of time can eliminate the offset error completely).</p>
+
+<p>For a typical 10mOhm sense resistor design, the offset current should be better than 1.5mA,
+meaning any measurement is +/-1.5mA (PCBoard layout can also affect this variation). For example,
+when measuring a large current (200mA) you can expect the following:</p>
+
+<ul>
+<li>2mA (1% gain error of 200mA due to fuel gauge gain error)</li>
+<li>+2mA (1% gain error of 200mA due to sense resistor error)</li>
+<li>+1.5mA (current sense offset error from fuel gauge)</li>
+</ul>
+
+<p>The total error is 5.5mA (2.75%). Compare this to a medium current (50mA) where the same error
+percentages give a total error of 7% or to a small current (15mA) where +/-1.5mA gives a total error
+of 10%.</p>
+
+<p>For best results, we recommend measuring greater than 20mA. Gain measurement errors are
+systematic and repeatable, enabling you to test a device in multiple modes and get clean relative
+measurements (with exceptions for the 1.5mA offset).</p>
+
+<p>For +/-100uA relative measurements, required measurement time depends on:</p>
+
+<ul>
+<li><b>ADC sampling noise</b>. The MAX17050 with its normal factory configuration produces +/-1.5mA
+sample-to-sample variation due to noise, with each sample delivered at 175.8ms. You can expect a
+rough +/-100uA for a 1 minute test window and a clean 3-sigma noise less than 100uA (or 1-sigma
+noise at 33uA) for a 6 minute test window.</li>
+<li><b>Sample Aliasing because of load variation</b>. Variation exaggerates errors, so for samples
+with variation inherent in the loading, consider using a longer test window.</li>
+</ul>
+
+<a name="nexus-devices"><h3>Supported Nexus Devices</h3></a>
+
+<h5><a name="nexus-5">Nexus 5</a></h5>
+
+<table>
+<tbody>
+<tr>
+<th>Model</th>
+<td>Nexus 5</td>
+</tr>
+<tr>
+<th>Fuel Gauge</th>
+<td>Maxim MAX17048 fuel gauge (ModelGauge™, no coulomb counter)</td>
+</tr>
+<tr>
+<th>Properties</th>
+<td>BATTERY_PROPERTY_CAPACITY</td>
+</tr>
+<tr>
+<th>Measurements</th>
+<td>The fuel gauge does not support any measurements other than battery State Of Charge to a
+resolution of %/256 (1/256th of a percent of full battery capacity).</td>
+</tr>
+</tbody>
+</table>
+
+
+<h5><a name="nexus-6">Nexus 6</a></h5>
+
+<table>
+<tbody>
+<tr>
+<th>Model</th>
+<td>Nexus 6</td>
+</tr>
+<tr>
+<th>Fuel Gauge</th>
+<td>Maxim MAX17050 fuel gauge (a coulomb counter with Maxim ModelGauge™ adjustments), and a 10mohm
+current sense resistor.</td>
+</tr>
+<tr>
+<th>Properties</th>
+<td>BATTERY_PROPERTY_CAPACITY<br>
+BATTERY_PROPERTY_CURRENT_NOW<br>
+BATTERY_PROPERTY_CURRENT_AVERAGE<br>
+BATTERY_PROPERTY_CHARGE_COUNTER<br>
+BATTERY_PROPERTY_ENERGY_COUNTER</td>
+</tr>
+<tr>
+<th>Measurements</th>
+<td>CURRENT_NOW resolution 156.25uA, update period is 175.8ms.<br>
+CURRENT_AVERAGE resolution 156.25uA, update period configurable 0.7s - 6.4h, default 11.25 secs.<br>
+CHARGE_COUNTER (accumulated current, non-extended precision) resolution is 500uAh (raw coulomb
+counter read, not adjusted by fuel gauge for coulomb counter offset, plus inputs from the ModelGauge
+m3 algorithm including empty compensation).<br>
+CHARGE_COUNTER_EXT (extended precision in kernel) resolution 8nAh.<br>
+ENERGY_COUNTER is CHARGE_COUNTER_EXT at nominal voltage of 3.7V.</td>
+</tr>
+</tbody>
+</table>
+
+
+<h5><a name="nexus-9">Nexus 9</a></h5>
+
+<table>
+<tbody>
+<tr>
+<th>Model</th>
+<td>Nexus 9</td>
+</tr>
+<tr>
+<th>Fuel Gauge</th>
+<td>Maxim MAX17050 fuel gauge (a coulomb counter with Maxim ModelGauge™ adjustments), and a 10mohm
+current sense resistor.</td>
+</tr>
+<tr>
+<th>Properties</th>
+<td>BATTERY_PROPERTY_CAPACITY<br>
+BATTERY_PROPERTY_CURRENT_NOW<br>
+BATTERY_PROPERTY_CURRENT_AVERAGE<br>
+BATTERY_PROPERTY_CHARGE_COUNTER<br>
+BATTERY_PROPERTY_ENERGY_COUNTER</td>
+</tr>
+<tr>
+<th>Measurements</th>
+<td>CURRENT_NOW resolution 156.25uA, update period is 175.8ms.<br>
+CURRENT_AVERAGE resolution 156.25uA, update period configurable 0.7s - 6.4h, default 11.25 secs.<br>
+CHARGE_COUNTER (accumulated current, non-extended precision) resolution is 500uAh.<br>
+CHARGE_COUNTER_EXT (extended precision in kernel) resolution 8nAh.<br>
+ENERGY_COUNTER is CHARGE_COUNTER_EXT at nominal voltage of 3.7V.<br>
+Accumulated current update period 175.8ms.<br>
+ADC sampled at 175ms quantization with a 4ms sample period. Can adjust duty cycle.</td>
+</tr>
+</tbody>
+</table>
+
+
+<h5><a name="nexus-10">Nexus 10</a></h5>
+
+<table>
+<tbody>
+<tr>
+<th>Model</th>
+<td>Nexus 10</td>
+</tr>
+<tr>
+<th>Fuel Gauge</th>
+<td>Dallas Semiconductor DS2784 fuel gauge (a coulomb counter), with a 10mohm current sense
+resistor.</td>
+</tr>
+<tr>
+<th>Properties</th>
+<td>BATTERY_PROPERTY_CAPACITY<br>
+BATTERY_PROPERTY_CURRENT_NOW<br>
+BATTERY_PROPERTY_CURRENT_AVERAGE<br>
+BATTERY_PROPERTY_CHARGE_COUNTER<br>
+BATTERY_PROPERTY_ENERGY_COUNTER</td>
+</tr>
+<tr>
+<th>Measurements</th>
+<td>Current measurement (instantaneous and average) resolution is 156.3uA.<br>
+CURRENT_NOW instantaneous current update period is 3.5 seconds.<br>
+CURRENT_AVERAGE update period is 28 seconds (not configurable).<br>
+CHARGE_COUNTER (accumulated current, non-extended precision) resolution is 625uAh.<br>
+CHARGE_COUNTER_EXT (extended precision in kernel) resolution is 144nAh.<br>
+ENERGY_COUNTER is CHARGE_COUNTER_EXT at nominal voltage of 3.7V.<br>
+Update period for all is 3.5 seconds.</td>
+</tr>
+</tbody>
+</table>
+
+
+<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>
+
+
+<h2 id="power-values">Power Values</h2>
<table>
<tr>
<th>Name</th>
- <th>Meaning</th>
- <th>Example value</th>
+ <th>Description</th>
+ <th>Example Value</th>
<th>Notes</th>
</tr>
<tr>
@@ -402,166 +579,148 @@
<tr>
<td>screen.on</td>
- <td>Additional power used when screen is turned on at minimum brightness </td>
+ <td>Additional power used when screen is turned on at minimum brightness.</td>
<td>200mA</td>
<td>Includes touch controller and display backlight. At 0 brightness, not the Android minimum which tends to be 10 or 20%.</td>
</tr>
<tr>
<td>screen.full</td>
- <td>Additional power used when screen is at maximum brightness, compared to screen at minimum brightness</td>
- <td>100- 300mA</td>
+ <td>Additional power used when screen is at maximum brightness, compared to screen at minimum brightness.</td>
+ <td>100mA-300mA</td>
<td>A fraction of this value (based on screen brightness) is added to the screen.on value to compute the power usage of the screen.</td>
</tr>
<tr>
- <td>bluetooth.active </td>
- <td>Additional power used when playing audio through bluetooth A2DP</td>
+ <td>bluetooth.active</td>
+ <td>Additional power used when playing audio through bluetooth A2DP.</td>
<td>14mA</td>
<td></td>
</tr>
<tr>
<td>bluetooth.on</td>
- <td> Additional power used when bluetooth
-is turned on but idle </td>
+ <td>Additional power used when bluetooth is turned on but idle.</td>
<td>1.4mA</td>
<td></td>
</tr>
<tr>
- <td>wifi.on </td>
- <td>Additional power used when wifi is turned on but not
-receiving, transmitting, or scanning</td>
- <td> 2mA </td>
+ <td>wifi.on</td>
+ <td>Additional power used when Wi-Fi is turned on but not receiving, transmitting, or scanning.</td>
+ <td>2mA</td>
<td></td>
</tr>
<tr>
- <td>wifi.active </td>
- <td>Additional power used when transmitting
-or receiving over Wifi </td>
+ <td>wifi.active</td>
+ <td>Additional power used when transmitting or receiving over Wi-Fi.</td>
<td>31mA</td>
<td></td>
</tr>
<tr>
- <td>wifi.scan </td>
- <td>Additional power used when wifi is scanning for access
-points </td>
+ <td>wifi.scan</td>
+ <td>Additional power used when Wi-Fi is scanning for access points.</td>
<td>100mA</td>
<td></td>
</tr>
<tr>
- <td>dsp.audio </td>
- <td>Additional power used when audio decoding/encoding via DSP </td>
- <td>14.1mA </td>
- <td>Not
-currently used</td>
+ <td>dsp.audio</td>
+ <td>Additional power used when audio decoding/encoding via DSP.</td>
+ <td>14.1mA</td>
+ <td>Reserved for future use.</td>
</tr>
<tr>
- <td>dsp.video </td>
- <td>Additional power used when video decoding via DSP</td>
- <td> 54mA</td>
- <td> Not currently
-used </td>
+ <td>dsp.video</td>
+ <td>Additional power used when video decoding via DSP.</td>
+ <td>54mA</td>
+ <td>Reserved for future use.</td>
</tr>
<tr>
- <td>gps.on </td>
- <td>Additional power used when GPS is acquiring a signal </td>
+ <td>gps.on</td>
+ <td>Additional power used when GPS is acquiring a signal.</td>
<td>50mA</td>
<td></td>
</tr>
<tr>
- <td>radio.active </td>
- <td>Additional
-power used when cellular radio is transmitting/receiving </td>
- <td>100- 300mA </td>
+ <td>radio.active</td>
+ <td>Additional power used when cellular radio is transmitting/receiving.</td>
+ <td>100mA-300mA</td>
<td></td>
</tr>
<tr>
- <td>radio.scanning </td>
- <td>Additional
-power used when cellular radio is paging the tower </td>
+ <td>radio.scanning</td>
+ <td>Additional power used when cellular radio is paging the tower.</td>
<td>1.2mA</td>
<td></td>
</tr>
<tr>
- <td>radio.on Additional power used when
-the cellular radio is on. </td>
- <td>This is a multi-value entry, one per signal strength (no signal,
-weak, moderate, strong) </td>
- <td>1.2mA </td>
- <td>Some radios boost up their power when there’s no signal and
-they’re trying to find a cell tower. So these numbers could all be the same or decreasing
-with increasing signal strength. If you provide only one value, the same value will be used
-for all strengths. If you provide 2 values, the first will be for no-signal and the second
-for all other strengths, and so on.</td>
+ <td>radio.on</td>
+ <td>Additional power used when the cellular radio is on. Multi-value entry, one per signal strength (no signal, weak, moderate, strong).</td>
+ <td>1.2mA</td>
+ <td>Some radios boost power when they search for a cell tower and do not detect a signal. These
+ numbers could all be the same or decreasing with increasing signal strength. If you provide only
+ one value, the same value will be used for all strengths. If you provide 2 values, the first will
+ be for no-signal and the second for all other strengths, and so on.</td>
</tr>
<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>The number and order of entries need to
-correspond to the mA entries in cpu.active </td>
+ <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>The number and order of entries must correspond to the mA entries in cpu.active.</td>
</tr>
<tr>
- <td>cpu.idle </td>
- <td>Total power drawn by the system when CPUs
-(and the SoC) are in system suspend state </td>
+ <td>cpu.idle</td>
+ <td>Total power drawn by the system when CPUs (and the SoC) are in system suspend state.</td>
<td>3mA</td>
<td></td>
</tr>
<tr>
- <td>cpu.awake
-</td>
- <td>Additional power used when CPUs are
-in scheduling idle state (kernel idle loop); system is not in system suspend state </td>
+ <td>cpu.awake</td>
+ <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>
</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>cpu.active</td>
+ <td>Additional power used by CPUs when running at different speeds.</td>
+ <td>100, 120, 140, 160, 200</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>
+same order.</td>
</tr>
<tr>
- <td>battery.capacity </td>
- <td>The total battery capacity in mAh</td>
+ <td>battery.capacity</td>
+ <td>The total battery capacity in mAh.</td>
<td>3000mAh</td>
<td></td>
</tr>
</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>
-Sample file
-</h3>
+<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>
<!-- Most values are the incremental current used by a feature, in mA (measured at
-nominal voltage). OEM's must measure and provide actual values before shipping a device.
-Example real-world values are given, but they are totally dependent on the platform
+nominal voltage). OEMs must measure and provide actual values before shipping a device.
+Example real-world values are given, but are dependent on the platform
and can vary significantly, so should be measured on the shipping platform with a power meter.
-->
0
@@ -605,4 +764,4 @@
3000
<!-- Battery capacity is 3000 mAH (at 3.6 Volts) -->
-</pre>
+</pre>
\ No newline at end of file
diff --git a/src/devices/tech/security/acknowledgements.jd b/src/devices/tech/security/acknowledgements.jd
index 485af30..2b20e90 100644
--- a/src/devices/tech/security/acknowledgements.jd
+++ b/src/devices/tech/security/acknowledgements.jd
@@ -108,13 +108,13 @@
title="This person contributed code that improved Android security">
</a></p>
-<p>Robert Craig of <a href="http://www.nsa.gov/research/ia_research/">
+<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"
title="This person contributed code that improved Android security"></a></p>
-<p>Stephen Smalley of <a href="http://www.nsa.gov/research/ia_research/">
+<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">
@@ -136,6 +136,22 @@
<p><a href="http://www.shackleton.io/">Will Shackleton</a> of <a href="https://www.facebook.com">Facebook</a></p>
+<p>Kunal Patel of <a href="https://www.samsungknox.com/">Samsung KNOX Security Team</a> (<a href="mailto:kunal.patel1@samsung.com">kunal.patel1@samsung.com</a>)</p>
+
+<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><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>
+
+<p><a href="http://davidmurdoch.com">David Murdoch</a></p>
+
+<p>Alexandru Gheorghita</p>
+
+<p>Mathew Solnik (<a href="https://twitter.com/msolnik">@msolnik</a>)</p>
+
+<p>Marc Blanchou (<a href="https://twitter.com/marcblanchou">@marcblanchou</a>)</p>
+
</div>
<h2>2013</h2>
@@ -179,13 +195,13 @@
at Urbana-Champaign</a>
<br>(<a href="mailto:naveed2@illinois.edu">naveed2@illinois.edu</a>)</p>
-<p>Robert Craig of <a href="http://www.nsa.gov/research/ia_research/">
+<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"
title="This person contributed code that improved Android security"></a></p>
-<p>Stephen Smalley of <a href="http://www.nsa.gov/research/ia_research/">
+<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">
@@ -208,13 +224,13 @@
<div style="LINE-HEIGHT:25px;">
-<p>Robert Craig of <a href="http://www.nsa.gov/research/ia_research/">
+<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"
title="This person contributed code that improved Android security"></a></p>
-<p>Stephen Smalley of <a href="http://www.nsa.gov/research/ia_research/">
+<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">
@@ -228,7 +244,6 @@
<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>
<p><a href="http://web.ict.kth.se/~rbbo/ussdvul.html">Ravishankar
diff --git a/src/devices/tech/security/enhancements50.jd b/src/devices/tech/security/enhancements50.jd
new file mode 100644
index 0000000..7a143b6
--- /dev/null
+++ b/src/devices/tech/security/enhancements50.jd
@@ -0,0 +1,56 @@
+page.title=Security Enhancements in Android 5.0
+@jd:body
+
+<p>Every Android release includes dozens of security enhancements to protect
+users. Here are some of the major security enhancements available in Android
+5.0:</p>
+
+<ul>
+ <li><strong>Encrypted by default.</strong> On devices that ship with L
+out-of-the-box, full disk encryption is enabled by default to improve
+protection of data on lost or stolen devices. Devices that
+update to L can be encrypted in <strong>Settings</strong> > <strong>Security</strong>.
+ <li><strong>Improved full disk encryption.</strong> The user password is
+protected against brute-force attacks using <code>scrypt</code> and, where
+available, the key is bound to the hardware keystore to prevent
+off-device attacks. As always, the Android screen lock secret and the device
+encryption key are not sent off the device or exposed to any application.
+ <li><strong>Android sandbox reinforced with SELinux</strong>. Android now
+requires SELinux in enforcing mode for all domains. SELinux is a
+mandatory access control (MAC) system in the Linux kernel used to augment the
+existing discretionary access control (DAC) security model. This new layer
+provides additional protection against potential security vulnerabilities.
+ <li><strong>Smart Lock. </strong>Android now includes trustlets that provide
+more flexibility for unlocking devices. For example, trustlets can allow
+devices to be unlocked automatically when close to another trusted device (via
+NFC, Bluetooth) or being used by someone with a trusted face.
+ <li><strong>Multi user, restricted profile, and guest modes for phones &
+tablets.</strong> Android now provides for multiple users on phones and
+includes a guest mode that can be used to provide easy temporary access to your
+device without granting access to your data and apps.
+ <li><strong>Updates to WebView without OTA. </strong> WebView can now be
+updated independent of the framework and without a system
+OTA. This will allow for faster response to potential security issues in
+WebView.
+ <li><strong>Updated cryptography for HTTPS and TLS/SSL.</strong> TLSv1.2 and
+TLSv1.1 is now enabled, Forward Secrecy is now preferred, AES-GCM
+is now enabled, and weak cipher suites (MD5, 3DES, and export cipher suites)
+are now disabled. See <a
+href="https://developer.android.com/reference/javax/net/ssl/SSLSocket.html">https://developer.android.com/reference/javax/net/ssl/SSLSocket.html</a>
+for more details.
+ <li><strong>non-PIE linker support removed.</strong> Android now requires all
+dynamically linked executables to support PIE
+(position-independent executables). This enhances Android’s address space
+layout randomization (ASLR) implementation.
+ <li><strong>FORTIFY_SOURCE improvements.</strong> The following libc
+functions now implement FORTIFY_SOURCE protections: <code>stpcpy()</code>,
+<code>stpncpy()</code>, <code>read()</code>, <code>recvfrom()</code>,
+<code>FD_CLR()</code>, <code>FD_SET()</code>, and <code>FD_ISSET()</code>. This
+provides protection against memory-corruption vulnerabilities involving
+those functions.
+ <li><strong>Security Fixes.</strong> Android 5.0 also includes fixes for
+Android-specific vulnerabilities. Information about these vulnerabilities has
+been provided to Open Handset Alliance members, and fixes are available in
+Android Open Source Project. To improve security, some devices with earlier
+versions of Android may also include these fixes.
+</ul>
diff --git a/src/devices/tech/security/index.jd b/src/devices/tech/security/index.jd
index f143b3f..b2982d7 100644
--- a/src/devices/tech/security/index.jd
+++ b/src/devices/tech/security/index.jd
@@ -78,9 +78,9 @@
</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.
+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 Dalvik and native
+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>
@@ -305,7 +305,7 @@
keys and certificate chains.
</p>
-<h2>Memory Management Security Enhancements</h2>
+<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
@@ -350,7 +350,7 @@
</dl>
-<h2>Rooting of Devices</h2>
+<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
@@ -396,7 +396,7 @@
the bootloader or operating system is not sufficient to access user data
without the user’s device password.
</p>
-<h2>User Security Features</h2>
+<h2 id="user-sec">User Security Features</h2>
<h3 id="filesystem-encryption">Filesystem Encryption</h3>
@@ -413,7 +413,7 @@
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/encryption/android_crypto_implementation.html">https://source.android.com/devices/tech/encryption/android_crypto_implementation.html</a></p>
+<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
@@ -441,7 +441,7 @@
<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
+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>
@@ -767,7 +767,7 @@
<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>
+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
diff --git a/src/devices/tech/security/se-linux.jd b/src/devices/tech/security/se-linux.jd
index 6c34a02..bbc6ed8 100644
--- a/src/devices/tech/security/se-linux.jd
+++ b/src/devices/tech/security/se-linux.jd
@@ -63,7 +63,7 @@
Per-domain permissive mode also enables policy development for new services
while keeping the rest of the system enforcing.</p>
-<p>In the L release, Android moves to full enforcement of SELinux. This builds
+<p>In the Android 5.0 (L) release, Android moves to full enforcement of SELinux. This builds
upon the permissive release of 4.3 and the partial enforcement of 4.4. In
short, Android is shifting from enforcement on a limited set of crucial domains
(<code>installd</code>, <code>netd</code>, <code>vold</code> and <code>zygote</code>) to everything (more than 60 domains). This means manufacturers will have to
@@ -71,7 +71,7 @@
devices. Understand that:</p>
<ul>
- <li> Everything is in enforcing mode in the L release
+ <li> Everything is in enforcing mode in the 5.0 release
<li> No processes other than <code>init</code> should run in the <code>init</code> domain
<li> Any generic denial (for a block_device, socket_device, default_service, etc.)
indicates that device needs a special domain
@@ -81,7 +81,7 @@
<p>See the documentation below for details on constructing useful policies:</p>
-<p><a href="https://seandroid.bitbucket.org/PapersandPresentations.html">https://seandroid.bitbucket.org/PapersandPresentations.html</a></p>
+<p><a href="http://seandroid.bitbucket.org/PapersandPresentations.html">http://seandroid.bitbucket.org/PapersandPresentations.html</a></p>
<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>
@@ -93,7 +93,7 @@
<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="https://freecomputerbooks.com/books/The_SELinux_Notebook-4th_Edition.pdf">https://freecomputerbooks.com/books/The_SELinux_Notebook-4th_Edition.pdf</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>
<h2 id=help>Help</h2>
diff --git a/src/devices/tech/storage/index.jd b/src/devices/tech/storage/index.jd
index e50abe9..1d7192d 100644
--- a/src/devices/tech/storage/index.jd
+++ b/src/devices/tech/storage/index.jd
@@ -1,8 +1,8 @@
-page.title=External Storage Technical Information
+page.title=External Storage
@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.
diff --git a/src/devices/tv/HDMI-CEC.jd b/src/devices/tv/HDMI-CEC.jd
new file mode 100644
index 0000000..bbf6547
--- /dev/null
+++ b/src/devices/tv/HDMI-CEC.jd
@@ -0,0 +1,311 @@
+page.title=HDMI-CEC Control Service
+@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=intro>Introduction</h2>
+
+<p>The High-Definition Multimedia Interface Consumer Electronics Control (HDMI-CEC) standard allows mulitmedia consumer products to communicate and
+exchange information with each other. HDMI-CEC supports many features, like
+Remote Control Passthrough and System Audio Control, but one of the most
+popular is One Touch Play. One Touch Play lets a media source device turn on
+the TV and switch its input port automatically, so you don’t have to search for
+the TV remote to switch from your Chromecast to Blu-ray player.</p>
+
+<p>Most manufacturers have adopted HDMI-CEC so their devices work with other
+companies’ devices. But because each manufacturer implements the HDMI-CEC
+standard in different ways, devices don’t always understand each other and
+supported features vary between devices. Because of this variance, consumers
+can’t safely assume that two products that claim CEC support are completely
+compatible.</p>
+
+<h2 id=solution>Solution</h2>
+
+
+<p>With the introduction of the Android TV Input Framework (TIF), HDMI-CEC brings
+together all connected devices and minimizes compatibility issues. Android has
+created a system service called <code>HdmiControlService</code> to alleviate these pain points.</p>
+
+<p>By offering <code>HdmiControlService</code> as a part of the Android ecosystem, Android hopes to provide:</p>
+
+<ul>
+ <li>A standard implementation of HDMI-CEC for all manufacturers, which will reduce
+device incompatibility. Previously, manufacturers had to develop their own
+implementations of HDMI-CEC or use third-party solutions.</li>
+ <li>A service that is well-tested against numerous HDMI-CEC devices already in the
+market. Android has been conducting rigorous research on compatibility issues
+found among the products and collecting useful advice from partners experienced
+in the technology. The CEC service is designed to keep a healthy balance
+between the standard and modifications to that standard so that it works with
+the products that people already use.</li>
+</ul>
+
+<h2 id=overall_design>Overall design</h2>
+
+
+<p><code>HdmiControlService</code> is connected with the rest of the system like TV Input Framework (TIF), Audio service, and Power service to implement the various features the standard
+specifies.</p>
+
+<p>See the following diagram for a depiction of the switch from a custom CEC
+controller to an implementation of the simpler HDMI-CEC hardware abstraction
+layer (HAL).</p>
+
+<img src="images/HDMI_Control_Service.png" alt="Diagram that shows how HDMI-CEC was implemented before and after Android 5.0">
+
+<p class="img-caption"><strong>Figure 1.</strong> HDMI Control Service replacement</p>
+
+<h2 id=implementation>Implementation</h2>
+
+
+<p>See the following diagram for a detailed view of the HDMI control service.</p>
+
+<img src="images/HDMI_Control_Service_Flow.png" alt="Image that shows how HDMI Control service details">
+
+<p class="img-caption"><strong>Figure 2.</strong> HDMI Control Service details</p>
+
+<p>Here are the key ingredients to a proper Android HDMI-CEC implementation:</p>
+
+<ul>
+ <li> A manager class <code>HdmiControlManager</code> provides priviledged apps with the API. System services like TV Input Manager service and Audio service can grab the service directly.</li>
+ <li> The service is designed to allow hosting more than one type of logical device.</li>
+ <li> HDMI-CEC is connected with the hardware via a hardware abstraction layer (HAL)
+to simplify handling differences of the protocol and signalling mechanisms
+between the devices. The HAL definition is available for device manufacturers
+to use to implement the HAL layer.</li>
+</ul>
+
+<p class="note"><strong>Note</strong>: Device manufacturers should add the following line into <code>PRODUCT_COPY_FILES</code> in <code>device.mk</code>.</p>
+
+<pre>
+PRODUCT_COPY_FILES += \
+frameworks/native/data/etc/android.hardware.hdmi.cec.xml:system/etc/permissions/android.hardware.hdmi.cec.xml
+</pre>
+
+
+<p>Depending on whether your device is a HDMI sink device or a HDMI source device,
+device manufactureres need to set <code>ro.hdmi.device_type</code> in <code>device.mk</code> for <code>HdmiControlService</code> to work correctly.</p>
+
+<p>For HDMI source devices, like Over the Top (OTT) boxes, set:</p>
+
+<pre>
+PRODUCT_PROPERTY_OVERRIDES += ro.hdmi.device_type=<strong>4</strong>
+</pre>
+
+<p>For HDMI sink devices, like panel TVs, set:</p>
+
+<pre>
+PRODUCT_PROPERTY_OVERRIDES += ro.hdmi.device_type=<strong>0</strong></pre>
+</p>
+
+
+<ul>
+ <li> A device manufacturer-provided proprietary CEC controller cannot coexist with <code>HdmiControlService</code>. It must be disabled or removed. Common requirements for this come from the need to handle manufacturer-specific commands. The manufacturer-specific
+command handler should be incorporated into the service by extending/modifying
+it. This work is left to the device manufacturer and not specified by Android.
+Note that any change made in the service for manufacturer-specific commands
+must not interfere with the way standard commands are handled or the device
+will not be Android compatible.</li>
+ <li> Access to the HDMI-CEC service is guarded with the protection level <code>SignatureOrSystem</code>. Only system components or the apps placed in <code>/system/priv-app</code> can access the service. This is to protect the service from abuse by apps with malicous intent.</li>
+</ul>
+
+<p>Android supports type <code>TV/Display(0)</code> and <code>playback device(4)</code>, which can issue the One Touch Play command to display. The other types (tuner
+and recorder) are currently not supported.</p>
+
+<h2 id=hdmi-cec_hal_definition>HDMI-CEC HAL definition</h2>
+
+
+<p>In order to have the service in action, the HDMI-CEC HAL needs to be
+implemented to the definition provided by Android. It abstracts differences in
+the hardware level and exposes the primitive operations (allocate/read/write,
+etc.) to the upper layer through API.</p>
+
+<p>The API calls that device manufacturers must support are:</p>
+
+<h3 id=tx_rx_events>TX/RX/Events</h3>
+<ul>
+ <li><code>send_message</code></li>
+ <li><code>register_event_callback</code></li>
+</ul>
+
+<h3 id=info>Info</h3>
+<ul>
+ <li><code>get_physical_address</code></li>
+ <li><code>get_version</code></li>
+ <li><code>get_vendor_id</code></li>
+ <li><code>get_port_info</code></li>
+</ul>
+
+<h3 id=logical_address>Logical Address</h3>
+<ul>
+ <li><code>add_logical_address</code></li>
+ <li><code>clear_logical_address</code></li>
+</ul>
+
+<h3 id=status>Status</h3>
+<ul>
+ <li><code>is_connected set_option</code></li>
+ <li><code>set_audio_return_channel</code></li>
+</ul>
+
+<p>Here is an excerpt of the HDMI-CEC HAL definition regarding APIs:</p>
+
+<pre>
+#ifndef ANDROID_INCLUDE_HARDWARE_HDMI_CEC_H
+#define ANDROID_INCLUDE_HARDWARE_HDMI_CEC_H
+
+...
+
+/*
+ * HDMI-CEC HAL interface definition.
+ */
+typedef struct hdmi_cec_device {
+ /**
+ * Common methods of the HDMI-CEC device. This *must* be the first member of
+ * hdmi_cec_device as users of this structure will cast a hw_device_t to hdmi_cec_device
+ * pointer in contexts where it's known the hw_device_t references a hdmi_cec_device.
+ */
+ struct hw_device_t common;
+
+ /*
+ * (*add_logical_address)() passes the logical address that will be used
+ * in this system.
+ *
+ * HAL may use it to configure the hardware so that the CEC commands addressed
+ * the given logical address can be filtered in. This method can be called
+ * as many times as necessary in order to support multiple logical devices.
+ * addr should be in the range of valid logical addresses for the call
+ * to succeed.
+ *
+ * Returns 0 on success or -errno on error.
+ */
+ int (*add_logical_address)(const struct hdmi_cec_device* dev, cec_logical_address_t addr);
+
+ /*
+ * (*clear_logical_address)() tells HAL to reset all the logical addresses.
+ *
+ * It is used when the system doesn't need to process CEC command any more,
+ * hence to tell HAL to stop receiving commands from the CEC bus, and change
+ * the state back to the beginning.
+ */
+ void (*clear_logical_address)(const struct hdmi_cec_device* dev);
+
+ /*
+ * (*get_physical_address)() returns the CEC physical address. The
+ * address is written to addr.
+ *
+ * The physical address depends on the topology of the network formed
+ * by connected HDMI devices. It is therefore likely to change if the cable
+ * is plugged off and on again. It is advised to call get_physical_address
+ * to get the updated address when hot plug event takes place.
+ *
+ * Returns 0 on success or -errno on error.
+ */
+ int (*get_physical_address)(const struct hdmi_cec_device* dev, uint16_t* addr);
+
+ /*
+ * (*send_message)() transmits HDMI-CEC message to other HDMI device.
+ *
+ * The method should be designed to return in a certain amount of time not
+ * hanging forever, which can happen if CEC signal line is pulled low for
+ * some reason. HAL implementation should take the situation into account
+ * so as not to wait forever for the message to get sent out.
+ *
+ * It should try retransmission at least once as specified in the standard.
+ *
+ * Returns error code. See HDMI_RESULT_SUCCESS, HDMI_RESULT_NACK, and
+ * HDMI_RESULT_BUSY.
+ */
+ int (*send_message)(const struct hdmi_cec_device* dev, const cec_message_t*);
+
+ /*
+ * (*register_event_callback)() registers a callback that HDMI-CEC HAL
+ * can later use for incoming CEC messages or internal HDMI events.
+ * When calling from C++, use the argument arg to pass the calling object.
+ * It will be passed back when the callback is invoked so that the context
+ * can be retrieved.
+ */
+ void (*register_event_callback)(const struct hdmi_cec_device* dev,
+ event_callback_t callback, void* arg);
+
+ /*
+ * (*get_version)() returns the CEC version supported by underlying hardware.
+ */
+ void (*get_version)(const struct hdmi_cec_device* dev, int* version);
+
+ /*
+ * (*get_vendor_id)() returns the identifier of the vendor. It is
+ * the 24-bit unique company ID obtained from the IEEE Registration
+ * Authority Committee (RAC).
+ */
+ void (*get_vendor_id)(const struct hdmi_cec_device* dev, uint32_t* vendor_id);
+
+ /*
+ * (*get_port_info)() returns the hdmi port information of underlying hardware.
+ * info is the list of HDMI port information, and 'total' is the number of
+ * HDMI ports in the system.
+ */
+ void (*get_port_info)(const struct hdmi_cec_device* dev,
+ struct hdmi_port_info* list[], int* total);
+
+ /*
+ * (*set_option)() passes flags controlling the way HDMI-CEC service works down
+ * to HAL implementation. Those flags will be used in case the feature needs
+ * update in HAL itself, firmware or microcontroller.
+ */
+ void (*set_option)(const struct hdmi_cec_device* dev, int flag, int value);
+
+ /*
+ * (*set_audio_return_channel)() configures ARC circuit in the hardware logic
+ * to start or stop the feature. Flag can be either 1 to start the feature
+ * or 0 to stop it.
+ *
+ * Returns 0 on success or -errno on error.
+ */
+ void (*set_audio_return_channel)(const struct hdmi_cec_device* dev, int flag);
+
+ /*
+ * (*is_connected)() returns the connection status of the specified port.
+ * Returns HDMI_CONNECTED if a device is connected, otherwise HDMI_NOT_CONNECTED.
+ * The HAL should watch for +5V power signal to determine the status.
+ */
+ int (*is_connected)(const struct hdmi_cec_device* dev, int port);
+
+ /* Reserved for future use to maximum 16 functions. Must be NULL. */
+ void* reserved[16 - 11];
+} hdmi_cec_device_t;
+
+#endif /* ANDROID_INCLUDE_HARDWARE_HDMI_CEC_H */
+</pre>
+
+
+<p>The API lets the service make use of the hardware resource to send/receive
+HDMI-CEC commands, configure necessary settings, and (optionally) communicate
+with the microprocessor in the underlying platform that will take over the CEC
+control while the Android system is in standby mode.</p>
+
+<h2 id=testing>Testing</h2>
+
+
+<p>Device manufacturers must test the APIs of the HDMI-CEC HAL with their own
+tools to make sure they provide expected functionality.</p>
diff --git a/src/devices/tv/images/Built-in_Tuner_TV_Input.png b/src/devices/tv/images/Built-in_Tuner_TV_Input.png
new file mode 100644
index 0000000..bff7fea
--- /dev/null
+++ b/src/devices/tv/images/Built-in_Tuner_TV_Input.png
Binary files differ
diff --git a/src/devices/tv/images/HDMI_Control_Service.png b/src/devices/tv/images/HDMI_Control_Service.png
new file mode 100644
index 0000000..cc8e43d
--- /dev/null
+++ b/src/devices/tv/images/HDMI_Control_Service.png
Binary files differ
diff --git a/src/devices/tv/images/HDMI_Control_Service_Flow.png b/src/devices/tv/images/HDMI_Control_Service_Flow.png
new file mode 100644
index 0000000..84fe4a6
--- /dev/null
+++ b/src/devices/tv/images/HDMI_Control_Service_Flow.png
Binary files differ
diff --git a/src/devices/tv/images/TIF_HDMI_TV_Input.png b/src/devices/tv/images/TIF_HDMI_TV_Input.png
new file mode 100644
index 0000000..5274588
--- /dev/null
+++ b/src/devices/tv/images/TIF_HDMI_TV_Input.png
Binary files differ
diff --git a/src/devices/tv/images/TIF_MHEG5_app.png b/src/devices/tv/images/TIF_MHEG5_app.png
new file mode 100644
index 0000000..f977ea4
--- /dev/null
+++ b/src/devices/tv/images/TIF_MHEG5_app.png
Binary files differ
diff --git a/src/devices/tv/images/TIF_Overview.png b/src/devices/tv/images/TIF_Overview.png
new file mode 100644
index 0000000..5041c17
--- /dev/null
+++ b/src/devices/tv/images/TIF_Overview.png
Binary files differ
diff --git a/src/devices/tv/images/TIF_PIP-PAP.png b/src/devices/tv/images/TIF_PIP-PAP.png
new file mode 100644
index 0000000..ea3a3a7
--- /dev/null
+++ b/src/devices/tv/images/TIF_PIP-PAP.png
Binary files differ
diff --git a/src/devices/tv/images/TIF_TV_Provider.png b/src/devices/tv/images/TIF_TV_Provider.png
new file mode 100644
index 0000000..d058d82
--- /dev/null
+++ b/src/devices/tv/images/TIF_TV_Provider.png
Binary files differ
diff --git a/src/devices/tv/images/TV_App_CEC_integration.png b/src/devices/tv/images/TV_App_CEC_integration.png
new file mode 100644
index 0000000..bf36fac
--- /dev/null
+++ b/src/devices/tv/images/TV_App_CEC_integration.png
Binary files differ
diff --git a/src/devices/tv/images/TV_Input_DVR.png b/src/devices/tv/images/TV_Input_DVR.png
new file mode 100644
index 0000000..3a652db
--- /dev/null
+++ b/src/devices/tv/images/TV_Input_DVR.png
Binary files differ
diff --git a/src/devices/tv/images/Third-party_Input_HDMI.png b/src/devices/tv/images/Third-party_Input_HDMI.png
new file mode 100644
index 0000000..684613a
--- /dev/null
+++ b/src/devices/tv/images/Third-party_Input_HDMI.png
Binary files differ
diff --git a/src/devices/tv/index.jd b/src/devices/tv/index.jd
new file mode 100644
index 0000000..1b8f75f
--- /dev/null
+++ b/src/devices/tv/index.jd
@@ -0,0 +1,483 @@
+page.title=TV Input Framework
+@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=introduction>Introduction</h2>
+
+<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 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>
+
+<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
+third-party app, to access built-in and IP tuner channels. The TV App
+communicates with TV Input modules supplied by the device manufacturer or other
+parties through the TV Input Manager.</p>
+
+<p>The TV Input Framework consists of:</p>
+
+<ul>
+ <li>TV Provider (<code>com.android.providers.tv.TvProvider</code>): a database of channels, programs, and associated permissions
+ <li>TV App (<code>com.android.tv.TvActivity</code>): the app that handles user interaction
+ <li>TV Input Manager (<code>android.media.tv.TvInputManager</code>): allows the TV Inputs to communicate with the TV App
+ <li>TV Input: an app representing physical or virtual tuners and input ports
+ <li>TV Input HAL (<code>tv_input</code> module): a hardware definition that allows system TV Inputs to access
+TV-specific hardware when implemented
+ <li>Parental Control: the technology to allow blocking of channels and programs
+ <li>HDMI-CEC: the technology to allow remote control of various devices over HDMI
+</ul>
+
+<p>These components are covered in detail below. See the following diagram for a
+detailed view of the Android TV Input Framework architecture.</p>
+
+<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>
+
+<p>Here is how the architecture is exercised:</p>
+
+<ol>
+ <li>The user sees and interacts with the TV App, a system app that can’t be
+replaced by a third-party app.
+ <li>The TV App displays the AV content from the TV Input.
+ <li>The TV App cannot talk directly with the TV Inputs. The TV Input Manager
+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>
+
+<ul>
+ <li>Only <code><a
+href="http://developer.android.com/guide/topics/manifest/permission-element.html#plevel">signatureOrSystem</a></code>
+TV Inputs and TV App have full access to the TV Provider database and are able
+to receive KeyEvents.
+ <li>Only system TV Inputs can access the TV Input HAL through the TV Input Manager
+service. TV Inputs are accessed one-to-one via TV Input Manager sessions.
+ <li>Third-party TV Inputs have package-locked access to the TV Provider database
+and can READ/WRITE only to matching package rows.
+ <li>Third-party TV inputs can either display their own content or content from a
+device manufacturer’s passthrough TV inputs, like HDMI1. They can’t display
+content from non-passthrough TV inputs, like a built-in or IPTV tuner.
+ <li><code>TV_INPUT_HARDWARE</code> permission for a hardware TV Input app, signals the TV Input Manager Service
+to notify the TV Input service on boot to call the TV Input Manager Service and
+add its TV Inputs. This permission allows a hardware TV Input app to support
+multiple TV Inputs per TV Input service, as well as being able to dynamically
+add and remove its supported TV Inputs.
+</ul>
+
+<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
+Inputs can see only their own records. For instance, a specific TV Input can
+see only the channels and programs it has supplied and is prohibited from
+accessing any other TV Inputs’ channels and programs. </p>
+
+<p>The TV Provider maps "broadcast genre" to "canonical genre" internally. TV
+Inputs are responsible for populating "broadcast genre" with the value in the
+underlying broadcast standard, and the "canonical genre" field will
+automatically be populated with the correct associated genre from <code>android.provider.TvContract.Genres</code>. For example, with broadcast standard ATSC A/65 and program with genre 0x25
+(meaning “Sports”), the TV Input will populate the “broadcast genre” with the
+String “Sports” and TV Provider will populate the “canonical genre” field with
+the mapped value <code>android.provider.TvContract.Genres.SPORTS</code>.</p>
+
+<p>See the diagram below for a detailed view of the TV Provider. </p>
+
+<img src="images/TIF_TV_Provider.png" alt="Android TV Provider">
+<p class="img-caption"><strong>Figure 2.</strong> Android TV Provider</p>
+
+<p><em>Only apps in the privileged system partition can read the entire TV Provider
+database. </em></p>
+
+<p>Passthrough TV inputs do not store channels and programs. </p>
+
+<p>In addition to the standard fields for channels and programs, the TV Provider
+database also offers a BLOB type field, <code>COLUMN_INTERNAL_PROVIDER_DATA</code>, in each table that TV Inputs may use to store arbitrary data. That BLOB data
+can include custom information, such as frequency of the associated tuner, and
+may be provided in a protocol buffer or another form. A Searchable field is
+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>
+
+<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>
+
+<ul>
+ <li><strong>Display: </strong>Display fields contain information that apps may want to make visible to the
+user, like a channel’s name (<code>COLUMN_DISPLAY_NAME</code>) or number (<code>COLUMN_DISPLAY_NUMBER</code>), or the title of the program being viewed.
+ <li><strong>Metadata:</strong> There are three fields for identifying content, according to relevant
+standards, like a channel’s transport stream ID (<code>COLUMN_TRANSPORT_STREAM_ID</code>), original network ID (<code>COLUMN_ORIGINAL_NETWORK_ID</code>) and service id (<code>COLUMN_SERVICE_ID</code>).
+ <li><strong>Internal data</strong>: Fields that are for the custom use of TV Inputs.<br>
+ Some fields, like <code>COLUMN_INTERNAL_PROVIDER_DATA</code>, are customizable BLOB fields where a TV Input can store arbitrary metadata
+about their channel or program.
+ <li><strong>Flag: </strong>Flag fields represent whether a channel should be restricted from search,
+browse, or viewing. This can be set only at the channel level. All programs
+defer to the setting on the channel.
+ <ul>
+ <li><code>COLUMN_SEARCHABLE</code>: Restricting search from some channels may be a requirement in certain
+regions. <code>COLUMN_SEARCHABLE = 0</code> means the channel should not be exposed in search results.
+ <li><code>COLUMN_BROWSABLE</code>: Visible to system applications only. Restricting channel from being browsed
+by applications. <code>COLUMN_BROWSABLE = 0</code> means the channel should not be included in the channel list.
+ <li><code>COLUMN_LOCKED</code>: Visible to system applications only. Restricting channel from being viewed by
+invalid accounts without entering PIN code. <code>COLUMN_LOCKED = 1</code> means the channel should be protected by parental control.
+ </ul>
+</ul>
+
+<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>
+
+<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
+apps, or TV Inputs surface.</p>
+
+<ul>
+ <li>Each row has <code>PACKAGE_NAME</code>, the package (app) that owns that row, checked on Query, Insert, Update via
+TvProvider.java.
+A TV Input may access only the information it wrote and is
+cordoned off from the information provided by other TV Inputs.
+ <li>READ, WRITE permissions via AndroidManifest.xml (requires user consent) to
+determine available channels.
+ <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>
+
+<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
+provides parental control functionality. TV Input Manager sessions must be
+created one-to-one with TV Inputs. The TV Input Manager allows access to
+installed TV Inputs so apps may:</p>
+
+<ul>
+ <li>List TV inputs and check their status
+ <li>Create sessions and manage listeners
+</ul>
+
+<p>For sessions, a TV Input may be tuned by the TV App only to URIs it has added
+to the TV Provider database, except for passthrough TV Inputs which can be
+tuned to using <code>TvContract.buildChannelUriForPassthroughInput()</code>. A TV Input may also have its volume set. TV Inputs provided and signed by the
+device manufacturer (signature apps) or other apps installed in the system
+partition will have access to the entire TV Provider database. This access can
+be used to construct apps to browse and search across all available TV channels
+and programs.</p>
+
+<p>An app may create and register a <code>TvInputCallback</code> with the <code>android.media.tv.TvInputManager</code> to be called back on a TV Input’s state change or on the addition or removal
+of a TV Input. For example, a TV App can react when a TV Input is disconnected
+by displaying it as disconnected and preventing its selection.</p>
+
+<p>The TV Input Manager abstracts communication between the TV App and TV Inputs.
+The standard interface of TV Input Manager and TV Input allows multiple
+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>
+
+<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
+pre-installed system apps, apps signed by the device manufacturer and
+third-party TV Inputs. </p>
+
+<p>Some inputs, like the HDMI input or built-in tuner input, can be provided only
+by the manufacturer as they speak directly with the underlying hardware.
+Others, such as IPTV, place-shifting, and external STB, can be supplied by
+third parties as APKs on Google Play Store. Once downloaded and installed, the
+new input can be selected within the TV App.</p>
+
+<h3 id=passthrough_input_example>Passthrough input example</h3>
+
+<img src="images/TIF_HDMI_TV_Input.png" alt="Android TV System Input">
+<p class="img-caption"><strong>Figure 3.</strong> Android TV System Input</p>
+
+<p>In this example, the TV Input provided by the device manufacturer is trusted
+and has full access to the TV Provider. As a passthrough TV Input, it does not
+register any channels or programs with the TV Provider. To obtain the URI used
+to reference the passthrough input, use the <code>android.media.tv.TvContract</code> utility method <code>buildChannelUriForPassthroughInput(String inputId)</code>. The TV App communicates with the TV Input Manager to reach the HDMI TV
+Input. </p>
+
+<h3 id=built-in_tuner_example>Built-in tuner example</h3>
+
+<img src="images/Built-in_Tuner_TV_Input.png" alt="Android TV Built-in Tuner Input">
+<p class="img-caption"><strong>Figure 4.</strong> Android TV Built-in Tuner Input</p>
+
+<p>In this example, the Built-in Tuner TV Input provided by the device
+manufacturer is trusted and has full access to the TV Provider. </p>
+
+<h3 id=third-party_input_example>Third-party input example</h3>
+
+<img src="images/Third-party_Input_HDMI.png" alt="Android TV third-party input">
+<p class="img-caption"><strong>Figure 5.</strong> Android TV third-party input</p>
+
+<p>In this example, the external STB TV Input is provided by a third party. Since
+that TV Input can’t directly access the HDMI video feed coming in, it must go
+through the TV Input Manager and use the HDMI TV Input provided by the device
+manufacture.</p>
+
+<p>Through the TV Input Manager, the external STB TV Input can speak with the HDMI
+TV Input and ask it to show the video on HDMI1. So the STB TV Input can control
+the TV while the manufacturer-provided HDMI TV Input renders the video.</p>
+
+<h3 id=picture_in_picture_pip_example>Picture in picture (PIP) example </h3>
+
+<img src="images/TIF_PIP-PAP.png" alt="Android TV KeyEvents">
+<p class="img-caption"><strong>Figure 6.</strong> Android TV KeyEvents</p>
+
+<p>The diagram above shows how buttons on a remote control are passed to a
+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>
+
+<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
+consume.</p>
+
+<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>
+
+<p>The following diagram shows a more detailed view of how <code>KeyEvents</code> are routed through the Android TIF.</p>
+
+<img src="images/TIF_MHEG5_app.png" alt="Android TV Red button example">
+<p class="img-caption"><strong>Figure 7.</strong> Android TV Red button example</p>
+
+<p>It depicts the flow of a Red button app, common in Europe for letting users
+access interactive apps on their televisions. An app can be delivered over this
+transport stream. When the button is clicked, it lets users interact with these
+broadcast apps. For example, you might use these broadcast apps to access
+related web pages or sports scores.</p>
+
+<p>See the <em>Broadcast app</em> section to learn how broadcast apps interact with the TV App.</p>
+
+<p>In this example:</p>
+
+<ol>
+ <li>The TV App is in focus and receives all keys.
+ <li><code>KeyEvents</code> (e.g. the Red button) is passed to the active TV Input as <code>InputEvents.</code>
+ <li>The system TV Input integrates with MHEG-5 stack and has the <code>RECEIVE_INPUT_EVENT</code> system permission.
+ <li>On receiving activation keycode (e.g. Red button), the TV Input activates
+broadcast app.
+ <li>TV input consumes <code>KeyEvents</code> as <code>InputEvents</code> and the broadcast app is the focus and handles <code>InputEvents</code> until dismissed.
+</ol>
+
+<p class="note"><strong>Note</strong>: Third-party TV inputs never receive keys. </p>
+
+<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>
+
+<p>The TV App provides channel and program search results (via
+<code>com.android.tv.search.TvProviderSearch</code>) and passes keys, tune, and
+volume calls to TV Inputs through the TV Input
+Manager. Manufacturers must implement the TV App to ensure search functions
+work for their users. Otherwise, users will struggle to navigate the resulting
+Android TV. Third-party developers cannot develop TV Apps as the APIs require
+system or signature permission.</p>
+
+<p>As with the TIF in general, the TV App does not seek to implement device
+manufacturer or country-specific features. Instead, it handles these tasks by
+default:</p>
+
+<h3 id=setup_and_configuration>Setup and configuration</h3>
+
+<ul>
+ <li>Auto-detect TV Inputs
+ <li>Let TV Inputs initiate channel setup
+ <li>Control parental settings
+ <li>Alter TV settings
+ <ul>
+ <li>Edit channel
+ </ul>
+</ul>
+
+<h3 id=viewing>Viewing</h3>
+<ul>
+ <li>Access and navigate all TV channels
+ <li>Access TV program information bar
+ <li>Multiple audio and subtitle track support
+ <li>Parental control PIN challenge
+ <li>Allow TV Input UI overlay for:
+ <ul>
+ <li>TV standard (HbbTV, etc.)
+ </ul>
+</ul>
+
+<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>
+
+<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>
+
+<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>
+
+<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>
+
+<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
+displayed content has changed
+(on program or channel change), or parental control settings have changed (on
+<code>ACTION_BLOCKED_RATINGS_CHANGED</code> and
+<code>ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED</code>). If the content should
+be blocked, the TV Input disables the audio and video
+and notifies the TV app that the current content is blocked by calling
+<code>notifyContentBlocked(TvContentRating)</code>. If the content should not
+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>
+
+<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
+attempts to view a blocked channel.</p>
+
+<p>The TV App does not directly store the parental control settings. When the user
+changes the parental control settings, every blocked
+<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>
+
+<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
+speed setup and allow distant control over various TV Inputs via the central TV
+App. For instance, it may switch inputs, power up or down devices, and more.</p>
+
+<p>The Android TIF implements HDMI-CEC as the HDMI Control Service so that
+device manufacturers merely need to develop low-level drivers that interact with the
+lightweight Android TV HAL, skipping more complex business logic. In providing
+a standard implementation, Android seeks to mitigate compatibility issues by
+reducing fragmented implementations and selective feature support. The HDMI
+Control Service uses the existing Android services, including input and power.</p>
+
+<p>This means existing HDMI-CEC implementations will need to be redesigned to
+interoperate with the Android TIF. We recommend the hardware platform contain a
+microprocessor to receive CEC power on and other commands.</p>
+
+<img src="images/TV_App_CEC_integration.png" alt="CEC integration on Android TV">
+<p class="img-caption"><strong>Figure 8.</strong> CEC integration on Android TV</p>
+
+<ol>
+ <li> The CEC bus receives a command from the currently active source to switch to a
+different source.
+ <li> The driver passes the command to the HDMI-CEC HAL.
+ <li> The HAL notifies all <code>ActiveSourceChangeListeners</code>.
+ <li> THe HDMI Control Service is notified of source change via <code>ActiveSourceChangeListener</code>.
+ <li> The TV Input Manager service generates an intent for the TV App to switch the
+source.
+ <li> The TV App then creates a TV Input Manager Session for the TV Input being
+switched to and calls <code>setMain</code> on that session.
+ <li> The TV Input Manager Session passes this information on to the HDMI TV Input.
+ <li> The HDMI TV input requests to set sideband surface.
+ <li> The TV Input Manager Service generates a corresponding routing control command
+back to HDMI Control Service when the surface is set.
+</ol>
+
+<h2 id=tv_integration_guidelines>TV integration guidelines</h2>
+
+<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
+the broadcast app, for example:</p>
+
+<ul>
+ <li> MHEG: native stack
+ <li> Teletext: native stack
+ <li> HbbTV: webkit modification by Opera browser
+</ul>
+
+<p>In the Android L release, Android TV expects device manufacturers to use systems
+integrators or the Android solutions for regional TV stacks, pass the surface
+to TV software stacks, or pass the necessary key code to interact with legacy
+stacks.</p>
+
+<p>Here’s how the broadcast app and TV App interact:</p>
+
+<ol>
+ <li>The TV App is in focus, receiving all keys.
+ <li>The TV App passes keys (e.g. Red button) to the TV Input device.
+ <li>The TV Input device internally integrates with legacy TV stack.
+ <li>On receiving an activation keycode (e.g. Red button), the TV Input device
+activates broadcast apps.
+ <li>A broadcast app takes focus in the TV App and handles user actions.
+</ol>
+
+<p>For voice search/recommendation, the broadcast app may support In-app search
+for voice search.</p>
+
+<h3 id=dvr>DVR</h3>
+
+<p>Android TV supports digital video recording (DVR) with device manufacturer development. The
+DVR function works like so:</p>
+
+<ol>
+ <li> DVR recording function / Live Buffer can be implemented by any TV Input.
+ <li> TV App passes on key inputs to TV Input (including recording/pause/fast
+forward/ rewind keys).
+ <li> When playing the recorded content, the TV Input handles it with trick play
+overlay.
+ <li> DVR app enables users to browse and manage recorded program.
+</ol>
+
+<p>For voice search/recommendation:</p>
+
+<ul>
+ <li>DVR app supports In-app search for Voice search.
+ <li>DVR app can propose recommendation using notifications.
+</ul>
+
+<p>See the following diagram for a view into a possible DVR implementation in
+Android TV.</p>
+
+<img src="images/TV_Input_DVR.png" alt="Digital video recording in Android TV">
+<p class="img-caption"><strong>Figure 9.</strong> Digital video recording in Android TV</p>
diff --git a/src/index.jd b/src/index.jd
index bcf28c3..21808ec 100644
--- a/src/index.jd
+++ b/src/index.jd
@@ -6,7 +6,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.
@@ -42,39 +42,47 @@
<div class="col-8">
<h3>What's New</h3>
-<a href="{@docRoot}devices/graphics.html">
- <h4>Graphics introduction and implementation rewritten</h4></a>
+<a href="{@docRoot}devices/audio.html">
+ <h4>Audio gains attributes, USB, and headset documentation</h4></a>
<p>The <strong><a
- href="{@docRoot}devices/graphics.html">Graphics introduction</a></strong> and <strong><a
- href="{@docRoot}devices/graphics/implement.html">implementation
- instructions</a></strong> have been revised in entirety.</p>
+ 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>
<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/drm.html">
- <h4>DRM page rewritten</h4></a>
- <p>The description of the Android <strong><a
- href="{@docRoot}devices/drm.html">DRM</a></strong> framework has been
- completely rewritten and expanded.</p>
+<a href="{@docRoot}devices/tech/security/index.html">
+ <h4>Encryption and SELinux revised</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>
-<a href="{@docRoot}devices/tuning.html">
- <h4>Performance tuning property removed</h4></a>
- <p>The <code>ro.hwui.fbo_cache_size</code> property has been removed
- from Android and the corresponding <strong><a
-href="{@docRoot}devices/tuning.html">Performance tuning</a></strong> list.</p>
+<a href="{@docRoot}devices/sensors/index.html">
+ <h4>Sensors and Power rewritten</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}compatibility/cts-intro.html">
- <h4>Compatibility Test Suite manual revised</h4></a>
+<a href="{@docRoot}devices/tv/index.html">
+ <h4>TV Input Framework and more come to Android</h4></a>
<p>The <strong><a
- href="{@docRoot}compatibility/android-cts-manual.pdf">Compatibility Test Suite
- (CTS) manual</a></strong> has been revised with additional details regarding location
- settings and more.</p>
+ 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}source/known-issues.html">
- <h4>Known issues refined</h4></a>
- <p>The list of <strong><a
- href="{@docRoot}source/known-issues.html">Known Issues</a></strong>
- has been updated and split into categories.</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>
</div>
<div class="col-8">
diff --git a/src/source/brands.jd b/src/source/brands.jd
index dfb3cb1..c345c02 100644
--- a/src/source/brands.jd
+++ b/src/source/brands.jd
@@ -128,5 +128,6 @@
<h2 id="Questions">Questions</h2>
<p>For additional brand usage information, please contact our Android Partner
-Marketing team at <a
-href="mailto:android-brand-approvals@google.com">android-brand-approvals@google.com</a>.</p>
+Marketing team by submitting the <a
+href="https://support.google.com/googleplay/contact/brand_developer">Partner
+Brand Inquiry Form</a>.</p>
diff --git a/src/source/build-numbers.jd b/src/source/build-numbers.jd
index c14ae13..eea5f48 100644
--- a/src/source/build-numbers.jd
+++ b/src/source/build-numbers.jd
@@ -135,6 +135,11 @@
<td>4.4 - 4.4.4</td>
<td>API level 19</td>
</tr>
+<tr>
+<td>Lollipop</td>
+<td>5.0</td>
+<td>API level 21</td>
+</tr>
</tbody>
</table>
<p>Starting with Cupcake, individual builds are identified with a short
@@ -168,6 +173,18 @@
<th>Supported devices</th>
</tr>
<tr>
+ <td>LRX21M</td>
+ <td>android-5.0.0_r2</td>
+ <td>Lollipop</td>
+ <td>Nexus Player (fugu)</td>
+</tr>
+<tr>
+ <td>LRX21L</td>
+ <td>android-5.0.0_r1</td>
+ <td>Lollipop</td>
+ <td>Nexus 9 (volantis)</td>
+</tr>
+<tr>
<td>KTU84Q</td>
<td>android-4.4.4_r2</td>
<td>KitKat</td>
diff --git a/src/source/code-lines.jd b/src/source/code-lines.jd
index 59da8bd..f277019 100644
--- a/src/source/code-lines.jd
+++ b/src/source/code-lines.jd
@@ -91,7 +91,7 @@
<p>
An <em>upstream</em> project is an open-source project from which the Android stack is
pulling code. These include obvious projects such as the Linux kernel and WebKit.
- Over time we are migrating some of the semi-autonomous Android projects (such as Dalvik,
+ Over time we are migrating some of the semi-autonomous Android projects (such as ART,
the Android SDK tools, Bionic, and so on) to work as "upstream" projects. Generally,
these projects are developed entirely in the public tree. For some upstream projects,
development is done by contributing directly to the upstream project itself. See <a href=
diff --git a/src/source/faqs.jd b/src/source/faqs.jd
index 58a9a21..346ad98 100644
--- a/src/source/faqs.jd
+++ b/src/source/faqs.jd
@@ -169,7 +169,7 @@
able to accept. For instance, someone might want to contribute an
alternative application API, such as a full C++-based environment. We would
decline that contribution, since Android encourages applications to be run
-in the Dalvik VM. Similarly, we won't accept contributions such as GPL
+in the ART runtime. Similarly, we won't accept contributions such as GPL
or LGPL libraries that are incompatible with our licensing goals.</p>
<p>We encourage those interested in contributing source code to contact us
via the channels listed on the <a href="{@docRoot}source/community/index.html">
diff --git a/src/source/report-bugs.jd b/src/source/report-bugs.jd
index 300df54..e0fcae9 100644
--- a/src/source/report-bugs.jd
+++ b/src/source/report-bugs.jd
@@ -93,7 +93,7 @@
See above.
</blockquote>
<p>This is a poor bug report because it doesn't provide any context for the
-issue; is it a problem in the Dalvik virtual machine, the core framework, or
+issue; is it a problem in the ART runtime, the core framework, or
something else? It also doesn't provide any code or hint on how to reproduce
it. In other words, this bug report doesn't provide enough information for
anyone to take action on, so it would be ignored.</p>
