Incremental File System

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:

  1. Set up the development machine to build the kernel.
  2. 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
  3. Validate that the following changes that are needed for IncFS are in the branch checkout:
  4. 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:
  5. Build the kernel
  6. Embed the kernel into the Android device image build.
  7. For your target Android device, append one of the following vendor-specific system-property lines to your device.mk file (optional in Android 12 and higher):

    8. 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
  8. See the example device.mk files for the Android emulator and Pixel 4.
  9. For Android 11 only: If you're using CONFIG_INCREMENTAL_FS=m, add SE Linux Rules.

    10. Create and add a vold.te file to your device /system/sepolicy/vendor folder with the following content:

    • vold.te

    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

  1. Set up a development environment.
  2. Complete implementation tasks outlined in the implementation section.
  3. 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)

  • Set up a development environment.
  • Complete implementation tasks outlined in the implementation section.
  • Flash the build on a target physical device or emulator.
  • Generate or obtain an existing APK.
  • Create a debug signing key.
  • Sign the APK with v4 signature format from thebuild-tools folder. 
    ./apksigner sign --ks debug.keystore game.apk
  • Install the APK on-device from the platform-tools folder. 
    ./adb install game.apk
Example of install
Figure 1: Install example

Locate these tests