Incremental File System

Incremental File System (IncFS) is a kernel module that enables the Android OS to receive streamed APKs over Android Debug Bridge (ADB). The self contained kernel module creates a new virtual file system that sits on top of existing Android File system and complements changes in the Android 11 framework and SDK to enable app and game developers to deploy large APKs through ADB to an Android 11 device.

The kernel change enables a new APK Signature Scheme v4 format, supports Android framework changes in the Android Package Manager, new system services, and changes to the Android Debug Bridge.

Implementation

OEMs and SoC manufacturers need to add a new kernel driver to their Android device builds. If the kernel driver is built as a module, it is loaded on demand. If no app is installed through ADB incremental installation, the device does not load the kernel driver. When building as a part of the kernel image the driver is always loaded.

The kernel driver is part of a larger system to enable streamed APK installations. Partners don't need to use the exact IncFS code provided in the sample implementations. However, to ensure a consistent experience across devices, partners must ensure the API implementation has a file system that has file read functionality and directory read / write functionality as defined here.

Additionally, partner implementations must have mount options and special files that functionally match the IncFS sample implementation.

The following describes the necessary changes for implementation:

  • Setup development machine to build 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 the following changes needed for IncFS are in the branch checkout:
  • Append CONFIG_INCREMENTAL_FS=y or CONFIG_INCREMENTAL_FS=m line to bottom of defconfig file. Examples can be found at the following links:
  • Build kernel
  • Embed 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:
    • In case when you're using CONFIG_INCREMENTAL_FS=y
    • PRODUCT_PROPERTY_OVERRIDES += \
    • ro.incremental.enable=yes
    • In case when you're using CONFIG_INCREMENTAL_FS=m
    • PRODUCT_PROPERTY_OVERRIDES += \
    • ro.incremental.enable=module:/vendor/lib/modules/incrementalfs.ko
    • There are example device.mk files for the Android emulator and Pixel 4.
  • Only if 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:
      • vold.te
      • Allow to load 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 existing file.te file found in your /system/sepolicy/vendor folder:
      • Example 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:
      • Example file_contents file
      • # Incremental file system driver
  • /vendor/lib/modules/incrementalfs\.ko
  • u:object_r:vendor_incremental_module:s0

Reference implementations

There are two ways to approach this implementation, either as a loadable module or as part of a kernel image.

Validation and testing

Validate the implementation using Feature Unit Tests, CTS and GTS.

CTS

GTS

  • atest GtsIncrementalInstallTestCases
    • /gts-tests/tests/packageinstaller/incremental/src/com/google/android/packageinstaller/incremental/gts/IncrementalInstallerTest.java

Testing the IncFs (Incremental FIle System)

  • Setup 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

Testing IncFS with Android SDK (ADB and apksigner)

  • Setup 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 apk with v4 signature format from thebuild-tools folder.
    • $ ./apksigner sign --ks debug.keystore game.apk
  • Install apk on device from platform-tools folder.
    • $ ./adb install game.apk
Example of install
Figure 1: Example of install

Where can these tests be found?