Boot image profiles

Android 11 or higher supports generating boot image profiles, which encapsulate information about the code of various system-level components such as system server and boot classpath. Android Runtime (ART) uses this information to perform system-wide optimizations, some of which are critical to Android's performance and impact the execution of all nonnative code (system or app level). In some cases, boot image profiles can impact execution performance and memory consumption by double digit percentages.

Get boot profile information

Boot image profiles are derived from the profiles of apps executed during critical user journeys (CUJs). In a specific device configuration, ART captures (as part of the JIT profiles) the boot classpath methods and classes used by apps, then records that information in the app profile (for example, /data/misc/profiles/cur/0/com.android.chrome/primary.prof), where it's indexed by the boot classpath Dalvik EXecutable (DEX) file (see ART profile format).

Review the app profiles recorded during CUJs to determine which part of the boot classpath is most used and most important to optimize (for an example, see ART profile format). Including all methods or classes negatively affects performance, so focus on the most commonly used code paths. For example, if a method from the boot classpath is used by a single app, it shouldn't be part of the boot profiles. Each device should configure the method/class selection based on the CUJ selection and the amount of data produced by testing.

To aggregate boot classpath information from all individual app profiles on the device, run the adb shell cmd package snapshot-profile android command. You can use the aggregated information as the basis for processing and method/class selection without manually aggregating individual profiles (although you can do that if desired).

Boot image profile

Figure 1. Process for getting boot image profiles

Boot image profile data

Boot image profiles include the following files and data.

Profile for the boot classpath (frameworks/base/config/boot-image-profile.txt). Determines which methods from the boot classpath get optimized, which class is included in the boot .art image, and how the corresponding DEX files are laid out.
List of preloaded classes. Determines which classes are preloaded in Zygote.
Profile for the system server components (frameworks/base/services/art-profile). Determines which methods from the system server get optimized/compiled, which class is included in the boot .art image, and how the corresponding DEX files are laid out.

ART profile format

The ART profile captures information from each of the loaded DEX files, including information about methods worth optimizing and classes used during startup. When boot image profiling is enabled, ART also includes the boot classpath and system server JAR files in the profile and annotates each DEX file with the name of the package that uses it.

For example, dump the raw boot image profile with the following command:

adb shell profman --dump-only --profile-file=/data/misc/profman/android.prof

This produces output similar to:

=== Dex files  ===
=== profile ===
ProfileInfo [012]

core-oj.jar:com.google.android.ext.services [index=0] [checksum=e4e3979a]
        hot methods: 520[], 611[] …
        startup methods: …
        classes: …
...
core-oj.jar:com.android.systemui [index=94] [checksum=e4e3979a]
        hot methods: 520[], 521[]…
        startup methods: …
        classes: …

In the above example:

core-oj.jar is used by com.google.android.ext.services and com.android.systemui. Each entry lists the two packages used from core-oj.jar.
Both processes use the method with DEX index 520, but only the systemui process uses the method with DEX index 521. The same rationale applies to the other profile sections (for example, the startup classes).

During data processing, filter methods/classes based on usage, giving priority to system-level processes (for example, the system server or systemui) or to methods that might not be commonly used but are still important (for example, methods used by the camera app).

The profile format internally annotates each method with multiple flags (startup, post-startup, hotness, abi), which is more than is displayed in the dump-only format. To make use of all the signals, modify the available scripts.

Recommendations

Use the following guidelines for best results.

Deploy the configuration for generating boot image profiles to several test devices and aggregate the results before generating the final boot image profile. The profman tool supports aggregating and selecting multiple boot image profiles, but it works only with the same version of the boot image (same boot classpath).
Give selection priority to the methods/classes that are used by system processes. These methods/classes might use code that isn't often used by other apps but that's still critical to optimize.
The data shape from a single device run looks very different compared to test devices that execute real-world CUJs. If you don't have a large fleet of test devices, use the same device to run several CUJs to increase the confidence that the boot image profile optimizations will work well in production (this scenario is described below).

Configure devices

To enable boot profile configuration through system properties, use one of the following methods.

Option 1: Manually set up props (works up to reboot):

adb root
adb shell stop
adb shell setprop dalvik.vm.profilebootclasspath true
adb shell setprop dalvik.vm.profilesystemserver true
adb shell start

Option 2: Use a local.prop (permanent effect until the file is deleted). To do so:

Create a local.prop file with the content:

dalvik.vm.profilebootclasspath=true
dalvik.vm.profilesystemserver=true

Run the following commands:

adb push local.prop /data/
adb shell chmod 0750 /data/local.prop
adb reboot

Option 3: Use device configuration to set the following server-side properties:

persist.device_config.runtime_native_boot.profilesystemserver
persist.device_config.runtime_native_boot.profilebootclasspath`

Generate boot image profiles

Use the following instructions to generate a basic boot image profile using testing on a single device.

Set up the device.
1. Configure the device as described in Configuring devices.
2. (Optional) It takes time for the new profile format to clean and replace the other profiles. To speed up profile collection, reset all profiles on the device.
```
adb shell stop
adb shell find "/data/misc/profiles -name *.prof -exec truncate -s 0 {} \;"
adb shell start
```
3. Run the CUJs on the device.

Capture the profile using the following command:

adb shell cmd package snapshot-profile android

Extract the profile using the following command:
```
adb pull /data/misc/profman/android.prof
```
Navigate to the boot classpath JAR files using the following commands:
```
m dist
ls $ANDROID_PRODUCT_OUT/boot.zip
```

Generate the boot image profile using the following profman command.

profman --generate-boot-image-profile --profile-file=android.prof --out-profile-path=... --out-preloaded-classes-path=...

Using data, tweak the profman command using the available selection threshold flags.
- --method-threshold
- --class-threshold
- --clean-class-threshold
- --preloaded-class-threshold
- --upgrade-startup-to-hot
- --special-package
To view the full list, refer to the profman help page or source code.