Zero/dev/maskrom
Radxa Zero > Development Guide > Enter maskrom mode
Contents
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:
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:
On Linux, you can run lsusb 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 Zagdig for USB device driver. Make sure that the device is GX-CHIP, USB ID is 1B8E:C003 and choose libusb-win32, then click Install Driver.
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 the Android driver from Google.
Unzip it and right click the .inf file to install the driver.
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 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:
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 Runbutton:
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 Radxa website. Below is a brief description on some of them:
- factory-loader.img: used to erase eMMC on Windows. Not recommended.
- 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.
- rz-fastboot-loader.bin: enable fastboot mode. This cannot be used to install our official Android.
- android-bootloader.img: this is the same bootloader.img from our official Android image. Some distro uses this bootloader.
- rz-udisk-loader.bin: expose embedded eMMC as a USB Mass Storage device.
- u-boot.bin: mainline U-Boot bootloader for USB boot. Won't work if you flashed it to eMMC/microSD.
- u-boot.bin.sd.bin: mainline U-Boot bootloader for eMMC/microSD boot. Please refer to 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:
- Q: RZ USB Boot Helper's Erase button is disabled.
- A: You can use radxa-zero-erase-emmc.bin to erase eMMC. It will wipe the device once you click "Run" button.