Update the Tech Storage doc for JB-MR2.
This doc on source.android.com needs updating to reflect the changes
made when unifying the fstab files in JB-MR2.
Bug: 8590069
Change-Id: I80120ed4f3982894436c81a994e9acd54f1fbe17
diff --git a/src/devices/tech/storage/index.jd b/src/devices/tech/storage/index.jd
index 71ea31c..0f1b267 100644
--- a/src/devices/tech/storage/index.jd
+++ b/src/devices/tech/storage/index.jd
@@ -26,8 +26,10 @@
<p>External storage is managed by a combination of the <code>vold</code> init service and
<code>MountService</code> system service.</p>
<p>Mounting of physical external storage volumes is handled by <code>vold</code>, which
-performs staging operations to prepare the media before exposing it to apps.
-The device-specific <code>vold.fstab</code> configuration file defines mappings from sysfs
+performs staging operations to prepare the media before exposing it to apps.</p>
+
+<p>For Android 4.2.2 and earlier, the device-specific <code>vold.fstab</code>
+configuration file defines mappings from sysfs
devices to filesystem mount points, and each line follows this format:</p>
<pre><code>dev_mount <label> <mount_point> <partition> <sysfs_path> [flags]
</code></pre>
@@ -40,6 +42,25 @@
<li><code>flags</code>: Optional comma separated list of flags, must not contain <code>/</code>.
Possible values include <code>nonremovable</code> and <code>encryptable</code>.</li>
</ul>
+<p>For Android releases 4.3 and later, the various fstab files used by init, vold and
+recovery were unified in the <code>/fstab.<device></code> file. For external
+storage volumes that are managed by <code>vold</code>, the entries should have the
+following format:</p>
+<pre><code><src> <mnt_point> <type> <mnt_flags> <fs_mgr_flags>
+</code></pre>
+<ul>
+<li><code>src</code>: A path under sysfs (usually mounted at /sys) to the device that
+can provide the mount point. The path must start with <code>/</code>.</li> <li><code>mount_point</code>: Filesystem path where the volume should be mounted.</li>
+<li><code>type</code>: The type of the filesystem on the volume. For external cards,
+this is usually <code>vfat</code>.</li>
+<li><code>mnt_flags</code>: <code>Vold</code> ignores this field and it should be set
+to <code>defaults</code></li>
+<li><code>fs_mgr_flags</code>: <code>Vold</code> ignores any lines in the unified fstab
+that do not include the <code>voldmanaged=</code> flag in this field. This flag must
+be followed by a label describing the card, and a partition number or the word
+<code>auto</code>. Here is an example: <code>voldmanaged=sdcard:auto</code>.
+Other possible flags are <code>nonremovable</code> and <code>encryptable=sdcard</code>.
+</ul>
<p>External storage interactions at and above the framework level are handled
through <code>MountService</code>. The device-specific <code>storage_list.xml</code> configuration
file, typically provided through a <code>frameworks/base</code> overlay, defines the
@@ -74,13 +95,18 @@
storage. The <code>/sdcard</code> path must also resolve to the same location, possibly
through a symlink. If a device adjusts the location of external storage between
platform updates, symlinks should be created so that old paths continue working.</p>
-<p>As an example, here’s the storage configuration for Xoom, which uses a FUSE
-daemon to provide primary external storage, and includes a physical SD card as
+<p>As an example for Android 4.2.2 and earlier, here's the storage configuration for Xoom,
+which uses a FUSE daemon to provide primary external storage, and includes a physical SD card as
secondary external storage:</p>
<ul>
<li><a href="https://android.googlesource.com/device/moto/wingray/+/master/vold.fstab">vold.fstab</a></li>
<li><a href="https://android.googlesource.com/device/moto/wingray/+/master/overlay/frameworks/base/core/res/res/xml/storage_list.xml">storage_list.xml</a></li>
</ul>
+<p>As an example for Android 4.3 and later devices, here's the <code>fstab.goldfish</code> file
+for the Android emulator, which emulates an external SD card as primary external storage:</p>
+<ul>
+<li><a href="https://android.googlesource.com/device/generic/goldfish/+/master/fstab.goldfish">fstab.goldfish</a></li>
+</ul>
<p>Access to external storage is protected by various Android permissions.
Starting in Android 1.0, write access is protected with the
<code>WRITE_EXTERNAL_STORAGE</code> permission, implemented using the <code>sdcard_rw</code> GID.
@@ -113,7 +139,7 @@
it bind mounts the appropriate user-specific subdirectory from under the FUSE
daemon to <code>EMULATED_STORAGE_TARGET</code> so that external storage paths resolve
correctly for the app. Because an app lacks accessible mount points for other
-users’ storage, they can only access storage for the user it was started as.</p>
+users' storage, they can only access storage for the user it was started as.</p>
<p>This implementation also uses the shared subtree kernel feature to propagate
mount events from the default root namespace into app namespaces, which ensures
that features like ASEC containers and OBB mounting continue working correctly.
