The Incremental File System (IncFS) kernel module introduced in Android 11
enables the Android OS to receive streamed APKs over the Android Debug Bridge
(ADB).
This self-contained kernel module creates a new virtual file system that sits
on top of the existing Android file system. This complements changes in the
framework and SDK to enable app and game developers to deploy large APKs through
the ADB to a device running on Android 11 or higher.
The kernel change enables a new
APK Signature Scheme v4 format
and supports Android framework changes in the Android Package Manager,
new system services, and changes to the ADB.
Implementation
To implement the IncFS, OEMs and SoC manufacturers must add a new kernel
driver to their Android device builds.
For Android 11 only
, if the kernel driver
is built as a module it's loaded on demand. If
there aren't any apps installed through an ADB incremental installation, the
device doesn't load the kernel driver.
Otherwise, when it builds as a part of the kernel
image, the driver is always loaded.
This implementation is valid for
Android 12 and higher, and can be used with Android 11
. For
information about upgrading the kernel driver to Android 12, see
Kernel driver upgrade
.
The kernel driver is part of a larger system to enable streamed APK
installations. OEMs and vendors don't need to use the exact IncFS code provided
in the sample implementations. However, to ensure a consistent experience across
devices, you must ensure the API implementation has a file system
that has file-read functionality and directory read-write functionality as
defined in the
Userspace interface for Incremental FS
documentation.
Additionally, implementations must have
mount options
and
special files
that functionally match the IncFS sample implementation.
The following lists the necessary changes for implementation:
- Set up
the development machine
to build the kernel.
- Target the common kernel from the
common-android-mainline
branch.
repo init -u https://android.googlesource.com/kernel/manifest -b common-android-mainline
repo sync
- Validate that the following changes that are needed for IncFS are in the
branch checkout:
- Append either
CONFIG_INCREMENTAL_FS=y
or
for
Android 11 only
,
CONFIG_INCREMENTAL_FS=m
at the bottom of the
defconfig
file. To see an example, click
one of the links below:
- Build the kernel
- Embed the kernel into the
Android device image build
.
- For your target Android device, append one of the following vendor-specific
system-property lines to your
device.mk
file (
optional in devices launched with Android 12 and higher
):
When you're using
CONFIG_INCREMENTAL_FS=y
, append the file with
one of these:
PRODUCT_PROPERTY_OVERRIDES += \
ro.incremental.enable=yes
When you're using
CONFIG_INCREMENTAL_FS=m
(for
Android 11 only
),
append the file with one of these:
PRODUCT_PROPERTY_OVERRIDES += \
ro.incremental.enable=module:/vendor/lib/modules/incrementalfs.ko
- See the example
device.mk
files for the Android emulator and
Pixel 4
.
- For Android 11 only
: If you're using
CONFIG_INCREMENTAL_FS=m
, add
SE Linux Rules
.
Create and add a
vold.te
file to your device
/system/sepolicy/vendor
folder with the following content:
Allow it to load the incremental file system driver:
allow vold self:capability sys_module;
allow vold vendor_incremental_module:file r_file_perms;
allow vold vendor_incremental_module:system module_load;
Append the following SE Linux rules to the existing
file.te
file
found in your
/system/sepolicy/vendor
folder:
-
file.te
file - For an example see this
file.te
file
.)
- Incremental file system driver
type vendor_incremental_module, vendor_file_type, file_type;
Append the following SE Linux rules to existing
file_contents
file found in your
/system/sepolicy/vendor
folder:
-
file_contents
file - For an example, see this
file_contents
file.
# Incremental file system driver
/vendor/lib/modules/incrementalfs\.ko
u:object_r:vendor_incremental_module:s0
Kernel driver upgrade
Devices upgrading to Android 12 might include an older version of the IncFS
driver. For those devices, AOSP recommends that you update the IncFS driver to
the current version (in this case v2) for these reasons:
- The version released with Android 11 is the initial implementation
of IncFS, targeted only for ADB installation support.
- Android 12 uses the IncFS driver for streaming installations of Play games,
which requires the new features and optimizations of IncFS v2 for a better user
experience.
- V1 supports game streaming, but does so with performance penalties and
higher battery, CPU, and RAM usage than v2.
- V2 provides improved UX for streaming, with smooth progress animations,
precise disk-space usage reporting, and prevention of 3rd-party apps-streaming
interference.
To upgrade the IncFS driver in your kernel, apply the following patches for
either kernel 4.14 or kernel 4.19:
For all other custom kernel versions please port one of the patchsets. They
only affect the
fs/incfs
directory and apply cleanly to the
existing v1 code.
Continue using the IncFS driver in the same manner as for the original but now
upgraded Android 11, either as a built-in part of the kernel image,
or as a separate module. Don’t change the system board or system property
configuration.
New devices using a GKI kernel image get the latest (v2) IncFS driver
automatically, configured as a part of the kernel image. This doesn’t require
additional steps.
The loadable module configuration was deprecated in Android 12, and isn’t
supported for new devices. It’s only allowed for the upgrades, or for a vendor
image freeze when the original kernel already had it built as a module.
Reference implementations
This implementation can be considered either as part of a kernel image, or (
for
Android 11 only
) as a loadable module.
Loadable module (Pixel 4 device)
Android Emulator (as a part of the kernel image)
Validation and testing
Validate the implementation using Feature Unit Tests, CTS and GTS.
CTS
Use
CtsIncrementalInstallHostTestCases
.
GTS
atest GtsIncrementalInstallTestCases
:
/gts-tests/tests/packageinstaller/incremental/src/com/google/android/packageinstaller/incremental/gts/IncrementalInstallerTest.java
Test the IncFS
- Set up
a development environment.
- Complete implementation tasks outlined in the implementation section.
- Run the following manual tests:
mmma system/incremental_delivery/incfs/tests
atest libincfs-test
atest IncrementalServiceTest
atest PackageManagerShellCommandTest
PackageManagerShellCommandIncrementalTest
How to test IncFS with Android SDK (ADB and apksigner)
Locate these tests