Jump to content

Template:RFC Installation guide fastboot-no-lk2nd

From postmarketOS Wiki
This page is a template. It contains no postmarketOS-related information, but should be used as part of other articles.

Check out all pages using this template and feel free to discuss it in the gitlab issues.

For more information, read Templates and Template:Template.

This is an unofficial installation guide template for devices originally running Android with the fastboot flashing interface. It is partially inspired by the auto-generated LineageOS installation guides.

Any parameters are presented at the beginning of the section where they are used.

These are the defaults, which may differ from this preview:

{{RFC Installation guide fastboot-no-lk2nd
| custom_vendor_unlock = No unlock codes are needed to enable unlocking on this device.
| prebuilts = no
| prebuilts_stable = no <!-- if pre-built images are available on the stable channel -->
| codename = qemu-aarch64 <!-- except for links to pre-built images, which link to images for all devices by default -->
| flash_mode = For instructions to enter your device's flashing mode, please look elsewhere or ask the device maintainer how to get to the flashing mode.
| unlock_command = fastboot flashing unlock
| ab_partitions = no
| dynpart = no
| dynpart_retrofit = no
| dynpart_unsupported = no
| dynpart_metadata = super
| default_partition = the <code>userdata</code> partition
| flash_dtbo = no
| flash_dtbo_conditions = In addition to flashing the rootfs and boot images, you need to erase the DTBO.
| flash_extra =
| fastboot = yes
| launch_installation = To boot into postmarketOS, run the command:

 $ fastboot reboot
| recovery_faulty_usb = If a faulty USB connection is a major concern, reach out on [[Matrix and IRC]] to ask how to recover.
| recovery_extra =
...
}}


Pre-installation

In this section, you will obtain two partition images comprising a full installation of postmarketOS and prepare your device to be flashed with them.

Read through

Read the pre-installation and installation sections fully before taking any steps. One of the worst things that can happen is being left with no working OS on your device, postmarketOS or otherwise, and no volunteers immediately available on the Matrix and IRC channels. Plan ahead, fully understand the instructions, and decide on the details of your desired installation first.

Back up your data

Your data will be wiped when you lock or unlock your bootloader, and when you install to the userdata partition. Back up any important data somewhere safe.

Additionally, if you wish to use your device regardless of whether you perform a successful installation, be prepared to reinstall your current operating system.

Allow bootloader unlocking

| custom_vendor_unlock = No unlock codes are needed to enable unlocking on this device.
Note If you already have a custom ROM installed with the bootloader unlocked, skip this section.

On Android, go to the About phone page in the Settings app. Click on the build number 7 times to enable developer settings. You will be prompted for your PIN or password.

In the Settings main page, go to System, then Developer options. Enable OEM unlocking.

No unlock codes are needed to enable unlocking on this device.

Obtain an installation

A complete installation for this device can be created with pmbootstrap or downloaded from the web.

Obtaining pre-built images

| prebuilts = yes
| prebuilts_stable = yes
| codename = qemu-aarch64

Find a rootfs and boot image pair that suits your needs from the v23.06 release, or alternatively, from the edge channel.

The images are compressed, so decompress them with xz:

$ xz -d 19700101-0000-postmarketOS-v23.06-phosh-0.1-qemu-aarch64.img.xz
$ xz -d 19700101-0000-postmarketOS-v23.06-phosh-0.1-qemu-aarch64-boot.img.xz

Building your own images with pmbootstrap

The pmbootstrap program can be used to create a custom installation when there are no pre-built images to fit your needs. You may wish to install a different UI, boot from netboot, test unfinished features, or install to a testing-category device.

See Pmbootstrap for instructions on how to set up pmbootstrap and prepare an installation for your device. You will be prompted for your sudo password.

Enter flashing mode

| flash_mode = For instructions to enter your device's flashing mode, please look elsewhere or ask the device maintainer how to get to the flashing mode.

For instructions to enter your device's flashing mode, please look elsewhere or ask the device maintainer how to get to the flashing mode.

In flashing mode, connect to your device with a USB cable.

Unlock the bootloader

| unlock_command = fastboot flashing unlock
Note If you already have a custom ROM installed with the bootloader unlocked, skip this section.

Before flashing anything, you need to unlock the bootloader with this command:

$ fastboot flashing unlock

Follow the prompts on your device's screen to complete the operation. This will erase your data.

Choose a target partition

| ab_partitions = yes
| dynpart = yes
| dynpart_retrofit = yes
| dynpart_unsupported = no
| dynpart_metadata = super
| default_partition = the <code>userdata</code> partition

The boot image must always be flashed to the boot partition.

By default, pmbootstrap installs the rootfs image for your device to the userdata partition. The rootfs can be installed to various places, depending on your needs:

The system partition

This is a small partition which normally stores read-only system components for an Android-like OS. It is not intended for user data, but can be used for a dual-boot installation.

This partition needs to be flashed in fastbootd instead of the bootloader fastboot. Run this command while in the bootloader to enter fastbootd:

$ fastboot reboot fastboot

The super partition

This is a small partition which normally contains dynamic partitions like system, vendor, etc.

You cannot use pmbootstrap's built-in flasher for this partition. If you have a rootfs image from pmbootstrap, run:

$ pmbootstrap export

Then use the /tmp/postmarketOS-export/qemu-aarch64.img and /tmp/postmarketOS-export/boot.img images as prebuilt images.

To flash to this partition, add the --force option to fastboot when flashing the rootfs image further down.

The userdata partition

This uses the majority of your device's internal storage and is normally used to store files for the user on an Android-like OS. Choose this partition if you want to use most of your device's storage.

Choose a target slot

| ab_partitions = yes

Flashing both images to mismatched slots will not prevent postmarketOS from booting, but will limit your opportunities to dual-boot. Before flashing anything, choose the slot that you wish to install to.

If you wish to dual-boot, you should select the opposite slot of the current one, so that you can continue running the most up-to-date version of your Android-like OS.

For example, if the current slot in the flashing interface is b:

$ fastboot getvar current-slot
current-slot: b
Finished. Total time: 0.013s

flash postmarketOS to slot a:

$ fastboot set_active a

Installation

| flash_extra = === Other partitions ===

Instructions for flashing to other necessary partitions go here.
| recovery_extra = === Other device-specific situations ===

Any considerable risks that can happen in flashing mode go here. This should be
populated to prevent users from getting stranded in flashing mode.

In this section, you will install postmarketOS on your device.

Erase the DTBO

| flash_dtbo = yes
| flash_dtbo_conditions = In addition to flashing the rootfs and boot images, you need to flash the DTBO.

The device tree overlay, or DTBO, supplements the kernel's device tree. Android installs this by default.

In addition to flashing the rootfs and boot images, you need to erase the DTBO.

You can erase it with the following command:

$ fastboot erase dtbo

Other partitions

Instructions for flashing to other necessary partitions go here.

Flash the installation

Flashing a pre-built installation

| fastboot = yes

You can flash a pre-built installation with fastboot.

$ fastboot flash system_a 19700101-0000-postmarketOS-v23.06-phosh-0.1-qemu-aarch64.img
$ fastboot flash boot_a 19700101-0000-postmarketOS-v23.06-phosh-0.1-qemu-aarch64-boot.img

Flashing an installation created with pmbootstrap

There is a built-in flashing utility included in pmbootstrap. Flash with:

$ pmbootstrap flasher flash_rootfs # You can flash to the default partition
$ pmbootstrap flasher flash_rootfs --partition system # or to a custom partition like system

Finally, flash the kernel:

$ pmbootstrap flasher flash_kernel

Launch the installation

| launch_installation = To boot into postmarketOS, run the command:

 $ fastboot reboot

To boot into postmarketOS, run the command:

$ fastboot reboot

Recovering from a faulty connection

| recovery_faulty_usb = If a faulty USB connection is a major concern, reach out on [[Matrix and IRC]] to ask how to recover.

You should ideally have a reliable USB connection.

If a faulty USB connection is a major concern, reach out on Matrix and IRC to ask how to recover.

Other device-specific situations

Any considerable risks that can happen in flashing mode go here. This should be populated to prevent users from getting stranded in flashing mode.

Maintenance

Updating

As with other distros, keep your system up-to-date with the apk package manager.

Keeping your installation on a dual-boot setup

| ab_other_updates = yes

Android updates normally make use of both slots to apply updates seamlessly, but you may have postmarketOS installed on one of them.

If you have an Android-like OS installed that publishes regular updates that you want to apply, back up your installation before applying these updates.

Reboot to your Android-like OS, apply the update, and reboot again to complete it.

Then restore your postmarketOS installation on the opposite slot:

$ fastboot flash system_b postmarketOS-rootfs.img
$ fastboot flash boot_b postmarketOS-boot.img

This will change the slot of your installation, so keep track of it.