External storage is managed by a combination of the vold
init service and StorageManagerService
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.
Note: In Android 8.0, the MountService
class was renamed to StorageManagerService
.
File mappings
For Android 4.2.2 and earlier, 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 includenonremovable
andencryptable
.
For Android releases 4.3 and later, the various fstab files used by init, vold and recovery were unified in the /fstab.<device>
file. For external storage volumes that are managed by vold
, the entries should have the following format:
<src> <mnt_point> <type> <mnt_flags> <fs_mgr_flags>
src
: A path under sysfs (usually mounted at /sys) to the device that can provide the mount point. The path must start with/
.mount_point
: Filesystem path where the volume should be mounted.type
: The type of the filesystem on the volume. For external cards, this is usuallyvfat
.mnt_flags
:Vold
ignores this field and it should be set todefaults
fs_mgr_flags
:Vold
ignores any lines in the unified fstab that do not include thevoldmanaged=
flag in this field. This flag must be followed by a label describing the card, and a partition number or the wordauto
. Here is an example:voldmanaged=sdcard:auto
. Other possible flags arenonremovable
,encryptable=sdcard
,noemulatedsd
, andencryptable=userdata
.
Configuration details
External storage interactions at and above the framework level are handled through StorageManagerService
. 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.
Android 5.x and earlier
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.
Android 6.0
Configuration of the storage subsystem is now concentrated in the device-specific fstab
file, and several historical static configuration files/variables have been removed to support more dynamic behavior:
- The
storage_list.xml
resource overlay has been removed and is no longer used by the framework. Storage devices are now configured dynamically when detected byvold
. - The
EMULATED_STORAGE_SOURCE/TARGET
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 byvold
at runtime.- 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,
/storage/ABCD-1234/report.txt
is clearly a different file than/storage/DCBA-4321/report.txt
.)
- 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,
- The hard-coded FUSE services have been removed from device-specific
init.rc
files and are instead forked dynamically fromvold
when needed.
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.
Adoptable storage
To indicate an adoptable storage device in the fstab
, use the encryptable=userdata
attribute in the fs_mgr_flags
field. Here’s a typical definition:
/devices/platform/mtk-msdc.1/mmc_host* auto auto defaults voldmanaged=sdcard1:auto,encryptable=userdata
When a storage device is adopted, the platform erases the contents and writes a GUID partition table that defines two partitions:
- a small empty
android_meta
partition that is reserved for future use. The partition type GUID is 19A710A2-B3CA-11E4-B026-10604B889DCF. - a large
android_ext
partition that is encrypted using dm-crypt and formatted using eitherext4
orf2fs
depending on the kernel capabilities. The partition type GUID is 193D1EA4-B3CA-11E4-B075-10604B889DCF.
Portable storage
In the fstab
, storage devices with the voldmanaged
attribute are considered to be portable by default unless another attribute like encryptable=userdata
is defined. For example, here’s a typical definition for USB OTG devices:
/devices/*/xhci-hcd.0.auto/usb* auto auto defaults voldmanaged=usb:auto
The platform uses blkid
to detect filesystem types before mounting, and users can choose to format the media when the filesystem is unsupported.