Radxa Wiki - User contributions [en]

Zero/install/Boot Troubleshooting

2022-11-26T21:14:33Z

Rauxon: /* Common boot related issues */

{{zero_header}}

{{Languages|Zero/install/Boot_Troubleshooting}}

[[zero | Radxa Zero]] > [[zero/install | Installation]] > [[zero/install/Boot_Troubleshooting | Boot troubleshooting]]

__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.

Experience with Linux, [[Zero/dev/maskrom | maskrom]], and Android <code>fastboot</code> tool is highly recommended.

__TOC__

== 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 <code>mmcblk0</code>, <code>mmcblk0boot0</code>, and <code>mmcblk0boot1</code>. 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

You can read more about eMMC's hardware partitions from [https://wiki.radxa.com/Zero/install/Boot_Troubleshooting#Modify_bootloader_on_eMMC here].

== Modify bootloader on eMMC ==

=== TL;DR ===

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 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 ===

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'''.

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. 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 [[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
# 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 [[Zero/install/eMMC_erase | 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, <code>fastboot</code> 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 <code>/dev/sdX</code>:

# 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

== Common boot related issues ==

* 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 [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

Zero/dev/maskrom

2022-11-26T21:03:51Z

Rauxon: /* Enable maskrom */

{{zero_header}}

{{Languages|zero/dev/maskrom}}

[[zero | Radxa Zero]] > [[zero/dev | Development Guide]] > [[zero/dev/maskrom | Enter maskrom mode]]

=== Description ===

This guide describes how to enter maskrom mode on Radxa Zero. Maskrom mode is a special boot mode for Radxa Zero. In this mode CPU will not boot off eMMC or microSD but will instead side load binaries from USB OTG port. This allows you to perform many low level maintenance tasks.

=== Requirement ===

* Radxa Zero
* A PC/laptop running Windows, Linux, or macOS
* USB A to C cable or C to C cable, depending on your host

=== Enable maskrom ===

First locate the USB boot button on the bottom of Zero:

[[File:Zero_usb_boot.jpg | 300px]]

Hold this button, then plug Zero into your computer. You can let go the button when you see power LED is on.

On Windows, you can open Device Manager and find the device:

[[File:Windows-GX-CHIP.png]]

On Linux, you can run <code>lsusb</code> to confirm the device is indeed in maskrom mode:

Bus 001 Device 048: ID 1b8e:c003 Amlogic, Inc. GX-CHIP

=== Install required tools ===

===== Windows =====

Download and install [https://zadig.akeo.ie/ Zagdig] for USB device driver. Make sure that the device is <code>GX-CHIP</code>, USB ID is <code>1B8E:C003</code> and choose '''libusb-win32''', then click '''Install Driver'''.

[[File:Zagdig-libusb.png]]

Additionally you can install '''fastboot with '''nexus-tools''' by running the following command in PowerShell:

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/corbindavenport/nexus-tools/master/install.ps1'))

You will also need [https://dl.google.com/android/repository/usb_driver_r13-windows.zip the Android driver] from Google.

Unzip it and right click the '''.inf''' file to install the driver.

[[File:Install-win-android-driver.png]]

'''fastboot''' is for installing Android, or manually clear eMMC bootloader. If you do not need those you can skip this step.

RZ USB Boot Helper is a Windows tool made by Radxa for maskrom sideloading. Download it from [https://dl.radxa.com/zero/tools/windows/RZ_USB_Boot_Helper_V1.0.0.zip Radxa DL] and unzip everything to a convenient location.

The tool will list the current mode on its interface. Right now we have '''Maskrom mode''':

[[File:Rz-usb-helper-maskrom.png | 500px]]

===== Linux(Ubuntu) & macOS =====

On *nix platform we can use Amlogic boot tool to side load binary. Run following commands in a new terminal:

macOS:
brew install python lsusb libusb
pip3 install pyamlboot

Ubuntu:
sudo apt update
sudo apt install python3-pip
sudo pip3 install pyamlboot

Additionally you can install '''fastboot''' with '''nexus-tools''':

bash <(curl -s https://raw.githubusercontent.com/corbindavenport/nexus-tools/master/install.sh)

'''fastboot''' is for installing Android, or manually clear eMMC bootloader. If you do not need those you can skip this step.

=== Side loading binaries ===

On Windows, once the tool detected maskrom mode, you can choose binary with '''Select''' button then side load with '''Run'''button:

[[File:Rz-usb-helper-fastboot.png | 500px]]

On *nix you can use '''boot-g12.py''' tool instead:

macOS:
boot-g12.py rz-fastboot-loader.bin

Ubuntu:
sudo boot-g12.py rz-fastboot-loader.bin

Some precomplied loaders are provided on [https://dl.radxa.com/zero/images/loader/ Radxa website]. Below is a brief description on some of them:

* [https://dl.radxa.com/zero/images/loader/factory-loader.img factory-loader.img]: used to erase eMMC on Windows. Not recommended.
* [https://dl.radxa.com/zero/images/loader/radxa-zero-erase-emmc.bin radxa-zero-erase-emmc.bin]: automatically erase eMMC, then present eMMC as a USB storage device. This is the recommended way to load a new Linux image.
* [https://dl.radxa.com/zero/images/loader/rz-fastboot-loader.bin rz-fastboot-loader.bin]: enable fastboot mode. This cannot be used to install our official Android.
* [https://dl.radxa.com/zero/images/loader/android-bootloader.img android-bootloader.img]: this is the same <b>bootloader.img</b> from our official Android image. Some distro uses this bootloader.
* [https://dl.radxa.com/zero/images/loader/rz-udisk-loader.bin rz-udisk-loader.bin]: expose embedded eMMC as a USB Mass Storage device.
* [https://dl.radxa.com/zero/images/loader/u-boot.bin u-boot.bin]: mainline U-Boot bootloader for USB boot. Won't work if you flashed it to eMMC/microSD.
* [https://dl.radxa.com/zero/images/loader/u-boot.bin.sd.bin u-boot.bin.sd.bin]: mainline U-Boot bootloader for eMMC/microSD boot. Please refer to [[Zero/dev/u-boot#Run_U-boot | this guide]] to see how to flash it when OS is already installed.

Once Radxa Zero enters into maskrom mode, it will reboot into maskrom mode until the power is cut. As such, it is recommended to completely shut down, unplug, and replug Radxa Zero when you are finish with the maintenance task.

=== Troubleshooting ===

* Q: RZ USB Boot Helper says "Not detected".
* A: Please make sure your USB driver is installed and Zero is in maskrom mode. You should see the following device in your Device Manager:

[[File:libusb.png]]

* Q: RZ USB Boot Helper's Erase button is disabled.
* A: You can use [https://dl.radxa.com/zero/images/loader/radxa-zero-erase-emmc.bin radxa-zero-erase-emmc.bin] to erase eMMC. It will wipe the device once you click "Run" button.

File:Windows-GX-CHIP.png

2022-11-26T21:03:20Z

Rauxon: GX-Chip entry in Windows device manager.

GX-Chip entry in Windows device manager.

Zero/install/eMMC erase

2022-11-26T20:58:55Z

Rauxon: /* How to erase eMMC */

{{zero_header}}
{{Languages|zero/install/eMMC_erase}}
[[zero | Radxa Zero]] > [[zero/install | Installation]] > [[zero/install/eMMC_erase | Erase eMMC]]

=== How to erase eMMC ===

This guide describes how to erase Radxa Zero series eMMC for installing a new system. Beware that this is not a secure erase, and only the bootloader and the partition header are wiped.

For more detailed guide on wiping eMMC (or if this fails), please refer to [[Zero/install/Boot_Troubleshooting | Boot Troubleshooting]] page.

== Requirement ==

* Radxa Zero or Radxa Zero 2
* A PC/laptop running Windows, Linux, or macOS
* USB A to C cable or C to C cable, depending on your host

== How to ==

Follow [[Zero/dev/maskrom#Enable_maskrom | maskrom guide]] to setup and load [https://dl.radxa.com/zero/images/loader/radxa-zero-erase-emmc.bin radxa-zero-erase-emmc.bin] or [https://dl.radxa.com/zero2/images/loader/radxa-zero2-erase-emmc.bin radxa-zero2-erase-emmc.bin]:

[[File:Rz-usb-helper-fastboot.png | 500px]]

Once your computer detects a new USB storage device, your eMMC will be wiped and you can flash to this newly found USB device.

Zero/install/Boot Troubleshooting

2022-11-26T20:58:23Z

Rauxon: /* An detailed guide for troubleshooting Radxa Zero's boot issue */