Docs: Changes to Storage section for M
Bug: 21155375
Change-Id: I0448445405e4cf3de00dfc1c46f993ddfa628e35
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 9184b0b..63aaee9 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>
