pyamlboot: Amlogic SoC USB Boot utility
The Amlogic SoCs have a USB Boot mode setting itself in USB Gadget mode with a custom protocol.
The protocol reverse engineering can be found in the PROTOCOL.md file.
A library pyamlboot provides all the calls provided by the USB protocol, and the boot.py permit booting from the SoC ROM in USB Boot mode.
Installation
From PyPi
pip3 install pyamlboot
From GitHub master branch
pip3 install git+https://github.com/superna9999/pyamlboot
For development
git clone https://github.com/superna9999/pyamlboot
S905X2/S905D2/S905X3/S905D3/A311D/S922X Protocol
The G12A, G12B & SM1 uses a specific USB Boot protocol, implemented in the boot-g12.py tool.
Supported Boards
- Odroid-C4, N2, N2+
The Micro USB is used to communicate with the Boot ROM.
Switch the N2 in eMMC mode, and remove eMMC & SDCard. Remove eMMC & SDCard of Odroid-C4.
- Khadas VIM3/VIM3L
The USB-C is used to power and communicate with the Boot ROM.
Follow https://docs.khadas.com/vim3/HowtoBootIntoUpgradeMode.html#TST-Mode-Recommended
Command
usage: boot-g12.py [-h] [--version] binary
USB boot tool for Amlogic G12 SoCs
positional arguments:
binary binary to load
optional arguments:
-h, --help show this help message and exit
--version, -v show program's version number and exit
The G12 protocol doesn't permit loading Linux & a ROOTFS from memory, please setup U-Boot to load Linux & a ROOTFS by Ethernet or Fastboot via USB or Ethernet.
sudo ./boot-g12.py /path/to/u-boot.bin
The u-boot.bin is the file generate by the Amlogic Tools after the mkboot stage.
S905X/S912/A113D Protocol
The GXL, GXM & GXBB uses a specific USB Boot protocol, implemented in the boot.py tool.
Supported Boards
- Libretech-CC (Le Potato)
Remove the SDCard & eMMC Connect a Serial2USB cable to the UART pins to see the boot log Connect a USB Type-A to Type-A cable to the top USB Connector right next to the Ethernet connector
Plug into this USB port
\/
___ __ __
| | |__| |__|
|___| |__| |__|
-----------------
- Libretech-AC (La Frite)
Remove the eMMC & erase the SPI Flash first sectors. Connect a Serial2USB cable to the UART pins to see the boot log Connect a USB Type-A to Type-A cable to the top USB Connector right next to the Ethernet connector
Plug into this USB port
\/
__ __
---| |-| |-----
| ::|
| ::|
| ::|
| ::|
- Khadas VIM & VIM2
The USB-C is used to power and communicate with the Boot ROM.
For Khadas-VIM, follow https://docs.khadas.com/vim1/HowtoBootIntoUpgradeMode.html#TST-Mode-Recommended
For Khadas-VIM2, follow https://docs.khadas.com/vim2/HowtoBootIntoUpgradeMode.html#TST-Mode-v1-4-only
Command
usage: boot.py [-h] [--version] [--board-files UPATH] [--image IMAGEFILE] [--script SCRIPTFILE]
[--fdt DTBFILE] [--ramfs RAMFSFILE]
{khadas-vim3,q200,libretech-ac,s400,khadas-vim2,libretech-cc,khadas-vim}
USB boot tool for Amlogic
positional arguments:
{khadas-vim3,q200,libretech-ac,s400,khadas-vim2,libretech-cc,khadas-vim}
board type to boot on
optional arguments:
-h, --help show this help message and exit
--version, -v show program's version number and exit
--board-files UPATH Path to Board files (default: None)
--image IMAGEFILE image file to load (default: None)
--script SCRIPTFILE script file to load (default: None)
--fdt DTBFILE dtb file to load (default: None)
--ramfs RAMFSFILE ramfs file to load (default: None)
Example from a Linux build directory:
sudo ./boot.py --image arch/arm64/boot/Image --fdt arch/arm64/boot/dts/amlogic/meson-gxl-s905x-libretech-cc.dtb --ramfs /path/to/rootfs.cpio.uboot --script boot.scr libretech-cc
Replace le board name, here libretech-cc by the board you want to boot.
A cpio initramfs in uboot format as rootfs.cpio.uboot is used in the example, can be built
using Buildroot.
Eventually change boot.cmd to add more commands before booting linux
If boot.cmd changed, run :
mkimage -C none -A arm -T script -d boot.cmd boot.scr