Merge "Docs: Adding new file for power mgmt (doze, app standby, exemptions). Update to toc." into mnc-dev
diff --git a/src/compatibility/android-cdd.html b/src/compatibility/android-cdd.html
index 55fa014..1d46261 100644
--- a/src/compatibility/android-cdd.html
+++ b/src/compatibility/android-cdd.html
@@ -350,7 +350,7 @@
implementer to ensure compatibility with existing implementations.</p>
<p>For this reason, the Android Open Source Project [<a href="http://source.android.com/">Resources, 2</a>] is both the reference and preferred implementation of Android. Device
-implementers are strongly encouraged to base their implementations to the
+implementers are STRONGLY RECOMMENDED to base their implementations to the
greatest extent possible on the “upstream” source code available from the
Android Open Source Project. While some components can hypothetically be
replaced with alternate implementations this practice is strongly discouraged,
@@ -595,13 +595,13 @@
<td>VERSION.SDK</td>
<td>The version of the currently-executing Android system, in a format accessible
to third-party application code. For Android ANDROID_VERSION, this field MUST have the
-integer value 22.</td>
+integer value ANDROID_VERSION_INT.</td>
</tr>
<tr>
<td>VERSION.SDK_INT</td>
<td>The version of the currently-executing Android system, in a format accessible
to third-party application code. For Android ANDROID_VERSION, this field MUST have the
-integer value 22.</td>
+integer value ANDROID_VERSION_INT.</td>
</tr>
<tr>
<td>VERSION.INCREMENTAL</td>
@@ -917,7 +917,7 @@
implemented.</p>
<p>Native code compatibility is challenging. For this reason, device implementers
-are <strong>very strongly encouraged</strong> to use the implementations of the libraries listed above from the upstream
+are <strong>STRONGLY RECOMMENDED</strong> to use the implementations of the libraries listed above from the upstream
Android Open Source Project. </p>
<h3 id="3_3_2_32-bit_arm_native_code_compatibility">
@@ -1433,7 +1433,7 @@
interacts with screens.</li>
</ul>
-<p>Device implementations are STRONGLY ENCOURAGED to use the upstream Android user
+<p>Device implementations are STRONGLY RECOMMENDED to use the upstream Android user
interface (or a similar thumbnail-based interface) for the overview screen.</p>
<h3 id="3_8_9_input_management">3.8.9. Input Management</h3>
@@ -1723,8 +1723,8 @@
<td></td>
<td>REQUIRED <br>(Android 3.1+)</td>
<td>Mono/Stereo (no multichannel). Sample rates up to 48 kHz (but up to 44.1 kHz is
-recommended on devices with 44.1 kHz output, as the 48 to 44.1 kHz downsampler
-does not include a low-pass filter). 16-bit recommended; no dither applied for
+RECOMMENDED on devices with 44.1 kHz output, as the 48 to 44.1 kHz downsampler
+does not include a low-pass filter). 16-bit RECOMMENDED; no dither applied for
24-bit.</td>
<td>FLAC (.flac) only</td>
</tr>
@@ -1915,7 +1915,7 @@
<p class="table_footnote">4 Device implementations SHOULD support writing Matroska WebM files.</p>
-<p class="table_footnote">5 Strongly recommended for Android Automotive, optional for Android Watch, and required for all other device types.</p>
+<p class="table_footnote">5 STRONGLY RECOMMENDED for Android Automotive, optional for Android Watch, and required for all other device types.</p>
<h2 id="5_2_video_encoding">5.2. Video Encoding</h2>
@@ -2191,7 +2191,7 @@
<p>While some of the requirements outlined in this section are stated as SHOULD
since Android 4.3, the Compatibility Definition for a future version is planned
-to change these to MUST. Existing and new Android devices are <strong>very strongly encouraged</strong> to meet these requirements, or they will not be able to attain Android
+to change these to MUST. Existing and new Android devices are <strong>STRONGLY RECOMMENDED</strong> to meet these requirements, or they will not be able to attain Android
compatibility when upgraded to the future version.</p>
<h3 id="5_4_1_raw_audio_capture">5.4.1. Raw Audio Capture</h3>
@@ -2339,7 +2339,7 @@
NDK_root/docs/opensles/index.html.</li>
</ul>
-<p>Device implementations that declare android.hardware.audio.output are STRONGLY ENCOURAGED to meet
+<p>Device implementations that declare android.hardware.audio.output are STRONGLY RECOMMENDED to meet
or exceed these audio output requirements:</p>
<ul>
@@ -2356,7 +2356,7 @@
android.content.pm.PackageManager class [<a href="http://developer.android.com/reference/android/content/pm/PackageManager.html">Resources, 53</a>]. Conversely, if the device implementation does not meet these requirements it
MUST NOT report support for low-latency audio.</p>
-<p>Device implementations that include android.hardware.microphone are STRONGLY ENCOURAGED to meet
+<p>Device implementations that include android.hardware.microphone are STRONGLY RECOMMENDED to meet
these input audio requirements:</p>
<ul>
@@ -2471,7 +2471,7 @@
<li>
If the device includes a 4 conductor 3.5mm audio jack,
-the device implementation is STRONGLY ENCOURAGED to comply with section
+the device implementation is STRONGLY RECOMMENDED to comply with section
<a href="https://source.android.com/accessories/headset/specification.html#mobile_device_jack_specifications">Mobile device (jack) specifications</a>
of the
<a href="https://source.android.com/accessories/headset/specification.html">Wired Audio Headset Specification (v1.1)</a>.
@@ -3209,7 +3209,7 @@
<li>SHOULD report the event time in nanoseconds as defined in the Android SDK
documentation, representing the time the event happened and synchronized with
the SystemClock.elapsedRealtimeNano() clock. Existing and new Android devices
-are <strong>very strongly encouraged</strong> to meet these requirement so they will be able to upgrade to the future
+are <strong>STRONGLY RECOMMENDED</strong> to meet these requirement so they will be able to upgrade to the future
platform releases where this might become a REQUIRED component. The
synchronization error SHOULD be below 100 milliseconds [<a href="http://developer.android.com/reference/android/hardware/SensorEvent.html#timestamp">Resources, 75</a>].</li>
</ul>
@@ -3244,7 +3244,7 @@
<p>Device implementations SHOULD include a 3-axis accelerometer. Android Handheld
-devices and Android Watch devices are strongly encouraged to include this
+devices and Android Watch devices are STRONGLY RECOMMENDED to include this
sensor. If a device implementation does include a 3-axis accelerometer, it:</p>
<ul>
@@ -3268,14 +3268,14 @@
period of at least 3 seconds at the fastest sampling rate.</li>
<li>SHOULD implement the TYPE_SIGNIFICANT_MOTION, TYPE_TILT_DETECTOR,
TYPE_STEP_DETECTOR, TYPE_STEP_COUNTER composite sensors as described in the
-Android SDK document. Existing and new Android devices are <strong>very strongly encouraged</strong> to implement the TYPE_SIGNIFICANT_MOTION composite sensor. If any of these
+Android SDK document. Existing and new Android devices are <strong>STRONGLY RECOMMENDED</strong> to implement the TYPE_SIGNIFICANT_MOTION composite sensor. If any of these
sensors are implemented, the sum of their power consumption MUST always be less
than 4 mW and SHOULD each be below 2 mW and 0.5 mW for when the device is in a
dynamic or static condition.</li>
<li>If a gyroscope sensor is included, MUST implement the TYPE_GRAVITY and
TYPE_LINEAR_ACCELERATION composite sensors and SHOULD implement the
TYPE_GAME_ROTATION_VECTOR composite sensor. Existing and new Android devices
-are strongly encouraged to implement the TYPE_GAME_ROTATION_VECTOR sensor.</li>
+are STRONGLY RECOMMENDED to implement the TYPE_GAME_ROTATION_VECTOR sensor.</li>
<li>SHOULD implement a TYPE_ROTATION_VECTOR composite sensor, if a gyroscope sensor
and a magnetometer sensor is also included.</li>
</ul>
@@ -3289,7 +3289,7 @@
<ul>
<li>MUST implement the TYPE_MAGNETIC_FIELD sensor and SHOULD also implement
TYPE_MAGNETIC_FIELD_UNCALIBRATED sensor. Existing and new Android devices are
-strongly encouraged to implement the TYPE_MAGNETIC_FIELD_UNCALIBRATED sensor.</li>
+STRONGLY RECOMMENDED to implement the TYPE_MAGNETIC_FIELD_UNCALIBRATED sensor.</li>
<li>MUST be able to report events up to a frequency of at least 10 Hz and SHOULD
report events up to at least 50 Hz.</li>
<li>MUST comply with the Android sensor coordinate system as detailed in the
@@ -3333,7 +3333,7 @@
<ul>
<li>MUST implement the TYPE_GYROSCOPE sensor and SHOULD also implement
TYPE_GYROSCOPE_UNCALIBRATED sensor. Existing and new Android devices are
-strongly encouraged to implement the SENSOR_TYPE_GYROSCOPE_UNCALIBRATED sensor.</li>
+STRONGLY RECOMMENDED to implement the SENSOR_TYPE_GYROSCOPE_UNCALIBRATED sensor.</li>
<li>MUST be capable of measuring orientation changes up to 1,000 degrees per second.</li>
<li>MUST be able to report events up to a frequency of at least 50 Hz for
Android Watch devices as such devices have a stricter power constraint and
@@ -3353,7 +3353,7 @@
<li>If an accelerometer sensor is included, MUST implement the TYPE_GRAVITY and
TYPE_LINEAR_ACCELERATION composite sensors and SHOULD implement the
TYPE_GAME_ROTATION_VECTOR composite sensor. Existing and new Android devices
-are strongly encouraged to implement the TYPE_GAME_ROTATION_VECTOR sensor.</li>
+are STRONGLY RECOMMENDED to implement the TYPE_GAME_ROTATION_VECTOR sensor.</li>
</ul>
<h3 id="7_3_5_barometer">7.3.5. Barometer</h3>
@@ -3907,7 +3907,7 @@
implementations MUST have at least 1.5GB of non-volatile storage available for
application private data. That is, the /data partition MUST be at least 5GB for
Android Television devices and at least 1.5GB for other device implementations.
-Device implementations that run Android are <strong>very strongly encouraged</strong> to have at least 3GB of non-volatile storage for application private data so
+Device implementations that run Android are <strong>STRONGLY RECOMMENDED</strong> to have at least 3GB of non-volatile storage for application private data so
they will be able to upgrade to the future platform releases.</p>
<p>The Android APIs include a Download Manager that applications MAY use to
@@ -3985,12 +3985,12 @@
<li>The port MUST be connectable to a USB host that has a standard type-A or type
-C USB port.</li>
<li>The port SHOULD use micro-A, micro-AB or type-C USB form factor. Existing and
-new Android devices are <strong>very strongly encouraged to meet these requirements</strong> so they will be able to upgrade to the future platform releases.</li>
+new Android devices are <strong>STRONGLY RECOMMENDED to meet these requirements</strong> so they will be able to upgrade to the future platform releases.</li>
<li>The port SHOULD be centered in the middle of an edge. Device implementations
SHOULD either locate the port on the bottom of the device (according to natural
orientation) or enable software screen rotation for all apps (including home
screen), so that the display draws correctly when the device is oriented with
-the port at bottom. Existing and new Android devices are <strong>very strongly encouraged to meet these requirements</strong> so they will be able to upgrade to future platform releases.</li>
+the port at bottom. Existing and new Android devices are <strong>STRONGLY RECOMMENDED to meet these requirements</strong> so they will be able to upgrade to future platform releases.</li>
<li>It MUST allow a USB host connected with the Android device to access the
contents of the shared storage volume using either USB mass storage or Media
Transfer Protocol.</li>
@@ -4004,7 +4004,7 @@
documentation [<a href="http://developer.android.com/reference/android/hardware/usb/UsbConstants.html#USB_CLASS_AUDIO">Resources, 98</a>].</li>
</ul></li>
<li>It SHOULD implement support to draw 1.5 A current during HS chirp and traffic
-as specified in the USB battery charging specification [<a href="http://www.usb.org/developers/docs/devclass_docs/USB_Battery_Charging_1.2.pdf">Resources, 99</a>]. Existing and new Android devices are <strong>very strongly encouraged to meet these requirements</strong> so they will be able to upgrade to the future platform releases.</li>
+as specified in the USB battery charging specification [<a href="http://www.usb.org/developers/docs/devclass_docs/USB_Battery_Charging_1.2.pdf">Resources, 99</a>]. Existing and new Android devices are <strong>STRONGLY RECOMMENDED to meet these requirements</strong> so they will be able to upgrade to the future platform releases.</li>
<li>The value of iSerialNumber in USB standard device descriptor MUST be equal to
the value of android.os.Build.SERIAL.</li>
</ul>
@@ -4419,7 +4419,7 @@
<p>Device implementations MUST pass all tests described in this section.</p>
<p>However, note that no software test package is fully comprehensive. For this
-reason, device implementers are <strong>very strongly encouraged</strong> to make the minimum number of changes as possible to the reference and
+reason, device implementers are <strong>STRONGLY RECOMMENDED</strong> to make the minimum number of changes as possible to the reference and
preferred implementation of Android available from the Android Open Source
Project. This will minimize the risk of introducing bugs that create
incompatibilities requiring rework and potential device updates.</p>
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index a6ac62b..7b7ed35 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -145,8 +145,10 @@
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/storage/config.html">Device Specific Configuration</a></li>
- <li><a href="<?cs var:toroot ?>devices/storage/config-example.html">Typical Configuration Examples</a></li>
+ <li><a href="<?cs var:toroot ?>devices/storage/traditional.html">Traditional Storage</a></li>
+ <li><a href="<?cs var:toroot ?>devices/storage/adoptable.html">Adoptable Storage</a></li>
+ <li><a href="<?cs var:toroot ?>devices/storage/config.html">Device Configuration</a></li>
+ <li><a href="<?cs var:toroot ?>devices/storage/config-example.html">Configuration Examples</a></li>
</ul>
</li>
<li class="nav-section">
diff --git a/src/devices/storage/adoptable.jd b/src/devices/storage/adoptable.jd
new file mode 100644
index 0000000..899db9b
--- /dev/null
+++ b/src/devices/storage/adoptable.jd
@@ -0,0 +1,98 @@
+page.title=Adoptable Storage
+@jd:body
+<!--
+ Copyright 2015 The Android Open Source Project
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+
+<p>Android has always supported external storage accessories (such as SD cards), but
+these accessories were historically limited to simple file storage, due to
+their expected impermanence and the minimal data protection offered to
+<a href="{@docRoot}devices/storage/traditional.html">traditional external storage</a>.
+Android 6.0 introduces the ability to
+<a href="https://developer.android.com/preview/behavior-changes.html#behavior-adoptable-storage">adopt</a>
+external storage media to act like internal storage.</p>
+
+<p>When external storage media is adopted, it’s formatted and encrypted to only
+work with a single Android device at a time. Because the media is strongly tied
+to the Android device that adopted it, it can safely store both apps and
+private data for all users.</p>
+
+<p>When users insert new storage media (such as an SD card) in an adoptable
+location, Android asks them how they want to use the media. They can choose to
+adopt the media, which formats and encrypts it, or they can continue using it
+as-is for simple file storage. If they choose to adopt, the platform offers to
+migrate the primary shared storage contents (typically mounted at <code>/sdcard</code>)
+to the newly adopted media, freeing up valuable space on internal storage.</p>
+
+<p>Apps can be placed on adopted storage media only when the developer has
+indicated support through the <code>android:installLocation</code> attribute.
+New installs of supported apps are automatically placed on the
+storage device with the most free space, and users can move supported apps
+between storage devices in the <em>Settings</em> app. Apps moved to adopted
+media are remembered while the media is ejected,
+and return when the media is reinserted.</p>
+
+<h2 id=security>Security</h2>
+
+
+<p>The platform randomly generates an encryption key for each adopted device,
+and that key is stored on the internal storage of the Android device. This
+effectively makes the adopted media as secure as internal storage. Keys are
+associated with adopted devices based on the adopted partition GUID. The
+adopted device is encrypted using <code>dm-crypt</code> configured with the
+<code>aes-cbc-essiv:sha256</code> algorithm and a 128-bit key size.</p>
+
+<p>The on-disk layout of the adopted device closely mirrors the internal data
+partition, including SELinux labels, etc. When multi-user is supported on the
+Android device, the adopted storage device also supports multi-user with the
+same level of isolation as internal storage.</p>
+
+<p>Because the contents of an adopted storage device are strongly tied to the
+Android device that adopted it, the encryption keys should not be extractable
+from the parent device, and therefore the storage device can't be mounted elsewhere.</p>
+
+<h2 id=performance_and_stability>Performance and stability</h2>
+
+
+<p>Only external storage media in stable locations, such as a slot inside a
+battery compartment or behind a protective cover, should be considered for
+adoption to help avoid accidental data loss or corruption. In particular, USB
+devices connected to a phone or tablet should never be considered for adoption.
+One common exception would be an external USB drive connected to a TV-style
+device, because the entire TV is typically installed in a stable location.</p>
+
+<p>When a user adopts a new storage device, the platform runs a benchmark and
+compares its performance against internal storage. If the adopted device is
+significantly slower than internal storage, the platform warns the user about a
+possibly degraded experience. This benchmark was derived from the actual I/O
+behavior of popular Android apps. Currently, the AOSP implementation will only
+warn users beyond a single threshold, but device manufacturers may adapt this
+further, such as rejecting adoption completely if the card is extremely slow.</p>
+
+<p>Adopted devices must be formatted with a filesystem that supports POSIX
+permissions and extended attributes, such as <code>ext4</code> or <code>f2fs</code>.
+For optimal performance, the <code>f2fs</code> filesystem is recommended for
+flash-based storage devices.</p>
+
+<p>When performing periodic idle maintenance, the platform issues <code>FI_TRIM</code>
+to adopted media just like it does for internal storage. The current SD card
+specification does not support the <code>DISCARD</code> command; but the kernel
+instead falls back to the <code>ERASE</code> command, which SD card firmware
+may choose to use for optimization purposes.</p>
diff --git a/src/devices/storage/config-example.jd b/src/devices/storage/config-example.jd
index 347d8d5..91be81b 100644
--- a/src/devices/storage/config-example.jd
+++ b/src/devices/storage/config-example.jd
@@ -1,56 +1,53 @@
-page.title=Typical Configuration Examples
+page.title=Configuration Examples
@jd:body
-
<!--
- Copyright 2013 The Android Open Source Project
-
+ Copyright 2015 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
-
http://www.apache.org/licenses/LICENSE-2.0
-
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
-<p>Below are examples of external storage configurations as of Android 4.4
-for various typical devices. Only the relevant portions of the configuration
+<p>Below are examples of external storage configurations
+for various device types. Only the relevant portions of the configuration
files are included.
+<p>Due to configuration changes in Android 6.0 (like the removal of the
+<code>storage_list.xml</code> resource overlay), the configuration examples are
+split into two categories.</p>
-<h2>Physical primary only (like Nexus One)</h2>
-
+<h2 id=android_5_x>Android 5.x and earlier</h2>
+<h3 id=android_5_x_physical>Physical primary only</h3>
<p>This is a typical configuration for a device with single external storage
-device which is a physical SD card.</p>
-
+device which is a physical SD card, like Nexus One.</p>
<p>The raw physical device must first be mounted under
<code>/mnt/media_rw</code> where only the system and FUSE daemon can access
it. <code>vold</code> will then manage the <code>fuse_sdcard0</code> service
when media is inserted/removed.
-
-<h3>fstab.hardware</h3>
-
+<h4>fstab.hardware</h4>
<pre><code>[physical device node] auto vfat defaults voldmanaged=sdcard0:auto,noemulatedsd
</code></pre>
-
-<h3>init.hardware.rc</h3>
-
+<h4>init.hardware.rc</h4>
<pre><code>on init
mkdir /mnt/media_rw/sdcard0 0700 media_rw media_rw
mkdir /storage/sdcard0 0700 root root
-
export EXTERNAL_STORAGE /storage/sdcard0
-
service fuse_sdcard0 /system/bin/sdcard -u 1023 -g 1023 -d /mnt/media_rw/sdcard0 /storage/sdcard0
class late_start
disabled
</code></pre>
-
-<h3>storage_list.xml</h3>
-
+<h4>storage_list.xml</h4>
<pre><code><storage
android:mountPoint="/storage/sdcard0"
android:storageDescription="@string/storage_sd_card"
@@ -58,82 +55,57 @@
android:primary="true"
android:maxFileSize="4096" />
</code></pre>
-
-
-<h2>Emulated primary only (like Nexus 4)</h2>
-
+<h3 id=android_5_x_emulated>Emulated primary only</h3>
<p>This is a typical configuration for a device with single external storage
-device which is backed by internal storage on the device.</p>
-
-<h3>init.hardware.rc</h3>
-
+device which is backed by internal storage on the device, like Nexus 4.</p>
+<h4>init.hardware.rc</h4>
<pre><code>on init
mkdir /mnt/shell/emulated 0700 shell shell
mkdir /storage/emulated 0555 root root
-
export EXTERNAL_STORAGE /storage/emulated/legacy
export EMULATED_STORAGE_SOURCE /mnt/shell/emulated
export EMULATED_STORAGE_TARGET /storage/emulated
-
on fs
setprop ro.crypto.fuse_sdcard true
-
service sdcard /system/bin/sdcard -u 1023 -g 1023 -l /data/media /mnt/shell/emulated
class late_start
</code></pre>
-
-<h3>storage_list.xml</h3>
-
+<h4>storage_list.xml</h4>
<pre><code><storage
android:storageDescription="@string/storage_internal"
android:emulated="true"
android:mtpReserve="100" />
</code></pre>
-
-
-<h2>Emulated primary, physical secondary (like Xoom)</h2>
-
+<h3 id=android_5_x_both>Emulated primary, physical secondary</h3>
<p>This is a typical configuration for a device with multiple external
storage devices, where the primary device is backed by internal storage
-on the device, and where the secondary device is a physical SD card.</p>
-
+on the device, and where the secondary device is a physical SD card, like Xoom.</p>
<p>The raw physical device must first be mounted under
<code>/mnt/media_rw</code> where only the system and FUSE daemon can
access it. <code>vold</code> will then manage the <code>fuse_sdcard1</code>
service when media is inserted/removed.</p>
-
-<h3>fstab.hardware</h3>
-
+<h4>fstab.hardware</h4>
<pre><code>[physical device node] auto vfat defaults voldmanaged=sdcard1:auto
</code></pre>
-
-<h3>init.hardware.rc</h3>
-
+<h4>init.hardware.rc</h4>
<pre><code>on init
mkdir /mnt/shell/emulated 0700 shell shell
mkdir /storage/emulated 0555 root root
-
mkdir /mnt/media_rw/sdcard1 0700 media_rw media_rw
mkdir /storage/sdcard1 0700 root root
-
export EXTERNAL_STORAGE /storage/emulated/legacy
export EMULATED_STORAGE_SOURCE /mnt/shell/emulated
export EMULATED_STORAGE_TARGET /storage/emulated
export SECONDARY_STORAGE /storage/sdcard1
-
on fs
setprop ro.crypto.fuse_sdcard true
-
service sdcard /system/bin/sdcard -u 1023 -g 1023 -l /data/media /mnt/shell/emulated
class late_start
-
service fuse_sdcard1 /system/bin/sdcard -u 1023 -g 1023 -w 1023 -d /mnt/media_rw/sdcard1 /storage/sdcard1
class late_start
disabled
</code></pre>
-
-<h3>storage_list.xml</h3>
-
+<h4>storage_list.xml</h4>
<pre><code><storage
android:storageDescription="@string/storage_internal"
android:emulated="true"
@@ -144,3 +116,43 @@
android:removable="true"
android:maxFileSize="4096" />
</code></pre>
+
+<h2 id=android_6>Android 6.0</h2>
+<h3 id=android_6_physical>Physical primary only</h3>
+<p>This is a typical configuration for a device with single external storage
+device which is a physical SD card, like the original Android One. There is no
+secondary shared storage and the device cannot support multi-user.</p>
+<h4>fstab.device</h4>
+<pre><code>/devices/platform/mtk-msdc.1/mmc_host* auto auto defaults
+voldmanaged=sdcard0:auto,encryptable=userdata,noemulatedsd
+</code></pre>
+<h4>init.device.rc</h4>
+<pre><code>on init
+ # By default, primary storage is physical
+ setprop ro.vold.primary_physical 1
+ </code></pre>
+<h3 id=android_6_emulated> Emulated primary only</h3>
+<p>This is a typical configuration for a device with single external storage
+device which is backed by internal storage on the device, like Nexus 6.</p>
+<ul>
+ <li>Primary shared storage (<code>/sdcard</code>) is emulated on top of internal storage.
+ <li>No secondary SD card storage.
+ <li>USB OTG storage devices supported.
+ <li>Supports multi-user.
+</ul>
+<h4>fstab.device</h4>
+<pre><code>/devices/*/xhci-hcd.0.auto/usb* auto auto defaults
+ voldmanaged=usb:auto</code></pre>
+<h3 id=android_6_both>Emulated primary, physical secondary</h3>
+<p>This is a typical configuration for a device with multiple external storage
+devices, where the primary device is backed by internal storage on the device,
+and where the secondary device is a physical SD card, like Xoom.</p>
+<ul>
+ <li>Primary shared storage (<code>/sdcard</code>) is emulated on top of internal storage.
+ <li>Secondary storage is a physical SD card slot that can be adopted.
+ <li>Supports multi-user.
+</ul>
+<h4>fstab.device</h4>
+<pre><code>/devices/platform/mtk-msdc.1/mmc_host* auto auto defaults
+voldmanaged=sdcard1:auto,encryptable=userdata
+</code></pre>
diff --git a/src/devices/storage/config.jd b/src/devices/storage/config.jd
index b8e4e4f..6db706c 100644
--- a/src/devices/storage/config.jd
+++ b/src/devices/storage/config.jd
@@ -1,34 +1,36 @@
-page.title=Device Specific Configuration
+page.title=Device Configuration
@jd:body
-
<!--
- Copyright 2013 The Android Open Source Project
-
+ Copyright 2015 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
-
http://www.apache.org/licenses/LICENSE-2.0
-
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
<p>External storage is managed by a combination of the <code>vold</code> init
-service and <code>MountService</code> system servic. Mounting of physical
+service and <code>MountService</code> system service. 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.</p>
+<h2 id=file_mappings>File mappings</h2>
<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>
-
<ul>
<li><code>label</code>: Label for the volume.</li>
<li><code>mount_point</code>: Filesystem path where the volume should be mounted.</li>
@@ -38,7 +40,6 @@
<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
@@ -58,10 +59,18 @@
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>,
-<code>encryptable=sdcard</code>, and <code>noemulatedsd</code>.</li>
+<code>encryptable=sdcard</code>, <code>noemulatedsd</code>, and <code>encryptable=userdata</code>.</li>
</ul>
+
+<h2 id=configuration_details>Configuration details</h2>
<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
+through <code>MountService</code>.
+Due to configuration changes in Android 6.0 (like the
+removal of the storage_list.xml resource overlay), the configuration details
+are split into two categories.
+
+<h3 id=android_5_x_and_earlier>Android 5.x and earlier</h3>
+The device-specific <code>storage_list.xml</code> configuration
file, typically provided through a <code>frameworks/base</code> overlay, defines the
attributes and constraints of storage devices. The <code><StorageList></code> element
contains one or more <code><storage></code> elements, exactly one of which should be marked
@@ -94,3 +103,46 @@
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>
+
+<h3 id=android_6_0>Android 6.0</h3>
+<p>Configuration of the storage subsystem is now concentrated in the
+device-specific <code>fstab</code> file, and several historical static configuration files/variables have been
+removed to support more dynamic behavior:</p>
+<ul>
+ <li>The <code>storage_list.xml</code> resource overlay has been removed and is no longer used by the framework.
+Storage devices are now configured dynamically when detected by <code>vold</code>.
+ <li>The <code>EMULATED_STORAGE_SOURCE/TARGET</code> environment variables have been removed and are no longer used by Zygote to
+configure user-specific mount points. Instead, user separation is now enforced
+with user-specific GIDs, and primary shared storage is mounted into place by <code>vold</code> at runtime.
+ <ul>
+ <li>Developers may continue to build paths dynamically or statically depending on
+their use case. Including the UUID in the path identifies each card to make
+location clearer for developers. (For example, <code>/storage/ABCD-1234/report.txt</code> is clearly a different file than <code>/storage/DCBA-4321/report.txt</code>.)
+ </ul>
+ <li>The hard-coded FUSE services have been removed from device-specific <code>init.rc</code> files and are instead forked dynamically from <code>vold</code> when needed.
+</ul>
+<p>In addition to these configuration changes, Android 6.0 includes the notion of
+adoptable storage. For Android 6.0 devices, any physical media that is not
+adopted is viewed as portable. </p>
+
+<h4 id=adoptable_storage>Adoptable storage </h4>
+<p>To indicate an adoptable storage device in the <code>fstab</code>, use the <code>encryptable=userdata</code> attribute in the <code>fs_mgr_flags</code> field. Here’s a typical definition:</p>
+<pre><code>/devices/platform/mtk-msdc.1/mmc_host* auto auto defaults
+voldmanaged=sdcard1:auto,encryptable=userdata
+</code></pre>
+<p>When a storage device is adopted, the platform erases the contents and writes a
+GUID partition table that defines two partitions:</p>
+<ul>
+ <li>a small empty <code>android_meta</code> partition that is reserved for future use. The partition type GUID is
+19A710A2-B3CA-11E4-B026-10604B889DCF.
+ <li>a large <code>android_ext</code> partition that is encrypted using dm-crypt and formatted using either <code>ext4</code> or <code>f2fs</code> depending on the kernel capabilities. The partition type GUID is
+193D1EA4-B3CA-11E4-B075-10604B889DCF.
+</ul>
+<h4 id=portable_storage>Portable storage </h4>
+<p>In the <code>fstab</code>, storage devices with the <code>voldmanaged</code> attribute are considered to be portable by default unless another attribute
+like <code>encryptable=userdata</code> is defined. For example, here’s a typical definition for USB OTG devices:</p>
+<pre><code>/devices/*/xhci-hcd.0.auto/usb* auto auto defaults
+ voldmanaged=usb:auto
+</code></pre>
+<p>The platform uses <code>blkid</code> to detect filesystem types before mounting, and users can choose to format the
+media when the filesystem is unsupported.</p>
diff --git a/src/devices/storage/index.jd b/src/devices/storage/index.jd
index 177e945..7e62fe6 100644
--- a/src/devices/storage/index.jd
+++ b/src/devices/storage/index.jd
@@ -1,36 +1,45 @@
page.title=Storage
@jd:body
-
<!--
Copyright 2015 The Android Open Source Project
-
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
-
http://www.apache.org/licenses/LICENSE-2.0
-
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_extstor.png" alt="Android external storage HAL icon"/>
+<p>Android has evolved over time to support a wide variety of storage device types
+and features. All versions of Android support devices with <a href="{@docRoot}devices/storage/traditional.html">traditional storage</a>,
+which includes portable and emulated storage. <em>Portable</em> storage can be provided by physical media, like an SD card or USB, that is for
+temporary data transfer/ file storage. The physical media may remain with the
+device for an extended period of time, but is not tied to the device and may be
+removed. SD cards have been available as portable storage since Android 1.0;
+Android 6.0 added USB support. <em>Emulated</em> storage is provided by exposing a portion of internal storage through an
+emulation layer and has been available since Android 3.0.</p>
-<p>Android supports devices with external storage, which is defined to be a
-case-insensitive filesystem with immutable POSIX permission classes and
-modes. External storage can be provided by physical media (such as an SD
-card), or by exposing a portion of internal storage through an emulation
-layer. Devices may contain multiple instances of external storage.</p>
+<p>Starting in Android 6.0, Android supports <a href="{@docRoot}devices/storage/adoptable.html"><em>adoptable</em> storage</a>, which is provided by physical media, like an SD card or USB, that is
+encrypted and formatted to behave like internal storage. Adoptable storage can
+store all types of application data. </p>
+<h2 id=permissions>Permissions</h2>
<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. Starting in Android 4.1,
read access is protected with the <code>READ_EXTERNAL_STORAGE</code>
permission.</p>
-
<p>Starting in Android 4.4, the owner, group and modes of files on external
storage devices are now synthesized based on directory structure. This
enables apps to manage their package-specific directories on external
@@ -41,65 +50,29 @@
no permissions. These synthesized permissions are accomplished by wrapping
raw storage devices in a FUSE daemon.</p>
-<p>Since external storage offers minimal protection for stored data, system
-code should not store sensitive data on external storage. Specifically,
-configuration and log files should only be stored on internal storage where
-they can be effectively protected.</p>
+<h3 id=runtime_permissions>Runtime permissions</h3>
-<h2 id="multiple-external-storage-devices">Multiple external storage devices</h2>
-
-<p>Starting in Android 4.4, multiple external storage devices are surfaced
-to developers through <code>Context.getExternalFilesDirs()</code>,
-<code>Context.getExternalCacheDirs()</code>, and
-<code>Context.getObbDirs()</code>.</p>
-
-</p>External storage devices surfaced through these APIs must be a
-semi-permanent part of the device (such as an SD card slot in a battery
-compartment). Developers expect data stored in these locations to be
-available over long periods of time. For this reason, transient storage
-devices (such as USB mass storage drives) should not be surfaced through
-these APIs.</p>
-
-<p>The <code>WRITE_EXTERNAL_STORAGE</code> permission must only grant write
-access to the primary external storage on a device. Apps must not be
-allowed to write to secondary external storage devices, except in their
-package-specific directories as allowed by synthesized
-permissions. Restricting writes in this way ensures the system can clean
-up files when applications are uninstalled.</p>
-
-
-<h2 id="multi-user-external-storage">Multi-user external storage</h2>
-
-<p>Starting in Android 4.2, devices can support multiple users, and external
-storage must meet the following constraints:</p>
+<p>Android 6.0 introduces a new <a href="{@docRoot}devices/tech/config/runtime_perms.html">runtime permissions</a> model where apps request
+capabilities when needed at runtime. Because the new model includes the <code>READ/WRITE_EXTERNAL_STORAGE</code> permissions, the platform needs to dynamically grant storage access without
+killing or restarting already-running apps. It does this by maintaining three
+distinct views of all mounted storage devices:</p>
<ul>
-<li>Each user must have their own isolated primary external storage, and
-must not have access to the primary external storage of other users.</li>
-<li>The <code>/sdcard</code> path must resolve to the correct user-specific
-primary external storage based on the user a process is running as.</li>
-<li>Storage for large OBB files in the <code>Android/obb</code> directory
-may be shared between multiple users as an optimization.</li>
-<li>Secondary external storage must not be writable by apps, except in
-package-specific directories as allowed by synthesized permissions.</li>
+ <li><code>/mnt/runtime/default</code> is shown to apps with no special storage permissions, and to the root
+namespace where <code>adbd</code> and other system components live.
+ <li><code>/mnt/runtime/read</code> is shown to apps with <code>READ_EXTERNAL_STORAGE</code>
+ <li><code>/mnt/runtime/write</code> is shown to apps with <code>WRITE_EXTERNAL_STORAGE</code>
</ul>
-<p>The default platform implementation of this feature leverages Linux kernel
-namespaces to create isolated mount tables for each Zygote-forked process,
-and then uses bind mounts to offer the correct user-specific primary external
-storage into that private namespace.</p>
+<p>At Zygote fork time, we create a mount namespace for each running app and bind
+mount the appropriate initial view into place. Later, when runtime permissions
+are granted, <code>vold</code> jumps into the mount namespace of already-running apps and bind mounts the
+upgraded view into place. Note that permission downgrades always result in the
+app being killed.</p>
-<p>At boot, the system mounts a single emulated external storage FUSE daemon
-at <code>EMULATED_STORAGE_SOURCE</code>, which is hidden from apps. After
-the Zygote forks, 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>
+<p>The <code>setns()</code> functionality used to implement this feature requires at least Linux 3.8, but
+patches have been backported successfully to Linux 3.4. The <code>PermissionsHostTest</code> CTS test can be used to verify correct kernel behavior.</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. It does this by mounting the rootfs as shared, and then
-remounting it as slave after each Zygote namespace is created.</p>
+<p>In Android 6.0, third-party apps don’t have access to the <code>sdcard_r</code> and <code>sdcard_rw</code> GIDs. Instead, access is controlled by mounting only the appropriate runtime
+view in place for that app. Cross-user interactions are blocked using the <code>everybody</code> GID.</p>
diff --git a/src/devices/storage/traditional.jd b/src/devices/storage/traditional.jd
new file mode 100644
index 0000000..c71c644
--- /dev/null
+++ b/src/devices/storage/traditional.jd
@@ -0,0 +1,94 @@
+page.title=Traditional Storage
+@jd:body
+<!--
+ Copyright 2015 The Android Open Source Project
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_extstor.png" alt="Android external storage HAL icon"/>
+
+<p>Android supports devices with traditional storage, which is defined to be a
+case-insensitive filesystem with immutable POSIX permission classes and modes.
+The notion of traditional storage encompasses emulated and portable storage.
+Portable storage is defined as any external storage that is not <a href="{@docRoot}devices/storage/adoptable.html">
+adopted</a> by the
+system and therefore not formatted and encrypted or tied to a specific device.
+Because traditional external storage offers minimal protection for stored data,
+system code should not store sensitive data on external storage. Specifically,
+configuration and log files should only be stored on internal storage where
+they can be effectively protected.</p>
+
+<h2 id="multi-user-external-storage">Multi-user external storage</h2>
+<p>Starting in Android 4.2, devices can support multiple users, and external
+storage must meet the following constraints:</p>
+<ul>
+<li>Each user must have their own isolated primary external storage, and
+must not have access to the primary external storage of other users.</li>
+<li>The <code>/sdcard</code> path must resolve to the correct user-specific
+primary external storage based on the user a process is running as.</li>
+<li>Storage for large OBB files in the <code>Android/obb</code> directory
+may be shared between multiple users as an optimization.</li>
+<li>Secondary external storage must not be writable by apps, except in
+package-specific directories as allowed by synthesized permissions.</li>
+</ul>
+<p>The default platform implementation of this feature leverages Linux kernel
+namespaces to create isolated mount tables for each Zygote-forked process,
+and then uses bind mounts to offer the correct user-specific primary external
+storage into that private namespace.</p>
+<p>At boot, the system mounts a single emulated external storage FUSE daemon
+at <code>EMULATED_STORAGE_SOURCE</code>, which is hidden from apps. After
+the Zygote forks, 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>
+<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. It does this by mounting the rootfs as shared, and then
+remounting it as slave after each Zygote namespace is created.</p>
+
+<h2 id="multiple-external-storage-devices">Multiple external storage devices</h2>
+<p>Starting in Android 4.4, multiple external storage devices are surfaced
+to developers through <code>Context.getExternalFilesDirs()</code>,
+<code>Context.getExternalCacheDirs()</code>, and
+<code>Context.getObbDirs()</code>.</p>
+</p>External storage devices surfaced through these APIs must be a
+semi-permanent part of the device (such as an SD card slot in a battery
+compartment). Developers expect data stored in these locations to be
+available over long periods of time. For this reason, transient storage
+devices (such as USB mass storage drives) should not be surfaced through
+these APIs.</p>
+<p>The <code>WRITE_EXTERNAL_STORAGE</code> permission must only grant write
+access to the primary external storage on a device. Apps must not be
+allowed to write to secondary external storage devices, except in their
+package-specific directories as allowed by synthesized
+permissions. Restricting writes in this way ensures the system can clean
+up files when applications are uninstalled.</p>
+
+<h2 id=support_usb_media>USB media support</h2>
+
+<p>Android 6.0 supports portable storage devices which are only connected to the
+device for a short period of time, like USB flash drives. When a user inserts a
+new portable device, the platform shows a notification to let them copy or
+manage the contents of that device.</p>
+
+<p>In Android 6.0, any device that is not adopted is considered portable. Because
+portable storage is connected for only a short time, the platform avoids heavy
+operations such as media scanning. Third-party apps must go through the <a href="https://developer.android.com/guide/topics/providers/document-provider.html">Storage Access Framework</a> to interact with files on portable storage; direct access is explicitly
+blocked for privacy and security reasons.</p>