Merge "Docs: Basic edits, 80 char column, consistent phrasing"
diff --git a/src/devices/audio/images/round_trip_bar_graph.png b/src/devices/audio/images/round_trip_bar_graph.png
new file mode 100644
index 0000000..0476574
--- /dev/null
+++ b/src/devices/audio/images/round_trip_bar_graph.png
Binary files differ
diff --git a/src/devices/audio/images/round_trip_on_device.png b/src/devices/audio/images/round_trip_on_device.png
new file mode 100644
index 0000000..e1cf0a2
--- /dev/null
+++ b/src/devices/audio/images/round_trip_on_device.png
Binary files differ
diff --git a/src/devices/audio/images/round_trip_via_headset_connector.png b/src/devices/audio/images/round_trip_via_headset_connector.png
new file mode 100644
index 0000000..5791cf5
--- /dev/null
+++ b/src/devices/audio/images/round_trip_via_headset_connector.png
Binary files differ
diff --git a/src/devices/audio/latency.jd b/src/devices/audio/latency.jd
index d4b46a6..59c3f73 100644
--- a/src/devices/audio/latency.jd
+++ b/src/devices/audio/latency.jd
@@ -46,4 +46,8 @@
<a href="loopback.html">Audio Loopback Dongle</a>
</td>
</tr>
+<tr>
+ <td>Round-trip audio latency results</td>
+ <td><a href="latency_measurements.html">Audio Latency Measurements</a></td>
+</tr>
</table>
diff --git a/src/devices/audio/latency_measurements.jd b/src/devices/audio/latency_measurements.jd
new file mode 100644
index 0000000..a85c77d
--- /dev/null
+++ b/src/devices/audio/latency_measurements.jd
@@ -0,0 +1,369 @@
+page.title=Audio Latency Measurements
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>
+This article gives round-trip audio latency measurements for select devices and
+platform versions.
+</p>
+
+<h2 id="definition">Definition</h2>
+
+<p>
+<a href="http://en.wikipedia.org/wiki/Latency_%28engineering%29">Latency</a>
+is an important system performance metric. There are many kinds
+of <a href="latency.html">audio latency</a>
+metrics. One useful and well-understood metric is
+<a href="latency_measure.html#measuringRoundTrip">round-trip latency</a>.
+Round-trip latency is defined as the time it takes for
+an audio signal to enter the input of a mobile device, be processed
+by an app running on the application processor, and exit the output.
+</p>
+
+<img src="images/round_trip_on_device.png" alt="Round-trip audio latency on device" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> Round-trip audio latency on device: T<sub>output</sub> - T<sub>input</sub>
+</p>
+
+<h2 id="why">Why we measure latency</h2>
+
+<p>
+We measure and report latency so Android
+app developers will have the data they need to make informed decisions about available
+latency on actual devices. By sharing these numbers for select Nexus devices, we also hope to
+encourage the entire Android community to measure, publish, and reduce
+latency on <i>all</i> devices.
+Please join us in our commitment to reducing audio latency.
+</p>
+
+<h2 id="app">Application impact on latency</h2>
+
+<p>
+There are two kinds of delays that a signal processing stage can add to latency:
+algorithmic delay and computational delay.
+Algorithmic delay is inherent and does not vary with the CPU.
+An example is the delay added by a
+<a href="http://en.wikipedia.org/wiki/Finite_impulse_response">finite impulse response</a>
+(FIR) filter.
+Computational delay is related to the number of CPU cycles required.
+For example, attenuation of a signal is usually done by a multiplication operation,
+and this multiplication will take a varying number of cycles depending on the CPU.
+</p>
+
+<h2 id="how">How we measure</h2>
+
+<p>
+The measurements below were taken with the
+<a href="loopback.html">Dr. Rick O’Rang audio loopback dongle</a>
+and an
+<a href="latency_measure.html#larsenTest">audio feedback (Larsen effect) test</a>.
+</p>
+
+<p>
+For our measurements, we assume the application signal processing
+adds zero algorithmic delay and near zero computational delay.
+</p>
+
+<p>
+We measure round-trip latency via the headset connector for several reasons:
+</p>
+<ul>
+ <li>
+ There are important music applications, such as guitar and voice processing,
+ that use the headset connector.
+ </li>
+ <li>
+ Measuring round-trip latency of the on-device microphone and speaker can
+ be cumbersome, as it is difficult to keep a feedback loop in open air from entering
+ uncontrolled oscillation.
+ </li>
+ <li>
+ The on-device transducers are small and sacrifice frequency response
+ to achieve their small size. To compensate, digital signal processing is
+ applied but increases algorithmic delay for the on-device path.
+ </li>
+</ul>
+
+<p>
+There are cases where on-device microphone and speaker latencies
+<i>do</i>
+matter, but they are usually for one direction, not round-trip.
+Techniques for measuring unidirectional latency are described at
+<a href="latency_measure.html#measuringOutput">Measuring Output Latency</a>
+and
+<a href="latency_measure.html#measuringInput">Measuring Input Latency</a>.
+</p>
+
+<img src="images/round_trip_via_headset_connector.png" alt="Round-trip latency via headset connector" id="figure2" />
+<p class="img-caption">
+ <strong>Figure 2.</strong> Round-trip latency via headset connector: T<sub>output</sub> - T<sub>input</sub>
+</p>
+
+<h2 id="measurements">Example measurements</h2>
+
+<p>
+The measurements shown are specific to a
+<a href="{@docRoot}source/build-numbers.html">build number</a>.
+Devices are listed in approximate order of initial release and within device by platform version.
+The test application uses the Android native audio API based on OpenSL ES.
+</p>
+
+<table>
+<tr>
+ <th>Model</th>
+ <th>Platform<br />version</th>
+ <th>Build<br />number</th>
+ <th>Sample rate<br />(Hz)</th>
+ <th>Buffer size<br />(frames)</th>
+ <th>Buffer size<br />(ms)</th>
+ <th>Round-trip<br />latency (ms)<br />± one buffer</th>
+</tr>
+
+<tr>
+ <td>Nexus One</td>
+ <td>2.3.6</td>
+ <td>GRK39F</td>
+ <td>44100</td>
+ <td>768</td>
+ <td>17.4</td>
+ <td>345</td>
+</tr>
+
+<tr>
+ <td>Nexus S</td>
+ <td>2.3.6</td>
+ <td>GRK39F</td>
+ <td>44100</td>
+ <td>1024</td>
+ <td>23.2</td>
+ <td>260</td>
+</tr>
+
+<tr>
+ <td>Nexus S</td>
+ <td>4.0.4</td>
+ <td>IMM76D</td>
+ <td>44100</td>
+ <td>1024</td>
+ <td>23.2</td>
+ <td>260</td>
+</tr>
+
+<tr>
+ <td>Nexus S</td>
+ <td>4.1.2</td>
+ <td>JZO54K</td>
+ <td>44100</td>
+ <td>880</td>
+ <td>20</td>
+ <td>210</td>
+</tr>
+
+<tr>
+ <td>Galaxy Nexus</td>
+ <td>4.0.1</td>
+ <td>ITL41D</td>
+ <td>44100</td>
+ <td>976</td>
+ <td>22.1</td>
+ <td>270</td>
+</tr>
+
+<tr>
+ <td>Galaxy Nexus</td>
+ <td>4.3</td>
+ <td>JWR66Y</td>
+ <td>44100</td>
+ <td>144</td>
+ <td>3.3</td>
+ <td>130</td>
+</tr>
+
+<tr>
+ <td>Nexus 4</td>
+ <td>4.2.2</td>
+ <td>JDQ39E</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>195</td>
+</tr>
+
+<tr>
+ <td>Nexus 4</td>
+ <td>5.1</td>
+ <td>LMY47R</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>58</td>
+</tr>
+
+<tr>
+ <td>Nexus 10</td>
+ <td>5.0.2</td>
+ <td>LRX22G</td>
+ <td>44100</td>
+ <td>256</td>
+ <td>5.8</td>
+ <td>36</td>
+</tr>
+
+<tr>
+ <td>Nexus 10</td>
+ <td>5.1</td>
+ <td>LMY47D</td>
+ <td>44100</td>
+ <td>256</td>
+ <td>5.8</td>
+ <td>35</td>
+</tr>
+
+<tr>
+ <td>Nexus 7<br />2013</td>
+ <td>4.3</td>
+ <td>JSR78D</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>149</td>
+</tr>
+
+<tr>
+ <td>Nexus 7<br />2013</td>
+ <td>4.4</td>
+ <td>KRT16S</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>85</td>
+</tr>
+
+<tr>
+ <td>Nexus 7<br />2013</td>
+ <td>5.0.2</td>
+ <td>LRX22G</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>64</td>
+</tr>
+
+<tr>
+ <td>Nexus 7<br />2013</td>
+ <td>5.1.1</td>
+ <td>LMY47W</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>55</td>
+</tr>
+
+<tr>
+ <td>Nexus 5</td>
+ <td>4.4.4</td>
+ <td>KTU84P</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>95</td>
+</tr>
+
+<tr>
+ <td>Nexus 5</td>
+ <td>5.0.0_r3.0.1</td>
+ <td>LRX21O</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>47</td>
+</tr>
+
+<tr>
+ <td>Nexus 5</td>
+ <td>5.1</td>
+ <td>LMY47M</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>42</td>
+</tr>
+
+<tr>
+ <td>Nexus 9</td>
+ <td>5.0.0</td>
+ <td>LRX21L</td>
+ <td>48000</td>
+ <td>256</td>
+ <td>5.3</td>
+ <td>35</td>
+</tr>
+
+<tr>
+ <td>Nexus 9</td>
+ <td>5.0.1</td>
+ <td>LRX22C</td>
+ <td>48000</td>
+ <td>256</td>
+ <td>5.3</td>
+ <td>38</td>
+</tr>
+
+<tr>
+ <td>Nexus 9</td>
+ <td>5.1.1</td>
+ <td>LMY47S</td>
+ <td>48000</td>
+ <td>256</td>
+ <td>5.3</td>
+ <td>32</td>
+</tr>
+
+<tr>
+ <td>Nexus 6</td>
+ <td>5.0.1</td>
+ <td>LRX22C</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>65</td>
+</tr>
+
+<tr>
+ <td>Nexus 6</td>
+ <td>5.1</td>
+ <td>LMY47I</td>
+ <td>48000</td>
+ <td>240</td>
+ <td>5</td>
+ <td>42</td>
+</tr>
+
+</table>
+
+<img src="images/round_trip_bar_graph.png" alt="Round-trip latency bar graph" id="figure3" />
+<p class="img-caption">
+ <strong>Figure 3.</strong> Round-trip latency bar graph
+</p>
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 35ef3b4..464dd98 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -45,6 +45,7 @@
<li><a href="<?cs var:toroot ?>devices/audio/latency_measure.html">Measure</a></li>
<li><a href="<?cs var:toroot ?>devices/audio/testing_circuit.html">Light Testing Circuit</a></li>
<li><a href="<?cs var:toroot ?>devices/audio/loopback.html">Audio Loopback Dongle</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/latency_measurements.html">Measurements</a></li>
</ul>
</li>
<li><a href="<?cs var:toroot ?>devices/audio/avoiding_pi.html">Priority Inversion</a></li>
@@ -250,6 +251,8 @@
</ul>
</li>
+ <li><a href="<?cs var:toroot ?>devices/tech/netstats.html">Viewing Network Data</a></li>
+
<li>
<a href="<?cs var:toroot ?>devices/tech/power.html">
<span class="en">Power</span>
diff --git a/src/devices/tech/debug/dumpsys.jd b/src/devices/tech/debug/dumpsys.jd
index 959385e..f971bb3 100644
--- a/src/devices/tech/debug/dumpsys.jd
+++ b/src/devices/tech/debug/dumpsys.jd
@@ -95,11 +95,12 @@
following articles:</p>
<ul>
- <li> <a href="{@docRoot}devices/input/diagnostics.html">Input Diagnostics</a>
+ <li> <a
+ href="{@docRoot}devices/input/diagnostics.html">Viewing Input Diagnostics (dumpsys input)</a>
+ <li> <a href="{@docRoot}devices/tech/ram/procstats.html">Viewing RAM Usage Data (dumpsys procstats)</a>
+ <li> <a href="{@docRoot}devices/tech/netstats.html">Viewing Network Data (dumpsys netstats)</a>
<!-- 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/netstats.jd b/src/devices/tech/netstats.jd
new file mode 100644
index 0000000..8c9097c
--- /dev/null
+++ b/src/devices/tech/netstats.jd
@@ -0,0 +1,140 @@
+page.title=Viewing Network Usage Data
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<p>Using the command <code>adb shell dumpsys netstats detail</code> provides
+network usage statistics collected since the device booted up.</p>
+
+<h2 id=input>Input</h2>
+
+
+<p>To view network usage statistics, run the following command:</p>
+
+<pre class=prettyprint>
+$ adb shell dumpsys netstats detail
+</pre>
+
+
+<h2 id=output>Output</h2>
+
+
+<p>The set of information reported varies depending on the version of Android but
+consists of several sections: </p>
+
+<ul>
+ <li> Active interfaces
+ <li> Active UID interfaces
+ <li> Dev statistics
+ <li> Xt statistics
+ <li> UID statistics (sometimes also called "Detailed UID statistics")
+ <li> UID tag statistics
+</ul>
+
+<h3 id=active_interfaces_active_uid_interfaces>Active interfaces/Active UID interfaces</h3>
+
+<p>Here is sample output for the active interfaces and active UID interfaces
+sections:</p>
+
+<pre>
+Active interfaces:
+ iface=wlan0 ident=[{type=WIFI, subType=COMBINED, networkId="GoogleGuest"}]
+Active UID interfaces:
+ iface=wlan0 ident=[{type=WIFI, subType=COMBINED, networkId="GoogleGuest"}]
+</pre>
+
+
+<p>This shows network statistics for the whole device. In most cases, the
+information in these two section is the same.</p>
+
+<h3 id=dev_stats_xt_stats>Dev statistics/Xt statistics</h3>
+
+
+<p>Here is sample output for the Dev statistics section:</p>
+
+<pre>
+Dev stats:
+ Pending bytes: 170775
+ Complete history:
+ ident=[[type=MOBILE_HIPRI, subType=COMBINED, subscriberId=311111...]] uid=-1 set=ALL tag=0x0
+ NetworkStatsHistory: bucketDuration=3600000
+ bucketStart=1406138400000 activeTime=3603995 rxBytes=19467 rxPackets=53 txBytes=7500 txPackets=61 operations=0
+ bucketStart=1406142000000 activeTime=20730 rxBytes=25403 rxPackets=66 txBytes=9140 txPackets=74 operations=0
+ bucketStart=1406145600000 activeTime=29161 rxBytes=9263 rxPackets=37 txBytes=5180 txPackets=38 operations=0
+ bucketStart=1406149200000 activeTime=9054 rxBytes=12387 rxPackets=31 txBytes=4052 txPackets=35 operations=0
+ ident=[[type=WIFI, subType=COMBINED, networkId="MySSID"]] uid=-1 set=ALL tag=0x0
+ NetworkStatsHistory: bucketDuration=3600000
+ bucketStart=1406138400000 activeTime=4811082 rxBytes=335913292 rxPackets=265144 txBytes=9729261 txPackets=117220 operations=0
+ bucketStart=1406142000000 activeTime=3513477 rxBytes=1193606876 rxPackets=956855 txBytes=29450792 txPackets=306634 operations=0
+ bucketStart=1406145600000 activeTime=3297986 rxBytes=729381849 rxPackets=586396 txBytes=24247211 txPackets=237438 operations=0
+ bucketStart=1406149200000 activeTime=3580941 rxBytes=57168575 rxPackets=51610 txBytes=5291167 txPackets=29260 operations=0
+ ident=[[type=WIFI, subType=COMBINED, networkId="MySecondSSID"]] uid=-1 set=ALL tag=0x0
+ NetworkStatsHistory: bucketDuration=3600000
+</pre>
+
+<h3 id=uid_stats>UID stats</h3>
+
+<pre>
+UID stats:
+ Pending bytes: 744
+ Complete history:
+ ident=[[type=MOBILE_SUPL, subType=COMBINED, subscriberId=311111...], [type=MOBILE, subType=COMBINED, subscriberId=311111...]] uid=10007 set=DEFAULT tag=0x0
+ NetworkStatsHistory: bucketDuration=7200000
+ bucketStart=1406167200000 activeTime=7200000 rxBytes=4666 rxPackets=7 txBytes=1597 txPackets=10 operations=0
+ ident=[[type=WIFI, subType=COMBINED, networkId="MySSID"]] uid=10007 set=DEFAULT tag=0x0
+ NetworkStatsHistory: bucketDuration=7200000
+ bucketStart=1406138400000 activeTime=7200000 rxBytes=17086802 rxPackets=15387 txBytes=1214969 txPackets=8036 operations=28
+ bucketStart=1406145600000 activeTime=7200000 rxBytes=2396424 rxPackets=2946 txBytes=464372 txPackets=2609 operations=70
+ bucketStart=1406152800000 activeTime=7200000 rxBytes=200907 rxPackets=606 txBytes=187418 txPackets=739 operations=0
+ bucketStart=1406160000000 activeTime=7200000 rxBytes=826017 rxPackets=1126 txBytes=267342 txPackets=1175 operations=35
+</pre>
+
+
+<h3 id=interpreting_the_results>Interpreting the results</h3>
+
+
+<p>To find the UID for your application, you can run this command:
+<code>adb shell dumpsys package <your package name></code>.
+Then look for the line labeled <code>userId</code>.</p>
+
+<p>In our example, suppose we are trying to find network usage for our app
+“com.example.myapp”. We would run the following command:</p>
+
+<pre>
+$ adb shell dumpsys package com.example.myapp | grep userId
+
+ userId=10007 gids=[3003, 1028, 1015]
+</pre>
+
+<p>Looking at the dump above, we look for lines that have uid=10007. Two such
+lines exist, the first indicating a mobile connection, and the second a Wi-Fi
+connection. Underneath each line, the number of bytes and packets sent and
+received can be seen, bucketed into two-hour windows. </p>
+
+<p>A bit more explanation:</p>
+
+<ul>
+ <li> <code>set=DEFAULT</code> indicates foreground
+ network usage, while <code>set=BACKGROUND</code> indicates
+background usage. <code>set=ALL</code> implies both.
+ <li> <code>tag=0x0</code> indicates the socket tag associated with the traffic.
+ <li> <code>rxBytes</code> and <code>rxPackets</code> represent received bytes and received packets in the
+corresponding time interval.
+ <li> <code>txBytes</code> and <code>txPackets</code> represent sent (transmitted) bytes and sent packets in
+the corresponding time interval.
+</ul>
+
