Fastboot, Sideload, and Flashing ROMs

[connglli]

Read also #36 and the official document

The Sophisticated Three-"System" Device

Informally, one can treat an Android devices as a three-"system" device, i.e., the bootloader, the recovery, and the normal Android system

• bootloader: bootloader is the first "system" that typically presents to ROM users, and is the loader program which helps to load recovery or Android; it is mainly responsible for managing all data and bootable partitions on the device, e.g., flash a new partition, flash a new recovery, etc. And one can use adb reboot bootloader to boot into it (on some devices, one can hold volume up + volume down + power to boot into it)

  for bootloader to function normally, one need to unlock it firstly by (1) in developer options, check the "OEM lock" (2) boot into bootloader via abd reboot bootloader (3) after bootloader is started, use fastboot flashing unlock to unlock the bootloader (or fastboot oem unlock for old devices) (4) after (3), if one see the "Device Status" becomes "unlocked", it succeeded; but note, (1) the first time one unlocks the bootloader, everything on data partition will be wiped (2) not all bootloaders can be unlocked, some OEM (e.g., MeiZu) locks their bootloader and forbit anyone from unlocking

• recovery: recovery is the second "system" that typically presents to ROM users, and is the program which is responsible to backup/recover data, or renew/reinstall an Android ROM (see #51 for more information); one can use adb reboot recovery to boot into it, or firstly boot into bootloader, then ask bootloader to load recovery (on some devices, one can hold volume down + power to boot into it)

  users who like to play devices often replace the default recovery to TWRP or LineageOS Recovery

• Android: this is the last and actual system that present to normal users, providing all kinds of functionalities; it presents to user because the bootloader by default load it instead of recovery

  users who like to play devices often install new ROMs to replace the original OEM ROM, e.g., LineageOS

Normally, the device boots into the Android system either when use the power button or type adb reboot. However, one can also reboot into the other two systems:

• bootloader: adb reboot bootloader
• recovery: adb reboot recovery
• Android: adb reboot

In real world, the partitions and booting sequences of Android is much more complicate than aforementioned. Read also #36 and Android booting shenanigans for further information.

fastboot, sideload

fastboot

fastboot is a protocol and tool that is used to interact with bootloader via USB cable; it can do anything that bootloader allows, e.g., lock/unlock bootloader, erase/format/flash partitions, boot from a ramdisk (see #52 to know more about image disks), etc. So the device need to reboot to bootloader first (someone also use the term "reboot into fastboot mode").

• to list all bootloader devices (-l list the device paths)

$ fastboot devices -l

Note, this command shows nothing when you haven't rebooted into fastboot mode. All following commands also wait for a device to reboot into bootloader before do anything.

• to lock/unlock bootloader

$ fastboot flashing lock
$ fastboot flashing unlock

# for old devices
$ fastboot oem lock
$ fastboot oem unlock

• to erase, format a partition

# PARTITION can be boot, data, cache, ...
$ fastboot erase PARTITION
$ fastboot format[:FS_TYPE[:SIZE]]

• to flash new images to a partition

# PARTITION can be boot, and RAMDISK can be for example 
$ fastboot flash PARTITION RAMDISK

Typically on A/B update devices (see #51), flash new images to boot send the images to boot_b slot, the following is the output of fastboot flash boot lineage-17.1-20200602-recovery-fajita.img on OnePlus6T

$ fastboot flash boot lineage-17.1-20200602-recovery-fajita.img
Sending 'boot_b' (65536 KB)                        OKAY [  1.820s]
Writing 'boot_b'                                   OKAY [  0.288s]
Finished. Total time: 2.116s

• to boot from a ramdisk

# RAMDISK can be any ramdisk made, e.g., twrp recovery ramdisk
$ fastboot boot RAMDISK

sideload

Sideloading is a mechanism of recovery that makes it easy to manually install a new ROM.zip to the device from PC instead of via the over-the-air system or SD card. This mechanism is by default disabled, and can be enabled in recovery (but disabled immediately the ROM is sideloaded)

Also sideload is a subcommand of adb, but a separate mode of adb, note:

1. sideload works only by USB cable
2. when such mode is enabled from recovery, common adb commands (logcat, reboot, shell, push, pull) don't work

To use sideload, one have to (1) boot to recovery via adb reboot recovery (2) in recovery, enable adb-sideload. For example, in TWRP goto "Advanced" then "ADB Sideload", in LineageOS goto "Apply Updates" then "Apply from ADB" (3) use adb sideload ROMZIP to sideload the rom (copying the zip from PC to device), and the updater script in ROMZIP (META-INF/com/google/android/updater-script) will be executed

the updater script is not a bash script, but an edify script language, see references for how to write it

References

• https://source.android.com/devices/tech/ota/nonab/device_code#sideloading
• https://twrp.me/faq/ADBSideload.html
• https://android.stackexchange.com/questions/66828/what-does-the-command-adb-sideload-file-do
• https://forum.xda-developers.com/showthread.php?t=936175
• https://forum.xda-developers.com/showthread.php?t=1669489
• https://androidforums.com/threads/edify-script-language-reference-updater-script.557602/

Steps to Flash New ROMs

A typical steps to flash and install new ROMs involves the following steps:

1. unlock the bootloader if locked
2. if necessary, flash a temporary recovery
3. reboot to recovery
4. wipe data and cache (双清)
5. sideload a new ROM
6. reboot to the new system

See references for a detailed step of "Installing LineageOS 17 to OnePlus 6T"

References

• https://wiki.lineageos.org/devices/fajita/install

[connglli]

The following essays also provide very clean, clear, and easy-to-underatanding introductions to bootloader and root permissions, from an end-user perspective.

• 当我们谈论解锁 BootLoader 时，我们在谈论什么？
• 何为 root？
• KernelSU: 内核 ROOT 方案，来了！