1page.title=Device Configuration 2@jd:body 3<!-- 4 Copyright 2015 The Android Open Source Project 5 Licensed under the Apache License, Version 2.0 (the "License"); 6 you may not use this file except in compliance with the License. 7 You may obtain a copy of the License at 8 http://www.apache.org/licenses/LICENSE-2.0 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14--> 15<div id="qv-wrapper"> 16 <div id="qv"> 17 <h2>In this document</h2> 18 <ol id="auto-toc"> 19 </ol> 20 </div> 21</div> 22 23<p>External storage is managed by a combination of the <code>vold</code> init 24service and <code>StorageManagerService</code> system service. Mounting of physical 25external storage volumes is handled by <code>vold</code>, which performs 26staging operations to prepare the media before exposing it to apps.</p> 27 28<h2 id=file_mappings>File mappings</h2> 29<p>For Android 4.2.2 and earlier, the device-specific <code>vold.fstab</code> 30configuration file defines mappings from sysfs devices to filesystem mount 31points, and each line follows this format:</p> 32<pre><code>dev_mount <label> <mount_point> <partition> <sysfs_path> [flags] 33</code></pre> 34<ul> 35<li><code>label</code>: Label for the volume.</li> 36<li><code>mount_point</code>: Filesystem path where the volume should be mounted.</li> 37<li><code>partition</code>: Partition number (1 based), or 'auto' for first usable partition.</li> 38<li><code>sysfs_path</code>: One or more sysfs paths to devices that can provide this mount 39point. Separated by spaces, and each must start with <code>/</code>.</li> 40<li><code>flags</code>: Optional comma separated list of flags, must not contain <code>/</code>. 41Possible values include <code>nonremovable</code> and <code>encryptable</code>.</li> 42</ul> 43<p>For Android releases 4.3 and later, the various fstab files used by init, vold and 44recovery were unified in the <code>/fstab.<device></code> file. For external 45storage volumes that are managed by <code>vold</code>, the entries should have the 46following format:</p> 47<pre><code><src> <mnt_point> <type> <mnt_flags> <fs_mgr_flags> 48</code></pre> 49<ul> 50<li><code>src</code>: A path under sysfs (usually mounted at /sys) to the device that 51can provide the mount point. The path must start with <code>/</code>.</li> 52<li><code>mount_point</code>: Filesystem path where the volume should be mounted.</li> 53<li><code>type</code>: The type of the filesystem on the volume. For external cards, 54this is usually <code>vfat</code>.</li> 55<li><code>mnt_flags</code>: <code>Vold</code> ignores this field and it should be set 56to <code>defaults</code></li> 57<li><code>fs_mgr_flags</code>: <code>Vold</code> ignores any lines in the unified fstab 58that do not include the <code>voldmanaged=</code> flag in this field. This flag must 59be followed by a label describing the card, and a partition number or the word 60<code>auto</code>. Here is an example: <code>voldmanaged=sdcard:auto</code>. 61Other possible flags are <code>nonremovable</code>, 62<code>encryptable=sdcard</code>, <code>noemulatedsd</code>, and <code>encryptable=userdata</code>.</li> 63</ul> 64 65<h2 id=configuration_details>Configuration details</h2> 66<p>External storage interactions at and above the framework level are handled 67through <code>StorageManagerService</code>. 68Due to configuration changes in Android 6.0 (like the 69removal of the storage_list.xml resource overlay), the configuration details 70are split into two categories. 71 72<h3 id=android_5_x_and_earlier>Android 5.x and earlier</h3> 73The device-specific <code>storage_list.xml</code> configuration 74file, typically provided through a <code>frameworks/base</code> overlay, defines the 75attributes and constraints of storage devices. The <code><StorageList></code> element 76contains one or more <code><storage></code> elements, exactly one of which should be marked 77primary. <code><storage></code> attributes include:</p> 78<ul> 79<li><code>mountPoint</code>: filesystem path of this mount.</li> 80<li><code>storageDescription</code>: string resource that describes this mount.</li> 81<li><code>primary</code>: true if this mount is the primary external storage.</li> 82<li><code>removable</code>: true if this mount has removable media, such as a physical SD 83card.</li> 84<li><code>emulated</code>: true if this mount is emulated and is backed by internal storage, 85possibly using a FUSE daemon.</li> 86<li><code>mtp-reserve</code>: number of MB of storage that MTP should reserve for free 87storage. Only used when mount is marked as emulated.</li> 88<li><code>allowMassStorage</code>: true if this mount can be shared via USB mass storage.</li> 89<li><code>maxFileSize</code>: maximum file size in MB.</li> 90</ul> 91<p>Devices may provide external storage by emulating a case-insensitive, 92permissionless filesystem backed by internal storage. One possible 93implementation is provided by the FUSE daemon in <code>system/core/sdcard</code>, which can 94be added as a device-specific <code>init.rc</code> service:</p> 95<pre><code># virtual sdcard daemon running as media_rw (1023) 96service sdcard /system/bin/sdcard <source_path> <dest_path> 1023 1023 97 class late_start 98</code></pre> 99<p>Where <code>source_path</code> is the backing internal storage and <code>dest_path</code> is the 100target mount point.</p> 101<p>When configuring a device-specific <code>init.rc</code> script, the <code>EXTERNAL_STORAGE</code> 102environment variable must be defined as the path to the primary external 103storage. The <code>/sdcard</code> path must also resolve to the same location, possibly 104through a symlink. If a device adjusts the location of external storage between 105platform updates, symlinks should be created so that old paths continue working.</p> 106 107<h3 id=android_6_0>Android 6.0</h3> 108<p>Configuration of the storage subsystem is now concentrated in the 109device-specific <code>fstab</code> file, and several historical static configuration files/variables have been 110removed to support more dynamic behavior:</p> 111<ul> 112 <li>The <code>storage_list.xml</code> resource overlay has been removed and is no longer used by the framework. 113Storage devices are now configured dynamically when detected by <code>vold</code>. 114 <li>The <code>EMULATED_STORAGE_SOURCE/TARGET</code> environment variables have been removed and are no longer used by Zygote to 115configure user-specific mount points. Instead, user separation is now enforced 116with user-specific GIDs, and primary shared storage is mounted into place by <code>vold</code> at runtime. 117 <ul> 118 <li>Developers may continue to build paths dynamically or statically depending on 119their use case. Including the UUID in the path identifies each card to make 120location 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>.) 121 </ul> 122 <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. 123</ul> 124<p>In addition to these configuration changes, Android 6.0 includes the notion of 125adoptable storage. For Android 6.0 devices, any physical media that is not 126adopted is viewed as portable. </p> 127 128<h4 id=adoptable_storage>Adoptable storage </h4> 129<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> 130<pre><code>/devices/platform/mtk-msdc.1/mmc_host* auto auto defaults 131voldmanaged=sdcard1:auto,encryptable=userdata 132</code></pre> 133<p>When a storage device is adopted, the platform erases the contents and writes a 134GUID partition table that defines two partitions:</p> 135<ul> 136 <li>a small empty <code>android_meta</code> partition that is reserved for future use. The partition type GUID is 13719A710A2-B3CA-11E4-B026-10604B889DCF. 138 <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 139193D1EA4-B3CA-11E4-B075-10604B889DCF. 140</ul> 141<h4 id=portable_storage>Portable storage </h4> 142<p>In the <code>fstab</code>, storage devices with the <code>voldmanaged</code> attribute are considered to be portable by default unless another attribute 143like <code>encryptable=userdata</code> is defined. For example, here’s a typical definition for USB OTG devices:</p> 144<pre><code>/devices/*/xhci-hcd.0.auto/usb* auto auto defaults 145 voldmanaged=usb:auto 146</code></pre> 147<p>The platform uses <code>blkid</code> to detect filesystem types before mounting, and users can choose to format the 148media when the filesystem is unsupported.</p> 149