Merge "Docs: Adding new audio-related diagrams and cropped photos"
diff --git a/README b/README
index 08a3bdf..77a76b8 100644
--- a/README
+++ b/README
@@ -58,7 +58,7 @@
3. Edit the Javadoc file(s) and save your changes.
-4. If a page was added or removed, update the corresponding *.toc.cs file to
+4. If a page was added or removed, update the corresponding _toc.cs file to
reflect the change.
5. Run the following make command from the root of the project parent directory:
diff --git a/src/app.yaml b/src/app.yaml
index c21e1ed..1fdcdda 100644
--- a/src/app.yaml
+++ b/src/app.yaml
@@ -1,7 +1,8 @@
application: google.com:sourceandroid-staging
version: 1
-runtime: python
+runtime: python27
api_version: 1
+threadsafe: true
handlers:
# re-direct to index.html if no path is given
diff --git a/src/devices/audio/latency.jd b/src/devices/audio/latency.jd
index 9d381e5..d4b46a6 100644
--- a/src/devices/audio/latency.jd
+++ b/src/devices/audio/latency.jd
@@ -16,198 +16,34 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<div id="qv-wrapper">
- <div id="qv">
- <h2>In this document</h2>
- <ol id="auto-toc">
- </ol>
- </div>
-</div>
-
<p>Audio latency is the time delay as an audio signal passes through a system.
- For a complete description of audio latency for the purposes of Android
- compatibility, see <em>Section 5.5 Audio Latency</em>
- in the <a href="{@docRoot}compatibility/index.html">Android CDD</a>.
- See <a href="latency_design.html">Design For Reduced Latency</a> for an
- understanding of Android's audio latency-reduction efforts.
</p>
-<p>
- This page focuses on the contributors to output latency,
- but a similar discussion applies to input latency.
-</p>
-<p>
- Assuming the analog circuitry does not contribute significantly, then the major
- surface-level contributors to audio latency are the following:
-</p>
+<h3 id="resources">Resources</h3>
-<ul>
- <li>Application</li>
- <li>Total number of buffers in pipeline</li>
- <li>Size of each buffer, in frames</li>
- <li>Additional latency after the app processor, such as from a DSP</li>
-</ul>
-
-<p>
- As accurate as the above list of contributors may be, it is also misleading.
- The reason is that buffer count and buffer size are more of an
- <em>effect</em> than a <em>cause</em>. What usually happens is that
- a given buffer scheme is implemented and tested, but during testing, an audio
- underrun or overrun is heard as a "click" or "pop." To compensate, the
- system designer then increases buffer sizes or buffer counts.
- This has the desired result of eliminating the underruns or overruns, but it also
- has the undesired side effect of increasing latency.
-</p>
-
-<p>
- A better approach is to understand the causes of the
- underruns and overruns, and then correct those. This eliminates the
- audible artifacts and may permit even smaller or fewer buffers
- and thus reduce latency.
-</p>
-
-<p>
- In our experience, the most common causes of underruns and overruns include:
-</p>
-<ul>
- <li>Linux CFS (Completely Fair Scheduler)</li>
- <li>high-priority threads with SCHED_FIFO scheduling</li>
- <li>long scheduling latency</li>
- <li>long-running interrupt handlers</li>
- <li>long interrupt disable time</li>
- <li>power management</li>
- <li>security kernels</li>
-</ul>
-
-<h3 id="linuxCfs">Linux CFS and SCHED_FIFO scheduling</h3>
-<p>
- The Linux CFS is designed to be fair to competing workloads sharing a common CPU
- resource. This fairness is represented by a per-thread <em>nice</em> parameter.
- The nice value ranges from -19 (least nice, or most CPU time allocated)
- to 20 (nicest, or least CPU time allocated). In general, all threads with a given
- nice value receive approximately equal CPU time and threads with a
- numerically lower nice value should expect to
- receive more CPU time. However, CFS is "fair" only over relatively long
- periods of observation. Over short-term observation windows,
- CFS may allocate the CPU resource in unexpected ways. For example, it
- may take the CPU away from a thread with numerically low niceness
- onto a thread with a numerically high niceness. In the case of audio,
- this can result in an underrun or overrun.
-</p>
-
-<p>
- The obvious solution is to avoid CFS for high-performance audio
- threads. Beginning with Android 4.1, such threads now use the
- <code>SCHED_FIFO</code> scheduling policy rather than the <code>SCHED_NORMAL</code> (also called
- <code>SCHED_OTHER</code>) scheduling policy implemented by CFS.
-</p>
-
-<h3 id="schedFifo">SCHED_FIFO priorities</h3>
-<p>
- Though the high-performance audio threads now use <code>SCHED_FIFO</code>, they
- are still susceptible to other higher priority <code>SCHED_FIFO</code> threads.
- These are typically kernel worker threads, but there may also be a few
- non-audio user threads with policy <code>SCHED_FIFO</code>. The available <code>SCHED_FIFO</code>
- priorities range from 1 to 99. The audio threads run at priority
- 2 or 3. This leaves priority 1 available for lower priority threads,
- and priorities 4 to 99 for higher priority threads. We recommend
- you use priority 1 whenever possible, and reserve priorities 4 to 99 for
- those threads that are guaranteed to complete within a bounded amount
- of time, execute with a period shorter than the period of audio threads,
- and are known to not interfere with scheduling of audio threads.
-</p>
-
-<h3 id="rms">Rate-monotonic scheduling</h3>
-<p>
- For more information on the theory of assignment of fixed priorities,
- see the Wikipedia article
- <a href="http://en.wikipedia.org/wiki/Rate-monotonic_scheduling">Rate-monotonic scheduling</a> (RMS).
- A key point is that fixed priorities should be allocated strictly based on period,
- with higher priorities assigned to threads of shorter periods, not based on perceived "importance."
- Non-periodic threads may be modeled as periodic threads, using the maximum frequency of execution
- and maximum computation per execution. If a non-periodic thread cannot be modeled as
- a periodic thread (for example it could execute with unbounded frequency or unbounded computation
- per execution), then it should not be assigned a fixed priority as that would be incompatible
- with the scheduling of true periodic threads.
-</p>
-
-<h3 id="schedLatency">Scheduling latency</h3>
-<p>
- Scheduling latency is the time between when a thread becomes
- ready to run, and when the resulting context switch completes so that the
- thread actually runs on a CPU. The shorter the latency the better, and
- anything over two milliseconds causes problems for audio. Long scheduling
- latency is most likely to occur during mode transitions, such as
- bringing up or shutting down a CPU, switching between a security kernel
- and the normal kernel, switching from full power to low-power mode,
- or adjusting the CPU clock frequency and voltage.
-</p>
-
-<h3 id="interrupts">Interrupts</h3>
-<p>
- In many designs, CPU 0 services all external interrupts. So a
- long-running interrupt handler may delay other interrupts, in particular
- audio direct memory access (DMA) completion interrupts. Design interrupt handlers
- to finish quickly and defer lengthy work to a thread (preferably
- a CFS thread or <code>SCHED_FIFO</code> thread of priority 1).
-</p>
-
-<p>
- Equivalently, disabling interrupts on CPU 0 for a long period
- has the same result of delaying the servicing of audio interrupts.
- Long interrupt disable times typically happen while waiting for a kernel
- <i>spin lock</i>. Review these spin locks to ensure that
- they are bounded.
-</p>
-
-<h3 id="power">Power, performance, and thermal management</h3>
-<p>
- <a href="http://en.wikipedia.org/wiki/Power_management">Power management</a>
- is a broad term that encompasses efforts to monitor
- and reduce power consumption while optimizing performance.
- <a href="http://en.wikipedia.org/wiki/Thermal_management_of_electronic_devices_and_systems">Thermal management</a>
- and <a href="http://en.wikipedia.org/wiki/Computer_cooling">computer cooling</a>
- are similar but seek to measure and control heat to avoid damage due to excess heat.
- In the Linux kernel, the CPU
- <a href="http://en.wikipedia.org/wiki/Governor_%28device%29">governor</a>
- is responsible for low-level policy, while user mode configures high-level policy.
- Techniques used include:
-</p>
-
-<ul>
- <li>dynamic voltage scaling</li>
- <li>dynamic frequency scaling</li>
- <li>dynamic core enabling</li>
- <li>cluster switching</li>
- <li>power gating</li>
- <li>hotplug (hotswap)</li>
- <li>various sleep modes (halt, stop, idle, suspend, etc.)</li>
- <li>process migration</li>
- <li><a href="http://en.wikipedia.org/wiki/Processor_affinity">processor affinity</a></li>
-</ul>
-
-<p>
- Some management operations can result in "work stoppages" or
- times during which there is no useful work performed by the application processor.
- These work stoppages can interfere with audio, so such management should be designed
- for an acceptable worst-case work stoppage while audio is active.
- Of course, when thermal runaway is imminent, avoiding permanent damage
- is more important than audio!
-</p>
-
-<h3 id="security">Security kernels</h3>
-<p>
- A <a href="http://en.wikipedia.org/wiki/Security_kernel">security kernel</a> for
- <a href="http://en.wikipedia.org/wiki/Digital_rights_management">Digital rights management</a>
- (DRM) may run on the same application processor core(s) as those used
- for the main operating system kernel and application code. Any time
- during which a security kernel operation is active on a core is effectively a
- stoppage of ordinary work that would normally run on that core.
- In particular, this may include audio work. By its nature, the internal
- behavior of a security kernel is inscrutable from higher-level layers, and thus
- any performance anomalies caused by a security kernel are especially
- pernicious. For example, security kernel operations do not typically appear in
- context switch traces. We call this "dark time" — time that elapses
- yet cannot be observed. Security kernels should be designed for an
- acceptable worst-case work stoppage while audio is active.
-</p>
+<table>
+<tr>
+ <th>Topic</th>
+ <th>Links</th>
+</tr>
+<tr>
+ <td>Description of audio latency for purposes of Android compatibility</td>
+ <td><a href="{@docRoot}compatibility/android-cdd.pdf">Android CDD</a><br /><em>section 5.5 Audio Latency</em></td>
+</tr>
+<tr>
+ <td>Common causes of audio latency</td>
+ <td><a href="latency_contrib.html">Contributors to Audio Latency</a></td>
+</tr>
+<tr>
+ <td>Android's audio latency-reduction efforts</td>
+ <td><a href="latency_design.html">Design For Reduced Latency</a></td>
+</tr>
+<tr>
+ <td>Techniques to measure audio latency</td>
+ <td>
+ <a href="latency_measure.html">Measuring Audio Latency</a><br />
+ <a href="testing_circuit.html">Light Testing Circuit</a><br />
+ <a href="loopback.html">Audio Loopback Dongle</a>
+ </td>
+</tr>
+</table>
diff --git a/src/devices/audio/latency_contrib.jd b/src/devices/audio/latency_contrib.jd
new file mode 100644
index 0000000..fb7cd71
--- /dev/null
+++ b/src/devices/audio/latency_contrib.jd
@@ -0,0 +1,204 @@
+page.title=Contributors to Audio Latency
+@jd:body
+
+<!--
+ Copyright 2013 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>
+ This page focuses on the contributors to output latency,
+ but a similar discussion applies to input latency.
+</p>
+<p>
+ Assuming the analog circuitry does not contribute significantly, then the major
+ surface-level contributors to audio latency are the following:
+</p>
+
+<ul>
+ <li>Application</li>
+ <li>Total number of buffers in pipeline</li>
+ <li>Size of each buffer, in frames</li>
+ <li>Additional latency after the app processor, such as from a DSP</li>
+</ul>
+
+<p>
+ As accurate as the above list of contributors may be, it is also misleading.
+ The reason is that buffer count and buffer size are more of an
+ <em>effect</em> than a <em>cause</em>. What usually happens is that
+ a given buffer scheme is implemented and tested, but during testing, an audio
+ underrun or overrun is heard as a "click" or "pop." To compensate, the
+ system designer then increases buffer sizes or buffer counts.
+ This has the desired result of eliminating the underruns or overruns, but it also
+ has the undesired side effect of increasing latency.
+</p>
+
+<p>
+ A better approach is to understand the causes of the
+ underruns and overruns, and then correct those. This eliminates the
+ audible artifacts and may permit even smaller or fewer buffers
+ and thus reduce latency.
+</p>
+
+<p>
+ In our experience, the most common causes of underruns and overruns include:
+</p>
+<ul>
+ <li>Linux CFS (Completely Fair Scheduler)</li>
+ <li>high-priority threads with SCHED_FIFO scheduling</li>
+ <li>long scheduling latency</li>
+ <li>long-running interrupt handlers</li>
+ <li>long interrupt disable time</li>
+ <li>power management</li>
+ <li>security kernels</li>
+</ul>
+
+<h3 id="linuxCfs">Linux CFS and SCHED_FIFO scheduling</h3>
+<p>
+ The Linux CFS is designed to be fair to competing workloads sharing a common CPU
+ resource. This fairness is represented by a per-thread <em>nice</em> parameter.
+ The nice value ranges from -19 (least nice, or most CPU time allocated)
+ to 20 (nicest, or least CPU time allocated). In general, all threads with a given
+ nice value receive approximately equal CPU time and threads with a
+ numerically lower nice value should expect to
+ receive more CPU time. However, CFS is "fair" only over relatively long
+ periods of observation. Over short-term observation windows,
+ CFS may allocate the CPU resource in unexpected ways. For example, it
+ may take the CPU away from a thread with numerically low niceness
+ onto a thread with a numerically high niceness. In the case of audio,
+ this can result in an underrun or overrun.
+</p>
+
+<p>
+ The obvious solution is to avoid CFS for high-performance audio
+ threads. Beginning with Android 4.1, such threads now use the
+ <code>SCHED_FIFO</code> scheduling policy rather than the <code>SCHED_NORMAL</code> (also called
+ <code>SCHED_OTHER</code>) scheduling policy implemented by CFS.
+</p>
+
+<h3 id="schedFifo">SCHED_FIFO priorities</h3>
+<p>
+ Though the high-performance audio threads now use <code>SCHED_FIFO</code>, they
+ are still susceptible to other higher priority <code>SCHED_FIFO</code> threads.
+ These are typically kernel worker threads, but there may also be a few
+ non-audio user threads with policy <code>SCHED_FIFO</code>. The available <code>SCHED_FIFO</code>
+ priorities range from 1 to 99. The audio threads run at priority
+ 2 or 3. This leaves priority 1 available for lower priority threads,
+ and priorities 4 to 99 for higher priority threads. We recommend
+ you use priority 1 whenever possible, and reserve priorities 4 to 99 for
+ those threads that are guaranteed to complete within a bounded amount
+ of time, execute with a period shorter than the period of audio threads,
+ and are known to not interfere with scheduling of audio threads.
+</p>
+
+<h3 id="rms">Rate-monotonic scheduling</h3>
+<p>
+ For more information on the theory of assignment of fixed priorities,
+ see the Wikipedia article
+ <a href="http://en.wikipedia.org/wiki/Rate-monotonic_scheduling">Rate-monotonic scheduling</a> (RMS).
+ A key point is that fixed priorities should be allocated strictly based on period,
+ with higher priorities assigned to threads of shorter periods, not based on perceived "importance."
+ Non-periodic threads may be modeled as periodic threads, using the maximum frequency of execution
+ and maximum computation per execution. If a non-periodic thread cannot be modeled as
+ a periodic thread (for example it could execute with unbounded frequency or unbounded computation
+ per execution), then it should not be assigned a fixed priority as that would be incompatible
+ with the scheduling of true periodic threads.
+</p>
+
+<h3 id="schedLatency">Scheduling latency</h3>
+<p>
+ Scheduling latency is the time between when a thread becomes
+ ready to run and when the resulting context switch completes so that the
+ thread actually runs on a CPU. The shorter the latency the better, and
+ anything over two milliseconds causes problems for audio. Long scheduling
+ latency is most likely to occur during mode transitions, such as
+ bringing up or shutting down a CPU, switching between a security kernel
+ and the normal kernel, switching from full power to low-power mode,
+ or adjusting the CPU clock frequency and voltage.
+</p>
+
+<h3 id="interrupts">Interrupts</h3>
+<p>
+ In many designs, CPU 0 services all external interrupts. So a
+ long-running interrupt handler may delay other interrupts, in particular
+ audio direct memory access (DMA) completion interrupts. Design interrupt handlers
+ to finish quickly and defer lengthy work to a thread (preferably
+ a CFS thread or <code>SCHED_FIFO</code> thread of priority 1).
+</p>
+
+<p>
+ Equivalently, disabling interrupts on CPU 0 for a long period
+ has the same result of delaying the servicing of audio interrupts.
+ Long interrupt disable times typically happen while waiting for a kernel
+ <i>spin lock</i>. Review these spin locks to ensure they are bounded.
+</p>
+
+<h3 id="power">Power, performance, and thermal management</h3>
+<p>
+ <a href="http://en.wikipedia.org/wiki/Power_management">Power management</a>
+ is a broad term that encompasses efforts to monitor
+ and reduce power consumption while optimizing performance.
+ <a href="http://en.wikipedia.org/wiki/Thermal_management_of_electronic_devices_and_systems">Thermal management</a>
+ and <a href="http://en.wikipedia.org/wiki/Computer_cooling">computer cooling</a>
+ are similar but seek to measure and control heat to avoid damage due to excess heat.
+ In the Linux kernel, the CPU
+ <a href="http://en.wikipedia.org/wiki/Governor_%28device%29">governor</a>
+ is responsible for low-level policy, while user mode configures high-level policy.
+ Techniques used include:
+</p>
+
+<ul>
+ <li>dynamic voltage scaling</li>
+ <li>dynamic frequency scaling</li>
+ <li>dynamic core enabling</li>
+ <li>cluster switching</li>
+ <li>power gating</li>
+ <li>hotplug (hotswap)</li>
+ <li>various sleep modes (halt, stop, idle, suspend, etc.)</li>
+ <li>process migration</li>
+ <li><a href="http://en.wikipedia.org/wiki/Processor_affinity">processor affinity</a></li>
+</ul>
+
+<p>
+ Some management operations can result in "work stoppages" or
+ times during which there is no useful work performed by the application processor.
+ These work stoppages can interfere with audio, so such management should be designed
+ for an acceptable worst-case work stoppage while audio is active.
+ Of course, when thermal runaway is imminent, avoiding permanent damage
+ is more important than audio!
+</p>
+
+<h3 id="security">Security kernels</h3>
+<p>
+ A <a href="http://en.wikipedia.org/wiki/Security_kernel">security kernel</a> for
+ <a href="http://en.wikipedia.org/wiki/Digital_rights_management">Digital rights management</a>
+ (DRM) may run on the same application processor core(s) as those used
+ for the main operating system kernel and application code. Any time
+ during which a security kernel operation is active on a core is effectively a
+ stoppage of ordinary work that would normally run on that core.
+ In particular, this may include audio work. By its nature, the internal
+ behavior of a security kernel is inscrutable from higher-level layers, and thus
+ any performance anomalies caused by a security kernel are especially
+ pernicious. For example, security kernel operations do not typically appear in
+ context switch traces. We call this "dark time" — time that elapses
+ yet cannot be observed. Security kernels should be designed for an
+ acceptable worst-case work stoppage while audio is active.
+</p>
diff --git a/src/devices/audio/latency_measure.jd b/src/devices/audio/latency_measure.jd
index 411e048..f6b1d3e 100644
--- a/src/devices/audio/latency_measure.jd
+++ b/src/devices/audio/latency_measure.jd
@@ -1,4 +1,4 @@
-page.title=Audio Latency
+page.title=Measuring Audio Latency
@jd:body
<!--
diff --git a/src/devices/bluetooth.jd b/src/devices/bluetooth.jd
index 13eb4b5..8677b7d 100644
--- a/src/devices/bluetooth.jd
+++ b/src/devices/bluetooth.jd
@@ -31,7 +31,7 @@
<p>To fully leverage the <a href="http://developer.android.com/about/versions/android-5.0.html#BluetoothBroadcasting">Bluetooth Low Energy APIs</a> added in Android 5.0, you should implement the <a href="Android-5.0-Bluetooth-HCI-Reqs.pdf">Android 5.0 Bluetooth HCI Requirements</a>.</p>
<h2 id="architecture">Architecture</h2>
-<p>A Bluetooth system service communicates with the Bluetooth stack through JNI and with applications through Binder IPC. The system service provides developers access to various Bluetooth profiles. The following diagram shows the general structure of the Bluetooth stack:
+<p>A Bluetooth system service communicates with the Bluetooth stack through JNI and with applications through Binder IPC. The system service provides developers access to various Bluetooth profiles. The following diagram shows the general structure of the Bluetooth stack:
</p>
<img src="images/ape_fwk_bluetooth.png" alt="Android Bluetooth architecture" id="figure1" />
@@ -43,7 +43,7 @@
<dt>Application framework</dt>
<dd>At the application framework level is the app's code, which utilizes the <a
href="http://developer.android.com/reference/android/bluetooth/package-summary.html">android.bluetooth</a>
- APIs to interact with the bluetooth hardware. Internally, this code calls the Bluetooth process through
+ APIs to interact with the Bluetooth hardware. Internally, this code calls the Bluetooth process through
the Binder IPC mechanism.</dd>
<dt>Bluetooth system service</dt>
@@ -61,7 +61,7 @@
<dt>HAL</dt>
<dd>The hardware abstraction layer defines the standard interface that the <a
href="http://developer.android.com/reference/android/bluetooth/package-summary.html">android.bluetooth</a> APIs
- and Bluetooth process calls into and that you must implement to have your bluetooth hardware
+ and Bluetooth process calls into and that you must implement to have your Bluetooth hardware
function correctly. The header files for the Bluetooth HAL is located
in the <code>hardware/libhardware/include/hardware/bluetooth.h</code> and
<code>hardware/libhardware/include/hardware/bt_*.h</code> files.
@@ -82,21 +82,22 @@
<h2 id="implementing">Implementing the HAL</h2>
-<p>The Bluetooth HAL is located in the <code>hardware/libhardware/include/hardware/</code> directory
- and consists of the following header files:
+<p>The Bluetooth HAL is located in the <code>hardware/libhardware/include/hardware/</code> directory. Please see that directory for the <strong>complete set</strong> of files, which include but are not limited to the following:
+</p>
<ul>
- <li><code>bluetooth.h</code>: Contains the HAL for the Bluetooth hardware on the device</li>
- <li><code>bt_av.h</code>: Contains the HAL for the advanced audio profile.</li>
- <li><code>bt_hf.h</code>: Contains the HAL for the handsfree profile.</li>
- <li><code>bt_hh.h</code>: Contains the HAL for the HID host profile</li>
- <li><code>bt_hl.h</code>: Contains the HAL for the health profile</li>
- <li><code>bt_pan.h</code>: Contains the HAL for the pan profile</li>
- <li><code>bt_sock.h</code>: Contains the HAL for the socket profile.</li>
+ <li><code>bluetooth.h</code>: Includes the interface definition for the Bluetooth hardware on the device.</li>
+ <li><code>bt_av.h</code>: Includes the interface definition for the A2DP profile.</li>
+ <li><code>bt_gatt.h</code>, <code>bt_gatt_client.h</code>, and <code>bt_gatt_server.h</code>: These include the interface definition for the GATT profile.</li>
+ <li><code>bt_hf.h</code>: Includes the interface definition for the HFP profile.</li>
+ <li><code>bt_hh.h</code>: Includes the interface definition for the HID host profile.</li>
+ <li><code>bt_hl.h</code>: Includes the interface definition for the HDP profile.</li>
+ <li><code>bt_mce.h</code>: Includes the interface definition for the MAP profile.</li>
+ <li><code>bt_pan.h</code>: Includes the interface definition for the PAN profile.</li>
+ <li><code>bt_rc.h</code>: Includes the interface definition for the AVRCP profile.</li>
+ <li><code>bt_sock.h</code>: Includes the interface definition for RFCOMM sockets.</li>
</ul>
-</p>
-
<p>Keep in mind that your Bluetooth implementation is not constrained to the features
and profiles exposed in the HAL. You can find the default implementation located
in the BlueDroid Bluetooth stack in the <code>external/bluetooth/bluedroid</code> directory,
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index b82c4ad..35ef3b4 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -1,5 +1,5 @@
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -15,9 +15,7 @@
-->
<?cs # Table of contents for devices.?>
<ul id="nav">
-
-<!-- Porting Android -->
- <li class="nav-section">
+ <li class="nav-section"> <!-- Begin nav section, Device Interfaces -->
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/index.html">
<span class="en">Interfaces</span>
@@ -42,10 +40,11 @@
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/audio/latency_measure.html">Measure</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/latency_contrib.html">Contributors</a></li>
<li><a href="<?cs var:toroot ?>devices/audio/latency_design.html">Design</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/latency_measure.html">Measure</a></li>
<li><a href="<?cs var:toroot ?>devices/audio/testing_circuit.html">Light Testing Circuit</a></li>
- <li><a href="<?cs var:toroot ?>devices/audio/loopback.html">Loopback Audio Dongle</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/loopback.html">Audio Loopback Dongle</a></li>
</ul>
</li>
<li><a href="<?cs var:toroot ?>devices/audio/avoiding_pi.html">Priority Inversion</a></li>
@@ -110,8 +109,7 @@
<li><a href="<?cs var:toroot ?>devices/graphics/cts-integration.html">Integrating with Android CTS</a></li>
</ul>
</li>
- </ul>
- </li>
+ </ul> </li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/input/index.html">
@@ -126,65 +124,29 @@
<li><a href="<?cs var:toroot ?>devices/input/migration-guide.html">Migration Guide</a></li>
<li><a href="<?cs var:toroot ?>devices/input/keyboard-devices.html">Keyboard Devices</a></li>
<li><a href="<?cs var:toroot ?>devices/input/touch-devices.html">Touch Devices</a></li>
- <li><a href="<?cs var:toroot ?>devices/input/dumpsys.html">Dumpsys</a></li>
+ <li><a href="<?cs var:toroot ?>devices/input/diagnostics.html">Diagnostics</a></li>
<li><a href="<?cs var:toroot ?>devices/input/getevent.html">Getevent</a></li>
<li><a href="<?cs var:toroot ?>devices/input/validate-keymaps.html">Validate Keymaps</a></li>
</ul>
</li>
<li><a href="<?cs var:toroot ?>devices/media.html">Media</a></li>
- <li class="nav-section">
- <div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/sensors/index.html">
- <span class="en">Sensors</span>
- </a>
- </div>
- <ul>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/sensor-stack.html">
- <span class="en">Sensor stack</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/report-modes.html">
- <span class="en">Reporting modes</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/suspend-mode.html">
- <span class="en">Suspend mode</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/power-use.html">
- <span class="en">Power consumption</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/interaction.html">
- <span class="en">Interaction</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/hal-interface.html">
- <span class="en">HAL interface</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/batching.html">
- <span class="en">Batching</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/sensor-types.html">
- <span class="en">Sensor types</span>
- </a>
- </li>
- <li>
- <a href="<?cs var:toroot ?>devices/sensors/versioning.html">
- <span class="en">Version deprecation</span>
- </a>
- </li>
- </ul>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/sensors/index.html">
+ <span class="en">Sensors</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/sensors/sensor-stack.html">Sensor stack</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/report-modes.html">Reporting modes</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/suspend-mode.html">Suspend mode</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/power-use.html">Power consumption</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/interaction.html">Interaction</span></a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/hal-interface.html">HAL interface</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/batching.html">Batching</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/sensor-types.html">Sensor types</a></li>
+ <li><a href="<?cs var:toroot ?>devices/sensors/versioning.html">Version deprecation</a></li>
+ </ul>
</li>
<li class="nav-section">
<div class="nav-section-header">
@@ -196,14 +158,11 @@
<li><a href="<?cs var:toroot ?>devices/tv/HDMI-CEC.html">HDMI-CEC control service</a></li>
</ul>
</li>
-
</ul>
- </li>
-<!-- End Porting Android -->
- </li>
+ </li> <!-- End nav-section, Device Interfaces-->
- <li class="nav-section">
+ <li class="nav-section"> <!--Begin nav-section, Core Technologies-->
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/index.html">
<span class="en">Core Technologies</span>
@@ -250,6 +209,7 @@
<ul>
<li><a href="<?cs var:toroot ?>devices/tech/debug/tuning.html">Performance Tuning</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/debug/native-memory.html">Native Memory Usage</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/debug/dumpsys.html">Dumpsys</a></li>
</ul>
</li>
@@ -261,31 +221,33 @@
</div>
</li>
- <li>
- <a href="<?cs var:toroot ?>devices/tech/kernel.html">
- <span class="en">Kernel</span>
- </a>
- </li>
+ <li><a href="<?cs var:toroot ?>devices/tech/kernel.html">Kernel</a></li>
- <li>
- <a href="<?cs var:toroot ?>devices/tech/low-ram.html">
- <span class="en">Low RAM</span>
- </a>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tech/ram/index.html">
+ <span class="en">RAM</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/ram/low-ram.html">Low RAM</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/ram/procstats.html">Viewing RAM Usage Data</a></li>
+ </ul>
</li>
<li class="nav-section">
- <div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/tech/ota/index.html">
- <span class="en">OTA Updates</span>
- </a>
- </div>
- <ul>
- <li><a href="<?cs var:toroot ?>devices/tech/ota/tools.html">OTA Tools</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/ota/block.html">Block-based OTA</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/ota/inside_packages.html">Inside OTA Packages</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/ota/device_code.html">Device-Specific Code</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/ota/sign_builds.html">Signing Builds for Release</a></li>
- </ul>
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tech/ota/index.html">
+ <span class="en">OTA Updates</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/ota/tools.html">OTA Tools</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/ota/block.html">Block-based OTA</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/ota/inside_packages.html">Inside OTA Packages</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/ota/device_code.html">Device-Specific Code</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/ota/sign_builds.html">Signing Builds for Release</a></li>
+ </ul>
</li>
<li>
@@ -293,14 +255,14 @@
<span class="en">Power</span>
</a>
</li>
- <li class="nav-section">
- <div class="nav-section-header">
+ <li class="nav-section">
+ <div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/security/index.html">
<span class="en">Security</span>
</a>
- </div>
+ </div>
<ul>
- <li class="nav-section">
+ <li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/security/overview/index.html">
<span class="en">Overview</span>
@@ -310,62 +272,58 @@
<li><a href="<?cs var:toroot ?>devices/tech/security/overview/kernel-security.html">Kernel security</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/security/overview/app-security.html">App security</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/security/overview/updates-resources.html">Updates and resources</a></li>
- <li class="nav-section">
- <div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/tech/security/enhancements/index.html">
- <span class="en">Enhancements</span>
- </a>
- </div>
- <ul>
- <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements50.html">Android 5.0</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements44.html">Android 4.4</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements43.html">Android 4.3</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements42.html">Android 4.2</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements41.html">Android 4.1</a></li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tech/security/enhancements/index.html">
+ <span class="en">Enhancements</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements50.html">Android 5.0</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements44.html">Android 4.4</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements43.html">Android 4.3</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements42.html">Android 4.2</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/enhancements/enhancements41.html">Android 4.1</a></li>
+ </ul>
+ </li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/overview/acknowledgements.html">Acknowledgements</a></li>
</ul>
</li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/overview/acknowledgements.html">Acknowledgements</a></li>
- </ul>
- </li>
- <li class="nav-section">
+ <li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/security/implement.html">
<span class="en">Implementation</span>
</a>
</div>
<ul>
- <li>
- <a href="<?cs var:toroot ?>devices/tech/security/encryption/index.html">
- <span class="en">Encryption</span>
- </a>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/encryption/index.html">Encryption</a></li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tech/security/verifiedboot/index.html">
+ <span class="en">Verified Boot</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/verifiedboot/verified-boot.html">Verifying boot</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/verifiedboot/dm-verity.html">Implementing dm-verity</a></li>
+ </ul>
+ </li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tech/security/selinux/index.html">
+ <span class="en">Security-Enhanced Linux</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/concepts.html">Concepts</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/implement.html">Implementation</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/customize.html">Customization</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/validate.html">Validation</a></li>
+ </ul>
</li>
- <li class="nav-section">
- <div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/tech/security/verifiedboot/index.html">
- <span class="en">Verified Boot</span>
- </a>
- </div>
- <ul>
- <li><a href="<?cs var:toroot ?>devices/tech/security/verifiedboot/verified-boot.html">Verifying boot</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/verifiedboot/dm-verity.html">Implementing dm-verity</a></li>
- </ul>
- </li>
- <li class="nav-section">
- <div class="nav-section-header">
- <a href="<?cs var:toroot ?>devices/tech/security/selinux/index.html">
- <span class="en">Security-Enhanced Linux</span>
- </a>
- </div>
- <ul>
- <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/concepts.html">Concepts</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/implement.html">Implementation</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/customize.html">Customization</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/security/selinux/validate.html">Validation</a></li>
- </ul>
- </li>
- </ul>
- </li>
- </ul>
+ </ul>
+ </li>
+ </ul>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/index.html">
@@ -373,29 +331,21 @@
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/index.html"
- >Start Here</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/machine_setup.html"
- >Machine Setup</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/devices.html"
- >Working with Devices</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/lifecycle.html"
- >Test Lifecycle</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/options.html"
- >Option Handling</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/full_example.html"
- >An End-to-End Example</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/index.html">Start Here</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/machine_setup.html">Machine Setup</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/devices.html">Working with Devices</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/lifecycle.html">Test Lifecycle</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/options.html">Option Handling</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/full_example.html">An End-to-End Example</a></li>
<li id="tradefed-tree-list" class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>reference/packages.html">
- <span class="en">Package Index</span>
- </a>
- <div>
- </li>
+ <span class="en">Package Index</span>
+ </a>
+ </div>
+ </li>
</ul>
</li>
-
</ul>
- </li>
-
-</ul>
+ </li> <!-- End nav-section, Core Technologies -->
+</ul>
diff --git a/src/devices/input/diagnostics.jd b/src/devices/input/diagnostics.jd
new file mode 100644
index 0000000..0fc7a3e
--- /dev/null
+++ b/src/devices/input/diagnostics.jd
@@ -0,0 +1,490 @@
+page.title=Dumpsys Input Diagnostics
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>The <code>dumpsys</code> input command dumps the state of the
+system’s input devices, such as keyboards and touchscreens, and the
+processing of input events.</p>
+
+<h2 id="input">Input</h2>
+<p>To dump the input system’s state, run the following command:</p>
+<pre>
+$ adb shell dumpsys input
+</pre>
+
+<h2 id="output">Output</h2>
+
+<p>The set of information reported varies depending on the version of Android
+but consists of three sections:</p>
+
+<ul>
+ <li> Event Hub State
+ <li> Input Reader State
+ <li> Input Dispatcher State
+</ul>
+
+<h3 id="event_hub_state">Event Hub State</h3>
+
+<pre><code>
+INPUT MANAGER (dumpsys input)
+
+Event Hub State:
+ BuiltInKeyboardId: -2
+ Devices:
+ -1: Virtual
+ Classes: 0x40000023
+ Path: <virtual>
+ Descriptor: a718a782d34bc767f4689c232d64d527998ea7fd
+ Location:
+ ControllerNumber: 0
+ UniqueId: <virtual>
+ Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
+ KeyLayoutFile: /system/usr/keylayout/Generic.kl
+ KeyCharacterMapFile: /system/usr/keychars/Virtual.kcm
+ ConfigurationFile:
+ HaveKeyboardLayoutOverlay: false
+ 1: msm8974-taiko-mtp-snd-card Headset Jack
+ Classes: 0x00000080
+ Path: /dev/input/event5
+ Descriptor: c8e3782483b4837ead6602e20483c46ff801112c
+ Location: ALSA
+ ControllerNumber: 0
+ UniqueId:
+ Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
+ KeyLayoutFile:
+ KeyCharacterMapFile:
+ ConfigurationFile:
+ HaveKeyboardLayoutOverlay: false
+ 2: msm8974-taiko-mtp-snd-card Button Jack
+ Classes: 0x00000001
+ Path: /dev/input/event4
+ Descriptor: 96fe62b244c555351ec576b282232e787fb42bab
+ Location: ALSA
+ ControllerNumber: 0
+ UniqueId:
+ Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
+ KeyLayoutFile: /system/usr/keylayout/msm8974-taiko-mtp-snd-card_Button_Jack.kl
+ KeyCharacterMapFile: /system/usr/keychars/msm8974-taiko-mtp-snd-card_Button_Jack.kcm
+ ConfigurationFile:
+ HaveKeyboardLayoutOverlay: false
+ 3: hs_detect
+ Classes: 0x00000081
+ Path: /dev/input/event3
+ Descriptor: 485d69228e24f5e46da1598745890b214130dbc4
+ Location:
+ ControllerNumber: 0
+ UniqueId:
+ Identifier: bus=0x0000, vendor=0x0001, product=0x0001, version=0x0001
+ KeyLayoutFile: /system/usr/keylayout/hs_detect.kl
+ KeyCharacterMapFile: /system/usr/keychars/hs_detect.kcm
+ ConfigurationFile:
+ HaveKeyboardLayoutOverlay: false
+ 4: touch_dev
+ Classes: 0x00000014
+ Path: /dev/input/event1
+ Descriptor: 4e2720e99bd2b59adae8529881343531fff7c98e
+ Location:
+ ControllerNumber: 0
+ UniqueId:
+ Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
+ KeyLayoutFile:
+ KeyCharacterMapFile:
+ ConfigurationFile: /system/usr/idc/touch_dev.idc
+ HaveKeyboardLayoutOverlay: false
+ 5: qpnp_pon
+ Classes: 0x00000001
+ Path: /dev/input/event0
+ Descriptor: fb60d4f4370f5dbe8267b63d38dea852987571ab
+ Location: qpnp_pon/input0
+ ControllerNumber: 0
+ UniqueId:
+ Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
+ KeyLayoutFile: /system/usr/keylayout/qpnp_pon.kl
+ KeyCharacterMapFile: /system/usr/keychars/qpnp_pon.kcm
+ ConfigurationFile:
+ HaveKeyboardLayoutOverlay: false
+ 6: gpio-keys
+ Classes: 0x00000081
+ Path: /dev/input/event2
+ Descriptor: d2c52ff0f656fac4cd7b7a118d575e0109a9fe1c
+ Location: gpio-keys/input0
+ ControllerNumber: 0
+ UniqueId:
+ Identifier: bus=0x0019, vendor=0x0001, product=0x0001, version=0x0100
+ KeyLayoutFile: /system/usr/keylayout/gpio-keys.kl
+ KeyCharacterMapFile: /system/usr/keychars/gpio-keys.kcm
+ ConfigurationFile:
+ HaveKeyboardLayoutOverlay: false
+</code></pre>
+
+<h4 id="things-to-look-for">Things to check</h4>
+
+<ul>
+ <li> All of the expected input devices are present.</li>
+
+ <li> Each input device has an appropriate key layout file, key character map
+ file and input device configuration file. If the files are missing or contain
+ syntax errors, then they will not be loaded.</li>
+
+ <li> Each input device is being classified correctly. The bits in the
+ <code>Classes</code> field correspond to flags in <code>EventHub.h</code> such
+ as <code>INPUT_DEVICE_CLASS_TOUCH_MT</code>.</li>
+
+ <li> The <code>BuiltInKeyboardId</code> is correct. If the device does not
+ have a built-in keyboard, then the id must be <code>-2</code>, otherwise it
+ should be the id of the built-in keyboard.</li>
+
+ <li>If you observe that the <code>BuiltInKeyboardId</code> is not
+ <code>-2</code> but it should be, then you are missing a key character map file
+ for a special function keypad somewhere. Special function keypad devices
+ should have key character map files that contain just the line <code>type
+ SPECIAL_FUNCTION</code> (that's what in the <code>tuna-gpio-keykad.kcm</code>
+ file we see mentioned above).</li>
+</ul>
+
+<h3 id="input-reader-state">Input Reader State</h3>
+<p>The <code>InputReader</code> is responsible for decoding input events from the kernel.
+Its state dump shows information about how each input device is configured
+and recent state changes that have occurred, such as key presses or touches on
+the touch screen.</p>
+
+<p>As an example, this is what a special function keypad looks like:</p>
+
+<pre>
+Input Reader State
+...
+ Device 3: tuna-gpio-keypad
+ IsExternal: false
+ Sources: 0x00000101
+ KeyboardType: 1
+ Keyboard Input Mapper:
+ Parameters:
+ AssociatedDisplayId: -1
+ OrientationAware: false
+ KeyboardType: 1
+ Orientation: 0
+ KeyDowns: 0 keys currently down
+ MetaState: 0x0
+ DownTime: 75816923828000
+</pre>
+
+<p>Here is a touch screen. Notice all of the information about the resolution of
+the device and the calibration parameters that were used.</p>
+
+<pre>
+Input Reader State
+...
+ Device 6: Melfas MMSxxx Touchscreen
+ IsExternal: false
+ Sources: 0x00001002
+ KeyboardType: 0
+ Motion Ranges:
+ X: source=0x00001002, min=0.000, max=719.001, flat=0.000, fuzz=0.999
+ Y: source=0x00001002, min=0.000, max=1279.001, flat=0.000, fuzz=0.999
+ PRESSURE: source=0x00001002, min=0.000, max=1.000, flat=0.000, fuzz=0.000
+ SIZE: source=0x00001002, min=0.000, max=1.000, flat=0.000, fuzz=0.000
+ TOUCH_MAJOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000
+ TOUCH_MINOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000
+ TOOL_MAJOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000
+ TOOL_MINOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000
+ Touch Input Mapper:
+ Parameters:
+ GestureMode: spots
+ DeviceType: touchScreen
+ AssociatedDisplay: id=0, isExternal=false
+ OrientationAware: true
+ Raw Touch Axes:
+ X: min=0, max=720, flat=0, fuzz=0, resolution=0
+ Y: min=0, max=1280, flat=0, fuzz=0, resolution=0
+ Pressure: min=0, max=255, flat=0, fuzz=0, resolution=0
+ TouchMajor: min=0, max=30, flat=0, fuzz=0, resolution=0
+ TouchMinor: unknown range
+ ToolMajor: unknown range
+ ToolMinor: unknown range
+ Orientation: unknown range
+ Distance: unknown range
+ TiltX: unknown range
+ TiltY: unknown range
+ TrackingId: min=0, max=65535, flat=0, fuzz=0, resolution=0
+ Slot: min=0, max=9, flat=0, fuzz=0, resolution=0
+ Calibration:
+ touch.size.calibration: diameter
+ touch.size.scale: 10.000
+ touch.size.bias: 0.000
+ touch.size.isSummed: false
+ touch.pressure.calibration: amplitude
+ touch.pressure.scale: 0.005
+ touch.orientation.calibration: none
+ touch.distance.calibration: none
+ SurfaceWidth: 720px
+ SurfaceHeight: 1280px
+ SurfaceOrientation: 0
+ Translation and Scaling Factors:
+ XScale: 0.999
+ YScale: 0.999
+ XPrecision: 1.001
+ YPrecision: 1.001
+ GeometricScale: 0.999
+ PressureScale: 0.005
+ SizeScale: 0.033
+ OrientationCenter: 0.000
+ OrientationScale: 0.000
+ DistanceScale: 0.000
+ HaveTilt: false
+ TiltXCenter: 0.000
+ TiltXScale: 0.000
+ TiltYCenter: 0.000
+ TiltYScale: 0.000
+ Last Button State: 0x00000000
+ Last Raw Touch: pointerCount=0
+ Last Cooked Touch: pointerCount=0
+</pre>
+
+<p>Here is an external keyboard / mouse combo HID device. (This device doesn't actually
+have a mouse but its HID descriptor says it does.)</p>
+
+<pre><code> Device 7: Motorola Bluetooth Wireless Keyboard
+ IsExternal: true
+ Sources: 0x00002103
+ KeyboardType: 2
+ Motion Ranges:
+ X: source=0x00002002, min=0.000, max=719.000, flat=0.000, fuzz=0.000
+ Y: source=0x00002002, min=0.000, max=1279.000, flat=0.000, fuzz=0.000
+ PRESSURE: source=0x00002002, min=0.000, max=1.000, flat=0.000, fuzz=0.000
+ VSCROLL: source=0x00002002, min=-1.000, max=1.000, flat=0.000, fuzz=0.000
+ Keyboard Input Mapper:
+ Parameters:
+ AssociatedDisplayId: -1
+ OrientationAware: false
+ KeyboardType: 2
+ Orientation: 0
+ KeyDowns: 0 keys currently down
+ MetaState: 0x0
+ DownTime: 75868832946000
+ Cursor Input Mapper:
+ Parameters:
+ AssociatedDisplayId: 0
+ Mode: pointer
+ OrientationAware: false
+ XScale: 1.000
+ YScale: 1.000
+ XPrecision: 1.000
+ YPrecision: 1.000
+ HaveVWheel: true
+ HaveHWheel: false
+ VWheelScale: 1.000
+ HWheelScale: 1.000
+ Orientation: 0
+ ButtonState: 0x00000000
+ Down: false
+ DownTime: 0
+</code></pre>
+<p>Here is a joystick. Notice how all of the axes have been scaled to a normalized
+range. The axis mapping can be configured using key layout files.</p>
+<pre><code>Device 18: Logitech Logitech Cordless RumblePad 2
+ IsExternal: true
+ Sources: 0x01000511
+ KeyboardType: 1
+ Motion Ranges:
+ X: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000
+ Y: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000
+ Z: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000
+ RZ: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000
+ HAT_X: source=0x01000010, min=-1.000, max=1.000, flat=0.000, fuzz=0.000
+ HAT_Y: source=0x01000010, min=-1.000, max=1.000, flat=0.000, fuzz=0.000
+ Keyboard Input Mapper:
+ Parameters:
+ AssociatedDisplayId: -1
+ OrientationAware: false
+ KeyboardType: 1
+ Orientation: 0
+ KeyDowns: 0 keys currently down
+ MetaState: 0x0
+ DownTime: 675270841000
+ Joystick Input Mapper:
+ Axes:
+ X: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000
+ scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000
+ rawAxis=0, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0
+ Y: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000
+ scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000
+ rawAxis=1, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0
+ Z: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000
+ scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000
+ rawAxis=2, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0
+ RZ: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000
+ scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000
+ rawAxis=5, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0
+ HAT_X: min=-1.00000, max=1.00000, flat=0.00000, fuzz=0.00000
+ scale=1.00000, offset=0.00000, highScale=1.00000, highOffset=0.00000
+ rawAxis=16, rawMin=-1, rawMax=1, rawFlat=0, rawFuzz=0, rawResolution=0
+ HAT_Y: min=-1.00000, max=1.00000, flat=0.00000, fuzz=0.00000
+ scale=1.00000, offset=0.00000, highScale=1.00000, highOffset=0.00000
+ rawAxis=17, rawMin=-1, rawMax=1, rawFlat=0, rawFuzz=0, rawResolution=0
+</code></pre>
+<p>At the end of the input reader dump there is some information about global configuration
+parameters such as the mouse pointer speed.</p>
+<pre><code> Configuration:
+ ExcludedDeviceNames: []
+ VirtualKeyQuietTime: 0.0ms
+ PointerVelocityControlParameters: scale=1.000, lowThreshold=500.000, highThreshold=3000.000, acceleration=3.000
+ WheelVelocityControlParameters: scale=1.000, lowThreshold=15.000, highThreshold=50.000, acceleration=4.000
+ PointerGesture:
+ Enabled: true
+ QuietInterval: 100.0ms
+ DragMinSwitchSpeed: 50.0px/s
+ TapInterval: 150.0ms
+ TapDragInterval: 300.0ms
+ TapSlop: 20.0px
+ MultitouchSettleInterval: 100.0ms
+ MultitouchMinDistance: 15.0px
+ SwipeTransitionAngleCosine: 0.3
+ SwipeMaxWidthRatio: 0.2
+ MovementSpeedRatio: 0.8
+ ZoomSpeedRatio: 0.3
+</code></pre>
+<h4 id="things-to-look-for_1">Things To Look For</h4>
+<ol>
+<li>
+<p>All of the expected input devices are present.</p>
+</li>
+<li>
+<p>Each input device has been configured appropriately. Especially check the
+ touch screen and joystick axes.</p>
+</li>
+</ol>
+<h3 id="input-dispatcher-state">Input Dispatcher State</h3>
+<p>The <code>InputDispatcher</code> is responsible for sending input events to applications.
+Its state dump shows information about which window is being touched, the
+state of the input queue, whether an ANR is in progress, and so on.</p>
+<pre>
+Input Dispatcher State:
+ DispatchEnabled: 1
+ DispatchFrozen: 0
+ FocusedApplication: <null>
+ FocusedWindow: name='Window{3fb06dc3 u0 StatusBar}'
+ TouchStates: <no displays touched>
+ Windows:
+ 0: name='Window{357bbbfe u0 SearchPanel}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01820100, type=0x000007e8, layer=211000, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms
+ 1: name='Window{3b14c0ca u0 NavigationBar}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01840068, type=0x000007e3, layer=201000, frame=[0,1776][1080,1920], scale=1.000000, touchableRegion=[0,1776][1080,1920], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms
+ 2: name='Window{2c7e849c u0 com.vito.lux}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x0089031a, type=0x000007d6, layer=191000, frame=[-495,-147][1575,1923], scale=1.000000, touchableRegion=[-495,-147][1575,1923], inputFeatures=0x00000000, ownerPid=4697, ownerUid=10084, dispatchingTimeout=5000.000ms
+ 3: name='Window{31c9f22 u0 Heads Up}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01820328, type=0x000007de, layer=161000, frame=[0,0][1794,750], scale=1.000000, touchableRegion=[0,0][1794,192], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms
+ 4: name='Window{3fb06dc3 u0 StatusBar}', displayId=0, paused=false, hasFocus=true, hasWallpaper=false, visible=true, canReceiveKeys=true, flags=0x81960040, type=0x000007d0, layer=151000, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000004, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms
+ 5: name='Window{278c1d65 u0 KeyguardScrim}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01110900, type=0x000007ed, layer=131000, frame=[0,0][1080,1776], scale=1.000000, touchableRegion=[0,0][1080,1776], inputFeatures=0x00000000, ownerPid=745, ownerUid=1000, dispatchingTimeout=5000.000ms
+ 6: name='Window{869f213 u0 com.android.systemui.ImageWallpaper}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x00000318, type=0x000007dd, layer=21025, frame=[0,0][2328,1920], scale=1.000000, touchableRegion=[0,0][2328,1920], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms
+ 7: name='Window{16ab6320 u0 InputMethod}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01800108, type=0x000007db, layer=21020, frame=[0,75][1080,1920], scale=1.000000, touchableRegion=[0,986][1080,1920], inputFeatures=0x00000000, ownerPid=8409, ownerUid=10056, dispatchingTimeout=5000.000ms
+ 8: name='Window{cf4ff0b u0 com.google.android.googlequicksearchbox/com.google.android.launcher.GEL}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x81910120, type=0x00000001, layer=21015, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=14722, ownerUid=10022, dispatchingTimeout=5000.000ms
+ 9: name='Window{1a7be08a u0 com.android.systemui/com.android.systemui.recents.RecentsActivity EXITING}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x81910120, type=0x00000001, layer=21010, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms
+ 10: name='Window{2280455f u0 com.google.android.gm/com.google.android.gm.ConversationListActivityGmail}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x81810120, type=0x00000001, layer=21005, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=9897, ownerUid=10070, dispatchingTimeout=5000.000ms
+ 11: name='Window{657fee5 u0 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01810520, type=0x00000001, layer=21000, frame=[0,0][1080,1776], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=3189, ownerUid=10085, dispatchingTimeout=5000.000ms
+ MonitoringChannels:
+ 0: 'WindowManager (server)'
+ RecentQueue: length=10
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (335.0, 1465.0)]), policyFlags=0x62000000, age=217264.0ms
+ MotionEvent(deviceId=4, source=0x00001002, action=1, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (335.0, 1465.0)]), policyFlags=0x62000000, age=217255.7ms
+ MotionEvent(deviceId=4, source=0x00001002, action=0, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (330.0, 1283.0)]), policyFlags=0x62000000, age=216805.0ms
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (330.0, 1287.0)]), policyFlags=0x62000000, age=216788.3ms
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (331.0, 1297.0)]), policyFlags=0x62000000, age=216780.0ms
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (332.0, 1316.0)]), policyFlags=0x62000000, age=216771.6ms
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (333.0, 1340.0)]), policyFlags=0x62000000, age=216763.3ms
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (333.0, 1362.0)]), policyFlags=0x62000000, age=216755.0ms
+ MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (332.0, 1384.0)]), policyFlags=0x62000000, age=216747.2ms
+ MotionEvent(deviceId=4, source=0x00001002, action=1, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (332.0, 1384.0)]), policyFlags=0x62000000, age=216738.9ms
+ PendingEvent: <none>
+ InboundQueue: <empty>
+ ReplacedKeys: <empty>
+ Connections:
+ 0: channelName='WindowManager (server)', windowName='monitor', status=NORMAL, monitor=true, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 1: channelName='278c1d65 KeyguardScrim (server)', windowName='Window{278c1d65 u0 KeyguardScrim}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 2: channelName='357bbbfe SearchPanel (server)', windowName='Window{357bbbfe u0 SearchPanel}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 3: channelName='869f213 com.android.systemui.ImageWallpaper (server)', windowName='Window{869f213 u0 com.android.systemui.ImageWallpaper}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 4: channelName='3fb06dc3 StatusBar (server)', windowName='Window{3fb06dc3 u0 StatusBar}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 5: channelName='2c7e849c (server)', windowName='Window{2c7e849c u0 com.vito.lux}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 6: channelName='cf4ff0b com.google.android.googlequicksearchbox/com.google.android.launcher.GEL (server)', windowName='Window{cf4ff0b
+u0 com.google.android.googlequicksearchbox/com.google.android.launcher.GEL}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 7: channelName='2280455f com.google.android.gm/com.google.android.gm.ConversationListActivityGmail (server)', windowName='Window{2280455f u0 com.google.android.gm/com.google.android.gm.ConversationListActivityGmail}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 8: channelName='1a7be08a com.android.systemui/com.android.systemui.recents.RecentsActivity (server)', windowName='Window{1a7be08a u0 com.android.systemui/com.android.systemui.recents.RecentsActivity EXITING}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 9: channelName='3b14c0ca NavigationBar (server)', windowName='Window{3b14c0ca u0 NavigationBar}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 10: channelName='16ab6320 InputMethod (server)', windowName='Window{16ab6320 u0 InputMethod}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 11: channelName='657fee5 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell (server)', windowName='Window{657fee5 u0 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 12: channelName='31c9f22 Heads Up (server)', windowName='Window{31c9f22 u0 Heads Up}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ AppSwitch: not pending
+ 7: channelName='2280455f com.google.android.gm/com.google.android.gm.ConversationListActivityGmail (server)', windowName='Window{2280455f u0 com.google.android.gm/com.google.android.gm.ConversationListActivityGmail}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 8: channelName='1a7be08a com.android.systemui/com.android.systemui.recents.RecentsActivity (server)', windowName='Window{1a7be08a u0 com.android.systemui/com.android.systemui.recents.RecentsActivity EXITING}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 9: channelName='3b14c0ca NavigationBar (server)', windowName='Window{3b14c0ca u0 NavigationBar}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 10: channelName='16ab6320 InputMethod (server)', windowName='Window{16ab6320 u0 InputMethod}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 11: channelName='657fee5 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell (server)', windowName='Window{657fee5 u0 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ 12: channelName='31c9f22 Heads Up (server)', windowName='Window{31c9f22 u0 Heads Up}', status=NORMAL, monitor=false, inputPublisherBlocked=false
+ OutboundQueue: <empty>
+ WaitQueue: <empty>
+ AppSwitch: not pending
+ Configuration:
+ KeyRepeatDelay: 50.0ms
+ KeyRepeatTimeout: 500.0ms
+</pre>
+<h4 id="things-to-look-for_2">Things To Look For</h4>
+<ol>
+ <li> In general, all input events are being processed as expected. </li>
+ <li> If you touch the touch screen and run dumpsys at the same time,
+ then the <code>TouchStates</code> line should show the window that
+ you are touching. </li>
+</ol>
+
diff --git a/src/devices/input/dumpsys.jd b/src/devices/input/dumpsys.jd
deleted file mode 100644
index 21ae764..0000000
--- a/src/devices/input/dumpsys.jd
+++ /dev/null
@@ -1,344 +0,0 @@
-page.title=Dumpsys
-@jd:body
-
-<!--
- Copyright 2013 The Android Open Source Project
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-<p>The <code>dumpsys</code> tool runs on the device and dumps interesting information
-about the status of system services.</p>
-<h2 id="usage">Usage</h2>
-<p>The input system is part of the window manager. To dump its state,
-run the following command.</p>
-<pre><code>$ adb shell su -- dumpsys window
-
-WINDOW MANAGER INPUT (dumpsys window input)
-Event Hub State:
- BuiltInKeyboardId: -1
- Devices:
-...
-</code></pre>
-<p>The set of information that is reported varies depending on the version of Android.</p>
-<h3 id="event-hub-state">Event Hub State</h3>
-<p>The <code>EventHub</code> component is responsible for communicating with the kernel device
-drivers and identifying device capabilities. Accordingly, its state shows
-information about how devices are configured.</p>
-<pre><code>Event Hub State:
- BuiltInKeyboardId: -1
- Devices:
- 3: tuna-gpio-keypad
- Classes: 0x00000001
- Path: /dev/input/event2
- Location:
- UniqueId:
- Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
- KeyLayoutFile: /system/usr/keylayout/tuna-gpio-keypad.kl
- KeyCharacterMapFile: /system/usr/keychars/tuna-gpio-keypad.kcm
- ConfigurationFile:
- 5: Tuna Headset Jack
- Classes: 0x00000080
- Path: /dev/input/event5
- Location: ALSA
- UniqueId:
- Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000
- KeyLayoutFile:
- KeyCharacterMapFile:
- ConfigurationFile:
- 6: Melfas MMSxxx Touchscreen
- Classes: 0x00000014
- Path: /dev/input/event1
- Location: 3-0048/input0
- UniqueId:
- Identifier: bus=0x0018, vendor=0x0000, product=0x0000, version=0x0000
- KeyLayoutFile:
- KeyCharacterMapFile:
- ConfigurationFile: /system/usr/idc/Melfas_MMSxxx_Touchscreen.idc
- 7: Motorola Bluetooth Wireless Keyboard
- Classes: 0x8000000b
- Path: /dev/input/event6
- Location: 0C:DF:A4:B3:2D:BA
- UniqueId: 00:0F:F6:80:02:CD
- Identifier: bus=0x0005, vendor=0x22b8, product=0x093d, version=0x0288
- KeyLayoutFile: /system/usr/keylayout/Vendor_22b8_Product_093d.kl
- KeyCharacterMapFile: /system/usr/keychars/Generic.kcm
- ConfigurationFile:
-</code></pre>
-<h4 id="things-to-look-for">Things To Look For</h4>
-<ol>
-<li>
-<p>All of the expected input devices are present.</p>
-</li>
-<li>
-<p>Each input device has an appropriate key layout file, key character map file
- and input device configuration file. If the files are missing or contain
- syntax errors, then they will not be loaded.</p>
-</li>
-<li>
-<p>Each input device is being classified correctly. The bits in the <code>Classes</code>
- field correspond to flags in <code>EventHub.h</code> such as <code>INPUT_DEVICE_CLASS_TOUCH_MT</code>.</p>
-</li>
-<li>
-<p>The <code>BuiltInKeyboardId</code> is correct. If the device does not have a built-in keyboard,
- then the id must be <code>-1</code>, otherwise it should be the id of the built-in keyboard.</p>
-<p>If you observe that the <code>BuiltInKeyboardId</code> is not <code>-1</code> but it should be, then
-you are missing a key character map file for a special function keypad somewhere.
-Special function keypad devices should have key character map files that contain
-just the line <code>type SPECIAL_FUNCTION</code> (that's what in the <code>tuna-gpio-keykad.kcm</code>
-file we see mentioned above).</p>
-</li>
-</ol>
-<h3 id="input-reader-state">Input Reader State</h3>
-<p>The <code>InputReader</code> is responsible for decoding input events from the kernel.
-Its state dump shows information about how each input device is configured
-and recent state changes that occurred, such as key presses or touches on
-the touch screen.</p>
-<p>This is what a special function keypad looks like:</p>
-<pre><code>Input Reader State:
- Device 3: tuna-gpio-keypad
- IsExternal: false
- Sources: 0x00000101
- KeyboardType: 1
- Keyboard Input Mapper:
- Parameters:
- AssociatedDisplayId: -1
- OrientationAware: false
- KeyboardType: 1
- Orientation: 0
- KeyDowns: 0 keys currently down
- MetaState: 0x0
- DownTime: 75816923828000
-</code></pre>
-<p>Here is a touch screen. Notice all of the information about the resolution of
-the device and the calibration parameters that were used.</p>
-<pre><code> Device 6: Melfas MMSxxx Touchscreen
- IsExternal: false
- Sources: 0x00001002
- KeyboardType: 0
- Motion Ranges:
- X: source=0x00001002, min=0.000, max=719.001, flat=0.000, fuzz=0.999
- Y: source=0x00001002, min=0.000, max=1279.001, flat=0.000, fuzz=0.999
- PRESSURE: source=0x00001002, min=0.000, max=1.000, flat=0.000, fuzz=0.000
- SIZE: source=0x00001002, min=0.000, max=1.000, flat=0.000, fuzz=0.000
- TOUCH_MAJOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000
- TOUCH_MINOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000
- TOOL_MAJOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000
- TOOL_MINOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000
- Touch Input Mapper:
- Parameters:
- GestureMode: spots
- DeviceType: touchScreen
- AssociatedDisplay: id=0, isExternal=false
- OrientationAware: true
- Raw Touch Axes:
- X: min=0, max=720, flat=0, fuzz=0, resolution=0
- Y: min=0, max=1280, flat=0, fuzz=0, resolution=0
- Pressure: min=0, max=255, flat=0, fuzz=0, resolution=0
- TouchMajor: min=0, max=30, flat=0, fuzz=0, resolution=0
- TouchMinor: unknown range
- ToolMajor: unknown range
- ToolMinor: unknown range
- Orientation: unknown range
- Distance: unknown range
- TiltX: unknown range
- TiltY: unknown range
- TrackingId: min=0, max=65535, flat=0, fuzz=0, resolution=0
- Slot: min=0, max=9, flat=0, fuzz=0, resolution=0
- Calibration:
- touch.size.calibration: diameter
- touch.size.scale: 10.000
- touch.size.bias: 0.000
- touch.size.isSummed: false
- touch.pressure.calibration: amplitude
- touch.pressure.scale: 0.005
- touch.orientation.calibration: none
- touch.distance.calibration: none
- SurfaceWidth: 720px
- SurfaceHeight: 1280px
- SurfaceOrientation: 0
- Translation and Scaling Factors:
- XScale: 0.999
- YScale: 0.999
- XPrecision: 1.001
- YPrecision: 1.001
- GeometricScale: 0.999
- PressureScale: 0.005
- SizeScale: 0.033
- OrientationCenter: 0.000
- OrientationScale: 0.000
- DistanceScale: 0.000
- HaveTilt: false
- TiltXCenter: 0.000
- TiltXScale: 0.000
- TiltYCenter: 0.000
- TiltYScale: 0.000
- Last Button State: 0x00000000
- Last Raw Touch: pointerCount=0
- Last Cooked Touch: pointerCount=0
-</code></pre>
-<p>Here is an external keyboard / mouse combo HID device. (This device doesn't actually
-have a mouse but its HID descriptor says it does.)</p>
-<pre><code> Device 7: Motorola Bluetooth Wireless Keyboard
- IsExternal: true
- Sources: 0x00002103
- KeyboardType: 2
- Motion Ranges:
- X: source=0x00002002, min=0.000, max=719.000, flat=0.000, fuzz=0.000
- Y: source=0x00002002, min=0.000, max=1279.000, flat=0.000, fuzz=0.000
- PRESSURE: source=0x00002002, min=0.000, max=1.000, flat=0.000, fuzz=0.000
- VSCROLL: source=0x00002002, min=-1.000, max=1.000, flat=0.000, fuzz=0.000
- Keyboard Input Mapper:
- Parameters:
- AssociatedDisplayId: -1
- OrientationAware: false
- KeyboardType: 2
- Orientation: 0
- KeyDowns: 0 keys currently down
- MetaState: 0x0
- DownTime: 75868832946000
- Cursor Input Mapper:
- Parameters:
- AssociatedDisplayId: 0
- Mode: pointer
- OrientationAware: false
- XScale: 1.000
- YScale: 1.000
- XPrecision: 1.000
- YPrecision: 1.000
- HaveVWheel: true
- HaveHWheel: false
- VWheelScale: 1.000
- HWheelScale: 1.000
- Orientation: 0
- ButtonState: 0x00000000
- Down: false
- DownTime: 0
-</code></pre>
-<p>Here is a joystick. Notice how all of the axes have been scaled to a normalized
-range. The axis mapping can be configured using key layout files.</p>
-<pre><code>Device 18: Logitech Logitech Cordless RumblePad 2
- IsExternal: true
- Sources: 0x01000511
- KeyboardType: 1
- Motion Ranges:
- X: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000
- Y: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000
- Z: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000
- RZ: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000
- HAT_X: source=0x01000010, min=-1.000, max=1.000, flat=0.000, fuzz=0.000
- HAT_Y: source=0x01000010, min=-1.000, max=1.000, flat=0.000, fuzz=0.000
- Keyboard Input Mapper:
- Parameters:
- AssociatedDisplayId: -1
- OrientationAware: false
- KeyboardType: 1
- Orientation: 0
- KeyDowns: 0 keys currently down
- MetaState: 0x0
- DownTime: 675270841000
- Joystick Input Mapper:
- Axes:
- X: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000
- scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000
- rawAxis=0, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0
- Y: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000
- scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000
- rawAxis=1, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0
- Z: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000
- scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000
- rawAxis=2, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0
- RZ: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000
- scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000
- rawAxis=5, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0
- HAT_X: min=-1.00000, max=1.00000, flat=0.00000, fuzz=0.00000
- scale=1.00000, offset=0.00000, highScale=1.00000, highOffset=0.00000
- rawAxis=16, rawMin=-1, rawMax=1, rawFlat=0, rawFuzz=0, rawResolution=0
- HAT_Y: min=-1.00000, max=1.00000, flat=0.00000, fuzz=0.00000
- scale=1.00000, offset=0.00000, highScale=1.00000, highOffset=0.00000
- rawAxis=17, rawMin=-1, rawMax=1, rawFlat=0, rawFuzz=0, rawResolution=0
-</code></pre>
-<p>At the end of the input reader dump there is some information about global configuration
-parameters such as the mouse pointer speed.</p>
-<pre><code> Configuration:
- ExcludedDeviceNames: []
- VirtualKeyQuietTime: 0.0ms
- PointerVelocityControlParameters: scale=1.000, lowThreshold=500.000, highThreshold=3000.000, acceleration=3.000
- WheelVelocityControlParameters: scale=1.000, lowThreshold=15.000, highThreshold=50.000, acceleration=4.000
- PointerGesture:
- Enabled: true
- QuietInterval: 100.0ms
- DragMinSwitchSpeed: 50.0px/s
- TapInterval: 150.0ms
- TapDragInterval: 300.0ms
- TapSlop: 20.0px
- MultitouchSettleInterval: 100.0ms
- MultitouchMinDistance: 15.0px
- SwipeTransitionAngleCosine: 0.3
- SwipeMaxWidthRatio: 0.2
- MovementSpeedRatio: 0.8
- ZoomSpeedRatio: 0.3
-</code></pre>
-<h4 id="things-to-look-for_1">Things To Look For</h4>
-<ol>
-<li>
-<p>All of the expected input devices are present.</p>
-</li>
-<li>
-<p>Each input device has been configured appropriately. Especially check the
- touch screen and joystick axes.</p>
-</li>
-</ol>
-<h3 id="input-dispatcher-state">Input Dispatcher State</h3>
-<p>The <code>InputDispatcher</code> is responsible for sending input events to applications.
-Its state dump shows information about which window is being touched, the
-state of the input queue, whether an ANR is in progress, and so on.</p>
-<pre><code>Input Dispatcher State:
- DispatchEnabled: 1
- DispatchFrozen: 0
- FocusedApplication: name='AppWindowToken{41b03a10 token=Token{41bdcf78 ActivityRecord{418ab728 com.android.settings/.Settings}}}', dispatchingTimeout=5000.000ms
- FocusedWindow: name='Window{41908458 Keyguard paused=false}'
- TouchDown: false
- TouchSplit: false
- TouchDeviceId: -1
- TouchSource: 0x00000000
- TouchedWindows: <none>
- Windows:
- 0: name='Window{41bd5b18 NavigationBar paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x05800068, type=0x000007e3, layer=181000, frame=[0,1184][720,1280], scale=1.000000, touchableRegion=[0,1184][720,1280], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms
- 1: name='Window{41a19770 RecentsPanel paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01820100, type=0x000007de, layer=151000, frame=[0,0][720,1184], scale=1.000000, touchableRegion=[0,0][720,1184], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms
- 2: name='Window{41a78768 StatusBar paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x00800048, type=0x000007d0, layer=141000, frame=[0,0][720,50], scale=1.000000, touchableRegion=[0,0][720,50], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms
- 3: name='Window{41877570 StatusBarExpanded paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x01811328, type=0x000007e1, layer=131005, frame=[0,-1184][720,-114], scale=1.000000, touchableRegion=[0,-1184][720,-114], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms
- 4: name='Window{41bedf20 TrackingView paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01020300, type=0x000007e1, layer=131000, frame=[0,-1032][720,102], scale=1.000000, touchableRegion=[0,-1032][720,102], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms
- 5: name='Window{41908458 Keyguard paused=false}', paused=false, hasFocus=true, hasWallpaper=false, visible=true, canReceiveKeys=true, flags=0x15120800, type=0x000007d4, layer=111000, frame=[0,50][720,1184], scale=1.000000, touchableRegion=[0,50][720,1184], inputFeatures=0x00000000, ownerPid=205, ownerUid=1000, dispatchingTimeout=5000.000ms
- 6: name='Window{4192cc30 com.android.phasebeam.PhaseBeamWallpaper paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x00000308, type=0x000007dd, layer=21010, frame=[0,0][720,1184], scale=1.000000, touchableRegion=[0,0][720,1184], inputFeatures=0x00000000, ownerPid=429, ownerUid=10046, dispatchingTimeout=5000.000ms
- 7: name='Window{41866c00 com.android.settings/com.android.settings.Settings paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01810100, type=0x00000001, layer=21005, frame=[0,0][720,1184], scale=1.000000, touchableRegion=[0,0][720,1184], inputFeatures=0x00000000, ownerPid=19000, ownerUid=1000, dispatchingTimeout=5000.000ms
- 8: name='Window{4197c858 com.android.launcher/com.android.launcher2.Launcher paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01910100, type=0x00000001, layer=21000, frame=[0,0][720,1184], scale=1.000000, touchableRegion=[0,0][720,1184], inputFeatures=0x00000000, ownerPid=515, ownerUid=10032, dispatchingTimeout=5000.000ms
- MonitoringChannels: <none>
- InboundQueue: length=0
- ActiveConnections: <none>
- AppSwitch: not pending
- Configuration:
- MaxEventsPerSecond: 90
- KeyRepeatDelay: 50.0ms
- KeyRepeatTimeout: 500.0ms
-</code></pre>
-<h4 id="things-to-look-for_2">Things To Look For</h4>
-<ol>
-<li>
-<p>In general, all input events are being processed as expected.</p>
-</li>
-<li>
-<p>If you touch the touch screen and run dumpsys at the same time, then the <code>TouchedWindows</code>
- line should show the window that you are touching.</p>
-</li>
-</ol>
-
diff --git a/src/devices/tech/debug/dumpsys.jd b/src/devices/tech/debug/dumpsys.jd
new file mode 100644
index 0000000..959385e
--- /dev/null
+++ b/src/devices/tech/debug/dumpsys.jd
@@ -0,0 +1,105 @@
+page.title=Dumpsys System Diagnostics
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>The <code>dumpsys</code> tool runs on the device and provides information about the status
+of system services. </p>
+
+<h2 id=how_to_use_dumpsys>How to use dumpsys</h2>
+
+<p>If you run <code>adb shell dumpsys</code>, you’ll get diagnostic output for
+all system services, which is usually more than you want. For more manageable
+output, specify the service you would like to examine. </p>
+
+<p>For example, the following command:</p>
+
+<pre>
+$ adb shell dumpsys input
+</pre>
+
+<p>provides system data for input components such as touchscreens or built-in
+keyboards.</p>
+
+<h2 id=list_of_system_services>List of system services</h2>
+
+
+<p>For a complete list of system services that you can use with dumpsys, try the
+following command:</p>
+
+<pre class="no-pretty-print">
+$ adb shell dumpsys -l
+Currently running services:
+ DockObserver
+ SurfaceFlinger
+ accessibility
+ account
+ activity
+ alarm
+ android.security.keystore
+ appops
+ appwidget
+ assetatlas
+ audio
+ backup
+ battery
+ batteryproperties
+ batterystats
+ bluetooth_manager
+ clipboard
+ commontime_management
+ connectivity
+ consumer_ir
+ content
+ country_detector
+ cpuinfo
+ dbinfo
+...
+</pre>
+
+<h2 id=dumpsys_command-line_options>Dumpsys command-line options</h2>
+
+<p>Command-line options are different for different services. Here are a few
+common ones:</p>
+
+<ul>
+ <li> For many services, you can append <code>-h</code> to see the help
+text.
+ <li> For some services, you can append <code>-c</code> to view the data in
+a machine-friendly format. </ul>
+
+<h2 id=understanding_diagnostic_output>Understanding diagnostic output</h2>
+
+<p>For details on some of the most commonly used dumpsys services, see the
+following articles:</p>
+
+<ul>
+ <li> <a href="{@docRoot}devices/input/diagnostics.html">Input Diagnostics</a>
+<!-- To add in upcoming CLs
+ <li> <a href="{@docRoot}devices/tech/ram/procstats.html">Procstats</a>
+ <li> <a href="{@docRoot}devices/tech/power/batterystats.html">Batterystats</a>
+ <li> <a href="{@docRoot}devices/tech/datausage/netstats.html">Dumpsys Netstats</a>
+-->
+</ul>
+
diff --git a/src/devices/tech/power.jd b/src/devices/tech/power.jd
index 38e1e6a..3515562 100644
--- a/src/devices/tech/power.jd
+++ b/src/devices/tech/power.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -28,9 +28,9 @@
<h2 id="usage-statistics">Battery Usage Statistics</h2>
<p>The framework automatically determines battery usage statistics by tracking how long device
-components spend in different states. As components (WiFi chipset, Cellular Radio, Bluetooth, GPS,
-Display, CPU) change states (OFF/ON, idle/full power, low/high brightness, etc.), the controlling
-service reports to the framework BatteryStats service, which collects information over time and
+components spend in different states. As components (Wi-Fi chipset, cellular radio, Bluetooth, GPS,
+display, CPU) change states (OFF/ON, idle/full power, low/high brightness, etc.), the controlling
+service reports to the framework BatteryStats service. BatteryStats collects information over time and
stores it for use across reboots. The service doesn’t track battery current draw directly,
but instead collects timing information that can be used to approximate battery
consumption by different components.</p>
@@ -59,9 +59,15 @@
<h2 id="profile-values">Power Profile Values</h2>
-<p>Device manufacturers must provide a component power profile that defines the current
-consumption value for the component and the approximate the actual battery drain caused by the
-component over time. Within a power profile, power consumption is specified in milliamps (mA) of
+<p class="caution"><strong>Caution:</strong> Device manufacturers must
+provide a component power profile that defines the current consumption value
+for the component and the approximate battery drain caused by the component
+over time. This profile is defined in <a
+href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/xml/power_profile.xml">platform/frameworks/base/core/res/res/xml/power_profile.xml</a>.
+See the <a href="#power-values">Power Values</a> table for guidance on these
+settings.</p>
+
+<p>Within a power profile, power consumption is specified in milliamps (mA) of
current draw at a nominal voltage and can be a fractional value specified in microamps (uA). The
value should be the mA consumed at the battery and not a value applicable to a power rail that does
not correspond to current consumed from the battery.</p>
@@ -144,7 +150,7 @@
connecting to external power supplies. Alternatively, you can modify the system to ignore the
invalid data from the missing battery.</p>
-<a name="control-suspend"><h3 id="control-suspend">Controlling System Suspend</h3></a>
+<h3 id="control-suspend">Controlling System Suspend</h3>
<p>This section describes how to avoid system suspend state when you don’t want it to interfere with
other measurements, and how to measure the power draw of system suspend state when you do want to
@@ -191,7 +197,7 @@
</li>
</ul>
-<a name="control-cpu"><h3 id="control-cpu">Controlling CPU Speeds</h3></a>
+<h3 id="control-cpu">Controlling CPU Speeds</h3>
<p>Active CPUs can be brought online or put offline, have their clock speeds and associated voltages
changed (possibly also affecting memory bus speeds and other system core power states), and
@@ -251,14 +257,15 @@
such limiting, either using the system console output when taking measurements or by checking the
kernel log after measuring.</p>
-<p>For the <code>cpu.active</code> value, measure the power consumed when the system is not in
+<p>For the <code>cpu.awake</code> value, measure the power consumed when the system is not in
suspend and not executing tasks. The CPU should be in a low-power scheduler <em>idle loop
-</em>, possibly executing an ARM Wait For Event instruction or in an SoC-specific low power state
-with a fast exit latency suitable for idle use. Your platform might have more than one idle state in
-use with differing levels of power consumption; choose a representative idle state for
-longer periods of scheduler idle (several milliseconds). Examine the power graph on your measurement
-equipment and choose samples where the CPU is at its lowest consumption, discarding higher samples
-where the CPU exited idle.</p>
+</em>, possibly executing an ARM Wait For Event instruction or in an SoC-specific low-power state
+with a fast-exit latency suitable for idle use.</p>
+
+<p>For the <code>cpu.active</code> value, power needs to be measured when the
+system is not in suspend mode and not executing tasks. One of the CPU (usually
+the primary CPU) should be running the task, and all the other CPUs should be in
+an idle state.</p>
<h3 id="screen-power">Measuring Screen Power</h3>
@@ -302,7 +309,7 @@
<p>The <code>wifi.scan</code> value measures the power consumed during a Wi-Fi scan for access
points. Applications can trigger Wi-Fi scans using the WifiManager class
-<a href = "http://developer.android.com/reference/android/net/wifi/WifiManager.html">
+<a href ="http://developer.android.com/reference/android/net/wifi/WifiManager.html">
<code>startScan()</code>API</a>. You can also open Settings > Wi-Fi, which performs access point
scans every few seconds with an apparent jump in power consumption, but you must subtract screen
power from these measurements.</p>
@@ -409,9 +416,9 @@
with variation inherent in the loading, consider using a longer test window.</li>
</ul>
-<a name="nexus-devices"><h3>Supported Nexus Devices</h3></a>
+<h3 id="nexus-devices">Supported Nexus Devices</h3>
-<h5><a name="nexus-5">Nexus 5</a></h5>
+<h5 id="nexus-5">Nexus 5</h5>
<table>
<tbody>
@@ -436,7 +443,7 @@
</table>
-<h5><a name="nexus-6">Nexus 6</a></h5>
+<h5 id="nexus-6">Nexus 6</h5>
<table>
<tbody>
@@ -471,7 +478,7 @@
</table>
-<h5><a name="nexus-9">Nexus 9</a></h5>
+<h5 id="nexus-9">Nexus 9</h5>
<table>
<tbody>
@@ -506,7 +513,7 @@
</table>
-<h5><a name="nexus-10">Nexus 10</a></h5>
+<h5 id="nexus-10">Nexus 10</h5>
<table>
<tbody>
@@ -563,6 +570,14 @@
<h2 id="power-values">Power Values</h2>
+
+<p>Device manufacturers must provide a component power profile defined in
+<em><device></em>/frameworks/base/core/res/res/xml/power_profile.xml. To
+determine these values, use hardware that measures the power being used by
+the device and perform the various operations for which information is needed.
+Measure the power use during those operations and compute the values (deriving
+differences from other base-line power uses as appropriate).</p>
+
<table>
<tr>
<th>Name</th>
@@ -675,7 +690,7 @@
<tr>
<td>cpu.speeds</td>
<td>Multi-value entry that lists each possible CPU speed in KHz.</td>
- <td>125000, 250000, 500000, 1000000, 1500000</td>
+ <td>125000KHz, 250000KHz, 500000KHz, 1000000KHz, 1500000KHz</td>
<td>The number and order of entries must correspond to the mA entries in cpu.active.</td>
</tr>
@@ -691,13 +706,17 @@
<td>Additional power used when CPUs are in scheduling idle state (kernel idle loop); system is not
in system suspend state.</td>
<td>50mA</td>
- <td></td>
+ <td>Your platform might have more than one idle state in use with differing
+levels of power consumption; choose a representative idle state for longer
+periods of scheduler idle (several milliseconds). Examine the power graph on
+your measurement equipment and choose samples where the CPU is at its lowest
+consumption, discarding higher samples where the CPU exited idle.</td>
</tr>
<tr>
<td>cpu.active</td>
<td>Additional power used by CPUs when running at different speeds.</td>
- <td>100, 120, 140, 160, 200</td>
+ <td>100mA, 120mA, 140mA, 160mA, 200mA</td>
<td>Set the max speed in the kernel to each of the allowed speeds and peg the CPU at that
speed. The number of entries here correspond to the number of entries in cpu.speeds, in the
same order.</td>
@@ -712,9 +731,6 @@
</table>
-<p>The power_profile.xml file is placed in an overlay in
-device///frameworks/base/core/res/res/xml/power_profile.xml</p>
-
<h3 id="sample">Sample file</h3>
<pre>
@@ -764,4 +780,4 @@
3000
<!-- Battery capacity is 3000 mAH (at 3.6 Volts) -->
-</pre>
\ No newline at end of file
+</pre>
diff --git a/src/devices/tech/ram/index.jd b/src/devices/tech/ram/index.jd
new file mode 100644
index 0000000..2bb2717
--- /dev/null
+++ b/src/devices/tech/ram/index.jd
@@ -0,0 +1,21 @@
+page.title=RAM
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<p> The following sections contain information, documentation, tips and tricks about Android memory managment and RAM diagnostics.</p>
+
diff --git a/src/devices/tech/low-ram.jd b/src/devices/tech/ram/low-ram.jd
similarity index 100%
rename from src/devices/tech/low-ram.jd
rename to src/devices/tech/ram/low-ram.jd
diff --git a/src/devices/tech/ram/procstats.jd b/src/devices/tech/ram/procstats.jd
new file mode 100644
index 0000000..48e6ed0
--- /dev/null
+++ b/src/devices/tech/ram/procstats.jd
@@ -0,0 +1,368 @@
+page.title=Viewing RAM Usage Data (procstats)
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc"></ol>
+ </div>
+</div>
+
+<p>The <code>procstats</code> tool is used to analyze application memory usage over time (versus at a
+particular snapshot in time, like <code>meminfo</code>). Its state dump displays statistics about every application’s runtime,
+proportional set size (PSS) and unique set size (USS).</p>
+
+<h2 id=input>Input</h2>
+
+
+<p>To get application memory usage stats for the last three hours, in
+human-readable form, run the following command:</p>
+
+<pre class=prettyprint>
+$ adb shell dumpsys procstats --hours 3
+</pre>
+
+
+
+<h2 id=output>Output</h2>
+
+
+<p>As can be seen in the example below, percentages display what percentage of
+time the application was running, while the numbers following show PSS and USS
+as minPSS-avgPSS-maxPSS/minUSS-avgUSS-maxUSS over samples.</p>
+
+<pre class="no-pretty-print">
+AGGREGATED OVER LAST 3 HOURS:
+ * com.android.systemui / u0a20 / v22:
+ TOTAL: 100% (109MB-126MB-159MB/108MB-125MB-157MB over 18)
+ Persistent: 100% (109MB-126MB-159MB/108MB-125MB-157MB over 18)
+ * com.android.nfc / 1027 / v22:
+ TOTAL: 100% (17MB-17MB-17MB/16MB-16MB-16MB over 18)
+ Persistent: 100% (17MB-17MB-17MB/16MB-16MB-16MB over 18)
+ * android.process.acore / u0a4 / v22:
+ TOTAL: 100% (14MB-15MB-15MB/14MB-14MB-14MB over 20)
+ Imp Fg: 100% (14MB-15MB-15MB/14MB-14MB-14MB over 20)
+ * com.google.android.inputmethod.latin / u0a56 / v21483:
+ TOTAL: 100% (57MB-59MB-59MB/56MB-58MB-58MB over 19)
+ Imp Fg: 100% (57MB-59MB-59MB/56MB-58MB-58MB over 19)
+ * com.redbend.vdmc / 1001 / v1:
+ TOTAL: 100% (9.5MB-9.6MB-9.7MB/8.8MB-8.9MB-9.0MB over 18)
+ Persistent: 100% (9.5MB-9.6MB-9.7MB/8.8MB-8.9MB-9.0MB over 18)
+ * com.android.phone / 1001 / v22:
+ TOTAL: 100% (19MB-22MB-27MB/18MB-21MB-26MB over 18)
+ Persistent: 100% (19MB-22MB-27MB/18MB-21MB-26MB over 18)
+ * com.google.android.gms.persistent / u0a8 / v7319438:
+ TOTAL: 100% (32MB-35MB-40MB/30MB-33MB-37MB over 19)
+ Imp Fg: 100% (32MB-35MB-40MB/30MB-33MB-37MB over 19)
+ * com.android.bluetooth / 1002 / v22:
+ TOTAL: 100% (9.3MB-9.7MB-10MB/8.5MB-8.9MB-9.2MB over 19)
+ Imp Fg: 100% (9.3MB-9.7MB-10MB/8.5MB-8.9MB-9.2MB over 19)
+ * com.google.android.googlequicksearchbox:interactor / u0a22 / v300404573:
+ TOTAL: 100% (3.4MB-3.5MB-3.6MB/2.8MB-2.8MB-2.8MB over 19)
+ Imp Fg: 100% (3.4MB-3.5MB-3.6MB/2.8MB-2.8MB-2.8MB over 19)
+ * com.google.process.gapps / u0a8 / v7306438:
+ TOTAL: 100% (23MB-24MB-28MB/21MB-22MB-26MB over 19)
+ Imp Fg: 100% (23MB-24MB-28MB/21MB-22MB-26MB over 19)
+ * com.vito.lux / u0a84 / v237:
+ TOTAL: 100% (32MB-48MB-83MB/31MB-47MB-82MB over 134)
+ Imp Fg: 100% (32MB-48MB-83MB/31MB-47MB-82MB over 134)
+ Service: 0.05%
+ * system / 1000 / v22:
+ TOTAL: 100% (79MB-85MB-102MB/78MB-83MB-100MB over 18)
+ Persistent: 100% (79MB-85MB-102MB/78MB-83MB-100MB over 18)
+ * com.rhapsody / u0a83 / v125:
+ TOTAL: 100% (7.9MB-12MB-19MB/6.9MB-11MB-17MB over 15)
+ Service: 100% (7.9MB-12MB-19MB/6.9MB-11MB-17MB over 15)
+ Service Rs: 0.04%
+ * com.qualcomm.qcrilmsgtunnel / 1001 / v22:
+ TOTAL: 100% (2.5MB-2.6MB-2.7MB/1.7MB-1.8MB-1.9MB over 15)
+ Service: 100% (2.5MB-2.6MB-2.7MB/1.7MB-1.8MB-1.9MB over 15)
+ Service Rs: 0.13%
+ * com.amazon.kindle / u0a82 / v1143472216:
+ TOTAL: 100% (44MB-54MB-77MB/43MB-52MB-74MB over 17)
+ Service: 100% (44MB-54MB-77MB/43MB-52MB-74MB over 17)
+ Service Rs: 0.04%
+ * com.outplaylab.VideoDiet2 / u0a93 / v21:
+ TOTAL: 100% (2.8MB-3.1MB-4.0MB/2.0MB-2.2MB-3.0MB over 15)
+ Service: 100% (2.8MB-3.1MB-4.0MB/2.0MB-2.2MB-3.0MB over 15)
+ Service Rs: 0.03%
+ * android.process.media / u0a6 / v800:
+ TOTAL: 99% (4.6MB-5.9MB-8.1MB/3.4MB-4.7MB-6.7MB over 25)
+ Imp Fg: 0.02%
+ Service: 99% (4.6MB-5.9MB-8.1MB/3.4MB-4.7MB-6.7MB over 25)
+ Service Rs: 0.02%
+ (Cached): 0.94%
+ * kr.sira.sound / u0a108 / v41:
+ TOTAL: 77% (117MB-191MB-219MB/111MB-187MB-213MB over 68)
+ Top: 77% (117MB-191MB-219MB/111MB-187MB-213MB over 68)
+ (Last Act): 18% (58MB-127MB-161MB/53MB-123MB-158MB over 3)
+ (Cached): 0.06%
+ * com.google.android.gms / u0a8 / v7319438:
+ TOTAL: 37% (41MB-45MB-57MB/38MB-42MB-53MB over 23)
+ Top: 13% (41MB-46MB-57MB/39MB-42MB-53MB over 16)
+ Imp Fg: 13% (41MB-44MB-47MB/39MB-41MB-44MB over 5)
+ Imp Bg: 0.38%
+ Service: 11% (42MB-42MB-42MB/38MB-38MB-38MB over 2)
+ Receiver: 0.03%
+ (Last Act): 2.0% (38MB-38MB-38MB/36MB-36MB-36MB over 1)
+ (Cached): 61% (39MB-40MB-43MB/37MB-37MB-40MB over 28)
+ * com.google.android.googlequicksearchbox / u0a22 / v300404573:
+ TOTAL: 22% (129MB-153MB-162MB/125MB-149MB-156MB over 20)
+ Top: 22% (129MB-153MB-162MB/125MB-149MB-156MB over 20)
+ Imp Bg: 0.04%
+ Receiver: 0.01%
+ (Home): 78% (75MB-84MB-122MB/74MB-82MB-117MB over 12)
+ * com.google.android.apps.thehub / u0a102 / v12:
+ TOTAL: 21% (6.4MB-7.6MB-8.7MB/4.8MB-6.0MB-7.2MB over 2)
+ Service: 21% (6.4MB-7.6MB-8.7MB/4.8MB-6.0MB-7.2MB over 2)
+ * com.google.android.talk / u0a54 / v22314462:
+ TOTAL: 9.3%
+ Top: 0.04%
+ Service: 9.3%
+ Receiver: 0.01%
+ (Last Act): 3.9% (69MB-70MB-71MB/67MB-68MB-69MB over 6)
+ (Cached): 87% (42MB-53MB-77MB/40MB-51MB-74MB over 137)
+ * com.google.android.apps.plus / u0a67 / v413836278:
+ TOTAL: 8.2% (9.6MB-12MB-18MB/8.1MB-11MB-16MB over 3)
+ Imp Bg: 0.10%
+ Service: 8.0% (9.6MB-12MB-18MB/8.1MB-11MB-16MB over 3)
+ Receiver: 0.05%
+ (Cached): 59% (7.8MB-19MB-33MB/6.8MB-18MB-31MB over 22)
+ * com.android.providers.calendar / u0a2 / v22:
+ TOTAL: 3.5% (7.3MB-7.7MB-8.0MB/5.9MB-6.5MB-6.9MB over 10)
+ Imp Bg: 0.32%
+ Service: 3.2% (7.3MB-7.7MB-8.0MB/5.9MB-6.5MB-6.9MB over 10)
+ Receiver: 0.01%
+ (Cached): 69% (4.7MB-6.6MB-7.8MB/3.5MB-5.5MB-6.7MB over 23)
+ * com.amazon.mShop.android / u0a104 / v5030102:
+ TOTAL: 2.7% (25MB-40MB-47MB/24MB-37MB-43MB over 6)
+ Service: 2.6% (25MB-40MB-47MB/24MB-37MB-43MB over 6)
+ Receiver: 0.15%
+ (Cached): 97% (25MB-33MB-48MB/24MB-31MB-44MB over 46)
+ * com.google.android.gm / u0a70 / v51001620:
+ TOTAL: 2.2% (209MB-209MB-209MB/203MB-203MB-203MB over 1)
+ Top: 0.48% (209MB-209MB-209MB/203MB-203MB-203MB over 1)
+ Imp Bg: 0.70%
+ Service: 1.0%
+ Receiver: 0.01%
+ (Last Act): 0.02%
+ (Cached): 94% (25MB-67MB-116MB/23MB-63MB-109MB over 61)
+ * com.google.android.googlequicksearchbox:search / u0a22 / v300404573:
+ TOTAL: 2.1% (66MB-66MB-66MB/63MB-63MB-63MB over 1)
+ Top: 1.4% (66MB-66MB-66MB/63MB-63MB-63MB over 1)
+ Imp Fg: 0.01%
+ Service: 0.66%
+ Receiver: 0.02%
+ (Cached): 98% (52MB-59MB-79MB/50MB-56MB-77MB over 56)
+ * com.google.android.calendar / u0a31 / v2015030452:
+ TOTAL: 1.4%
+ Imp Bg: 0.33%
+ Service: 1.1%
+ Receiver: 0.02%
+ (Cached): 80% (7.4MB-12MB-17MB/5.8MB-9.8MB-14MB over 18)
+ * com.android.vending / u0a16 / v80341100:
+ TOTAL: 1.3% (88MB-154MB-220MB/85MB-151MB-217MB over 2)
+ Top: 1.3% (88MB-154MB-220MB/85MB-151MB-217MB over 2)
+ Service: 0.06%
+ Receiver: 0.02%
+ (Last Act): 4.4% (46MB-68MB-89MB/45MB-66MB-87MB over 2)
+ (Cached): 11% (15MB-74MB-133MB/13MB-72MB-131MB over 2)
+ * com.google.android.apps.photos / u0a65 / v5616:
+ TOTAL: 0.94%
+ Service: 0.90%
+ Receiver: 0.04%
+ (Cached): 80% (9.2MB-12MB-17MB/7.5MB-11MB-15MB over 20)
+ * com.amazon.avod.thirdpartyclient / u0a107 / v451210:
+ TOTAL: 0.52%
+ Service: 0.49%
+ Receiver: 0.03%
+ (Cached): 97% (14MB-24MB-34MB/13MB-22MB-31MB over 40)
+ * com.google.android.gms.wearable / u0a8 / v7319438:
+ TOTAL: 0.51%
+ Imp Fg: 0.47%
+ Service: 0.04%
+ (Cached): 65% (4.7MB-6.5MB-8.2MB/3.6MB-4.2MB-5.4MB over 10)
+ * com.amazon.mShop.android.shopping / u0a103 / v5040011:
+ TOTAL: 0.50%
+ Service: 0.37%
+ Receiver: 0.13%
+ (Cached): 77% (13MB-17MB-21MB/11MB-15MB-19MB over 15)
+ * com.google.android.gms:car / u0a8 / v7319438:
+ TOTAL: 0.49% (7.1MB-7.1MB-7.1MB/4.3MB-4.3MB-4.3MB over 1)
+ Top: 0.05%
+ Imp Fg: 0.39% (7.1MB-7.1MB-7.1MB/4.3MB-4.3MB-4.3MB over 1)
+ Service: 0.05%
+ (Cached): 0.60% (6.6MB-6.6MB-6.6MB/3.6MB-3.6MB-3.6MB over 1)
+ * com.amazon.mp3 / u0a92 / v4033010:
+ TOTAL: 0.46%
+ Service: 0.43%
+ Receiver: 0.03%
+ (Cached): 84% (12MB-16MB-23MB/9.7MB-14MB-21MB over 25)
+ * com.android.chrome:privileged_process1 / u0a34 / v2272096:
+ TOTAL: 0.43%
+ Service: 0.04%
+ Service Rs: 0.39%
+ (Cached): 100% (2.9MB-4.0MB-4.9MB/1.7MB-2.9MB-3.9MB over 18)
+ * com.google.android.dialer / u0a10 / v20100:
+ TOTAL: 0.39% (93MB-93MB-93MB/89MB-89MB-89MB over 1)
+ Top: 0.23% (93MB-93MB-93MB/89MB-89MB-89MB over 1)
+ Imp Fg: 0.16%
+ (Cached): 16% (5.0MB-31MB-57MB/4.1MB-29MB-54MB over 2)
+ * com.google.android.apps.maps / u0a58 / v906101124:
+ TOTAL: 0.38%
+ Service: 0.33%
+ Receiver: 0.05%
+ (Cached): 69% (8.7MB-15MB-18MB/7.2MB-14MB-17MB over 8)
+ * com.google.android.youtube / u0a80 / v101451214:
+ TOTAL: 0.26%
+ Service: 0.26%
+ (Cached): 36% (15MB-22MB-29MB/13MB-19MB-27MB over 5)
+ * com.google.android.apps.fitness / u0a45 / v2015109100:
+ TOTAL: 0.26%
+ Service: 0.23%
+ Receiver: 0.02%
+ (Cached): 82% (3.9MB-6.4MB-9.2MB/2.8MB-5.3MB-7.9MB over 19)
+ * com.google.android.apps.enterprise.dmagent / u0a37 / v630:
+ TOTAL: 0.06%
+ Service: 0.06%
+ Receiver: 0.01%
+ (Cached): 2.2% (6.5MB-7.4MB-8.2MB/4.8MB-5.8MB-6.8MB over 2)
+ * com.audible.application / u0a95 / v3068:
+ TOTAL: 0.06%
+ Receiver: 0.06%
+ (Cached): 34% (14MB-16MB-19MB/11MB-14MB-17MB over 7)
+ * com.android.defcontainer / u0a5 / v22:
+ TOTAL: 0.06%
+ Imp Fg: 0.06%
+ (Cached): 0.12%
+ * com.google.android.music:main / u0a60 / v1847:
+ TOTAL: 0.04%
+ Top: 0.01%
+ Service: 0.02%
+ Receiver: 0.01%
+ (Cached): 9.8% (10MB-12MB-14MB/8.3MB-9.6MB-11MB over 2)
+ * com.google.android.apps.magazines / u0a61 / v2015040100:
+ TOTAL: 0.03%
+ Top: 0.02%
+ Receiver: 0.01%
+ (Cached): 8.7% (12MB-14MB-16MB/9.7MB-11MB-13MB over 2)
+ * com.google.android.videos / u0a77 / v37191:
+ TOTAL: 0.03%
+ Imp Fg: 0.01%
+ Service: 0.02%
+ (Cached): 1.3% (11MB-12MB-13MB/9.1MB-10MB-12MB over 2)
+ * com.google.android.apps.books / u0a28 / v30336:
+ TOTAL: 0.03%
+ Imp Fg: 0.01%
+ Service: 0.02%
+ (Cached): 1.3% (7.9MB-9.6MB-11MB/6.3MB-8.0MB-9.7MB over 2)
+ * com.google.android.keep / u0a71 / v3115:
+ TOTAL: 0.02%
+ Service: 0.01%
+ Receiver: 0.01%
+ (Cached): 11% (6.3MB-8.7MB-9.6MB/5.1MB-7.4MB-8.3MB over 4)
+ * com.android.chrome / u0a34 / v2272096:
+ TOTAL: 0.02%
+ Service: 0.01%
+ Receiver: 0.02%
+ (Cached): 90% (5.1MB-70MB-96MB/3.4MB-66MB-92MB over 15)
+ * com.google.android.apps.gcs / u0a94 / v14:
+ TOTAL: 0.02%
+ Service: 0.02%
+ (Cached): 17% (5.8MB-5.9MB-6.0MB/4.6MB-4.7MB-4.8MB over 2)
+ * com.android.chrome:privileged_process0 / u0a34 / v2272096:
+ TOTAL: 0.02%
+ Service: 0.01%
+ Receiver: 0.01%
+ (Cached): 73% (162MB-163MB-164MB/157MB-157MB-157MB over 13)
+ * com.android.chrome:sandboxed_process12 / u0a34 / v2272096:
+ TOTAL: 0.02%
+ Service: 0.01%
+ Receiver: 0.01%
+ (Cached): 73% (48MB-49MB-51MB/46MB-47MB-50MB over 13)
+ * com.google.android.apps.docs / u0a40 / v51410735:
+ TOTAL: 0.01%
+ Receiver: 0.01%
+ (Cached): 0.45% (10MB-10MB-10MB/9.3MB-9.3MB-9.3MB over 1)
+ * com.google.android.deskclock / u0a38 / v303:
+ TOTAL: 0.01%
+ Receiver: 0.01%
+ (Cached): 82% (2.5MB-3.3MB-4.3MB/1.7MB-2.3MB-3.2MB over 13)
+ * com.google.android.gm.exchange / u0a69 / v500065:
+ TOTAL: 0.01%
+ Imp Bg: 0.01%
+ (Cached): 27% (3.3MB-3.7MB-3.9MB/2.2MB-2.7MB-2.9MB over 6)
+ * com.android.cellbroadcastreceiver / u0a3 / v22:
+ TOTAL: 0.01%
+ Service: 0.01%
+ (Cached): 1.1% (3.5MB-3.5MB-3.5MB/2.5MB-2.5MB-2.5MB over 1)
+ * com.coulombtech / u0a106 / v26:
+ TOTAL: 0.01%
+ Receiver: 0.01%
+ (Cached): 21% (4.9MB-5.0MB-5.2MB/3.8MB-3.9MB-4.1MB over 2)
+ * com.softcoil.mms / u0a86 / v32:
+ TOTAL: 0.01%
+ (Cached): 0.25%
+ * com.udemy.android / u0a91 / v38:
+ TOTAL: 0.01%
+ Receiver: 0.01%
+ (Cached): 0.75% (9.8MB-9.8MB-9.8MB/8.5MB-8.5MB-8.5MB over 1)
+ * com.qualcomm.timeservice / u0a76 / v22:
+ (Cached): 16% (2.3MB-2.4MB-2.4MB/1.6MB-1.6MB-1.6MB over 4)
+ * com.lge.SprintHiddenMenu / 1000 / v22:
+ (Cached): 0.16%
+ * com.android.chrome:sandboxed_process13 / u0a34 / v2272096:
+ (Cached): 0.01%
+ * com.google.android.partnersetup / u0a13 / v22:
+ (Cached): 0.14%
+ * com.android.musicfx / u0a15 / v10400:
+ (Cached): 0.41% (2.5MB-2.5MB-2.5MB/1.6MB-1.6MB-1.6MB over 1)
+ * com.android.chrome:sandboxed_process9 / u0a34 / v2272096:
+ (Cached): 30% (34MB-34MB-34MB/32MB-32MB-32MB over 9)
+ * com.android.chrome:sandboxed_process11 / u0a34 / v2272096:
+ (Cached): 7.2% (56MB-56MB-56MB/54MB-54MB-54MB over 3)
+
+Run time Stats:
+ SOff/Norm: +32m52s226ms
+ SOn /Norm: +2h10m8s364ms
+ Mod : +17s930ms
+ TOTAL: +2h43m18s520ms
+
+Memory usage:
+ Kernel : 265MB (38 samples)
+ Native : 73MB (38 samples)
+ Persist: 262MB (90 samples)
+ Top : 190MB (325 samples)
+ ImpFg : 204MB (569 samples)
+ ImpBg : 754KB (345 samples)
+ Service: 93MB (1912 samples)
+ Receivr: 227KB (1169 samples)
+ Home : 66MB (12 samples)
+ LastAct: 30MB (255 samples)
+ CchAct : 220MB (450 samples)
+ CchCAct: 193MB (71 samples)
+ CchEmty: 182MB (652 samples)
+ Cached : 58MB (38 samples)
+ Free : 60MB (38 samples)
+ TOTAL : 1.9GB
+ ServRst: 50KB (278 samples)
+
+ Start time: 2015-04-08 13:44:18
+ Total elapsed time: +2h43m18s521ms (partial) libart.so
+</pre>
+
diff --git a/src/devices/tech/security/overview/acknowledgements.jd b/src/devices/tech/security/overview/acknowledgements.jd
index 6fe71f8..19e79ec 100644
--- a/src/devices/tech/security/overview/acknowledgements.jd
+++ b/src/devices/tech/security/overview/acknowledgements.jd
@@ -30,6 +30,19 @@
<p><a href="mailto:higongguang@gmail.com">Guang Gong</a> of <a href="http://www.360safe.com/">Qihoo 360 Technology Co. Ltd</a> (<a href="https://twitter.com/oldfresher">@oldfresher</a>)</p>
+<p>Stephan Huber of Testlab Mobile Security, <a
+href="https://www.sit.fraunhofer.de/">Fraunhofer SIT</a> (<a
+href="mailto:Stephan.Huber@sit.fraunhofer.de">Stephan.Huber@sit.fraunhofer.de</a>)
+</p>
+
+<p><a
+href="http://www.ec-spride.tu-darmstadt.de/en/research-groups/secure-software-engineering-group/staff/siegfried-rasthofer/">Siegfried
+Rasthofer</a> of <a href="http://sseblog.ec-spride.de/">Secure Software
+Engineering Group</a>, EC SPRIDE Technische Universität Darmstadt (<a
+href="mailto:siegfried.rasthofer@gmail.com">siegfried.rasthofer@gmail.com</a>)</p>
+
+<p><a href="mailto:laginimaineb@gmail.com">Gal Beniamini</a> (<a href="http://bits-please.blogspot.com">http://bits-please.blogspot.com</a>)</p>
+
</div>
<h2>2014</h2>
diff --git a/src/devices/tech/security/selinux/customize.jd b/src/devices/tech/security/selinux/customize.jd
index 592b9b4..63b3b56 100644
--- a/src/devices/tech/security/selinux/customize.jd
+++ b/src/devices/tech/security/selinux/customize.jd
@@ -72,9 +72,8 @@
<li>Put those policies in *.te files (the extension for SELinux policy source
files) within the <code>/device/manufacturer/device-name/sepolicy</code> directory and use
<code>BOARD_SEPOLICY</code> variables to include them in your build.
- <li>Make new domains permissive initially. In Android 4.4 and earlier, this is done
-using a permissive declaration. In later versions of Android, per-domain
-permissive mode is specified using the <code>permissive_or_unconfined()</code> macro.
+ <li>Make new domains permissive initially. This is done by
+using a permissive declaration in the domain's .te file.
<li>Analyze results and refine your domain definitions.
<li>Remove the permissive declaration when no further denials appear in userdebug
builds.
@@ -127,7 +126,7 @@
<pre>
type dhcp, domain;
-permissive_or_unconfined(dhcp)
+permissive dhcp;
type dhcp_exec, exec_type, file_type;
type dhcp_data_file, file_type, data_file_type;
@@ -162,7 +161,7 @@
security policy (<code>domain</code>). From the previous statement examples, we know DHCP can read from and write
to <code>/dev/null.</code></p>
-<p>In the second line, DHCP is identified as an experimental domain (<code>permissive_or_unconfined</code>) with only minimal rules enforced.</p>
+<p>In the second line, DHCP is identified as a permissive domain.</p>
<p>In the <code>init_daemon_domain(dhcp)</code> line, the policy states DHCP is spawned from <code>init</code> and is allowed to communicate with it.</p>
diff --git a/src/devices/tech/security/selinux/implement.jd b/src/devices/tech/security/selinux/implement.jd
index 655a6bc..aa89303 100644
--- a/src/devices/tech/security/selinux/implement.jd
+++ b/src/devices/tech/security/selinux/implement.jd
@@ -220,8 +220,8 @@
These should
be given domains EARLY in order to avoid adding rules to init or otherwise
confusing <code>init</code> accesses with ones that are in their own policy.
- <li>Set up <code>BOARD_CONFIG.mk</code> to use <code>BOARD_SEPOLICY_UNION</code> and <code>BOARD_SEPOLICY_DIRS</code>. See
-the README in /sepolicy for details on setting this up.
+ <li>Set up <code>BOARD_CONFIG.mk</code> to use <code>BOARD_SEPOLICY_*</code> variables. See
+the README in external/sepolicy for details on setting this up.
<li> Examine the init.<device>.rc and fstab.<device> file and make sure every use of “mount”
corresponds to a properly labeled filesystem or that a context= mount option is specified.
<li> Go through each denial and create SELinux policy to properly handle each. See
diff --git a/src/index.jd b/src/index.jd
index a0e4624..6cc69db 100644
--- a/src/index.jd
+++ b/src/index.jd
@@ -41,6 +41,43 @@
<div class="landing-docs">
<div class="col-8">
<h3>What's New</h3>
+<a href="{@docRoot}source/initializing.html">
+ <h4>Initializing Improvements</h4></a>
+ <p>Build environment <strong><a
+ href="{@docRoot}source/initializing.html#setting-up-a-mac-os-x-build-environment">Initializing</a></strong>
+ instructions now explain how to resize and unmount Mac OS sparse
+ images. And the ccache section has been moved to an optional <strong><a
+ href="{@docRoot}source/initializing.html#optimizing-a-build-environment">Optimizing
+ a build environment</a></strong> section.</p>
+
+<a href="{@docRoot}devices/tech/security/selinux/index.html">
+ <h4>SELinux Permissive Declarations</h4></a>
+ <p>SELinux <strong><a
+ href="{@docRoot}devices/tech/security/selinux/customize.html">Customizing</a></strong>
+ and <strong><a
+ href="{@docRoot}devices/tech/security/selinux/implement.html">Implementing</a></strong>
+ instructions have been updated to recommend using permissive declarations
+ directly as <code>permissive_or_unconfined()</code> has been deprecated.
+ Similarly, <code>BOARD_SEPOLICY_UNION</code> has been removed, so
+ <code>BOARD_SEPOLICY_*</code> variables are suggested insead.</p>
+
+<a href="{@docRoot}devices/input/diagnostics.html">
+ <h4>Dumpsys Input and System Diagnostics</h4></a>
+ <p>Dumpsys contents have been completely rewritten with fresh output
+ examples and split into <strong><a
+ href="{@docRoot}devices/input/diagnostics.html">Input Diagnostics</a></strong>
+ and <strong><a href="{@docRoot}devices/tech/debug/dumpsys.html">System
+ Diagnostics</a></strong>.</p>
+
+<a href="{@docRoot}devices/bluetooth.html">
+ <h4>Android 5.0 Bluetooth HCI Requirements</h4></a>
+ <p><strong><a
+ href="{@docRoot}devices/Android-5.0-Bluetooth-HCI-Reqs.pdf">Bluetooth
+ Host Controller Interface (HCI) requirements</a></strong> to leverage
+ the Bluetooth Low Energy APIs in Android 5.0 have
+ been published and linked from the <strong><a
+ href="{@docRoot}devices/bluetooth.html">Bluetooth</a></strong> introduction.</p>
+
<a href="{@docRoot}devices/tech/ota/index.html">
<h4>OTA Updates</h4></a>
<p>An entire suite of documentation has been added describing the <strong><a
@@ -61,43 +98,6 @@
boot</a></strong> and <strong><a
href="{@docRoot}devices/tech/security/verifiedboot/dm-verity.html">implementing
dm-verity</a></strong>.</p>
-
-<a href="{@docRoot}devices/graphics/testing.html">
- <h4>OpenGL ES Graphics Diagnostics</h4></a>
- <p>The graphics diagnostics user guide has been converted to an <strong><a
- href="{@docRoot}devices/graphics/testing.html">OpenGL ES
- testing</a></strong> section of the site for easy access to information for <strong><a
- href="{@docRoot}devices/graphics/build-tests.html">building test programs</a></strong>, <strong><a
- href="{@docRoot}devices/graphics/run-tests.html">running the tests</a></strong>, <strong><a
- href="{@docRoot}devices/graphics/test-groups.html">using special test groups</a></strong>, and more.</p>
-
-<a href="{@docRoot}devices/index.html">
- <h4>Devices Diagrams and Other Figures</h4></a>
- <p>Diagrams and other figures within <strong><a
- href="{@docRoot}devices/index.html">Devices</a></strong> have been redesigned
- to become more clear and adhere to Android’s material design theme.</p>
-
-<a href="{@docRoot}source/submit-patches.html">
- <h4>Submitting Patches</h4></a>
- <p>The <strong><a
- href="{@docRoot}source/submit-patches.html#resolving-sync-conflicts">Resolving
- sync conflicts section of Submitting Patches</a></strong> has been updated to
- replace an outdated <code>git rebase</code> command with: <code>repo
- rebase</code></p>
-
-<a href="{@docRoot}source/build-numbers.html">
- <h4>Lollipop API level, Build Tag</h4></a>
- <p>The latest <strong><a
- href="{@docRoot}source/build-numbers.html#platform-code-names-versions-api-levels-and-ndk-releases">Lollipop
- API level</a></strong> and <strong><a
- href="{@docRoot}source/build-numbers.html#source-code-tags-and-builds">build
- tag</a></strong> have been updated to 22 and LMY47D, respectively.</p>
-
-<a href="{@docRoot}compatibility/contact-us.html">
- <h4>Google Mobile Services Inquiry Form</h4></a>
- <p>Prospective Google Mobile Services (GMS) partners now have an online <strong><a
- href="https://docs.google.com/a/google.com/forms/d/1qAHuR-MbmXeYuJ1aBd3neaUjNGxnnnCd2kzb0MEJpGQ/viewform"
- target="_blank">inquiry form</a></strong> to request a GMS license.</p>
</div>
<div class="col-8">
diff --git a/src/source/build-numbers.jd b/src/source/build-numbers.jd
index 3337685..bff9b0d 100644
--- a/src/source/build-numbers.jd
+++ b/src/source/build-numbers.jd
@@ -187,7 +187,7 @@
<td>LMY47D</td>
<td>android-5.1.0_r1</td>
<td>Lollipop</td>
- <td>Nexus 5, Nexus 6, Nexus 7 (grouper), Nexus 10, Nexus Player</td>
+ <td>Nexus 5, Nexus 6, Nexus 7 (grouper/tilapia), Nexus 10, Nexus Player</td>
</tr>
<tr>
<td>LRX22G</td>
diff --git a/src/source/building-running.jd b/src/source/building-running.jd
index ed8c4b7..239ebe6 100644
--- a/src/source/building-running.jd
+++ b/src/source/building-running.jd
@@ -24,14 +24,14 @@
</div>
</div>
-The following instructions to build the Android source tree apply to all branches, including master.
+The following instructions to build the Android source tree apply to all branches, including <code>master</code>.
<h2 id="choosing-a-branch">Choosing a Branch</h2>
<p>Some of the requirements for your build environment are determined by which
version of the source code you plan to compile. See
<a href="build-numbers.html">Codenames, Tags, and Build Numbers</a> for a full listing of branches you may
choose from. You may also choose to download and build the latest source code
-(called "master"), in which case you will simply omit the branch specification
+(called <code>master</code>), in which case you will simply omit the branch specification
when you initialize the repository.</p>
<p>Once you have selected a branch, follow the appropriate instructions below to
set up your build environment.</p>
@@ -40,7 +40,7 @@
<p>The basic sequence of build commands is as follows:</p>
<h2 id="initialize">Initialize</h2>
<p>Initialize the environment with the <code>envsetup.sh</code> script. Note
-that replacing "source" with a single dot saves a few characters,
+that replacing <code>source</code> with <code>.</code> (a single dot) saves a few characters,
and the short form is more commonly used in documentation.</p>
<pre><code>$ source build/envsetup.sh
</code></pre>
@@ -49,12 +49,12 @@
</code></pre>
<h2 id="choose-a-target">Choose a Target</h2>
<p>Choose which target to build with <code>lunch</code>. The exact configuration can be passed as
-an argument, e.g. </p>
+an argument. For example, the following command:</p>
<pre><code>$ lunch aosp_arm-eng
</code></pre>
-<p>The example above refers to a complete build for the emulator, with all debugging enabled.</p>
+<p>refers to a complete build for the emulator, with all debugging enabled.</p>
<p>If run with no arguments <code>lunch</code> will prompt you to choose a target from the menu. </p>
-<p>All build targets take the form BUILD-BUILDTYPE, where the BUILD is a codename
+<p>All build targets take the form <code>BUILD-BUILDTYPE</code>, where the <code>BUILD</code> is a codename
referring to the particular feature combination. Here's a partial list:</p>
<table>
<thead>
@@ -111,7 +111,7 @@
<p>Build everything with <code>make</code>. GNU make can handle parallel
tasks with a <code>-jN</code> argument, and it's common to use a number of
tasks N that's between 1 and 2 times the number of hardware
-threads on the computer being used for the build. E.g. on a
+threads on the computer being used for the build. For example, on a
dual-E5520 machine (2 CPUs, 4 cores per CPU, 2 threads per core),
the fastest builds are made with commands between <code>make -j16</code> and
<code>make -j32</code>.</p>
@@ -126,7 +126,7 @@
<p>Once the device is in fastboot mode, run </p>
<pre><code>$ fastboot flashall -w
</code></pre>
-<p>The <code>-w</code> option wipes the <code>/data</code> partition on the device; this is useful for your first time flashing a particular device, but is otherwise unnecessary.</p>
+<p>The <code>-w</code> option wipes the <code>/data</code> partition on the device; this is useful for your first time flashing a particular device but is otherwise unnecessary.</p>
<p>For more information about building for and running on actual hardware, see
<a href="building-devices.html">Building for Devices.</a></p>
<h3 id="emulate-an-android-device">Emulate an Android Device</h3>
@@ -141,10 +141,10 @@
$ prebuilts/misc/linux-x86/ccache/ccache -M 50G
</code></pre>
<p>The suggested cache size is 50-100G.</p>
-<p>You can watch ccache being used by doing the following:</p>
+<p>On Linux, you can watch ccache being used by doing the following:</p>
<pre><code>$ watch -n1 -d prebuilts/misc/linux-x86/ccache/ccache -s
</code></pre>
-<p>On OSX, you should replace <code>linux-x86</code> with <code>darwin-x86</code>.</p>
+<p>On Mac OS, you should replace <code>linux-x86</code> with <code>darwin-x86</code>.</p>
<p>When using Ice Cream Sandwich (4.0.x) or older, you should replace
<code>prebuilts/misc</code> with <code>prebuilt</code>.</p>
<h2 id="troubleshooting-common-build-errors">Troubleshooting Common Build Errors</h2>
@@ -176,7 +176,7 @@
<pre><code>$ apt-get install python
</code></pre>
<h3 id="case-insensitive-filesystem">Case Insensitive Filesystem</h3>
-<p>If you are building on an HFS filesystem on Mac OS X, you may encounter an error such as</p>
+<p>If you are building on an HFS filesystem on Mac OS, you may encounter an error such as</p>
<pre><code>************************************************************
You are building on a case-insensitive filesystem.
Please move your source tree to a case-sensitive filesystem.
diff --git a/src/source/building.jd b/src/source/building.jd
index a0c3985..408ddb1 100644
--- a/src/source/building.jd
+++ b/src/source/building.jd
@@ -25,7 +25,7 @@
<ul>
- <li>A Linux or Mac system. It is also possible
+ <li>A Linux or Mac OS system. It is also possible
to build Android in a virtual machine on unsupported systems such as Windows.
If you are running Linux in a virtual machine, you need at
least 16GB of RAM/swap and 50GB or more of disk space in order to
diff --git a/src/source/initializing.jd b/src/source/initializing.jd
index 371e8e3..829a975 100644
--- a/src/source/initializing.jd
+++ b/src/source/initializing.jd
@@ -34,17 +34,17 @@
version of the source code you plan to compile. See
<a href="build-numbers.html">Build Numbers</a> for a full listing of branches you may
choose from. You may also choose to download and build the latest source code
-(called "master"), in which case you will simply omit the branch specification
+(called <code>master</code>), in which case you will simply omit the branch specification
when you initialize the repository.</p>
<p>Once you have selected a branch, follow the appropriate instructions below to
set up your build environment.</p>
<h2 id="setting-up-a-linux-build-environment">Setting up a Linux build environment</h2>
-<p>These instructions apply to all branches, including master.</p>
+<p>These instructions apply to all branches, including <code>master</code>.</p>
<p>The Android build is routinely tested in house on recent versions of
Ubuntu LTS (14.04), but most distributions should have the required
build tools available. Reports of successes or failures on other
distributions are welcome.</p>
-<p>For Gingerbread (2.3.x) and newer versions, including the master
+<p>For Gingerbread (2.3.x) and newer versions, including the <code>master</code>
branch, a 64-bit environment is required. Older versions can be
compiled on 32-bit systems.</p>
<p><strong>Note</strong>: See the <a href="building.html">Downloading and
@@ -52,7 +52,7 @@
follow the detailed instructions for Ubuntu and Mac OS below.</p>
<h3 id="installing-the-jdk">Installing the JDK</h3>
-<p>The master branch of Android in the <a
+<p>The <code>master</code> branch of Android in the <a
href="https://android.googlesource.com/">Android Open Source Project (AOSP)</a>
requires Java 7. On Ubuntu, use <a href="http://openjdk.java.net/install/">OpenJDK</a>.</p>
<p>Java 7: For the latest version of Android</p>
@@ -107,7 +107,7 @@
<pre><code>$ sudo apt-get install libx11-dev:i386
</code></pre>
<h3 id="configuring-usb-access">Configuring USB Access</h3>
-<p>Under GNU/linux systems (and specifically under Ubuntu systems),
+<p>Under GNU/Linux systems (and specifically under Ubuntu systems),
regular users can't directly access USB devices by default. The
system needs to be configured to allow such access.</p>
<p>The recommended approach is to create a file
@@ -155,33 +155,9 @@
back into the computer.</p>
<p>This is known to work on both Ubuntu Hardy Heron (8.04.x LTS) and
Lucid Lynx (10.04.x LTS). Other versions of Ubuntu or other
-variants of GNU/linux might require different configurations.</p>
-<p><a name="ccache"></a></p>
-<h3 id="setting-up-ccache">Setting up ccache</h3>
-<p>You can optionally tell the build to use the ccache compilation tool.
-Ccache acts as a compiler cache that can be used to speed-up rebuilds.
-This works very well if you do "make clean" often, or if you frequently
-switch between different build products.</p>
-<p>Put the following in your .bashrc or equivalent.</p>
-<pre><code>export USE_CCACHE=1
-</code></pre>
-<p>By default the cache will be stored in ~/.ccache.
-If your home directory is on NFS or some other non-local filesystem,
-you will want to specify the directory in your .bashrc as well.</p>
-<pre><code>export CCACHE_DIR=<path-to-your-cache-directory>
-</code></pre>
-<p>The suggested cache size is 50-100GB.
-You will need to run the following command once you have downloaded
-the source code:</p>
-<pre><code>prebuilts/misc/linux-x86/ccache/ccache -M 50G
-</code></pre>
-<p>When building Ice Cream Sandwich (4.0.x) or older, ccache is in
-a different location:</p>
-<pre><code>prebuilt/linux-x86/ccache/ccache -M 50G
-</code></pre>
-<p>This setting is stored in the CCACHE_DIR and is persistent.</p>
+variants of GNU/Linux might require different configurations.</p>
<h3 id="using-a-separate-output-directory">Using a separate output directory</h3>
-<p>By default, the output of each build is stored in the out/
+<p>By default, the output of each build is stored in the <code>out/</code>
subdirectory of the matching source tree.</p>
<p>On some machines with multiple storage devices, builds are
faster when storing the source files and the output on
@@ -205,37 +181,50 @@
as those would end up sharing an output directory, with
unpredictable results.</p>
<p>This is only supported on Jelly Bean (4.1) and newer,
-including the master branch.</p>
+including the <code>master</code> branch.</p>
<h2 id="setting-up-a-mac-os-x-build-environment">Setting up a Mac OS build environment</h2>
<p>In a default installation, Mac OS runs on a case-preserving but case-insensitive
filesystem. This type of filesystem is not supported by git and will cause some
-git commands (such as "git status") to behave abnormally. Because of this, we
+git commands (such as <code>git status</code>) to behave abnormally. Because of this, we
recommend that you always work with the AOSP source files on a case-sensitive
filesystem. This can be done fairly easily using a disk image, discussed below.</p>
-<p>Once the proper filesystem is available, building the master branch in a modern
+<p>Once the proper filesystem is available, building the <code>master</code> branch in a modern
Mac OS environment is very straightforward. Earlier branches, including ICS,
require some additional tools and SDKs.</p>
<h3 id="creating-a-case-sensitive-disk-image">Creating a case-sensitive disk image</h3>
<p>You can create a case-sensitive filesystem within your existing Mac OS environment
using a disk image. To create the image, launch Disk
Utility and select "New Image". A size of 25GB is the minimum to
-complete the build, larger numbers are more future-proof. Using sparse images
+complete the build; larger numbers are more future-proof. Using sparse images
saves space while allowing to grow later as the need arises. Be sure to select
"case sensitive, journaled" as the volume format.</p>
<p>You can also create it from a shell with the following command:</p>
<pre><code># hdiutil create -type SPARSE -fs 'Case-sensitive Journaled HFS+' -size 40g ~/android.dmg
</code></pre>
-<p>This will create a .dmg (or possibly a .dmg.sparsefile) file which, once mounted, acts as a drive with the required formatting for Android development. For a disk image named "android.dmg" stored in your home directory, you can add the following to your <code>~/.bash_profile</code> to mount the image when you execute "mountAndroid":</p>
+<p>This will create a <code>.dmg</code> (or possibly a <code>.dmg.sparsefile</code>) file which, once mounted, acts as a drive with the required formatting for Android development.
+<p>If you need a larger volume later, you can also resize the sparse image with the following command:</p>
+<pre><code># hdiutil resize -size <new-size-you-want>g ~/android.dmg.sparseimage
+</code></pre>
+For a disk image named <code>android.dmg</code> stored in your home directory, you can add helper functions to your <code>~/.bash_profile</code>:
+<ul>
+<li>
+To mount the image when you execute <code>mountAndroid</code>:</p>
<pre><code># mount the android file image
function mountAndroid { hdiutil attach ~/android.dmg -mountpoint /Volumes/android; }
</code></pre>
-
-<p><strong>Note</strong>: If your system created a .dmg.sparsefile file, replace <code>~/android.dmg</code> with <code>~/android.dmg.sparsefile</code>.</p>
-
-<p>Once you've mounted, the <code>android</code> volume, you'll do all your work there. You can eject it (unmount it) just like you would with an external drive.</p>
+<p><strong>Note</strong>: If your system created a <code>.dmg.sparsefile</code> file, replace <code>~/android.dmg</code> with <code>~/android.dmg.sparsefile</code>.</p>
+</li>
+<li>
+<p>To unmount it when you execute <code>umountAndroid</code>:</p>
+<pre><code># unmount the android file image
+function umountAndroid() { hdiutil detach /Volumes/android; }
+</code></pre>
+</li>
+</ul>
+<p>Once you've mounted the <code>android</code> volume, you'll do all your work there. You can eject it (unmount it) just like you would with an external drive.</p>
<h3 id="installing-the-mac-jdk">Installing the JDK</h3>
-<p>The master and 5.0.x branches of Android in the <a
+<p>The <code>master</code> and <code>5.0.x</code> branches of Android in the <a
href="https://android.googlesource.com/">Android Open Source Project (AOSP)</a>
require Java 7. On Mac OS, use <a
href="https://www.oracle.com/technetwork/java/javase/downloads/java-archive-downloads-javase7-521261.html#jdk-7u71-oth-JPR">jdk-7u71-macosx-x64.dmg</a>.</p>
@@ -246,17 +235,17 @@
<h3 id="master-branch">Master branch</h3>
<p>To build the latest source in a Mac OS environment, you will need an Intel/x86
-machine running MacOS 10.8 (Mountain Lion) or later, along with Xcode
+machine running Mac OS X v10.8 (Mountain Lion) or later, along with Xcode
4.5.2 or later including the Command Line Tools.</p>
<h3 id="branch-50x-and-all-earlier-branches">Branch 5.0.x and earlier branches</h3>
<p>To build 5.0.x and earlier source in a Mac OS environment, you will need an Intel/x86
-machine running MacOS 10.8 (Mountain Lion), along with Xcode
+machine running Mac OS X v10.8 (Mountain Lion), along with Xcode
4.5.2 and Command Line Tools.</p>
<h3 id="branch-44x-and-all-earlier-branches">Branch 4.4.x and earlier branches</h3>
<p>To build 4.2.x and earlier source in a Mac OS environment, you will need an Intel/x86
-machine running MacOS 10.6 (Snow Leopard) or MacOS 10.7 (Lion), along with Xcode
+machine running Mac OS X v10.6 (Snow Leopard) or Mac OS X v10.7 (Lion), along with Xcode
4.2 (Apple's Developer Tools). Although Lion does not come with a JDK, it should
install automatically when you attempt to build the source.</p>
<p>The remaining sections for Mac OS apply only to those who wish to build
@@ -264,13 +253,13 @@
<h3 id="branch-40x-and-all-earlier-branches">Branch 4.0.x and all earlier branches</h3>
<p>To build android-4.0.x and earlier branches in a Mac OS environment, you need an
-Intel/x86 machine running MacOS 10.5 (Leopard) or MacOS 10.6 (Snow Leopard). You
-will need the MacOS 10.5 SDK.</p>
+Intel/x86 machine running Mac OS X v10.5 (Leopard) or Mac OS X v10.6 (Snow Leopard). You
+will need the Mac OS X v10.5 SDK.</p>
<h4 id="installing-required-packages">Installing required packages</h4>
<ul>
<li>
<p>Install Xcode from <a href="http://developer.apple.com/">the Apple developer site</a>.
-We recommend version 3.1.4 or newer, i.e. gcc 4.2.
+We recommend version 3.1.4 or newer (e.g., gcc 4.2).
Version 4.x could cause difficulties.
If you are not already registered as an Apple developer, you will have to
create an Apple ID in order to download.</p>
@@ -289,7 +278,7 @@
<p>Get make, git, and GPG packages from MacPorts: </p>
<pre><code>$ POSIXLY_CORRECT=1 sudo port install gmake libsdl git gnupg
</code></pre>
-<p>If using Mac OS 10.4, also install bison:</p>
+<p>If using Mac OS X v10.4, also install bison:</p>
<pre><code>$ POSIXLY_CORRECT=1 sudo port install bison
</code></pre>
</li>
@@ -322,11 +311,39 @@
</li>
</ul>
<h4 id="setting-a-file-descriptor-limit">Setting a file descriptor limit</h4>
-<p>On MacOS the default limit on the number of simultaneous file descriptors open is too low and a highly parallel build process may exceed this limit.<br />
+<p>On Mac OS, the default limit on the number of simultaneous file descriptors open is too low and a highly parallel build process may exceed this limit.<br />
</p>
<p>To increase the cap, add the following lines to your <code>~/.bash_profile</code>: </p>
<pre><code># set the number of open files to be 1024
ulimit -S -n 1024
</code></pre>
+<h2 id="optimizing-a-build-environment">Optimizing a build environment (optional)</h2>
+<p><a name="ccache"></a></p>
+<h3 id="setting-up-ccache">Setting up ccache</h3>
+<p>You can optionally tell the build to use the ccache compilation tool.
+Ccache acts as a compiler cache that can be used to speed up rebuilds.
+This works very well if you use <code>make clean</code> often, or if you frequently
+switch between different build products.</p>
+<p>Put the following in your <code>.bashrc</code> (or equivalent):</p>
+<pre><code>export USE_CCACHE=1
+</code></pre>
+<p>By default the cache will be stored in <code>~/.ccache</code>.
+If your home directory is on NFS or some other non-local filesystem,
+you will want to specify the directory in your <code>.bashrc</code> file as well:</p>
+<pre><code>export CCACHE_DIR=<path-to-your-cache-directory>
+</code></pre>
+<p>The suggested cache size is 50-100GB.
+You will need to run the following command once you have downloaded
+the source code:</p>
+<pre><code>prebuilts/misc/linux-x86/ccache/ccache -M 50G
+</code></pre>
+<p>On Mac OS, you should replace <code>linux-x86</code> with <code>darwin-x86</code>:</p>
+<pre><code>prebuilts/misc/darwin-x86/ccache/ccache -M 50G
+</code></pre>
+<p>When building Ice Cream Sandwich (4.0.x) or older, ccache is in
+a different location:</p>
+<pre><code>prebuilt/linux-x86/ccache/ccache -M 50G
+</code></pre>
+<p>This setting is stored in the CCACHE_DIR and is persistent.</p>
<h2 id="next-download-the-source">Next: Download the source</h2>
<p>Your build environment is good to go! Proceed to <a href="downloading.html">downloading the source</a>.</p>