Docs: Changes to source.android.com

- 178024672 CDD updates for Android 8.1 (O MR1). by Gina Dimino <gdimino@google.com> - 178024315 Document tags pushed to AOSP for December Security Releas... by Android Partner Docs <noreply@android.com> - 178019963 Add TextClassifier feature to Site Updates. by Mark Hecomovich <mheco@google.com> - 177986632 Add CTS/CTS-Verifier downloads for CTS-8.1R1 Release by Android Partner Docs <noreply@android.com> - 177981307 Update December Pixel bulletin to note that firmware imag... by Android Partner Docs <noreply@android.com> - 177977792 Note Source->Setup rename in site updates. by Billy Lamberta <blamb@google.com> - 177972113 Add O MR1 doc changes to Site Updates by Clay Murphy <claym@google.com> - 177970750 Integrate O MR1 branch into mainline by Clay Murphy <claym@google.com> - 177966804 Fix typo: Digital Stream Digital > Direct Stream Digital by Christina Nguyen <cqn@google.com> - 177966781 Exclude Android 8.1 compatibility directory from localiza... by Danielle Roberts <daroberts@google.com> - 177857487 Specify additional ABI breaking changes. by Android Partner Docs <noreply@android.com> - 177855089 Add attribution for William Roberts by Danielle Roberts <daroberts@google.com> - 177844366 Devsite localized content from translation request 63bb47... by Android Partner Docs <noreply@android.com> - 177840956 Devsite localized content from translation request 3a9204... by Android Partner Docs <noreply@android.com> - 177840933 Devsite localized content from translation request 526dee... by Android Partner Docs <noreply@android.com> - 177840699 Devsite localized content from translation request f000cb... by Android Partner Docs <noreply@android.com> - 177833559 Fix table in Dec pixel bulletin by Danielle Roberts <daroberts@google.com> - 177832645 Fix broken link in Security bulletin by Danielle Roberts <daroberts@google.com> - 177830793 Fix index files for security bulletins by Danielle Roberts <daroberts@google.com> - 177829204 December 2017 Android and Pixel security bulletins by Danielle Roberts <daroberts@google.com> - 177619977 Add links to most recently localized files by Clay Murphy <claym@google.com> - 177553556 Devsite localized content from translation request df5038... by Android Partner Docs <noreply@android.com> - 177553553 Devsite localized content from translation request 3feff8... by Android Partner Docs <noreply@android.com> - 177553549 Devsite localized content from translation request 57c74f... by Android Partner Docs <noreply@android.com> - 177530761 Devsite localized content from translation request 52ae7a... by Android Partner Docs <noreply@android.com> - 177530750 Devsite localized content from translation request f48e7b... by Android Partner Docs <noreply@android.com> - 177402074 Make CVE-2017-0639 optional by Android Partner Docs <noreply@android.com> - 177220538 Devsite localized content from translation request eaaf1d... by Android Partner Docs <noreply@android.com> - 177208086 Fixing bad link. by Heidi von Markham <hvm@google.com> - 177091447 updated CVEs by Android Partner Docs <noreply@android.com> - 177091159 Devsite localized content from translation request dcaa09... by Android Partner Docs <noreply@android.com> - 177091156 Devsite localized content from translation request 23af27... by Android Partner Docs <noreply@android.com> - 177087486 Update HIDL documentation to reflect actual passthrough i... by Android Partner Docs <noreply@android.com> PiperOrigin-RevId: 178024672 Change-Id: I593c61d26aac1fdcebb184ac048dbca7696161b1
author: Android Partner Docs <noreply@android.com> 2017-12-05 15:57:15 -0800
committer: Clay Murphy <claym@google.com> 2017-12-05 21:16:56 -0800
commit: a63d28d20492979243f7cac739a506d308334a86 (patch)
tree: ae2e203f4bf4eb3072e9a06ba2e512dc9230d8da /en/devices/audio
parent: 54024816e734bc99e432f281baabcf4718b9197a (diff)
download: source.android.com-a63d28d20492979243f7cac739a506d308334a86.tar.gz
4 files changed, 365 insertions, 2 deletions
diff --git a/en/devices/audio/aaudio.html b/en/devices/audio/aaudio.html
new file mode 100644
index 00000000..fb62ab87
--- /dev/null
+++ b/en/devices/audio/aaudio.html
@@ -0,0 +1,359 @@
+<html devsite>
+  <head>
+    <title>AAudio and MMAP</title>
+    <meta name="project_path" value="/_project.yaml" />
+    <meta name="book_path" value="/_book.yaml" />
+  </head>
+  <body>
+  <!--
+      Copyright 2017 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>
+AAudio is an audio API introduced in the Android 8.0 release. The Android 8.1
+release has enhancements to reduce latency when used in conjunction with a HAL
+and driver that support MMAP. This document describes the hardware abstraction
+layer (HAL) and driver changes needed to support AAudio's MMAP feature in
+Android.
+</p>
+
+<p>
+Support for AAudio MMAP requires:
+</p>
+
+<ul>
+<li>reporting the MMAP capabilities of the HAL
+<li>implementing new functions in the HAL
+<li>optionally implementing a custom ioctl() for the EXCLUSIVE mode buffer
+<li>providing an additional hardware data path</li>
+<li>setting system properties that enable MMAP feature</li>
+</ul>
+
+<aside class="note"><strong>Note:</strong> Enable the MMAP feature
+only on Android O MR1 or higher.</aside>
+
+<h2 id="aaudio-architecture">AAudio architecture</h2>
+
+<p>
+<a
+href="https://developer.android.com/ndk/guides/audio/aaudio/aaudio.html">AAudio</a>
+is a new native C API that provides an alternative to Open SL ES. It uses a
+Builder design pattern to create audio streams.
+</p>
+
+<p>
+AAudio provides a low-latency data path. In EXCLUSIVE mode, the feature
+allows client application code to write directly into a memory mapped buffer
+that is shared with the ALSA driver. In SHARED mode, the MMAP buffer is used by
+a mixer running in the AudioServer. In EXCLUSIVE mode, the latency is
+significantly less because the data bypasses the mixer.
+</p>
+
+<p>
+In EXCLUSIVE mode, the service requests the MMAP buffer from the HAL and manages
+the resources. The MMAP buffer is running in NOIRQ mode, so there are no shared
+read/write counters to manage access to the buffer. Instead, the client
+maintains a timing model of the hardware and predicts when the buffer will be
+read.
+</p>
+
+<p>
+In the diagram below, we can see the Pulse-code modulation (PCM) data flowing
+down through the MMAP FIFO into the ALSA driver.  Timestamps are periodically
+requested by the AAudio service and then passed up to the client's timing model
+through an atomic message queue.
+</p>
+
+<figure id="pcm-data-flow">
+  <img src="/devices/audio/images/pcm_data_flow.png"
+    width="630"
+    alt="PCM data flow diagram.">
+  <figcaption><b>Figure 1.</b> PCM data flow through FIFO to ALSA</figcaption>
+</figure>
+
+<p>
+In SHARED mode, a timing model is also used, but it lives in the AAudioService.
+</p>
+
+<p>
+For audio capture, a similar model is used, but the PCM data flows in the
+opposite direction.
+</p>
+
+<h2 id="hal-changes">HAL changes</h2>
+<p>
+For tinyALSA see:
+</p>
+
+<pre
+class="prettyprint">
+external/tinyalsa/include/tinyalsa/asoundlib.h
+external/tinyalsa/include/tinyalsa/pcm.c
+</pre>
+
+<pre
+class="prettyprint">
+int pcm_start(struct pcm *pcm);
+int pcm_stop(struct pcm *pcm);
+int pcm_mmap_begin(struct pcm *pcm, void **areas,
+           unsigned int *offset,
+           unsigned int *frames);
+int pcm_get_poll_fd(struct pcm *pcm);
+int pcm_mmap_commit(struct pcm *pcm, unsigned int offset,
+           unsigned int frames);
+int pcm_mmap_get_hw_ptr(struct pcm* pcm, unsigned int *hw_ptr,
+           struct timespec *tstamp);
+</pre>
+
+<p>
+For the legacy HAL, see:
+</p>
+
+<pre
+class="prettyprint">
+hardware/libhardware/include/hardware/audio.h
+hardware/qcom/audio/hal/audio_hw.c
+</pre>
+
+<pre
+class="prettyprint">
+int start(const struct audio_stream_out* stream);
+int stop(const struct audio_stream_out* stream);
+int create_mmap_buffer(const struct audio_stream_out *stream,
+                        int32_t min_size_frames,
+                        struct audio_mmap_buffer_info *info);
+int get_mmap_position(const struct audio_stream_out *stream,
+                        struct audio_mmap_position *position);
+</pre>
+
+<p>
+For HIDL audio HAL:
+</p>
+
+<pre
+class="prettyprint">
+hardware/interfaces/audio/2.0/IStream.hal
+hardware/interfaces/audio/2.0/types.hal
+hardware/interfaces/audio/2.0/default/Stream.h
+</pre>
+
+<pre
+class="prettyprint">
+start() generates (Result retval);
+stop() generates (Result retval) ;
+createMmapBuffer(int32_t minSizeFrames)
+       generates (Result retval, MmapBufferInfo info);
+getMmapPosition()
+       generates (Result retval, MmapPosition position);
+</pre>
+
+<h3 id="reporting-mmap-support">Reporting MMAP support</h3>
+
+<p>
+System property "aaudio.mmap_policy" should be set to 2 (AAUDIO_POLICY_AUTO) so
+the audio framework knows that MMAP mode is supported by the audio HAL. (see
+"Enabling AAudio MMAP Data Path" below.)
+</p>
+
+<p>
+audio_policy_configuration.xml file must also contain an output and input
+profile specific to MMAP/NO IRQ mode so that the Audio Policy Manager knows
+which stream to open when MMAP clients are created:
+</p>
+
+<pre
+class="prettyprint">
+&lt;mixPort name="mmap_no_irq_out" role="source"
+            flags="AUDIO_OUTPUT_FLAG_DIRECT|AUDIO_OUTPUT_FLAG_MMAP_NOIRQ"&gt;
+            &lt;profile name="" format="AUDIO_FORMAT_PCM_16_BIT"
+                                samplingRates="48000"
+                                channelMasks="AUDIO_CHANNEL_OUT_STEREO"/&gt;
+&lt;/mixPort&gt;
+
+&lt;mixPort name="mmap_no_irq_in" role="sink" flags="AUDIO_INPUT_FLAG_MMAP_NOIRQ"&gt;
+            &lt;profile name="" format="AUDIO_FORMAT_PCM_16_BIT"
+                                samplingRates="48000"
+                                channelMasks="AUDIO_CHANNEL_IN_STEREO"/&gt;
+&lt;/mixPort&gt;
+</pre>
+
+<h3 id="opening-and-closing-an-mmap-stream">Opening and closing an MMAP
+stream</h3>
+
+<pre
+class="prettyprint">
+createMmapBuffer(int32_t minSizeFrames)
+            generates (Result retval, MmapBufferInfo info);
+</pre>
+
+<p>
+The MMAP stream can be opened and closed by calling Tinyalsa functions.
+</p>
+
+<h3 id="querying-mmap-position">Querying MMAP position</h3>
+
+<p>
+The timestamp passed back to the Timing Model contains a frame position and a
+MONOTONIC time in nanoseconds:
+</p>
+
+<pre
+class="prettyprint">
+getMmapPosition()
+        generates (Result retval, MmapPosition position);
+</pre>
+
+<p>
+The HAL can obtain this information from the ALSA driver by calling a new
+Tinyalsa function:
+</p>
+
+<pre
+class="prettyprint">
+int pcm_mmap_get_hw_ptr(struct pcm* pcm,
+                        unsigned int *hw_ptr,
+                        struct timespec *tstamp);
+</pre>
+
+<h2 id="kernel-changes">Kernel changes</h2>
+
+<p>
+Enable MMAP/NOIRQ mode in the driver.
+</p>
+
+<p>
+The shared memory is referenced using a file descriptor that is generated by the
+ALSA driver.  If the file descriptor is directly associated with a
+<code>/dev/snd/</code> driver file, then it can be used by the AAudio service in
+SHARED mode. But the descriptor cannot be passed to the client code for
+EXCLUSIVE mode. The <code>/dev/snd/</code> file descriptor would provide too
+broad of access to the client, so it is blocked by SELinux.
+</p>
+
+<p>
+In order to support EXCLUSIVE mode, it is necessary to convert the
+<code>/dev/snd/</code> descriptor to an <code>anon_inode:dmabuffer</code> file
+descriptor. SELinux allows that file descriptor to be passed to the client. It
+can also be used by the AAudioService.
+</p>
+
+<p>
+An <code>anon_inode:dmabuffer</code> file descriptor can be generated using the
+Android Ion memory library.
+</p>
+
+<p>
+For additional information, see these external resources:
+</p>
+
+<ol>
+<li>"The Android ION memory allocator" <a
+href="https://lwn.net/Articles/480055/">https://lwn.net/Articles/480055/</a>
+<li>"Android ION overview" <a
+href="https://wiki.linaro.org/BenjaminGaignard/ion">https://wiki.linaro.org/BenjaminGaignard/ion</a>
+<li>"Integrating the ION memory allocator" <a
+href="https://lwn.net/Articles/565469/">https://lwn.net/Articles/565469/</a></li>
+</ol>
+
+<p>
+The AAudio service needs to know if this <code>anon_inode:dmabuffer</code> is
+supported. Currently, the only way to do that is to pass the size of the MMAP
+buffer as a negative number, eg. -2048 instead of 2048, if supported.  A better
+way of reporting this without having to open the stream is planned.
+</p>
+
+<h2 id="audio-subsystem-changes">Audio subsystem changes</h2>
+
+<p>
+AAudio requires an additional data path at the audio front end of the audio
+subsystem so it can operate in parallel with the original AudioFlinger path.
+That legacy path is used for all other system sounds and application sounds.
+This functionality could be provided by a software mixer in a DSP or a hardware
+mixer in the SOC.
+</p>
+
+<h2 id="enabling-aaudio-mmap-data-path">Enabling AAudio MMAP Data Path</h2>
+
+<p>
+AAudio will use the legacy AudioFlinger data path if MMAP is not supported or
+fails to open a stream. So AAudio will work with an audio device that does not
+support MMAP/NOIRQ path.
+</p>
+
+<p>
+When testing MMAP support for AAudio, it is important to know whether you are
+actually testing the MMAP data path or merely testing the legacy data path. The
+following describes how to enable or force specific data paths, and how to query
+the path used by a stream.
+</p>
+
+<h3 id="system-properties">System properties</h3>
+
+<p>
+You can set the MMAP policy through system properties:
+</p>
+
+<ul>
+<li>1 = AAUDIO_POLICY_NEVER - Only use legacy path. Do not even try to use MMAP.
+<li>2 = AAUDIO_POLICY_AUTO - Try to use MMAP. If that fails or is not available,
+then use legacy path.
+<li>3 = AAUDIO_POLICY_ALWAYS - Only use MMAP path. Do not fall back to legacy
+path.</li>
+</ul>
+
+<p>
+These may be set in the devices Makefile, like so:
+</p>
+
+<pre
+class="prettyprint">
+# Enable AAudio MMAP/NOIRQ data path.
+# 2 is AAUDIO_POLICY_AUTO so it will try MMAP then fallback to Legacy path.
+PRODUCT_PROPERTY_OVERRIDES += aaudio.mmap_policy=2
+# Allow EXCLUSIVE then fall back to SHARED.
+PRODUCT_PROPERTY_OVERRIDES += aaudio.mmap_exclusive_policy=2
+</pre>
+
+<p>
+You can also override these values after the device has booted. For example, to
+enable AUTO mode for MMAP:
+</p>
+
+<pre class="devsite-terminal devsite-click-to-copy">
+adb root
+</pre>
+<pre class="devsite-terminal devsite-click-to-copy">
+adb shell setprop aaudio.mmap_policy 2
+</pre>
+
+<p>
+There are functions provided in
+<code>ndk/sysroot/usr/include/aaudio/AAudioTesting.h</code> that allow you to
+override the policy for using MMAP path:
+</p>
+
+<pre
+class="prettyprint">aaudio_result_t AAudio_setMMapPolicy(aaudio_policy_t policy);
+</pre>
+
+<p>
+To find out whether a stream is using MMAP path, call:
+</p>
+
+<pre
+class="prettyprint">bool AAudioStream_isMMapUsed(AAudioStream* stream);
+</pre>
+</body>
+</html>
diff --git a/en/devices/audio/images/pcm_data_flow.png b/en/devices/audio/images/pcm_data_flow.png
new file mode 100644
index 00000000..2279e422
--- /dev/null
+++ b/en/devices/audio/images/pcm_data_flow.png
diff --git a/en/devices/audio/latency.html b/en/devices/audio/latency.html
index 58b3024b..03dabb64 100644
--- a/en/devices/audio/latency.html
+++ b/en/devices/audio/latency.html
@@ -34,7 +34,8 @@
 </tr>
 <tr>
   <td>Description of audio latency for purposes of Android compatibility</td>
-  <td><a href="/compatibility/android-cdd#5_6_audio_latency">Android CDD</a><br /><em>section 5.6 Audio Latency</em></td>
+  <td><a href="/compatibility/android-cdd#5_6_audio_latency">Android Compatibility Definition Document (CDD)</a><br />
+    <em>section 5.6 Audio Latency</em></td>
 </tr>
 <tr>
   <td>Common causes of audio latency</td>
@@ -60,6 +61,9 @@
   <td>Applications</td>
   <td><a href="latency_app.html">Audio Latency for App Developers</a></td>
 </tr>
+<tr>
+  <td>AAudio and MMAP</td>
+  <td><a href="aaudio.html">AAudio for OEMs and SoC Vendors</a></td>
 </table>
 
   </body>
diff --git a/en/devices/audio/terminology.html b/en/devices/audio/terminology.html
index 277b25e4..e691e285 100644
--- a/en/devices/audio/terminology.html
+++ b/en/devices/audio/terminology.html
@@ -94,7 +94,7 @@ Both PCM and DSD represent multiple channels by independent sequences. DSD is
 better suited to content distribution than as an internal representation for
 processing as it can be difficult to apply traditional digital signal processing
 (DSP) algorithms to DSD. DSD is used in <a href="http://en.wikipedia.org/wiki/Super_Audio_CD">Super Audio CD (SACD)</a> and in DSD over PCM (DoP) for USB. For details, refer
-to <a href="http://en.wikipedia.org/wiki/Direct_Stream_Digital">Digital Stream
+to <a href="http://en.wikipedia.org/wiki/Direct_Stream_Digital">Direct Stream
 Digital</a>.
 </dd>
author	Android Partner Docs <noreply@android.com>	2017-12-05 15:57:15 -0800
committer	Clay Murphy <claym@google.com>	2017-12-05 21:16:56 -0800
commit	a63d28d20492979243f7cac739a506d308334a86 (patch)
tree	ae2e203f4bf4eb3072e9a06ba2e512dc9230d8da /en/devices/audio
parent	54024816e734bc99e432f281baabcf4718b9197a (diff)
download	source.android.com-a63d28d20492979243f7cac739a506d308334a86.tar.gz