User Data Checkpoint (UDC) in Android 13

User Data Checkpoint is a crucial feature, which was initially introduced in Android 10, but has now improved over time, and now in Android 13, is better than ever. In this article, we will understand more about the concept of UDC, and how we can avail it in case our app ever differs from the OTA update policy and the update fails.

GeekTip #1: The User Data Checkpoint (UDC) is a fallback support, and is not ensured to act always when a crash or software update fails.

What is User Data Checkpoint?

When an Android over-the-air (OTA) update fails, Android 10 introduces User Data Checkpoint (UDC), which enables Android to revert to its previous state. If an Android OTA update fails, the device can safely revert to its prior state thanks to UDC. While rollback is not supported when the user data partition (mounted on /data) is changed, A/B updates do solve this issue during early boot.

Even after the user data partition has been changed, UDC allows the device to roll it back. The UDC feature achieves this by providing the file system with checkpoint capabilities, a fallback implementation in the event that the file system does not support checkpoints, integration with the bootloader A/B mechanism while supporting non-A/B updates, support for key version binding, and key rollback prevention.

The underlying concept behind the working of UDC:

1. Checkpoint features in several file systems: UDC backports the checkpoint capability to all common kernels supported by devices running Android 10 and adds it to the mainline Linux kernel 4.20 for the F2FS file system. UDC employs a device mapper virtual device called dm bow for checkpoint functionality for other file systems. The file system and the device are separated by dm bow. When a partition is mounted, the file system issues a trim command, causing trim commands to be sent to all available free blocks. These trims are captured by dm bow, which utilizes control of keymaster keys
2. Using the keymaster key: Devices can be encrypted using keymaster keys or for other purposes. Android waits until the checkpoint is committed before making key delete requests to manage these keys. them to create a free block list. The data required for a restore is then backed up to a free block before reads and writes are permitted to be delivered to the device without modification. 
3. Checking Procedure: Android invokes restoreCheckpoint on the drive when a partition with the checkpoint=fs/block flag is mounted, enabling the device to restore any recent checkpoints. In order to establish whether the device is either in a bootloader A/B state or has set the update retry count, init then uses the needsCheckpoint method. If both conditions are satisfied, Android launches createCheckpoint to either build a dm bow device or add mount flags.

We will now be looking at how this affects the user of the device, and what can he do in case the update over the OTA fails or the updater crashes.

User-Interaction

Because fewer people lose their data when an OTA update fails thanks to the UDC feature, users have a better OTA update experience. As a result, fewer people may contact customer service with update-related problems. Users may observe numerous device reboots when an OTA update fails, though. We will now be discussing the various APIs which are a part of the Data Checkpoint one by one.

Particulars	API Used	Description
To Mark a Checkpoint	void startCheckpoint(int retry)	When the framework is prepared to begin an update, it calls this function. Before checkpointed file systems, like userdata, are mounted R/W after a reboot, the checkpoint is created. The updater calls needsRollback to determine whether a rollback of the update is necessary if the retry count is positive. The API defers to the A/B bootloader’s judgment if the retry count is zero.
To Mark the Changes	void commitChanges()	When the modifications are ready to be committed after a reboot, the framework invokes this function. This is invoked prior to BootComplete and before data (such as images, videos, SMS, and server reception of receipt) is written to userdata. This approach is ineffective if there are no ongoing checkpointed updates.
To Check if a RollBack is required	bool needsRollback()	When the system needs to enquire that does the fallback needs to be called, it can use this API and get the status in the form of a boolean value. A true means yes, a rollback is required.
To Cancel all the Changes Made	abortChanges()	If you want to cancel all the changes made, and also stop the process in between you can call the abort API to handle that, and use it to stop the process in between.

GeekTip #2: When performing a typical A/B update, this procedure is not invoked.

How to Implement UDC in Android?

To add the User Data Checkpoint, you will have to add several lines of code in your application, to let the Android system know that your app is ready to support UDC.

Step #1: Adding support for the checkpoint in the Android Manifest XML file

<manifest>
...
//Setting the User Data Checkpoint Flag to 'True'
BOARD_USES_METADATA_PARTITION := true
//Rest of your Android Manifest goes here.
</manifest>

Step #2: Adding the extra folders in the root partition, to resume from the checkpoint:

// This line adds the folders to the partition.
EXTRA_ROOT_FOLDER := existing_folders metadata

Conclusion

The User Data Checkpoint is a vital feature that is introduced and greatly improved over time, if your app is an app that handles the OTA updates on a user device, as part of the policy, or otherwise, then you can use these APIs to make the upgrade experience better for the users and save some time as well.