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.
Developing new devices
When defining the device Target FCM Version for new devices:
- Implement HALs for the Target FCM Version.
- Write the correct device manifest file.
- Write the Target FCM Version to device manifest file.
Releasing 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
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>
Upgrading 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.
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
- 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
- Even though the
compatibility_matrix.2.xmlspecifies 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
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|
Upgrading 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:
- Implement all new required HAL Versions for the Target FCM Version.
- Modify HAL Versions in the device manifest file.
- Modify the Target FCM Version in the device manifest file.
- 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
<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
firstname.lastname@example.org, 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
If a device is receiving an Android 9 update, cherry-pick these CLs before generating OTA update packages:
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. 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. For more information about this build flag, see
Updating devices from Android
These changes are already merged in Android 10, so
there is no need to cherry-pick if the device updates to Android
10. However, keep
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 and writes this information
to the OTA package metadata. OTA clients on devices running Android
10 or higher read this information to check
If the script fails to extract this information for your kernel image, do one of the following:
BOARD_KERNEL_VERSIONto the kernel version and
BOARD_KERNEL_CONFIG_FILEto the path of the built kernel configuration file
.config. Both variables must be updated when the kernel image is updated.
- Alternatively, set
falseto remove kernel requirements from the OTA package.
You can view the source code of the kernel information extraction script