Device manifest development

When developing and releasing new devices, vendors can define and declare the target FCM version in the device manifest (DM). When upgrading the vendor image for old devices, vendors can choose to implement new HAL versions and increment the target FCM version.

Develop new devices

When defining the device target FCM version for new devices:

  1. Leave DEVICE_MANIFEST_FILE and PRODUCT_ENFORCE_VINTF_MANIFEST undefined.
  2. Implement HALs for the target FCM version.
  3. Write the correct device manifest file.
  4. Write the target FCM version to device manifest file.
  5. Set DEVICE_MANIFEST_FILE.
  6. Set PRODUCT_ENFORCE_VINTF_MANIFEST to true.

Release new devices

When a new device is released, its initial target FCM version needs to be determined and declared in the device manifest as the "target-level" attribute in the top-level <manifest> element.

For example, devices launching with Android 9 must have target FCM version equal to 3 (the higher version available at this time). To declare this in the device manifest:

<manifest version="1.0" type="device" target-level="3">
    <!-- ... -->
</manifest>

Upgrade vendor image

When upgrading the vendor image for an old device, vendors can choose to implement new HAL versions and increment the target FCM version.

Upgrade HALs

During a vendor image upgrade, vendors can implement new HAL versions provided that HAL name, interface name, and instance name are the same. For example:

  • Google Pixel 2 and Pixel 2 XL devices released with target FCM version 2, which implemented the required audio 2.0 HAL android.hardware.audio@2.0::IDeviceFactory/default.
  • For the audio 4.0 HAL that released with Android 9, Google Pixel 2 and Pixel 2 XL devices can use a full OTA to upgrade to the 4.0 HAL, which implements android.hardware.audio@4.0::IDeviceFactory/default.
  • Even though the compatibility_matrix.2.xml specifies audio 2.0 only, the requirement on a vendor image with target FCM version 2 has been loosened because the Android 9 framework (FCM version 3) considers audio 4.0 a replacement of audio 2.0 HAL in terms of functionality.

To summarize, given that compatibility_matrix.2.xml requires audio 2.0 and compatibility_matrix.3.xml requires audio 4.0, the requirements are as follows:

FCM version (system) Target FCM version (vendor) Requirements
2 (8.1) 2 (8.1) Audio 2.0
3 (9) 2 (8.1) Audio 2.0 or 4.0
3 (9) 3 (9) Audio 4.0

Upgrade target FCM version

During a vendor image upgrade, vendors can also increment the target FCM version to specify the targeted FCM version the upgraded vendor image can work with. To bump the target FCM version of a device, vendors need to:

  1. Implement all new required HAL Versions for the target FCM version.
  2. Modify HAL Versions in the device manifest file.
  3. Modify the target FCM version in the device manifest file.
  4. Remove deprecated HAL versions.

For example, Google Pixel and Pixel XL devices launched with Android 7.0 so their target FCM version must be at least legacy. However, the device manifest declares the target FCM version 2 because the vendor image has been updated to conform with compatibility_matrix.2.xml:

<manifest version="1.0" type="device" target-level="2">

If vendors do not implement all required new HAL versions or do not remove deprecated HAL versions, the target FCM version cannot be upgraded.

For example, Google Pixel 2 and Pixel 2 XL devices have target FCM version 2. While they do implement some HALs required by compatibility_matrix.3.xml (such as audio 4.0, health 2.0, etc.), they do not remove android.hardware.radio.deprecated@1.0, which is deprecated at FCM version 3 (Android 9). Hence, these devices cannot upgrade the target FCM version to 3.

Mandating kernel requirements during OTA

Updating devices from Android 9 or lower

On devices with Android 9 or lower, ensure the following CLs are cherry-picked:

These changes introduce the build flag PRODUCT_OTA_ENFORCE_VINTF_KERNEL_REQUIREMENTS and leave the flag unset for devices launched with Android 9 or lower.

  • When updating to Android 10, OTA clients on devices running Android 9 or lower don't check kernel requirements in the OTA package correctly. These changes are needed to drop kernel requirements from the generated OTA package.
  • When updating to Android 11, it is optional to set the PRODUCT_OTA_ENFORCE_VINTF_KERNEL_REQUIREMENTS build flag to check VINTF compatibility when the update package is generated.

For more information about this build flag, see Updating devices from Android 10.

Updating devices from Android 10

Android 10 introduces a new build flag, PRODUCT_OTA_ENFORCE_VINTF_KERNEL_REQUIREMENTS. For devices launched with Android 10, this flag is automatically set to true. When the flag is set to true, a script extracts the kernel version and the kernel configurations from the installed kernel image.

  • When updating to Android 10, OTA update package contains kernel version and configuration. OTA clients on devices running Android 10 read this information to check compatibility.
  • When updating to Android 11, OTA package genreation reads kernel version and configuration to check compatibility.

If the script fails to extract this information for your kernel image, do one of the following:

  • Edit the script to support your kernel format and contribute to AOSP.
  • Set BOARD_KERNEL_VERSION to the kernel version and BOARD_KERNEL_CONFIG_FILE to the path of the built kernel configuration file .config. Both variables must be updated when the kernel image is updated.
  • Alternatively, set PRODUCT_OTA_ENFORCE_VINTF_KERNEL_REQUIREMENTS to false to skip checking kernel requirements. This is not recommended because any incompatibility is hidden and is only discovered when running VTS tests after the update.

You can view the source code of the kernel information extraction script extract_kernel.py.