External storage technical information.android-sdk-support_r11android-cts-4.2_r1android-4.2_r1android-4.2.1_r1.2android-4.2.1_r1.1android-4.2.1_r1jb-mr1-release

Bug: 7384941
Change-Id: I7e788415048122e5fda7c7fffaafcec23c01b938

2 files changed, 138 insertions, 0 deletions

diff --git a/src/tech/index.md b/src/tech/index.md
index d871a9ae..42908bec 100644
--- a/src/tech/index.md
+++ b/src/tech/index.md
@@ -67,4 +67,10 @@ of when porting Android to specific devices.
 
 [» Data Usage Information](/tech/datausage/index.html)
 
+## External Storage Technical Information
 
+Android supports devices with external storage, typically provided by physical
+media or an emulation layer.  This document is designed to help systems
+integrators configure Android devices.
+
+[» External Storage Technical Information](/tech/storage/index.html)
diff --git a/src/tech/storage/index.md b/src/tech/storage/index.md
new file mode 100644
index 00000000..016cb6c3
--- /dev/null
+++ b/src/tech/storage/index.md
@@ -0,0 +1,132 @@
+<!--
+   Copyright 2012 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.
+-->
+
+# External Storage Technical Information
+
+Android supports devices with external storage, which is defined to be a
+case-insensitive and permissionless filesystem.  External storage can be
+provided by physical media (such as an SD card), or by an emulation layer backed
+by internal storage.  Devices may contain multiple instances of external
+storage, but currently only the primary external storage is exposed to
+developers through API.
+
+## Device specific configuration
+
+External storage is managed by a combination of the `vold` init service and
+`MountService` system service.
+
+Mounting of physical external storage volumes is handled by `vold`, which
+performs staging operations to prepare the media before exposing it to apps.
+The device-specific `vold.fstab` configuration file defines mappings from sysfs
+devices to filesystem mount points, and each line follows this format:
+
+    dev_mount <label> <mount_point> <partition> <sysfs_path> [flags]
+
+* `label`: Label for the volume.
+* `mount_point`: Filesystem path where the volume should be mounted.
+* `partition`: Partition number (1 based), or 'auto' for first usable partition.
+* `sysfs_path`: One or more sysfs paths to devices that can provide this mount
+point.  Separated by spaces, and each must start with `/`.
+* `flags`: Optional comma separated list of flags, must not contain `/`.
+Possible values include `nonremovable` and `encryptable`.
+
+External storage interactions at and above the framework level are handled
+through `MountService`.  The device-specific `storage_list.xml` configuration
+file, typically provided through a `frameworks/base` overlay, defines the
+attributes and constraints of storage devices.  The `<StorageList>` element
+contains one or more `<storage>` elements, exactly one of which should be marked
+primary.  `<storage>` attributes include:
+
+* `mountPoint`: filesystem path of this mount.
+* `storageDescription`: string resource that describes this mount.
+* `primary`: true if this mount is the primary external storage.
+* `removable`: true if this mount has removable media, such as a physical SD
+card.
+* `emulated`: true if this mount is emulated and is backed by internal storage,
+possibly using a FUSE daemon.
+* `mtp-reserve`: number of MB of storage that MTP should reserve for free
+storage.  Only used when mount is marked as emulated.
+* `allowMassStorage`: true if this mount can be shared via USB mass storage.
+* `maxFileSize`: maximum file size in MB.
+
+Devices may provide external storage by emulating a case-insensitive,
+permissionless filesystem backed by internal storage.  One possible
+implementation is provided by the FUSE daemon in `system/core/sdcard`, which can
+be added as a device-specific `init.rc` service:
+
+    # virtual sdcard daemon running as media_rw (1023)
+    service sdcard /system/bin/sdcard <source_path> <dest_path> 1023 1023
+        class late_start
+
+Where `source_path` is the backing internal storage and `dest_path` is the
+target mount point.
+
+When configuring a device-specific `init.rc` script, the `EXTERNAL_STORAGE`
+environment variable must be defined as the path to the primary external
+storage.  The `/sdcard` 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.
+
+As an example, here’s the storage configuration for Xoom, which uses a FUSE
+daemon to provide primary external storage, and includes a physical SD card as
+secondary external storage:
+
+* [vold.fstab](https://android.googlesource.com/device/moto/wingray/+/master/vold.fstab)
+* [storage_list.xml](https://android.googlesource.com/device/moto/wingray/+/master/overlay/frameworks/base/core/res/res/xml/storage_list.xml)
+
+Access to external storage is protected by various Android permissions.
+Starting in Android 1.0, write access is protected with the
+`WRITE_EXTERNAL_STORAGE` permission, implemented using the `sdcard_rw` GID.
+Starting in Android 4.1, read access is protected with the new
+`READ_EXTERNAL_STORAGE` permission, implemented using the `sdcard_r` GID.  To
+implement the read permission, a new top-level `/storage` directory was created
+such that processes must hold the `sdcard_r` GID to traverse into it.
+
+Since external storage offers no support for traditional POSIX filesystem
+permissions, 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.
+
+## Multi-user external storage
+
+Starting in Android 4.2, devices can support multiple users, and external
+storage must meet the following constraints:
+
+* Each user must have their own isolated primary external storage, and must not
+have access to the primary external storage of other users.
+* The `/sdcard` path must resolve to the correct user-specific primary external
+storage based on the user a process is running as.
+* Storage for large OBB files in the `Android/obb` directory may be shared
+between multiple users as an optimization.
+* Secondary external storage must not be writable by apps.
+
+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.
+
+At boot, the system mounts a single emulated external storage FUSE daemon at
+`EMULATED_STORAGE_SOURCE`, which is hidden from apps.  After the Zygote forks,
+it bind mounts the appropriate user-specific subdirectory from under the FUSE
+daemon to `EMULATED_STORAGE_TARGET` 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.
+
+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.