Merge "Docs: Adding dm-verity to Security section. Bug: 10706838 Staging location: http://claym.mtv.corp.google.com:8091/devices/tech/security/dm-verity.html"
diff --git a/src/compatibility/cts-intro.jd b/src/compatibility/cts-intro.jd
index 54edeb2..b1458e6 100644
--- a/src/compatibility/cts-intro.jd
+++ b/src/compatibility/cts-intro.jd
@@ -42,7 +42,7 @@
<p>Attach at least one device (or emulator) to your machine.</p>
</li>
<li>
-<p>For CTS 2.1 R2 and earlier versions, set up your device (or emulator) to run the accessibility tests:</p>
+<p>For CTS versions 2.1 R2 through 4.2 R4, set up your device (or emulator) to run the accessibility tests:</p>
<ol>
<li>
<p>adb install -r android-cts/repository/testcases/CtsDelegatingAccessibilityService.apk</p>
@@ -89,7 +89,6 @@
<p>Once all the tests are executed, you can view the test results in your browser and use the results to adjust your design. You can continue to run the CTS throughout your development process.</p>
</li>
</ol>
-<p>When you are ready, you can submit the report generated by the CTS to cts@android.com. The report is a .zip archived file that contains XML results and supplemental information such as screen captures.</p>
<h2 id="types-of-test-cases">Types of test cases</h2>
<p>The CTS includes the following types of test cases:</p>
<ul>
diff --git a/src/devices/audio_terminology.jd b/src/devices/audio_terminology.jd
index 23592d4..c21e595 100644
--- a/src/devices/audio_terminology.jd
+++ b/src/devices/audio_terminology.jd
@@ -21,6 +21,8 @@
These are audio terms that are widely used, with their conventional meanings.
</p>
+<h3 id="digitalAudioTerms">Digital Audio</h3>
+
<dl>
<dt>acoustics</dt>
@@ -30,6 +32,13 @@
a device affects perceived audio quality.
</dd>
+<dt>attenuation</dt>
+<dd>
+A multiplicative factor less than or equal to 1.0,
+applied to an audio signal to decrease the signal level.
+Compare to "gain".
+</dd>
+
<dt>bits per sample or bit depth</dt>
<dd>
Number of bits of information per sample.
@@ -41,6 +50,22 @@
location of recording or playback.
</dd>
+<dt>downmixing</dt>
+<dd>
+To decrease the number of channels, e.g. from stereo to mono, or from 5.1 to stereo.
+This can be accomplished by dropping some channels, mixing channels, or more advanced signal processing.
+Simple mixing without attenuation or limiting has the potential for overflow and clipping.
+Compare to "upmixing".
+</dd>
+
+<dt>duck</dt>
+<dd>
+To temporarily reduce the volume of one stream, when another stream
+becomes active. For example, if music is playing and a notification arrives,
+then the music stream could be ducked while the notification plays.
+Compare to "mute".
+</dd>
+
<dt>frame</dt>
<dd>
A set of samples, one per channel, at a point in time.
@@ -52,6 +77,13 @@
for example the audio HAL interface uses this concept.
</dd>
+<dt>gain</dt>
+<dd>
+A multiplicative factor greater than or equal to 1.0,
+applied to an audio signal to increase the signal level.
+Compare to "attenuation".
+</dd>
+
<dt>Hz</dt>
<dd>
The units for sample rate or frame rate.
@@ -67,6 +99,33 @@
One channel.
</dd>
+<dt>multichannel</dt>
+<dd>
+See "surround sound".
+Strictly, since stereo is more than one channel, it is also "multi" channel.
+But that usage would be confusing.
+</dd>
+
+<dt>mute</dt>
+<dd>
+To (temporarily) force volume to be zero, independently from the usual volume controls.
+</dd>
+
+<dt>PCM</dt>
+<dd>
+Pulse Code Modulation, the most common low-level encoding of digital audio.
+The audio signal is sampled at a regular interval, called the sample rate,
+and then quantized to discrete values within a particular range depending on the bit depth.
+For example, for 16-bit PCM, the sample values are integers between -32768 and +32767.
+</dd>
+
+<dt>ramp</dt>
+<dd>
+To gradually increase or decrease the level of a particular audio parameter,
+for example volume or the strength of an effect.
+A volume ramp is commonly applied when pausing and resuming music, to avoid a hard audible transition.
+</dd>
+
<dt>sample</dt>
<dd>
A number representing the audio value for a single channel at a point in time.
@@ -79,13 +138,234 @@
but "sample rate" is conventionally used to mean "frame rate."
</dd>
+<dt>sonification</dt>
+<dd>
+The use of sound to express feedback or information,
+for example touch sounds and keyboard sounds.
+</dd>
+
<dt>stereo</dt>
<dd>
Two channels.
</dd>
+<dt>stereo widening</dt>
+<dd>
+An effect applied to a stereo signal, to make another stereo signal which sounds fuller and richer.
+The effect can also be applied to a mono signal, in which case it is a type of upmixing.
+</dd>
+
+<dt>surround sound</dt>
+<dd>
+Various techniques for increasing the ability of a listener to perceive
+sound position beyond stereo left and right.
+</dd>
+
+<dt>upmixing</dt>
+<dd>
+To increase the number of channels, e.g. from mono to stereo, or from stereo to surround sound.
+This can be accomplished by duplication, panning, or more advanced signal processing.
+Compare to "downmixing".
</dl>
+<dt>virtualizer</dt>
+<dd>
+An effect that attempts to spatialize audio channels, such as trying to
+simulate more speakers, or give the illusion that various sound sources have position.
+</dd>
+
+<dt>volume</dt>
+<dd>
+Loudness, the subjective strength of an audio signal.
+</dd>
+
+<h3 id="hardwareTerms">Hardware and Accessories</h3>
+
+<p>
+These terms are related to audio hardware and accessories.
+</p>
+
+<h4 id="interDeviceTerms">Inter-device interconnect</h4>
+
+<p>
+These technologies connect audio and video components between devices,
+and are readily visible at the external connectors. The HAL implementor
+may need to be aware of these, as well as the end user.
+</p>
+
+<dl>
+
+<dt>Bluetooth</dt>
+<dd>
+A short range wireless technology.
+The major audio-related
+<a class="external-link" href="http://en.wikipedia.org/wiki/Bluetooth_profile"
+target="_android">Bluetooth profiles</a>
+and
+<a class="external-link" href="http://en.wikipedia.org/wiki/Bluetooth_protocols"
+target="_android">Bluetooth protocols</a>
+are described at these Wikipedia articles:
+
+<ul>
+
+<li><a class="external-link"
+href="http://en.wikipedia.org/wiki/Bluetooth_profile#Advanced_Audio_Distribution_Profile_.28A2DP.29"
+target="_android">A2DP</a>
+for music
+</li>
+
+<li><a class="external-link"
+href="http://en.wikipedia.org/wiki/Bluetooth_protocols#Synchronous_connection-oriented_.28SCO.29_link"
+target="_android">SCO</a>
+for telephony
+</li>
+
+</ul>
+
+</dd>
+
+<dt>DisplayPort</dt>
+<dd>
+Digital display interface by VESA.
+</dd>
+
+<dt>HDMI</dt>
+<dd>
+High-Definition Multimedia Interface, an interface for transferring
+audio and video data. For mobile devices, either a micro-HDMI (type D) or MHL connector is used.
+</dd>
+
+<dt>MHL</dt>
+<dd>
+Mobile High-Definition Link is a mobile audio/video interface, often
+over micro-USB connector.
+</dd>
+
+<dt>phone connector</dt>
+<dd>
+A mini or sub-mini phone connector
+connects a device to wired headphones, headset, or line-level amplifier.
+</dd>
+
+<dt>SlimPort</dt>
+<dd>
+An adapter from micro-USB to HDMI.
+</dd>
+
+<dt>S/PDIF</dt>
+<dd>
+Sony/Philips Digital Interface Format is an interconnect for uncompressed PCM.
+See Wikipedia article <a class="external-link" href="http://en.wikipedia.org/wiki/S/PDIF"
+target="_android">S/PDIF</a>.
+</dd>
+
+<dt>USB</dt>
+<dd>
+Universal Serial Bus.
+See Wikipedia article <a class="external-link" href="http://en.wikipedia.org/wiki/USB" target="_android">USB</a>.
+</dd>
+
+</dl>
+
+<h4 id="intraDeviceTerms">Intra-device interconnect</h4>
+
+<p>
+These technologies connect internal audio components within a given
+device, and are not visible without disassembling the device. The HAL
+implementor may need to be aware of these, but not the end user.
+</p>
+
+See these Wikipedia articles:
+<ul>
+<li><a class="external-link" href="http://en.wikipedia.org/wiki/General-purpose_input/output"
+target="_android">GPIO</a></li>
+<li><a class="external-link" href="http://en.wikipedia.org/wiki/I%C2%B2C" target="_android">I²C</a></li>
+<li><a class="external-link" href="http://en.wikipedia.org/wiki/I%C2%B2S" target="_android">I²S</a></li>
+<li><a class="external-link" href="http://en.wikipedia.org/wiki/McASP" target="_android">McASP</a></li>
+<li><a class="external-link" href="http://en.wikipedia.org/wiki/SLIMbus" target="_android">SLIMbus</a></li>
+<li><a class="external-link" href="http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus"
+target="_android">SPI</a></li>
+</ul>
+
+<h3 id="signalTerms">Audio Signal Path</h3>
+
+<p>
+These terms are related to the signal path that audio data follows from
+an application to the transducer, or vice-versa.
+</p>
+
+<dt>ADC</dt>
+<dd>
+Analog to digital converter, a module that converts an analog signal
+(continuous in both time and amplitude) to a digital signal (discrete in
+both time and amplitude). Conceptually, an ADC consists of a periodic
+sample-and-hold followed by a quantizer, although it does not have to
+be implemented that way. An ADC is usually preceded by a low-pass filter
+to remove any high frequency components that are not representable using
+the desired sample rate. See Wikipedia article
+<a class="external-link" href="http://en.wikipedia.org/wiki/Analog-to-digital_converter"
+target="_android">Analog-to-digital_converter</a>.
+</dd>
+
+<dt>AP</dt>
+<dd>
+Application processor, the main general-purpose computer on a mobile device.
+</dd>
+
+<dt>codec</dt>
+<dd>
+Coder-decoder, a module that encodes and/or decodes an audio signal
+from one representation to another. Typically this is analog to PCM, or PCM to analog.
+Strictly, the term "codec" is reserved for modules that both encode and decode,
+however it can also more loosely refer to only one of these.
+See Wikipedia article
+<a class="external-link" href="http://en.wikipedia.org/wiki/Audio_codec" target="_android">Audio codec</a>.
+</dd>
+
+<dt>DAC</dt>
+<dd>
+Digital to analog converter, a module that converts a digital signal
+(discrete in both time and amplitude) to an analog signal
+(continuous in both time and amplitude). A DAC is usually followed by
+a low-pass filter to remove any high frequency components introduced
+by digital quantization.
+See Wikipedia article
+<a class="external-link" href="http://en.wikipedia.org/wiki/Digital-to-analog_converter"
+target="_android">Digital-to-analog converter</a>.
+</dd>
+
+<dt>DSP</dt>
+<dd>
+Digital Signal Processor, an optional component which is typically located
+after the application processor (for output), or before the application processor (for input).
+The primary purpose of a DSP is to off-load the application processor,
+and provide signal processing features at a lower power cost.
+</dd>
+
+<dt>PDM</dt>
+<dd>
+Pulse-density modulation
+is a form of modulation used to represent an analog signal by a digital signal,
+where the relative density of 1s versus 0s indicates the signal level.
+It is commonly used by digital to analog converters.
+See Wikipedia article
+<a class="external-link" href="http://en.wikipedia.org/wiki/Pulse-density_modulation"
+target="_android">Pulse-density modulation</a>.
+</dd>
+
+<dt>PWM</dt>
+<dd>
+Pulse-width modulation
+is a form of modulation used to represent an analog signal by a digital signal,
+where the relative width of a digital pulse indicates the signal level.
+It is commonly used by analog to digital converters.
+See Wikipedia article
+<a class="external-link" href="http://en.wikipedia.org/wiki/Pulse-width_modulation"
+target="_android">Pulse-width modulation</a>.
+</dd>
+
+</p>
+
<h2 id="androidSpecificTerms">Android-Specific Terms</h2>
<p>
@@ -110,7 +390,7 @@
<dd>
An API and implementation framework for output (post-processing) effects
and input (pre-processing) effects. The API is defined at
-<a class="external-link" href="http://developer.android.com/reference/android/media/audiofx/AudioEffect.html" target="_android">android.media.audiofx.AudioEffect</a>
+<a href="http://developer.android.com/reference/android/media/audiofx/AudioEffect.html" target="_android">android.media.audiofx.AudioEffect</a>.
</dd>
<dt>AudioFlinger</dt>
@@ -121,6 +401,14 @@
for the generic definition.
</dd>
+<dt>audio focus</dt>
+<dd>
+A set of APIs for managing audio interactions across multiple independent apps.
+See <a href="http://developer.android.com/training/managing-audio/audio-focus.html">Managing Audio
+Focus</a> and the focus-related methods and constants of
+<a href="http://developer.android.com/reference/android/media/AudioManager.html">android.media.AudioManager</a>.
+</dd>
+
<dt>AudioMixer</dt>
<dd>
The module within AudioFlinger responsible for
@@ -132,11 +420,22 @@
or a software application, rather than a software module within a system.
</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>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 pulse-code modulation
(PCM) format.
+The API is defined at
+<a href="http://developer.android.com/reference/android/media/AudioRecord.html"
+target="_android">android.media.AudioRecord</a>.
+</dd>
</dd>
<dt>AudioResampler</dt>
@@ -146,17 +445,13 @@
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.
+The API is defined at
+<a href="http://developer.android.com/reference/android/media/AudioTrack.html"
+target="_android">android.media.AudioTrack</a>.
</dd>
<dt>client</dt>
@@ -226,6 +521,27 @@
OpenSL ES 1.0.1.
</dd>
+<dt>silent mode</dt>
+<dd>
+A user-settable feature to mute the phone ringer and notifications,
+without affecting media playback (music, videos, games) or alarms.
+</dd>
+
+<dt>SoundPool</dt>
+<dd>
+A higher-level client API than AudioTrack, used for playing sampled
+audio clips. It is useful for triggering UI feedback, game sounds, etc.
+The API is defined at
+<a href="http://developer.android.com/reference/android/media/SoundPool.html"
+target="_android">android.media.SoundPool</a>.
+</dd>
+</dd>
+
+<dt>Stagefright</dt>
+<dd>
+See <a href="{@docRoot}devices/media.html">Media</a>.
+</dd>
+
<dt>StateQueue</dt>
<dd>
A module within AudioFlinger responsible for synchronizing state
@@ -233,6 +549,20 @@
to pass control information.
</dd>
+<dt>strategy</dt>
+<dd>
+A grouping of stream types with similar behavior, used by the audio policy service.
+</dd>
+
+<dt>stream type</dt>
+<dd>
+An enumeration that expresses a use case for audio output.
+The audio policy implementation uses the stream type, along with other parameters,
+to determine volume and routing decisions.
+Specific stream types are listed at
+<a href="http://developer.android.com/reference/android/media/AudioManager.html">android.media.AudioManager</a>.
+</dd>
+
<dt>tee sink</dt>
<dd>
An AudioFlinger debugging feature, available in custom builds only,
@@ -247,11 +577,36 @@
for use in HAL implementations.
</dd>
+<dt>ToneGenerator</dt>
+<dd>
+A higher-level client API than AudioTrack, used for playing DTMF signals.
+See the Wikipedia article
+<a class="external-link" href="http://en.wikipedia.org/wiki/Dual-tone_multi-frequency_signaling"
+target="_android">Dual-tone multi-frequency signaling</a>,
+and the API definition at
+<a href="http://developer.android.com/reference/android/media/ToneGenerator.html"
+target="_android">android.media.ToneGenerator</a>.
+</dd>
+
<dt>track</dt>
<dd>
An audio stream, controlled by the AudioTrack API.
</dd>
+<dt>volume attenuation curve</dt>
+<dd>
+A device-specific mapping from a generic volume index to a particular attenuation factor
+for a given output.
+</dd>
+
+<dt>volume index</dt>
+<dd>
+A unitless integer that expresses the desired relative volume of a stream.
+The volume-related APIs of
+<a href="http://developer.android.com/reference/android/media/AudioManager.html">android.media.AudioManager</a>
+operate in volume indices rather than absolute attenuation factors.
+</dd>
+
</dl>
</p>
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index af6ab77..42f58ea 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -84,6 +84,7 @@
<li><a href="<?cs var:toroot ?>devices/tech/input/validate-keymaps.html">Validate Keymaps</a></li>
</ul>
</li>
+ <li><a href="<?cs var:toroot ?>devices/low-ram.html">Low RAM</a></li>
<li><a href="<?cs var:toroot ?>devices/media.html">Media</a></li>
<li class="nav-section">
<div class="nav-section-header">
@@ -105,6 +106,12 @@
</a>
</li>
<li>
+ <a href="<?cs var:toroot
+?>devices/tech/security/enhancements44.html">
+ <span class="en">Security Enhancements in Android 4.4</span>
+ </a>
+ </li>
+ <li>
<a href="<?cs var:toroot ?>devices/tech/security/dm-verity.html">
<span class="en">dm-verity on boot</span>
</a>
@@ -140,6 +147,7 @@
<li><a href="<?cs var:toroot ?>devices/tech/dalvik/dalvik-bytecode.html">Bytecode Format</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/dalvik/dex-format.html">.Dex Format</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/dalvik/instruction-formats.html">Instruction Formats</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/dalvik/art.html">Introducing ART</a></li>
</ul>
</li>
diff --git a/src/devices/low-ram.jd b/src/devices/low-ram.jd
new file mode 100644
index 0000000..711fadc
--- /dev/null
+++ b/src/devices/low-ram.jd
@@ -0,0 +1,362 @@
+page.title=Running Android with low RAM
+@jd:body
+
+<!--
+ Copyright 2010 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<h2 id="intro">Introduction</h2>
+
+<p>In release 4.4, Android begins explicit support for devices with 512MB
+memory. As of Q3 2013, more than 30% of all Android devices run on
+platform versions older than 4.0. Most of these devices tend to be low-end with
+512MB or less RAM. One of the primary goals of this release
+is to ensure Android can continue to run on a 512MB device.</p>
+
+<p>This documentation is intended to help OEMs optimize and configure Android 4.4 for
+ low-RAM devices. Several of these optimizations are generic enough that
+they can be applied to previous releases as well. </p>
+
+<h2 id="optimizations">Android 4.4 platform optimizations</h2>
+
+<h3 id="opt-mgmt">Improved memory management</h3>
+<ul>
+<li>Validated memory-saving kernel configurations: Kernel Same-page Merging
+(KSM), and Swap to ZRAM.</li>
+<li>Kill cached processes if about to be uncached and too large.</li>
+<li>Don’t allow large services to put themselves back into A Services (so they
+can’t cause the launcher to be killed).</li>
+<li>Kill processes (even ordinarily unkillable ones such as the current IME)
+that get too large in idle maintenance.</li>
+<li>Serialize the launch of background services.</li>
+<li>Tuned memory use of low-RAM devices: tighter out-of-memory (OOM) adjustment
+levels, smaller graphics caches, etc.</li>
+</ul>
+
+<h3 id="opt-mem">Reduced system memory</h3>
+<ul>
+<li>Trimmed system_server and SystemUI processes (saved several MBs).</li>
+<li>Preload dex caches in Dalvik (saved several MBs).</li>
+<li>Validated JIT-off option (saves up to 1.5MB per process).</li>
+<li>Reduced per-process font cache overhead.</li>
+<li>Introduced ArrayMap/ArraySet and used extensively in framework as a
+lighter-footprint replacement for HashMap/HashSet.</li>
+levels, smaller graphics caches, etc.</li>
+</ul>
+
+<h3 id="opt-proc">Procstats</h3>
+<p>
+Added a new Developer Option to show memory state and application memory usage
+ranked by how often they run and amount of memory consumed.
+</p>
+
+<h3 id="opt-api">API</h3>
+<p>
+Added a new ActivityManager.isLowRamDevice() to allow applications to detect
+when running on low memory devices and choose to disable large-RAM features.
+</p>
+
+<h3 id="opt-track">Memory tracking</h3>
+<p>
+New memtrack HAL to track graphics memory allocations, additional information
+in dumpsys meminfo, clarified summaries in meminfo (for example reported free
+RAM includes RAM of cached processes, so that OEMs don’t try to optimize the
+wrong thing).
+</p>
+
+<h2 id="build-time">Build-time configuration</h2>
+<h3 id="flag">Enable Low Ram Device flag</h3>
+<p>We are introducing a new API called <code>ActivityManager.isLowRamDevice()</code> for applications to determine if they should turn off specific memory-intensive
+ features that work poorly on low-end devices.</p>
+<p>For 512MB devices, this API is expected to return: "true" It can be enabled by
+ the following system property in the device makefile.<br/>
+<code>PRODUCT_PROPERTY_OVERRIDES += ro.config.low_ram=true</code></p>
+
+<h3 id="jit">Disable JIT</h3>
+
+ <p>System-wide JIT memory usage is dependent on the number of applications
+ running and the code footprint of those applications. The JIT establishes a
+ maximum translated code cache size and touches the pages within it as needed.
+ JIT costs somewhere between 3M and 6M across a typical running system.<br/>
+ <br/>
+ The large apps tend to max out the code cache fairly quickly (which by default
+ has been 1M). On average, JIT cache usage runs somewhere between 100K and 200K
+ bytes per app. Reducing the max size of the cache can help somewhat with
+ memory usage, but if set too low will send the JIT into a thrashing mode. For
+the really low-memory devices, we recommend the JIT be disabled entirely.<code>
+</code></p>
+
+<p>This can be achieved by adding the following line to the product makefile:<br/>
+<code>PRODUCT_PROPERTY_OVERRIDES += dalvik.vm.jit.codecachesize=0</code></p>
+<h3 id="launcher">Launcher Configs</h3>
+
+
+ <p>Ensure the default wallpaper setup on launcher is <strong>not</strong>
+using live-wallpaper. Low-end devices should not pre-install any live wallpapers. </p>
+
+
+<h2 id="kernel">Kernel configuration</h2>
+<h3 id="kernel-tuning">Tuning kernel/ActivityManager to reduce direct reclaim </h3>
+
+
+ <p>Direct reclaim happens when a process or the kernel tries to allocate a page
+ of memory (either directly or due to faulting in a new page) and the kernel
+ has used all available free memory. This requires the kernel to block the
+ allocation while it frees up a page. This in turn often requires disk I/O to
+ flush out a dirty file-backed page or waiting for <code>lowmemorykiller</code> to kill a
+ process. This can result in extra I/O in any thread, including a UI thread.</p>
+
+ <p>To avoid direct reclaim, the kernel has watermarks that trigger <code>kswapd</code> or
+ background reclaim. This is a thread that tries to free up pages so the next
+ time a real thread allocates it can succeed quickly.</p>
+
+ <p>The default threshold to trigger background reclaim is fairly low, around 2MB
+ on a 2GB device and 636KB on a 512MB device. And the kernel reclaims only a
+ few MB of memory in background reclaim. This means any process that quickly
+ allocates more than a few megabytes is going to quickly hit direct reclaim.</p>
+
+<p>Support for a new kernel tunable is added in the android-3.4 kernel branch as
+ patch 92189d47f66c67e5fd92eafaa287e153197a454f ("add extra free kbytes
+ tunable"). Cherry-picking this patch to a device's kernel will allow
+ ActivityManager to tell the kernel to try to keep 3 full-screen 32 bpp buffers
+ of memory free.</p>
+
+<p>These thresholds can be configured via the framework config.xml</p>
+<p><code> <!-- Device configuration setting the /proc/sys/vm/extra_free_kbytes tunable in the kernel (if it exists). A high value will increase the amount of memory that the kernel tries to keep free, reducing allocation time and causing the lowmemorykiller to kill earlier. A low value allows more memory to be used by processes but may cause more allocations to block waiting on disk I/O or lowmemorykiller. Overrides the default value chosen by ActivityManager based on screen size. 0 prevents keeping any extra memory over what the kernel keeps by default. -1 keeps the default. --><br />
+<integer name="config_extraFreeKbytesAbsolute">-1</integer></code></p>
+
+<code>
+<p> <!-- Device configuration adjusting the /proc/sys/vm/extra_free_kbytes tunable in the kernel (if it exists). 0 uses the default value chosen by ActivityManager. A positive value will increase the amount of memory that the kernel tries to keep free, reducing allocation time and causing the lowmemorykiller to kill earlier. A negative value allows more memory to be used by processes but may cause more allocations to block waiting on disk I/O or lowmemorykiller. Directly added to the default value chosen by ActivityManager based on screen size. --><br />
+ <integer name="config_extraFreeKbytesAdjust">0</integer></code>
+
+<h3 id="lowmem">Tuning LowMemoryKiller</h3>
+
+
+ <p>ActivityManager configures the thresholds of the LowMemoryKiller to match its
+ expectation of the working set of file-backed pages (cached pages) required to
+ run the processes in each priority level bucket. If a device has high
+ requirements for the working set, for example if the vendor UI requires more
+memory or if more services have been added, the thresholds can be increased. </p>
+<p>The thresholds can be reduced if too much memory is being reserved for file
+ backed pages, so that background processes are being killed long before disk
+thrashing would occur due to the cache getting too small.</p>
+<p> <code><!-- Device configuration setting the minfree tunable in the lowmemorykiller in the kernel. A high value will cause the lowmemorykiller to fire earlier, keeping more memory in the file cache and preventing I/O thrashing, but allowing fewer processes to stay in memory. A low value will keep more processes in memory but may cause thrashing if set too low. Overrides the default value chosen by ActivityManager based on screen size and total memory for the largest lowmemorykiller bucket, and scaled proportionally to the smaller buckets. -1 keeps the default. --><br />
+ <integer name="config_lowMemoryKillerMinFreeKbytesAbsolute">-1</integer></code></p>
+<p> <code><!-- Device configuration adjusting the minfree tunable in the lowmemorykiller in the kernel. A high value will cause the lowmemorykiller to fire earlier, keeping more memory in the file cache and preventing I/O thrashing, but allowing fewer processes to stay in memory. A low value will keep more processes in memory but may cause thrashing if set too low. Directly added to the default value chosen by ActivityManager based on screen size and total memory for the largest lowmemorykiller bucket, and scaled proportionally to the smaller buckets. 0 keeps the default. --><br />
+ <integer name="config_lowMemoryKillerMinFreeKbytesAdjust">0</integer></code></p>
+<h3 id="ksm">KSM (Kernel samepage merging)</h3>
+
+
+ <p>KSM is a kernel thread that runs in the background and compares pages in
+ memory that have been marked <code>MADV_MERGEABLE</code> by user-space. If two pages are
+ found to be the same, the KSM thread merges them back as a single
+ copy-on-write page of memory.</p>
+
+ <p>KSM will save memory over time on a running system, gaining memory duplication
+ at a cost of CPU power, which could have an impact on battery life. You should
+ measure whether the power tradeoff is worth the memory savings you get by
+ enabling KSM.</p>
+
+ <p>To test KSM, we recommend looking at long running devices (several hours) and
+ seeing whether KSM makes any noticeable improvement on launch times and
+ rendering times.</p>
+
+<p>To enable KSM, enable <code>CONFIG_KSM</code> in the kernel and then add the following lines to your` <code>init.<device>.rc</code> file:<br>
+ <code>write /sys/kernel/mm/ksm/pages_to_scan 100<br>
+ write /sys/kernel/mm/ksm/sleep_millisecs 500<br>
+write /sys/kernel/mm/ksm/run 1</code></p>
+<p>Once enabled, there are few utilities that will help in the debugging namely :
+ procrank, librank, & ksminfo. These utilities allow you to see which KSM
+ memory is mapped to what process, which processes use the most KSM memory.
+ Once you have found a chunk of memory that looks worth exploring you can use
+ either the hat utility if it's a duplicate object on the dalvik heap. </p>
+<h3 id="zram">Swap to zRAM</h3>
+
+
+ <p>zRAM swap can increase the amount of memory available in the system by
+ compressing memory pages and putting them in a dynamically allocated swap area
+ of memory.</p>
+
+ <p>Again, since this is trading off CPU time for a small increase in memory, you
+ should be careful about measuring the performance impact zRAM swap has on your
+ system.</p>
+
+
+<p>Android handles swap to zRAM at several levels:</p>
+
+<ul>
+ <li>First, the following kernel options must be enabled to use zRAM swap
+ effectively:
+ <ul>
+ <li><code>CONFIG_SWAP</code></li>
+ <li><code>CONFIG_CGROUP_MEM_RES_CTLR</code></li>
+ <li><code>CONFIG_CGROUP_MEM_RES_CTLR_SWAP</code></li>
+ <li><code>CONFIG_ZRAM</code></li>
+ </ul>
+ </li>
+ <li>Then, you should add a line that looks like this to your fstab:<br />
+ <code>/dev/block/zram0 none swap defaults zramsize=<size in bytes>,swapprio=<swap partition priority></code><br />
+ <code><br />
+ zramsize</code> is mandatory and indicates how much uncompressed memory you want
+ the zram area to hold. Compression ratios in the 30-50% range are usually
+ observed.<br />
+ <br />
+ <code>swapprio</code> is optional and not needed if you don't have more than one swap
+ area.<br />
+ <br />
+ </li>
+ <li>By default, the Linux kernel swaps in 8 pages of memory at a time. When
+ using ZRAM, the incremental cost of reading 1 page at a time is negligible
+ and may help in case the device is under extreme memory pressure. To read
+ only 1 page at a time, add the following to your init.rc:<br />
+ `write /proc/sys/vm/page-cluster 0`</li>
+ <li>In your init.rc, after the `mount_all /fstab.X` line, add:<br />
+ `swapon_all /fstab.X`</li>
+ <li>The memory cgroups are automatically configured at boot time if the
+ feature is enabled in kernel.</li>
+ <li>If memory cgroups are available, the ActivityManager will mark lower
+ priority threads as being more swappable than other threads. If memory is
+ needed, the Android kernel will start migrating memory pages to zRAM swap,
+ giving a higher priority to those memory pages that have been marked by
+ ActivityManager. </li>
+</ul>
+<h3 id="carveouts">Carveouts, Ion and Contiguous Memory Allocation (CMA)</h3>
+
+ <p>It is especially important on low memory devices to be mindful about
+ carveouts, especially those that will not always be fully utilized -- for
+ example a carveout for secure video playback. There are several solutions to
+ minimizing the impact of your carveout regions that depend on the exact
+ requirements of your hardware.</p>
+ <p>If hardware permits discontiguous memory
+ allocations, the ion system heap allows memory allocations from system memory,
+ eliminating the need for a carveout. It also attempts to make large
+ allocations to eliminate TLB pressure on peripherals. If memory regions must
+ be contiguous or confined to a specific address range, the contiguous memory
+ allocator (CMA) can be used.</p>
+<p>This creates a carveout that the system can also
+ use of for movable pages. When the region is needed, movable pages will be
+ migrated out of it, allowing the system to use a large carveout for other
+ purposes when it is free. CMA can be used directly or more simply via ion by
+ using the ion cma heap.</p>
+
+<h2 id="app-opts">Application optimization tips</h2>
+<ul>
+ <li>Review <a
+href="http://developer.android.com/training/articles/memory.html">Managing your
+App's Memory</a> and these past blog posts on the same topic:
+ <ul>
+ <li><a
+href="http://android-developers.blogspot.com/2009/01/avoiding-memory-leaks.html">http://android-developers.blogspot.com/2009/01/avoiding-memory-leaks.html</a></li>
+ <li><a
+href="http://android-developers.blogspot.com/2011/03/memory-analysis-for-android.html">http://android-developers.blogspot.com/2011/03/memory-analysis-for-android.html</a></li>
+ <li><a
+href="http://android-developers.blogspot.com/2009/02/track-memory-allocations.html">http://android-developers.blogspot.com/2009/02/track-memory-allocations.html</a></li>
+ <li> <a
+href="http://tools.android.com/recent/lintperformancechecks">http://tools.android.com/recent/lintperformancechecks</a></li>
+ </ul>
+</li>
+ <li>Check/remove any unused assets from preinstalled apps -
+development/tools/findunused (should help make the app smaller).</li>
+<li>Use PNG format for assets, especially when they have transparent areas</li>
+<li>If writing native code, use calloc() rather than malloc/memset</li>
+<li>Don't enable code that is writing Parcel data to disk and reading it later.</li>
+<li>Don't subscribe to every package installed, instead use ssp filtering. Add
+filtering like below:
+<br />
+ <code><data android:scheme="package" android:ssp="com.android.pkg1" /><br />
+ <data android:scheme="package" android:ssp="com.myapp.act1" /></code></li>
+</ul>
+
+<h3 id="process-states">Understand the various process states in Android</h3>
+
+ <ul>
+ <li><p>SERVICE - SERVICE_RESTARTING<br/>
+ Applications that are making themselves run in the background for their own
+ reason. Most common problem apps have when they run in the background too
+ much. %duration * pss is probably a good "badness" metric, although this set
+ is so focused that just doing %duration is probably better to focus on the
+ fact that we just don't want them running at all.</p></li>
+ <li><p>IMPORTANT_FOREGROUND - RECEIVER<br/>
+ Applications running in the background (not directly interacting with the
+ user) for any reason. These all add memory load to the system. In this case
+ the (%duration * pss) badness value is probably the best ordering of such
+ processes, because many of these will be always running for good reason, and
+ their pss size then is very important as part of their memory load.</p></li>
+ <li><p>PERSISTENT<br/>
+ Persistent system processes. Track pss to watch for these processes getting
+ too large.</p></li>
+ <li><p>TOP<br/>
+ Process the user is currently interacting with. Again, pss is the important
+ metric here, showing how much memory load the app is creating while in use.</p></li>
+ <li><p>HOME - CACHED_EMPTY<br/>
+ All of these processes at the bottom are ones that the system is keeping
+ around in case they are needed again; but they can be freely killed at any
+ time and re-created if needed. These are the basis for how we compute the
+ memory state -- normal, moderate, low, critical is based on how many of these
+ processes the system can keep around. Again the key thing for these processes
+ is the pss; these processes should try to get their memory footprint down as
+ much as possible when they are in this state, to allow for the maximum total
+ number of processes to be kept around. Generally a well behaved app will have
+ a pss footprint that is significantly smaller when in this state than when
+ TOP.</p></li>
+ <li>
+ <p>TOP vs. CACHED_ACTIVITY-CACHED_ACTIVITY_CLIENT<em><br/>
+ </em>The difference in pss between when a process is TOP vs. when it is in either
+ of these specific cached states is the best data for seeing how well it is
+ releasing memory when going into the background. Excluding CACHED_EMPTY state
+ makes this data better, since it removes situations when the process has
+ started for some reasons besides doing UI and so will not have to deal with
+ all of the UI overhead it gets when interacting with the user.</p></li>
+ </ul>
+
+
+<h2 id="analysis">Analysis</h2>
+<h3 id="app-startup">Analyzing app startup time</h3>
+
+
+ <p>Use "<code>adb shell am start</code>" with the <code>-P</code> or <code>--start-profiler</code> option to run
+ the profiler when your app starts. This will start the profiler almost
+ immediately after your process is forked from zygote, before any of your code
+is loaded into it.</p>
+<h3 id="bug-reports">Analyze using bugreports </h3>
+
+
+ <p>Now contains various information that can be used for debugging. The services
+ include <code>batterystats</code>, <code>netstats</code>, <code>procstats</code>, and <code>usagestats</code>. You can
+ find them with lines like this:</p>
+
+
+<pre>------ CHECKIN BATTERYSTATS (dumpsys batterystats --checkin) ------
+7,0,h,-2558644,97,1946288161,3,2,0,340,4183
+7,0,h,-2553041,97,1946288161,3,2,0,340,4183
+</pre>
+<h3 id="persistent">Check for any persistent processes</h3>
+
+
+ <p>Reboot the device and check the processes.<br/>
+ Run for a few hours and check the processes again. There should not be any
+long running processes.</p>
+<h3 id="longevity">Run longevity tests</h3>
+
+
+ <p>Run for longer durations and track the memory of the process. Does it
+ increase? Does it stay constant? Create Canonical use cases and run longevity tests on these scenarios</p>
diff --git a/src/devices/tech/dalvik/art.jd b/src/devices/tech/dalvik/art.jd
new file mode 100644
index 0000000..dd3c6f6
--- /dev/null
+++ b/src/devices/tech/dalvik/art.jd
@@ -0,0 +1,52 @@
+page.title=Introducing ART
+@jd:body
+
+<!--
+ Copyright 2013 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<p>
+ART is a new Android runtime being introduced experimentally in the 4.4
+release. This is a preview of work in progress in KitKat that can be turned on
+in Settings > developer options. This is available for the purpose of
+obtaining early developer and partner feedback.</p>
+
+<p><strong>Important</strong>: Dalvik must remain the default runtime or
+you risk breaking your Android implementations and third-party applications.</p>
+
+<p>
+Two runtimes are now available, the existing Dalvik runtime (libdvm.so) and the
+ART (libart.so). A device can be built using either or both.
+(You can dual boot from Developer options if both are installed.)
+</p>
+
+<p>
+The <code>dalvikvm</code> command line tool can run with either of them now.
+See runtime_common.mk. That is included from build/target/product/runtime_libdvm.mk or
+build/target/product/runtime_libdvm.mk or both.</p>
+
+<p>
+A new <code>PRODUCT_RUNTIMES</code> variable controls which runtimes
+are included in a build. Include it within either
+build/target/product/core_minimal.mk or build/target/product/core_base.mk.
+</p>
+
+<p>
+Add this to the device makefile to have both runtimes
+built and installed, with Dalvik as the default:
+</br>
+<code>PRODUCT_RUNTIMES := runtime_libdvm_default</code>
+</br>
+<code>PRODUCT_RUNTIMES += runtime_libart</code>
+</p>
diff --git a/src/devices/tech/dalvik/index.jd b/src/devices/tech/dalvik/index.jd
index ed36231..7bc11bb 100644
--- a/src/devices/tech/dalvik/index.jd
+++ b/src/devices/tech/dalvik/index.jd
@@ -22,4 +22,8 @@
<p>Much of the documentation in this directory is intended to help
with the ongoing development of Dalvik, as opposed to most of the
other documentation on this site, which is geared more towards
-application development.</p>
\ No newline at end of file
+application development.</p>
+
+<p>Please note, in Android 4.4 a new virtual machine - ART - is being introduced
+experimentally that will eventually replace Dalvik. Please see <a
+href="{@docRoot}devices/tech/dalvik/art.html">Introducing ART</a> for details.
diff --git a/src/devices/tech/security/enhancements44.jd b/src/devices/tech/security/enhancements44.jd
new file mode 100644
index 0000000..ec0aee8
--- /dev/null
+++ b/src/devices/tech/security/enhancements44.jd
@@ -0,0 +1,48 @@
+page.title=Security Enhancements in Android 4.4
+@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.4:
+</p>
+
+<ul>
+ <li><strong>Android sandbox reinforced with SELinux.</strong>
+ Android now uses SELinux in enforcing mode. SELinux is a mandatory
+ access control (MAC) system in the Linux kernel used to augment the
+ existing discretionary access control (DAC) based security model.
+ This provides additional protection against potential security
+ vulnerabilities.</li>
+
+ <li><strong>Per User VPN.</strong>
+ On multi-user devices, VPNs are now applied per user.
+ This can allow a user to route all network traffic through a VPN
+ without affecting other users on the device.</li>
+
+ <li><strong>ECDSA Provider support in AndroidKeyStore.</strong>
+ Android now has a keystore provider that allows use of ECDSA and
+ DSA algorithms.</li>
+
+ <li><strong>Device Monitoring Warnings.</strong>
+ Android provides users with a warning if any certificate has been
+ added to the device certificate store that could allow monitoring of
+ encrypted network traffic.</li>
+
+ <li><strong>FORTIFY_SOURCE.</strong>
+ Android now supports FORTIFY_SOURCE level 2, and all code is compiled
+ with these protections. FORTIFY_SOURCE has been enhanced to work with
+ clang.</li>
+
+ <li><strong>Certificate Pinning.</strong>
+ Android 4.4 detects and prevents the use of fraudulent Google
+ certificates used in secure SSL/TLS communications.</li>
+
+ <li><strong>Security Fixes.</strong>
+ Android 4.4 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/security/index.jd b/src/devices/tech/security/index.jd
index 2c0186c..e53895a 100644
--- a/src/devices/tech/security/index.jd
+++ b/src/devices/tech/security/index.jd
@@ -16,6 +16,13 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
<h2 id="introduction">Introduction</h2>
<p>Android is a modern mobile platform that was designed to be truly open. Android
@@ -273,6 +280,14 @@
applications, files created by one application cannot be read or altered by
another application.</p>
+<h2 id="se-linux">Security-Enhanced Linux</h2>
+
+<p>Android uses Security-Enhanced
+Linux (SELinux) to apply access control policies and establish an environment of
+mandatory access control (mac). See <a
+href="{@docRoot}devices/tech/security/se-linux.html">Validating
+Security-Enhanced Linux in
+Android</a> for details.</p>
<h2 id="crypto">Cryptography</h2>
diff --git a/src/devices/tech/security/se-linux.jd b/src/devices/tech/security/se-linux.jd
index d23be8c..acf9291 100644
--- a/src/devices/tech/security/se-linux.jd
+++ b/src/devices/tech/security/se-linux.jd
@@ -1,4 +1,4 @@
-page.title=Security-Enhanced Linux
+page.title=Validating Security-Enhanced Linux in Android
@jd:body
<!--
@@ -16,70 +16,121 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
-<h2 id="introduction">Introduction</h2> <p>In Android 4.3,
-Android begins supporting Security-Enhanced Linux (SELinux), a tool for applying
-access control policies. SELinux enhances Android security, and contributions to
-it have been made by a number of companies and organizations; all Android code
-and contributors are publicly available for review on this same site <a
-href="http://source.android.com/">source.android.com</a>. With SELinux, Android
-can better control access to application data and system logs, reduce the
-effects of malicious software, and protect users from potential flaws in mobile
-code. </p>
+<h2 id="introduction">Introduction</h2>
+<p>
+As part of the Android <a href="{@docRoot}devices/tech/security/index.html">security
+model</a>, Android uses Security-Enhanced Linux (SELinux) to apply access
+control policies. SELinux enhances Android security, and contributions to it
+have been made by a number of companies and organizations; all Android code and
+contributors are publicly available for review on
+<a href="https://android.googlesource.com/">android.googlesource.com</a>. With SELinux,
+Android can
+better control access to application data and system logs, reduce the effects of
+malicious software, and protect users from potential flaws in code on mobile
+devices.
+</p>
+<p>
+Android includes SELinux in enforcing mode and a corresponding security policy
+that works by default across the <a
+href="https://android.googlesource.com/">Android Open Source
+Project</a>. In enforcing mode, illegitimate
+actions are prevented and all potential violations are logged by the kernel to
+<code>dmesg</code>. Android device manufacturers should gather information about errors so
+they may refine their software and SELinux policies before enforcing them.
+</p>
-<p>In this release, Android includes SELinux in permissive mode and a
-corresponding security policy that works by default across the <a
-href="https://android.googlesource.com/">Android Open Source Project</a>. In
-permissive mode, no actions are prevented. Instead, all potential violations are
-logged by the kernel to <code>dmesg</code>. This allows Android and Android device
-manufacturers to gather information about errors so they may refine their
-software and SELinux policies before enforcing them.</p>
+<h2 id="background">Background</h2>
+<p>
+Please note, Android upgraded its SELinux policy version to allow the SELinux
+mode to be set on a per-domain basis. For example, if you run all of your
+applications on a single domain, you could set that domain to be permissive and
+then have all other functions and their domains set to enforcement. Domains are
+associated with applications by the key used to sign each application. This
+setting is made at the top of each SELinux policy source (*.te) file.
+</p>
+<p>
+Android follows this model of isolating applications to a single domain. With
+this, only the root domain and root-level processes (such as <code>initd</code>,
+<code>installd</code> and
+<code>vold</code>) are now set to enforcing mode. <em>The application domain remains in
+permissive mode to allow further evaluation and prevent failures. Still, an
+errant application could trigger an action in the root domain that is not
+allowed, thereby causing the application to crash.</em>
+</p>
+<p>
+For this reason, device manufacturers should retain the default settings
+provided by Android and limit enforcing mode to the root domain only until
+they've resolved issues reported in dmesg. That said, device manufacturers may
+need to augment their SELinux implementation to account for their additions and
+other changes to the operating system. See the <em>Customization</em> section for
+instructions.
+</p>
-<h2 id="background">Background</h2> <p>Used properly, SELinux greatly limits the
-potential damage of compromised machines and accounts. When you adopt SELinux,
-you instill a structure by which software runs at only the minimum privilege
-level. This mitigates the effects of attacks and reduces the likelihood of
-errant processes overwriting or even transmitting data.</p>
-
-<p>SELinux provides a mandatory access control (MAC) umbrella over traditional
+<h2 id="mac">Mandatory access control</h2>
+<p>
+In conjunction with other Android security measures, Android's access control
+policy greatly limits the potential damage of compromised
+machines and accounts. Using tools like Android's discretionary and mandatory
+access controls gives you a structure to ensure your software runs
+only at the minimum privilege level. This mitigates the effects of
+attacks and reduces the likelihood of errant processes overwriting or even
+transmitting data.
+</p>
+<p>
+Starting in Android 4.3, SELinux provides a mandatory access control (MAC) umbrella over traditional
discretionary access control (DAC) environments. For instance, software must
typically run as the root user account to write to raw block devices. In a
traditional DAC-based Linux environment, if the root user becomes compromised
that user can write to every raw block device. However, SELinux can be used to
label these devices so the user role assigned the root privilege can write to
only those specified in the associated policy. In this way, root cannot
-overwrite data and system settings outside of the specific raw block device.</p>
+overwrite data and system settings outside of the specific raw block
+device.
+</p>
+<p>
+See the <em>Use Cases</em> section for more examples of threats and ways to address
+them with SELinux.
+</p>
-<p>See the <em>Use Cases</em> section for more examples of threats and ways to
-address them with SELinux.</p>
-
-<h2 id="implementation">Implementation</h2> <p>Android’s initial SELinux
-implementation is launching in permissive mode - rather than the non-functional
-disabled mode or the most stringent enforcing mode - to act as a reference and
-facilitate testing and development.</p>
-
-<p>SELinux is launching in permissive mode on Android to enable the first phase
-of policy development, and it is accompanied by everything you need to enable
-SELinux now.</p>
-
-<p>You merely need to integrate the <a
-href="https://android.googlesource.com/kernel/common/">latest Android kernel</a>
-and then incorporate the files found in the ~<a
+<h2 id="implementation">Implementation</h2>
+<p>
+Android's SELinux implementation is in enforcing mode - rather than the
+non-functional disabled mode or the notification-only permissive mode - to act
+as a reference and facilitate testing and development. Although enforcing mode
+is set globally, please remember this can be overridden on a per-domain basis
+as is in the case of the application domain.
+</p>
+<p>
+SELinux for Android is accompanied by everything you need to enable SELinux
+now. You merely need to integrate the <a
+href="https://android.googlesource.com/kernel/common/">latest Android
+kernel</a> and then incorporate the files found in the
+~<a
href="https://android.googlesource.com/platform/external/sepolicy/">platform/external/sepolicy</a>
-directory:<br>
+directory (where examples can also be found):<br/>
<a
href="https://android.googlesource.com/kernel/common/">https://android.googlesource.com/kernel/common/</a>
-<br>
+<br/>
<a
-href="https://android.googlesource.com/platform/external/sepolicy/">https://android.googlesource.com/platform/external/sepolicy/</a></p>
+href="https://android.googlesource.com/platform/external/sepolicy/">https://android.googlesource.com/platform/external/sepolicy/</a>
+</p>
-<p>Those files when compiled comprise the SELinux kernel security policy and
-cover the upstream Android operating system. Place those files within the
-<root>/device/manufacturer/device-name/sepolicy directory.</p>
-
-<p>Then just update your <code>BoardConfig.mk</code> makefile - located in the
-<device-name> directory containing the sepolicy subdirectory - to
-reference the sepolicy subdirectory once created, like so:</p>
+</p>
+ Those files when compiled comprise the SELinux kernel security policy and cover
+the upstream Android operating system. Place those files within the
+<root>/device/manufacturer/device-name/sepolicy directory.<br/>
+Then just update your <code>BoardConfig.mk</code> makefile - located in the <device-name>
+directory containing the sepolicy subdirectory - to reference the sepolicy
+subdirectory once created, like so:
+</p>
<pre>
BOARD_SEPOLICY_DIRS := \
@@ -91,88 +142,100 @@
sepolicy.te
</pre>
-<p>After rebuilding your device, it is enabled with SELinux. You can now either
+<p>
+After rebuilding your device, it is enabled with SELinux. You can now either
customize your SELinux policies to accommodate your own additions to the Android
operating system as described in the <em>Customization</em> section or verify
-your existing setup as covered in the <em>Validation</em> section.</p>
+your
+existing setup as covered in the <em>Validation</em> section.
+</p>
-<h2 id="customization">Customization</h2> <p>Once you’ve integrated this
-base level of functionality and thoroughly analyzed the results, you may add
-your own policy settings to cover your customizations to the Android operating
-system. Of course, these policies must still meet the <a
-href="{@docRoot}compatibility/index.html">Android Compatibility
-program</a> requirements and not remove the default SELinux settings.</p>
-
-<p>Manufacturers should not remove existing security settings. Otherwise, they
-risk breaking the Android SELinux implementation and the applications it
-governs. This includes third-party applications that will likely need to be
-improved to be compliant and operational. Applications must require no
-modification to continue functioning on SELinux-enabled devices.</p>
-
-<p>See section 9.7 of the Android 4.3 Compatibility Definition document for
-specific requirements:<br><a
-href="{@docRoot}compatibility/android-4.3-cdd.pdf">http://source.android.com/compatibility/android-4.3-cdd.pdf</a></p>
-
-<p>SELinux uses a whitelist approach, meaning it grants special privileges based
-upon role. Because the default policy provided by Android is so permissive, OEMs
-have great leeway in strengthening it. Here is how we recommend proceeding:</p>
+<h2 id="customization">Customization</h2>
+<p>
+Once you've integrated this base level of functionality and thoroughly analyzed
+the results, you may add your own policy settings to cover your customizations
+to the Android operating system. Of course, these policies must still meet the
+<a href="http://source.android.com/compatibility/index.html">Android
+Compatibility
+program</a> requirements and
+not remove the default SELinux settings.
+</p>
+<p>
+Manufacturers should not remove existing security settings. Otherwise, they risk
+breaking the Android SELinux implementation and the applications it governs.
+This includes third-party applications that will likely need to be improved to
+be compliant and operational. Applications must require no modification to
+continue functioning on SELinux-enabled devices.
+</p>
+<p>
+See the <em>Kernel Security Features</em> section of the Android Compatibility
+Definition document for specific requirements:<br/>
+<a
+href="http://source.android.com/compatibility/index.html">http://source.android.com/compatibility/index.html</a>
+</p>
+<p>
+SELinux uses a whitelist approach, meaning it grants special privileges based
+upon role. Since Android's default SELinux policy already supports the Android
+Open Source Project, OEMs are not required to modify SELinux settings in any
+way. If they do customize SELinux settings, they should take great care not to
+break existing applications. Here is how we recommend proceeding:
+</p>
<ol>
-<li>
-<p>Use the <a
-href="https://android.googlesource.com/kernel/common/">latest Android
-kernel</a>.</p> </li>
-<li>
-<p>Adopt the <a
+<li>Use the <a href="https://android.googlesource.com/kernel/common/">latest
+Android
+kernel</a>.</li>
+<li>Adopt the <a
href="http://en.wikipedia.org/wiki/Principle_of_least_privilege">principle of
-least privilege</a>.</p></li>
-<li>
-<p>Address only your own additions to
-Android. The default policy works with the <a
-href="https://android.googlesource.com/">Android Open Source Project</a>
-codebase automatically.</p></li>
-<li>
-<p>Compartmentalize software components
-into modules that conduct singular tasks.</p></li>
-<li>
-<p>Create SELinux
-policies that isolate those tasks from unrelated functions.</p></li>
-<li>
-<p>Put those policies in *.te files (the extension for SELinux policy source
-files) within the <root>/device/manufacturer/device-name/sepolicy
-directory.</p></li>
-<li>
-<p>Release your SELinux implementation in permissive
-mode first.</p></li>
-<li><p>Analyze results and refine policy settings.</p>
-</li>
+least
+privilege</a>.</li>
+<li>Address only your own additions to Android. The default policy works with
+the
+<a href="https://android.googlesource.com/">Android Open Source Project</a>
+codebase
+automatically.</li>
+<li>Compartmentalize software components into modules that conduct singular
+tasks.</li>
+<li>Create SELinux policies that isolate those tasks from unrelated
+functions.</li>
+<li>Put those policies in *.te files (the extension for SELinux policy source
+files) within the <root>/device/manufacturer/device-name/sepolicy
+directory.</li>
+<li>Release your SELinux implementation in permissive mode first.</li>
+<li>Analyze results and refine policy settings.</li>
</ol>
-<p>Once integrated, OEM Android development should include a step to ensure
-SELinux compatibility going forward. In an ideal software development process,
-SELinux policy changes only when the software model changes and not the actual
-implementation.</p>
-
-<p>As device manufacturers begin to customize SELinux, they should first audit
-their additions to Android. If you’ve added a component that conducts a
-new function, the manufacturer will need to ensure the component meets the
-security policy applied by Android, as well as any associated policy crafted by
-the OEM, before turning on enforcement.</p>
-
-<p>To prevent unnecessary issues, it is better to be overbroad and
-over-compatible than too restrictive and incompatible, which results in broken
-device functions. Conversely, if a manufacturer’s changes will benefit
-others, it should supply the modifications to the default SELinux policy as a <a
-href="{@docRoot}source/submit-patches.html">patch</a>. If the
-patch is applied to the default security policy, the manufacturer will no longer
-need to make this change with each new Android release.</p>
+<p>
+Once integrated, OEM Android development should include a step to ensure
+SELinux
+compatibility going forward. In an ideal software development process, SELinux
+policy changes only when the software model changes and not the actual
+implementation.
+</p>
+<p>
+As device manufacturers begin to customize SELinux, they should first audit
+their additions to Android. If they've added a component that conducts a new
+function, the manufacturers will need to ensure the component meets the security
+policy applied by Android, as well as any associated policy crafted by the OEM,
+before turning on enforcement.
+</p>
+<p>
+To prevent unnecessary issues, it is better to be overbroad and over-compatible
+than too restrictive and incompatible, which results in broken device functions.
+Conversely, if a manufacturer's changes will benefit others, it should supply
+the modifications to the default SELinux policy as a
+<a href="http://source.android.com/source/submit-patches.html">patch</a>. If the
+patch is
+applied to the default security policy, the manufacturer will no longer need to
+make this change with each new Android release.
+</p>
<h2 id="use-cases">Use Cases</h2> <p>Here are specific examples of exploits to
consider when crafting your own software and associated SELinux policies:</p>
<p><strong>Symlinks</strong> - Because symlinks appear as files, they are often read
just as that. This can lead to exploits. For instance, some privileged components such
-as init change the permissions of certain files, sometimes to be excessively
+as <code>init</code> change the permissions of certain files, sometimes to be excessively
open.</p>
<p>Attackers might then replace those files with symlinks to code they control,
@@ -224,7 +287,11 @@
<root>/device/manufacturer/device-name/sepolicy directory These files
define domains and their labels. The new policy files get concatenated with the
existing policy files during compilation into a single SELinux kernel policy
-file.</p></li>
+file.</p>
+<p><strong>Important</strong>:Do not alter the app.te file provided by the
+Android Open Source Project. Doing so risks breaking all third-party applications.
+</p>
+</li>
<li>
<p><em>Updated <code>BoardConfig.mk</code> makefile</em> - Located in the
<device-name> directory containing the sepolicy subdirectory. It must be
@@ -268,20 +335,19 @@
<h2 id="validation">Validation</h2> <p>Android strongly encourages OEMs to test
their SELinux implementations thoroughly. As manufacturers implement SELinux,
they should initially release their own policies in permissive mode. If
-possible, apply the new policy to devices of employees first as a test.</p>
+possible, apply the new policy to a test pool of devices first.</p>
<p>Once applied, make sure SELinux is running in the correct mode on the device
by issuing the command: <code>getenforce</code></p>
-<p>This will print the SELinux mode: either Disabled, Enforcing, or Permissive.
-If permissive, you are compliant. Enforcing is explicitly not compliant in
-Android 4.3. (Because of its risk, enforcing mode comes with a much heavier
-testing burden.)</p>
+<p>This will print the global SELinux mode: either Disabled, Enforcing, or Permissive.
+Please note, this command shows only the global SELinux mode. To determine the
+SELinux mode for each domain, you must examine the corresponding files.</p>
<p>Then check for errors. Errors are routed as event logs to <code>dmesg</code>
and viewable locally on the device. Manufacturers should examine the SELinux output
to <code>dmesg</code> on these devices and refine settings prior to public release in
-permissive mode.</p>
+permissive mode and eventual switch to enforcing mode.</p>
<p>With this output, manufacturers can readily identify when system users or
components are in violation of SELinux policy. Manufacturers can then repair
@@ -289,7 +355,29 @@
both.</p>
<p>Specifically, these log messages indicate what roles and processes would fail
-under policy enforcement and why. Android is taking this information, analyzing
+under policy enforcement and why. Here is an example:</p>
+
+<pre>
+denied { connectto } for pid=2671 comm="ping" path="/dev/socket/dnsproxyd"
+scontext=u:r:shell:s0 tcontext=u:r:netd:s0 tclass=unix_stream_socket
+</pre>
+
+<p>Interpret this output like so:</p>
+<ul>
+<li>The { connectto } above represents the action being taken. Together with the
+tclass at the end (unix_stream_socket) it tells you roughly what was being done
+to what. In this case, something was trying to connect to a unix stream
+socket.</li>
+<li>The scontext (u:r:shell:s0) tells you what context initiated the action. In
+this case this is something running as the shell.</li>
+<li>The tcontext (u:r:netd:s0) tells you the context of the action’s target. In
+this case, that’s a unix_stream_socket owned by netd.</li>
+<li>The comm="ping" at the top gives you an additional hint about what was being
+run at the time the denial was generated. In this case, it’s a pretty good
+hint.</li>
+</ul>
+
+<p>Android is taking this information, analyzing
it and refining its default security policy so that it works on a wide range of
Android devices with little customization. With this policy, OEMs must only
accommodate their own changes to the Android operating system.</p>
@@ -298,11 +386,7 @@
href="{@docRoot}compatibility/cts-intro.html">Android
Compatibility Test Suite</a> (CTS).</p> <p>As said, any new policies must still
meet the <a href="{@docRoot}compatibility/index.html">Android
-Compatibility program</a> requirements:<br><a
-href="{@docRoot}compatibility/android-4.3-cdd.pdf">http://source.android.com/compatibility/android-4.3-cdd.pdf</a></p>
-
-<p>If you run the devices through the CTS and find no errors in
-<code>dmesg</code>, you can consider your SELinux implementation compatible.</p>
+Compatibility program</a> requirements.</p>
<p>Finally, if possible, turn on enforcement internally (on devices of
employees) to raise the visibility of failures. Identify any user issues and
diff --git a/src/index.jd b/src/index.jd
index c48a90e..5f2639a 100644
--- a/src/index.jd
+++ b/src/index.jd
@@ -43,7 +43,7 @@
<div class="col-8">
<h3>Updates</h3>
<a href="{@docRoot}source/index.html">
- <h4>Source Code Available for Android 4.3</h4>
+ <h4>Source Code Available for Android</h4>
<p>Android is an open-source software stack for a wide array of mobile devices with different form factors.
<img border="0" src="images/Android_Robot_100.png" alt="Android Partner icon" style="display:inline;float:right;margin:5px 10px">
We created Android in response to our own experiences launching mobile apps. We wanted to make sure there was
@@ -51,7 +51,7 @@
why we created Android and made its source code open.</p>
</a>
<a href="{@docRoot}compatibility/index.html">
- <h4>Compatibility Definition for Android 4.3</h4>
+ <h4>Compatibility Definition for Android</h4>
<p>Android's purpose is to establish an open platform for developers to build innovative apps. The Android
Compatibility program defines the technical details of the Android platform and provides tools for device manufacturers to
ensure developers' apps run on a variety of devices.</p>