am 3683a6ad: (-s ours) am d578e0ad: am 45a4bde3: Add audio latency design
* commit '3683a6add8bc5b8ebeb77cd1fef983f1a8b46a32':
Add audio latency design
diff --git a/src/devices/audio_terminology.jd b/src/devices/audio_terminology.jd
new file mode 100644
index 0000000..f625850
--- /dev/null
+++ b/src/devices/audio_terminology.jd
@@ -0,0 +1,218 @@
+page.title=Audio Terminology
+@jd:body
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>
+This document provides a glossary of audio-related terminology, including
+a list of widely used, generic terms and a list of terms that are specific
+to Android.
+</p>
+
+<h2 id="genericTerm">Generic Terms</h2>
+
+<p>
+These are audio terms that are widely used, with their conventional meanings.
+</p>
+
+<dl>
+
+<dt>bits per sample or bit depth</dt>
+<dd>
+Number of bits of information per sample.
+</dd>
+
+<dt>channel</dt>
+<dd>
+A single stream of audio information, usually corresponding to one
+location of recording or playback.
+</dd>
+
+<dt>frame</dt>
+<dd>
+A set of samples, one per channel, at a point in time.
+</dd>
+
+<dt>frames per buffer</dt>
+<dd>
+The number of frames handed from one module to the next at once;
+for example the audio HAL interface uses this concept.
+</dd>
+
+<dt>mono</dt>
+<dd>
+One channel.
+</dd>
+
+<dt>sample</dt>
+<dd>
+A number representing the audio value for a single channel at a point in time.
+</dd>
+
+<dt>sample rate or frame rate</dt>
+<dd>
+Number of frames per second;
+note that "frame rate" is thus more accurate,
+but "sample rate" is conventionally used to mean "frame rate".
+</dd>
+
+<dt>stereo</dt>
+<dd>
+Two channels.
+</dd>
+
+</dl>
+
+<h2 id="androidSpecificTerms">Android-Specific Terms</h2>
+
+<p>
+These are terms that are specific to Android audio framework, or that
+may have a special meaning within Android beyond their general meaning.
+</p>
+
+<dl>
+
+<dt>ALSA</dt>
+<dd>
+Advanced Linux Sound Architecture. As the name suggests, it is an audio
+framework primarily for Linux, but it has influenced other systems.
+See Wikipedia article
+<a class="external-link" href="http://en.wikipedia.org/wiki/Advanced_Linux_Sound_Architecture" target="_android">ALSA</a>
+for the general definition. As used within Android, it refers primarily
+to the kernel audio framework and drivers, not to the user-mode API. See
+tinyalsa.
+</dd>
+
+<dt>AudioFlinger</dt>
+<dd>
+The sound server implementation for Android. AudioFlinger
+runs within the mediaserver process. See Wikipedia article
+<a class="external-link" href="http://en.wikipedia.org/wiki/Sound_server" target="_android">Sound server</a>
+for the generic definition.
+</dd>
+
+<dt>AudioMixer</dt>
+<dd>
+The module within AudioFlinger responsible for
+combining multiple tracks and applying attenuation
+(volume) and certain effects. The Wikipedia article
+<a class="external-link" href="http://en.wikipedia.org/wiki/Audio_mixing_(recorded_music)" target="_android">Audio mixing (recorded music)</a>
+may be useful for understanding the generic
+concept. But that article describes a mixer more as a hardware device
+or a software application, rather than a software module within a system.
+</dd>
+
+<dt>AudioRecord</dt>
+<dd>
+The primary low-level client API for receiving data from an audio
+input device such as microphone. The data is usually in PCM format.
+</dd>
+
+<dt>AudioResampler</dt>
+<dd>
+The module within AudioFlinger responsible for sample-rate conversion. See Wikipedia article
+<a class="external-link" href="http://en.wikipedia.org/wiki/Resampling_(audio)" target="_android">Resampling (audio)</a>
+for the generic definition.
+</dd>
+
+<dt>audio policy</dt>
+<dd>
+Service responsible for all actions that require a policy decision
+to be made first, such as opening a new I/O stream, re-routing after a
+change and stream volume management.
+</dd>
+
+<dt>AudioTrack</dt>
+<dd>
+The primary low-level client API for sending data to an audio output
+device such as a speaker. The data is usually in PCM format.
+</dd>
+
+<dt>client</dt>
+<dd>
+Usually same as application or app, but sometimes the "client" of
+AudioFlinger is actually a thread running within the mediaserver system
+process. An example of that is when playing media that is decoded by a
+MediaPlayer object.
+</dd>
+
+<dt>HAL</dt>
+<dd>
+Hardware Abstraction Layer. HAL is a generic term in Android. With
+respect to audio, it is a layer between AudioFlinger and the kernel
+device driver with a C API, which replaces the earlier C++ libaudio.
+</dd>
+
+<dt>FastMixer</dt>
+<dd>
+A thread within AudioFlinger that services lower latency "fast tracks"
+and drives the primary output device.
+</dd>
+
+<dt>fast track</dt>
+<dd>
+An AudioTrack client with lower latency but fewer features, on some devices.
+</dd>
+
+<dt>MediaPlayer</dt>
+<dd>
+A higher-level client API than AudioTrack, for playing either encoded
+content, or content which includes multi-media audio and video tracks.
+</dd>
+
+<dt>mediaserver</dt>
+<dd>
+An Android system process that contains a number of media-related
+services, including AudioFlinger.
+</dd>
+
+<dt>NBAIO</dt>
+<dd>
+An abstraction for "non-blocking" audio input/output ports used within
+AudioFlinger. The name can be misleading, as some implementations of
+the NBAIO API actually do support blocking. The key implementations of
+NBAIO are for pipes of various kinds.
+</dd>
+
+<dt>normal mixer</dt>
+<dd>
+A thread within AudioFlinger that services most full-featured
+AudioTrack clients, and either directly drives an output device or feeds
+it's sub-mix into FastMixer via a pipe.
+</dd>
+
+<dt>OpenSL ES</dt>
+<dd>
+An audio API standard by The Khronos Group. Android versions since
+API level 9 support a native audio API which is based on a subset of
+OpenSL ES 1.0.1.
+</dd>
+
+<dt>StateQueue</dt>
+<dd>
+A module within AudioFlinger responsible for synchronizing state
+among threads. Whereas NBAIO is used to pass data, StateQueue is used
+to pass control information.
+</dd>
+
+<dt>tinyalsa</dt>
+<dd>
+A small user-mode API above ALSA kernel with BSD license, recommended
+for use by HAL implementations.
+</dd>
+
+<dt>track</dt>
+<dd>
+An audio stream, controlled by the AudioTrack API.
+</dd>
+
+</dl>
+
+</p>
+
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 36ac8cc..ac5c09e 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -36,6 +36,7 @@
<li><a href="<?cs var:toroot ?>devices/audio_warmup.html">Warmup</a></li>
<li><a href="<?cs var:toroot ?>devices/audio_avoiding_pi.html">Avoiding Priority Inversion</a></li>
<li><a href="<?cs var:toroot ?>devices/latency_design.html">Design For Reduced Latency</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio_terminology.html">Terminology</a></li>
</ul>
</li>
<li><a href="<?cs var:toroot ?>devices/camera.html">Camera v1</a></li>
@@ -153,10 +154,15 @@
</div>
<ul>
<li>
- <a href="<?cs var:toroot ?>devices/tech/security/enhancements.html">
+ <a href="<?cs var:toroot ?>devices/tech/security/enhancements42.html">
<span class="en">Security Enhancements in Android 4.2</span>
</a>
</li>
+ <li>
+ <a href="<?cs var:toroot ?>devices/tech/security/enhancements43.html">
+ <span class="en">Security Enhancements in Android 4.3</span>
+ </a>
+ </li>
</ul>
</li>
diff --git a/src/devices/tech/input/key-layout-files.jd b/src/devices/tech/input/key-layout-files.jd
index 63fbcac..e925881 100644
--- a/src/devices/tech/input/key-layout-files.jd
+++ b/src/devices/tech/input/key-layout-files.jd
@@ -108,9 +108,10 @@
<p>An inverted axis inverts the sign of the axis value.</p>
<p>The following declaration maps <code>ABS_RZ</code> (indicated by <code>0x05</code>) to <code>AXIS_BRAKE</code>
(indicated by <code>BRAKE</code>), and inverts the output by negating it.</p>
-<pre><code>axis 0x05 invert AXIS_RZ
+<pre><code>axis 0x05 invert BRAKE
</code></pre>
-<p>In the above example, if the value of <code>ABS_RZ</code> is <code>2</code> then <code>AXIS_RZ</code> is set to <code>-2</code>.</p>
+<p>In the above example, if the value of <code>ABS_RZ</code> is <code>2</code> then
+<code>AXIS_BRAKE</code> is set to <code>-2</code>.</p>
<h4 id="center-flat-position-option">Center Flat Position Option</h4>
<p>The Linux input protocol provides a way for input device drivers to specify the
center flat position of joystick axes but not all of them do and some of them
diff --git a/src/devices/tech/security/enhancements.jd b/src/devices/tech/security/enhancements42.jd
similarity index 100%
rename from src/devices/tech/security/enhancements.jd
rename to src/devices/tech/security/enhancements42.jd
diff --git a/src/devices/tech/security/enhancements43.jd b/src/devices/tech/security/enhancements43.jd
new file mode 100644
index 0000000..277e010
--- /dev/null
+++ b/src/devices/tech/security/enhancements43.jd
@@ -0,0 +1,87 @@
+page.title=Security Enhancements in Android 4.3
+@jd:body
+
+<p>
+Every Android release includes dozens of security enhancements to protect
+users. The following are some of the security enhancements available
+in Android 4.3:
+</p>
+
+<ul>
+ <li><strong>Android sandbox reinforced with SELinux.</strong>
+ This release strengthens the Android sandbox using the SELinux
+ mandatory access control system (MAC) in the Linux kernel. SELinux
+ reinforcement is invisible to users and developers, and adds robustness
+ to the existing Android security model while maintaining compatibility
+ with existing applications. To ensure continued compatibility this release
+ allows the use of SELinux in a permissive mode. This mode logs any policy
+ violations, but will not break applications or affect system behavior.</li>
+
+ <li><strong>No setuid/setgid programs.</strong>
+ Added support for filesystem capabilities
+ to Android system files and removed all setuid/setguid programs. This
+ reduces root attack surface and the likelihood of potential security
+ vulnerabilities.</li>
+
+ <li><strong>ADB Authentication.</strong>
+ Since Android 4.2.2, connections to ADB are
+ authenticated with an RSA keypair. This prevents unauthorized use of
+ ADB where the attacker has physical access to a device.</li>
+
+ <li><strong>Restrict Setuid from Android Apps.</strong>
+ The /system partition is now mounted
+ nosuid for zygote-spawned processes, preventing Android applications
+ from executing setuid programs. This reduces root attack surface and
+ the likelihood of potential security vulnerabilities.</li>
+
+ <li><strong>Capability bounding.</strong>
+ Android zygote and ADB now use prctl(PR_CAPBSET_DROP) to drop
+ unnecessary capabilities prior to executing applications.
+ This prevents Android applications and applications launched from
+ the shell from acquiring privileged capabilities.</li>
+
+ <li><strong>AndroidKeyStore Provider.</strong>
+ Android now has a keystore provider that allows
+ applications to create exclusive use keys. This provides applications
+ with an API to create or store private keys that cannot be used by
+ other applications.</li>
+
+ <li><strong>KeyChain isBoundKeyAlgorithm.</strong>
+ Keychain API now provides a method
+ (isBoundKeyType) that allows applications to confirm that system-wide keys
+ are bound to a hardware root of trust for the device. This provides
+ a place to create or store private keys that cannot be exported off the
+ device, even in the event of a root compromise.</li>
+
+ <li><strong>NO_NEW_PRIVS.</strong>
+ Android zygote now uses prctl(PR_SET_NO_NEW_PRIVS) to block addition
+ of new privileges prior to execution application code. This
+ prevents Android applications from performing operations which can
+ elevate privileges via execve. (This requires Linux kernel version 3.5
+ or greater).</li>
+
+ <li><strong>FORTIFY_SOURCE enhancements.</strong>
+ Enabled FORTIFY_SOURCE on Android x86 and MIPS
+ and fortified strchr(), strrchr(), strlen(), and umask() calls. This
+ can detect potential memory corruption vulnerabilities or unterminated
+ string constants.</li>
+
+ <li><strong>Relocation protections.</strong>
+ Enabled read only relocations (relro) for
+ statically linked executables and removed all text relocations in Android
+ code. This provides defense in depth against potential memory corruption
+ vulnerabilities.</li>
+
+ <li><strong>Improved EntropyMixer.</strong>
+ EntropyMixer now writes entropy at shutdown /
+ reboot, in addition to periodic mixing. This allows retention of all
+ entropy generated while devices are powered on, and is especially useful
+ for devices that are rebooted immediately after provisioning.</li>
+
+ <li><strong>Security Fixes.</strong>
+ Android 4.3 also includes fixes for Android-specific
+ vulnerabilities. Information about these vulnerabilities has been provided
+ to Open Handset Alliance members and fixes are available in Android Open
+ Source Project. To improve security, some devices with earlier versions
+ of Android may also include these fixes.</li>
+</ul>
diff --git a/src/devices/tech/storage/index.jd b/src/devices/tech/storage/index.jd
index 71ea31c..0f1b267 100644
--- a/src/devices/tech/storage/index.jd
+++ b/src/devices/tech/storage/index.jd
@@ -26,8 +26,10 @@
<p>External storage is managed by a combination of the <code>vold</code> init service and
<code>MountService</code> system service.</p>
<p>Mounting of physical external storage volumes is handled by <code>vold</code>, which
-performs staging operations to prepare the media before exposing it to apps.
-The device-specific <code>vold.fstab</code> configuration file defines mappings from sysfs
+performs staging operations to prepare the media before exposing it to apps.</p>
+
+<p>For Android 4.2.2 and earlier, the device-specific <code>vold.fstab</code>
+configuration file defines mappings from sysfs
devices to filesystem mount points, and each line follows this format:</p>
<pre><code>dev_mount <label> <mount_point> <partition> <sysfs_path> [flags]
</code></pre>
@@ -40,6 +42,25 @@
<li><code>flags</code>: Optional comma separated list of flags, must not contain <code>/</code>.
Possible values include <code>nonremovable</code> and <code>encryptable</code>.</li>
</ul>
+<p>For Android releases 4.3 and later, the various fstab files used by init, vold and
+recovery were unified in the <code>/fstab.<device></code> file. For external
+storage volumes that are managed by <code>vold</code>, the entries should have the
+following format:</p>
+<pre><code><src> <mnt_point> <type> <mnt_flags> <fs_mgr_flags>
+</code></pre>
+<ul>
+<li><code>src</code>: A path under sysfs (usually mounted at /sys) to the device that
+can provide the mount point. The path must start with <code>/</code>.</li> <li><code>mount_point</code>: Filesystem path where the volume should be mounted.</li>
+<li><code>type</code>: The type of the filesystem on the volume. For external cards,
+this is usually <code>vfat</code>.</li>
+<li><code>mnt_flags</code>: <code>Vold</code> ignores this field and it should be set
+to <code>defaults</code></li>
+<li><code>fs_mgr_flags</code>: <code>Vold</code> ignores any lines in the unified fstab
+that do not include the <code>voldmanaged=</code> flag in this field. This flag must
+be followed by a label describing the card, and a partition number or the word
+<code>auto</code>. Here is an example: <code>voldmanaged=sdcard:auto</code>.
+Other possible flags are <code>nonremovable</code> and <code>encryptable=sdcard</code>.
+</ul>
<p>External storage interactions at and above the framework level are handled
through <code>MountService</code>. The device-specific <code>storage_list.xml</code> configuration
file, typically provided through a <code>frameworks/base</code> overlay, defines the
@@ -74,13 +95,18 @@
storage. The <code>/sdcard</code> path must also resolve to the same location, possibly
through a symlink. If a device adjusts the location of external storage between
platform updates, symlinks should be created so that old paths continue working.</p>
-<p>As an example, here’s the storage configuration for Xoom, which uses a FUSE
-daemon to provide primary external storage, and includes a physical SD card as
+<p>As an example for Android 4.2.2 and earlier, here's the storage configuration for Xoom,
+which uses a FUSE daemon to provide primary external storage, and includes a physical SD card as
secondary external storage:</p>
<ul>
<li><a href="https://android.googlesource.com/device/moto/wingray/+/master/vold.fstab">vold.fstab</a></li>
<li><a href="https://android.googlesource.com/device/moto/wingray/+/master/overlay/frameworks/base/core/res/res/xml/storage_list.xml">storage_list.xml</a></li>
</ul>
+<p>As an example for Android 4.3 and later devices, here's the <code>fstab.goldfish</code> file
+for the Android emulator, which emulates an external SD card as primary external storage:</p>
+<ul>
+<li><a href="https://android.googlesource.com/device/generic/goldfish/+/master/fstab.goldfish">fstab.goldfish</a></li>
+</ul>
<p>Access to external storage is protected by various Android permissions.
Starting in Android 1.0, write access is protected with the
<code>WRITE_EXTERNAL_STORAGE</code> permission, implemented using the <code>sdcard_rw</code> GID.
@@ -113,7 +139,7 @@
it bind mounts the appropriate user-specific subdirectory from under the FUSE
daemon to <code>EMULATED_STORAGE_TARGET</code> so that external storage paths resolve
correctly for the app. Because an app lacks accessible mount points for other
-users’ storage, they can only access storage for the user it was started as.</p>
+users' storage, they can only access storage for the user it was started as.</p>
<p>This implementation also uses the shared subtree kernel feature to propagate
mount events from the default root namespace into app namespaces, which ensures
that features like ASEC containers and OBB mounting continue working correctly.