Soft restarts (<= AOSP 14)

Android 11 supports soft restarts, which are runtime restarts of processes in the user space used to apply updates that require a reboot (for example, updates to APEX packages). Currently, soft restart is limited to processes that started after userdata has been mounted.

A soft restart is requested in the following ways:

  • From PowerManager, by calling PowerManager.reboot(PowerManager.REBOOT_USERSPACE)

  • From shell, using adb shell svc power reboot userspace or adb reboot userspace

After a soft restart, credential encrypted storage remains unlocked.

If a device supports soft restarts, then the PowerManager.isRebootingUserspace() API method returns true, and the value of the system property init.userspace_reboot.is_supported is equal to 1.

If device doesn't support soft restarts, then calls to PowerManager.reboot(PowerManager.REBOOT_USERSPACE), adb reboot userspace, and adb shell svc power reboot userspace fail.

Soft restart execution

After a soft restart is requested (through PowerManager or from a shell), init performs the following steps:

  1. Receives sys.powerctl=reboot,userspace.

  2. Forks a separate UserspaceRebootWatchdogThread() process to monitor the soft restart.

  3. Triggers a userspace-reboot-requested action, which resets all system properties that might impact the soft restart. Affected properties:

    • sys.usb.config
    • sys.usb.state
    • sys.boot_completed
    • dev.bootcomplete
    • sys.init.updatable_crashing
    • sys.init.updatable_crashing_process_name
    • apexd.status
    • sys.user.0.ce_available
    • sys.shutdown.requested
    • service.bootanim.exit

    The above properties should be set again during boot sequence. If needed, you can reset additional properties. For examples, refer to the on userspace-reboot-requested action in rootdir/init.rc.

  4. Runs the DoUserspaceReboot function, which performs the following actions:

    1. Sends SIGTERM to processes started after userdata has been mounted and waits for them to stop.
    2. After the timeout is reached, sends SIGKILL to kill any running processes.
    3. Calls /system/bin/vdc volume reset.
    4. Unmounts the zRAM backing device.
    5. Unmounts active APEX packages.
    6. Switches back to the bootstrap mount namespace.
    7. Triggers the userspace-reboot-resume action.

If file system checkpointing was requested before the soft restart, userdata is remounted into checkpointing mode during the userspace-reboot-fs-remount action (see the following section for details). A soft restart is considered after the sys.boot_completed property is set to 1. At the end of the soft restart, the display is kept off and explicit user interaction is required to wake it.

File system checkpointing

If a file system checkpoint was requested before the soft restart, userdata is remounted in checkpointing mode during the soft restart. Remounting logic is implemented in the fs_mgr_remount_userdata_into_checkpointing function, and differs between checkpointing methods. Specifically, when userdata supports:

  • Filesystem level checkpointing (for example, f2fs), userdata is remounted with the checkpoint=disable option.

  • Block level checkpointing (for example, ext4), then /data is unmounted and all the parent device mapper devices it was mounted on top of are destroyed. Next, userdata is mounted using the same code path as used in normal checkpointing boot.

If a file system level keyring is used to manage credential-encrypted (CE) and device-encrypted (DE) keys, then keys are lost after userdata is unmounted. To allow key restoration, when installing a key to a file system keyring, vold also installs the same key of type fscrypt-provisioning to session-level keyring. When init_user0 is called, vold reinstalls the keys in the file system keyring.

Fallback to hard reboot

To ensure that a soft restart doesn't leave a device in an unusable state, Android 11 includes a fallback to hard reboot that's triggered when one of the following conditions is met:

  • A device fails to start soft restart (that is, sys.init.userspace_reboot.in_progress=1) within a given timeout.
  • A process fails to stop within a given timeout.
  • The /system/bin/vdc volume reset operation fails.
  • The unmounting of the zRAM device fails.
  • An active APEX package unmounts incorrectly.
  • An attempt to remount userdata into checkpointing mode fails.
  • A device fails to successfully boot (that is, sys.boot_completed=1) within a given timeout.

Per-device configuration

Some soft restart aspects can be tuned by changing values of the following properties:

  • init.userspace_reboot.is_supported controls when a device can perform a soft restart. If value of this property is false, 0, or not specified, then attempts to restart are rejected.
  • init.userspace_reboot.sigkill.timeoutmillis controls the timeout in milliseconds for processes that received a SIGKILL signal to stop. If one of the processes fails to stop in the given timeout, then a fallback to hard reboot is triggered.
  • init.userspace_reboot.sigterm.timeoutmillis controls the timeout in milliseconds for processes that received a SIGTERM signal to terminate. All the processes that failed to terminate in the given timeout receive a SIGKILL signal.
  • init.userspace_reboot.started.timeoutmillis controls the timeout in milliseconds for soft restart to start (that is, sys.init.userspace_reboot.in_progress=1). If a device fails to start soft restart within the given timeout, a fallback to hard reboot is triggered.
  • init.userspace_reboot.userdata_remount.timeoutmillis controls the timeout in milliseconds to unmount userdata. If a device fails to unmount userdata within the given timeout, a fallback to hard reboot is triggered.
  • init.userspace_reboot.watchdog.timeoutmillis controls the timeout for a device to successfully boot (that is, sys.boot_completed=1). If a device fails to boot within the given timeout, a fallback to hard reboot is triggered.

Customize animation during soft restart

The reference implementation of a soft restart includes an ability to customize animation shown during the soft restart.

At the end of the userspace-reboot-fs-remount action, init starts the bootanim service. This service looks for the existence of the following animation files, in the order listed, and plays the first one it finds:

  • /product/media/userspace-reboot.zip
  • /oem/media/userspace-reboot.zip
  • /system/media/userspace-reboot.zip

If no soft restart specific animation files are specified, bootanim shows a default android animation.

Testing

Android 11 includes a reference implementation of a soft restart. In addition, you can verify a soft restart using CTS tests in UserspaceRebootHostTest.