am e69f3081: Merge "Update the Tech Storage doc for JB-MR2." into jb-mr2-dev

* commit 'e69f308185fb3e3dc92fa8e5ab1b16423a4e334d':
  Update the Tech Storage doc for JB-MR2.

1 files changed, 31 insertions, 5 deletions

diff --git a/src/devices/tech/storage/index.jd b/src/devices/tech/storage/index.jd
index 71ea31c0..0f1b2678 100644
--- a/src/devices/tech/storage/index.jd
+++ b/src/devices/tech/storage/index.jd
@@ -26,8 +26,10 @@ developers through API.</p>
 <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 &lt;label&gt; &lt;mount_point&gt; &lt;partition&gt; &lt;sysfs_path&gt; [flags]
 </code></pre>
@@ -40,6 +42,25 @@ point.  Separated by spaces, and each must start with <code>/</code>.</li>
 <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.&lt;device&gt;</code> file.  For external
+storage volumes that are managed by <code>vold</code>, the entries should have the
+following format:</p>
+<pre><code>&lt;src&gt; &lt;mnt_point&gt; &lt;type&gt; &lt;mnt_flags&gt; &lt;fs_mgr_flags&gt;
+</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 @@ environment variable must be defined as the path to the primary external
 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 @@ storage into that private namespace.</p>
 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.