Difference between revisions of "Zero/install/Boot Troubleshooting"
RadxaYuntian (Talk | contribs) (→TL;DR) |
RadxaYuntian (Talk | contribs) |
||
(10 intermediate revisions by 3 users not shown) | |||
Line 7: | Line 7: | ||
__NOTOC__ | __NOTOC__ | ||
− | == | + | == A detailed guide for troubleshooting Radxa Zero's boot issue == |
This is a more advanced guide aiming to help user fix their boot related issues. Due to how Zero's bootloader can be stored at various locations and how each distro usually has their own quirk about how bootloader is configured, user may find it confusing why the board is not booting as they are expected. This guide will help you understand how Zero decided which bootloader to boot, the current available bootloaders from Radxa, and how to wipe and reinstall any bootloader. | This is a more advanced guide aiming to help user fix their boot related issues. Due to how Zero's bootloader can be stored at various locations and how each distro usually has their own quirk about how bootloader is configured, user may find it confusing why the board is not booting as they are expected. This guide will help you understand how Zero decided which bootloader to boot, the current available bootloaders from Radxa, and how to wipe and reinstall any bootloader. | ||
Line 33: | Line 33: | ||
# boot from mmcblk0boot1 after mmcblk0 and mmcblk0boot0 are wiped | # boot from mmcblk0boot1 after mmcblk0 and mmcblk0boot0 are wiped | ||
G12A:BL:0253b8:61aa2d;FEAT:E0F83180:2000;POC:F;RCY:0;EMMC:0;READ:0;CHK:1F;READ:0;CHK:1F;READ:0;0.0 | G12A:BL:0253b8:61aa2d;FEAT:E0F83180:2000;POC:F;RCY:0;EMMC:0;READ:0;CHK:1F;READ:0;CHK:1F;READ:0;0.0 | ||
+ | # maskrom mode | ||
+ | G12A:BL:0253b8:61aa2d;FEAT:E0F83180:2000;POC:D;RCY:0;USB:0; | ||
You can read more about eMMC's hardware partitions from [https://wiki.radxa.com/Zero/install/Boot_Troubleshooting#Modify_bootloader_on_eMMC here]. | You can read more about eMMC's hardware partitions from [https://wiki.radxa.com/Zero/install/Boot_Troubleshooting#Modify_bootloader_on_eMMC here]. | ||
Line 40: | Line 42: | ||
=== TL;DR === | === TL;DR === | ||
− | We have updated our | + | We have updated our [[Zero/install/eMMC_erase | eMMC erase]] guide, which does the below operations automatically, and should fix most boot related issues. |
− | Beware this will result in data loss since the partition header | + | Beware this will result in data loss since the partition header will be wiped as well. If you need to preserve the data, either make a disk image before wiping, or follow the manual guide below. |
+ | |||
+ | === With dd === | ||
+ | |||
+ | If your bootloader is broken you can usually try manual in-place update first. This will preserve your data in eMMC. | ||
+ | |||
+ | First, follow [[Zero/dev/maskrom#Enable_maskrom | maskrom guide]] to setup and load '''rz-udisk-loader.bin'''. Also download [u-boot.bin.sd.bin](https://dl.radxa.com/zero/images/loader/u-boot.bin.sd.bin) and put it in your current directory. | ||
+ | |||
+ | Once '''rz-udisk-loader.bin''' is loaded you should have a USB storage device detected by your Linux system. Here we call it '''/dev/sdX''' but replace it with your real block device. | ||
+ | |||
+ | Run the following command to update bootloader: | ||
+ | |||
+ | DEVICE=/dev/sdX | ||
+ | sudo dd if=u-boot.bin.sd.bin of=$DEVICE bs=1 count=444 | ||
+ | sudo dd if=u-boot.bin.sd.bin of=$DEVICE bs=512 skip=1 seek=1 | ||
=== With fastboot === | === With fastboot === | ||
+ | |||
+ | First, follow [[Zero/dev/maskrom#Enable_maskrom | maskrom guide]] to setup and load '''rz-fastboot-loader.bin'''. | ||
+ | |||
+ | Once a device with ID 18d1:0d02 is shown in <code>lsusb</code> and you can see a fastboot device is detected by <code>sudo fastboot devices</code>, you can run the following command to wipe/flash image to eMMC: | ||
+ | |||
+ | # Erase eMMC | ||
+ | sudo fastboot erase mmc0 | ||
+ | sudo fastboot erase mmc0boot0 | ||
+ | sudo fastboot erase mmc0boot1 | ||
+ | # Flash eMMC | ||
+ | sudo fastboot flash mmc0 linux_distro.img | ||
+ | sudo fastboot flash mmc0boot0 bootloader.img | ||
+ | sudo fastboot flash mmc0boot1 bootloader.img | ||
+ | |||
+ | You do not need to erase before flashing, and you do not need to flash all 3 partitions. Beware '''sudo fastboot flash mmc0''' could potentially damage your existing data. | ||
+ | |||
+ | === With Android fastboot === | ||
+ | |||
+ | In some cases, you will have to use Android's bootloader. This is based on Amlogic's U-Boot source code, so it will behave differently from upstream U-Boot. | ||
First, follow [[Zero/dev/maskrom#Enable_maskrom | maskrom guide]] to setup and load '''android-bootloader.img'''. | First, follow [[Zero/dev/maskrom#Enable_maskrom | maskrom guide]] to setup and load '''android-bootloader.img'''. | ||
− | Once a device with ID 18d1:0d02 is shown in <code>lsusb</code> and you can see a fastboot device is detected by <code>sudo fastboot devices</code>, you can run the following command to wipe/flash | + | Once a device with ID 18d1:0d02 is shown in <code>lsusb</code> and you can see a fastboot device is detected by <code>sudo fastboot devices</code>, you can run the following command to wipe/flash image to eMMC: |
− | + | # Unlock eMMC before we can do anything | |
− | + | sudo fastboot unlock | |
− | + | sudo fastboot unlock_critical | |
− | + | # Backup bootloader | |
− | + | sudo fastboot fetch bootloader bootloader.bak | |
− | + | sudo fastboot fetch bootloader-boot0 bootloader-boot0.bak | |
− | + | sudo fastboot fetch bootloader-boot1 bootloader-boot1.bak | |
− | + | # Erase bootloader | |
− | + | sudo fastboot erase bootloader | |
− | + | sudo fastboot erase bootloader-boot0 | |
− | + | sudo fastboot erase bootloader-boot1 | |
+ | # Flash bootloader | ||
+ | sudo fastboot flash bootloader bootloader.img | ||
+ | sudo fastboot flash bootloader-boot0 bootloader.img | ||
+ | sudo fastboot flash bootloader-boot1 bootloader.img | ||
− | You do not need to erase before flashing, and you do not need to flash all 3 partitions. | + | You do not need to erase before flashing, and you do not need to flash all 3 partitions. Beware '''sudo fastboot flash bootloader''' could potentially damage your existing data. |
=== From inside U-Boot === | === From inside U-Boot === | ||
− | If your eMMC is so | + | If your eMMC is so corrupt that above commands fails, you will need to erase those partitions from U-Boot console. Here is the instructions to do so as a last-ditch. |
− | First set up [[Zero/dev/serial-console | serial console]] since U-Boot console can only be accessed via serial. Follow [[Zero/dev/maskrom#Enable_maskrom | maskrom guide]] to setup and load ''' | + | First set up [[Zero/dev/serial-console | serial console]] since U-Boot console can only be accessed via serial. Follow [[Zero/dev/maskrom#Enable_maskrom | maskrom guide]] to setup and load '''u-boot.bin'''. After the file is loaded keep hitting Ctrl+C in serial console until the bootloader stopped with a console waiting for command. |
# mmcblk0 | # mmcblk0 | ||
− | mmc dev | + | # WARNING! |
− | mmc erase | + | # Potential data loss! |
+ | mmc dev 2 0 | ||
+ | mmc erase 0 20000 | ||
# mmcblk0boot0 | # mmcblk0boot0 | ||
− | mmc dev | + | mmc dev 2 1 |
mmc erase 0 2000 | mmc erase 0 2000 | ||
# mmcblk0boot1 | # mmcblk0boot1 | ||
− | mmc dev | + | mmc dev 2 2 |
mmc erase 0 2000 | mmc erase 0 2000 | ||
− | + | Restart and you should be able to flash the bootloader according to the instructions listed in the [[Zero/install/eMMC_erase | eMMC erase]] guide. | |
− | # | + | #restart |
− | + | reset | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
== Modify bootloader on microSD or USB drive == | == Modify bootloader on microSD or USB drive == | ||
Line 110: | Line 147: | ||
* Q: Manjaro won't boot. | * Q: Manjaro won't boot. | ||
− | * A: | + | * A: Before 2022-02-04, Manjaro requires the usage of vendor U-Boot, and its image does not contain any bootloader. Please flash [https://dl.radxa.com/zero/images/loader/android-bootloader.img android-bootloader.img] to your storage media. [https://forum.radxa.com/t/update-qt5-version/8552/8?u=radxayuntian Release from 2022-02-04] will contain mainline U-Boot, so the image can be flashed like other distro. |
+ | |||
+ | * Q: After using maskrom to start rz-udisk-loader.bin I cannot see the eMMC storage and see on the console (UART or HDMI): Couldn't find partition mmc 2 | ||
+ | * A: Use maskrom to load u-boot.bin and once the 'starting fastboot' message appears use 'fastboot reboot' and then use maskrom to push rz-udisk-loader.bin |
Latest revision as of 08:30, 24 April 2024
Radxa Zero > Installation > Boot troubleshooting
A detailed guide for troubleshooting Radxa Zero's boot issue
This is a more advanced guide aiming to help user fix their boot related issues. Due to how Zero's bootloader can be stored at various locations and how each distro usually has their own quirk about how bootloader is configured, user may find it confusing why the board is not booting as they are expected. This guide will help you understand how Zero decided which bootloader to boot, the current available bootloaders from Radxa, and how to wipe and reinstall any bootloader.
Experience with Linux, maskrom, and Android fastboot
tool is highly recommended.
Contents
Amlogic's boot logic
When you boot a bare board without any bootloader, you will see the following string printed on your serial console:
G12A:BL:0253b8:61aa2d;FEAT:E0F83180:2000;POC:F;RCY:0;EMMC:0;READ:0;CHK:1F;READ:0;CHK:1F;READ:0;CHK:1F;SD?:0;SD:0;READ:0;CHK:1F;USB:8;
This is how the SoC finds the boot target. It will search eMMC first with 3 read instructions, each for mmcblk0
, mmcblk0boot0
, and mmcblk0boot1
. If it fails to boot from eMMC it will search microSD card next, and finally the USB devices.
This means, to boot off any given storage media, you need to make sure bootloaders stored before this chain get wiped. Otherwise a different boot configuration will be used, instead of the one that came with your installation media.
Some extra messages when boot from eMMC:
# boot from mmcblk0 G12A:BL:0253b8:61aa2d;FEAT:E0F83180:2000;POC:F;RCY:0;EMMC:0;READ:0;0.0 # boot from mmcblk0boot0 after mmcblk0 is wiped G12A:BL:0253b8:61aa2d;FEAT:E0F83180:2000;POC:F;RCY:0;EMMC:0;READ:0;CHK:1F;READ:0;0.0 # boot from mmcblk0boot1 after mmcblk0 and mmcblk0boot0 are wiped G12A:BL:0253b8:61aa2d;FEAT:E0F83180:2000;POC:F;RCY:0;EMMC:0;READ:0;CHK:1F;READ:0;CHK:1F;READ:0;0.0 # maskrom mode G12A:BL:0253b8:61aa2d;FEAT:E0F83180:2000;POC:D;RCY:0;USB:0;
You can read more about eMMC's hardware partitions from here.
Modify bootloader on eMMC
TL;DR
We have updated our eMMC erase guide, which does the below operations automatically, and should fix most boot related issues.
Beware this will result in data loss since the partition header will be wiped as well. If you need to preserve the data, either make a disk image before wiping, or follow the manual guide below.
With dd
If your bootloader is broken you can usually try manual in-place update first. This will preserve your data in eMMC.
First, follow maskrom guide to setup and load rz-udisk-loader.bin. Also download [u-boot.bin.sd.bin](https://dl.radxa.com/zero/images/loader/u-boot.bin.sd.bin) and put it in your current directory.
Once rz-udisk-loader.bin is loaded you should have a USB storage device detected by your Linux system. Here we call it /dev/sdX but replace it with your real block device.
Run the following command to update bootloader:
DEVICE=/dev/sdX sudo dd if=u-boot.bin.sd.bin of=$DEVICE bs=1 count=444 sudo dd if=u-boot.bin.sd.bin of=$DEVICE bs=512 skip=1 seek=1
With fastboot
First, follow maskrom guide to setup and load rz-fastboot-loader.bin.
Once a device with ID 18d1:0d02 is shown in lsusb
and you can see a fastboot device is detected by sudo fastboot devices
, you can run the following command to wipe/flash image to eMMC:
# Erase eMMC sudo fastboot erase mmc0 sudo fastboot erase mmc0boot0 sudo fastboot erase mmc0boot1 # Flash eMMC sudo fastboot flash mmc0 linux_distro.img sudo fastboot flash mmc0boot0 bootloader.img sudo fastboot flash mmc0boot1 bootloader.img
You do not need to erase before flashing, and you do not need to flash all 3 partitions. Beware sudo fastboot flash mmc0 could potentially damage your existing data.
With Android fastboot
In some cases, you will have to use Android's bootloader. This is based on Amlogic's U-Boot source code, so it will behave differently from upstream U-Boot.
First, follow maskrom guide to setup and load android-bootloader.img.
Once a device with ID 18d1:0d02 is shown in lsusb
and you can see a fastboot device is detected by sudo fastboot devices
, you can run the following command to wipe/flash image to eMMC:
# Unlock eMMC before we can do anything sudo fastboot unlock sudo fastboot unlock_critical # Backup bootloader sudo fastboot fetch bootloader bootloader.bak sudo fastboot fetch bootloader-boot0 bootloader-boot0.bak sudo fastboot fetch bootloader-boot1 bootloader-boot1.bak # Erase bootloader sudo fastboot erase bootloader sudo fastboot erase bootloader-boot0 sudo fastboot erase bootloader-boot1 # Flash bootloader sudo fastboot flash bootloader bootloader.img sudo fastboot flash bootloader-boot0 bootloader.img sudo fastboot flash bootloader-boot1 bootloader.img
You do not need to erase before flashing, and you do not need to flash all 3 partitions. Beware sudo fastboot flash bootloader could potentially damage your existing data.
From inside U-Boot
If your eMMC is so corrupt that above commands fails, you will need to erase those partitions from U-Boot console. Here is the instructions to do so as a last-ditch.
First set up serial console since U-Boot console can only be accessed via serial. Follow maskrom guide to setup and load u-boot.bin. After the file is loaded keep hitting Ctrl+C in serial console until the bootloader stopped with a console waiting for command.
# mmcblk0 # WARNING! # Potential data loss! mmc dev 2 0 mmc erase 0 20000 # mmcblk0boot0 mmc dev 2 1 mmc erase 0 2000 # mmcblk0boot1 mmc dev 2 2 mmc erase 0 2000
Restart and you should be able to flash the bootloader according to the instructions listed in the eMMC erase guide.
#restart reset
Modify bootloader on microSD or USB drive
microSD and USB drive both show in Linux system as block devices, so you can modify their bootloader in the same way. Additionally you can also use this method to flash bootloader to eMMC's main partition. However, fastboot
has less potential to make a mistake, so it is still recommended.
First, make sure you have installed the OS of your choice to the storage media. OS installation usually comes with their own bootloader, so if you want to modify the bootloader you have to do so after the installation.
Run any of the following commands to modify bootloader on device /dev/sdX
:
# Backup bootloader sudo dd if=/dev/sdX of=bootloader.bak conv=fsync bs=512 skip=1 count=8192 # Erase bootloader sudo dd if=/dev/zero of=/dev/sdX conv=fsync bs=512 seek=1 count=8192 # Flash bootloader sudo dd if=bootloader.img of=/dev/sdX conv=fsync bs=512 seek=1 count=8192
- Q: Board won't boot on my microSD/USB drive, and is booting stock Android instead.
- A: Please wipe eMMC's all 3 bootloaders and try again.
- Q: Manjaro won't boot.
- A: Before 2022-02-04, Manjaro requires the usage of vendor U-Boot, and its image does not contain any bootloader. Please flash android-bootloader.img to your storage media. Release from 2022-02-04 will contain mainline U-Boot, so the image can be flashed like other distro.
- Q: After using maskrom to start rz-udisk-loader.bin I cannot see the eMMC storage and see on the console (UART or HDMI): Couldn't find partition mmc 2
- A: Use maskrom to load u-boot.bin and once the 'starting fastboot' message appears use 'fastboot reboot' and then use maskrom to push rz-udisk-loader.bin