Snagboot is an open-source cross-vendor recovery tool for embedded targets

Bootlin has just released the Snagboot open-source recovery tool for embedded platforms designed to work with multiple vendors, and currently STMicro STM32MP1, Microchip SAMA5, NXP i.MX6/7/8, Texas Instruments AM335x and AM62x, and Allwinner “sunxi” processors are supported.

Silicon vendors usually provide firmware flashing tools, some closed-source binaries, that only work with their hardware. So if you work on STM32MP1 you’d use STM32CubeProgrammer, while SAM-BA is the tool for Microchip processors, NXP i.MX SoC relies on UUU, and if you’ve ever worked on Allwinner processors you’re probably family with sunxi-fel. Bootlin aims to replace all those with the Snagboot recovery tool.

The Python tool is comprised of two parts:

snagrecover using vendor-specific ROM code mechanisms to initialize external RAM and run the bootloader (typically U-Boot) without modifying any non-volatile memories.
snagflash communicates with the bootloader over USB to flash system images to non-volatile memories, using either DFU, USB Mass Storage, or fastboot.

You’ll find the source code on GitHub, but if you just want to install snagboot, you can do so with pip:

$ pip3 install snagboot

1	$ pip3 install snagboot

You’ll also need to add udev rules so that snagrecover has read and write access to the USB devices to the target SoCs:

$ snagrecover --udev > 80-snagboot.rules
$ sudo cp 80-snagboot.rules /etc/udev/rules.d/
$ sudo udevadm control --reload-rules
$ sudo udevadm trigger

$ snagrecover --udev > 80-snagboot.rules

$ sudo cp 80-snagboot.rules /etc/udev/rules.d/

$ sudo udevadm control --reload-rules

$ sudo udevadm trigger

snagrecover usage:

jaufranc@cnx-laptop-4:~$ snagrecover -h
usage: snagrecover [-h] [-s SOC] [-f "templates/colibri-imx7d.yaml"]
                   [-F "{'fw1': {'path': '/path/to', 'address': 0x00}}"] [--uart /dev/ttyx]
                   [--baudrate BAUDRATE] [--netns NETNS] [--loglevel {silent,info,debug}] [--logfile LOGFILE]
                   [--rom-usb vid:pid] [--list-socs] [--version] [-t name] [--udev] [--am335x-setup]

options:
  -h, --help            show this help message and exit

Mandatory:
  -s SOC, --soc SOC     soc model
  -f "templates/colibri-imx7d.yaml", --firmware-file "templates/colibri-imx7d.yaml"
                        firmware configurations, passed as a yaml file
  -F "{'fw1': {'path': '/path/to', 'address': 0x00}}", --firmware "{'fw1': {'path': '/path/to', 'address': 0x00}}"
                        firmware configurations, formatted as a python3 dict

Optional:
  --uart /dev/ttyx      use UART for AM335x recovery
  --baudrate BAUDRATE   UART baudrate
  --netns NETNS         network namespace for AM335x USB recovery, defaults to 'snagbootnet'
  --loglevel {silent,info,debug}
                        set loglevel
  --logfile LOGFILE     set logfile
  --rom-usb vid:pid     USB ID used by ROM code

Utilities:
  --list-socs           list supported socs
  --version             show version
  -t name, --template name
                        get an example firmware configuration file
  --udev                get required udev rules for snagrecover
  --am335x-setup        get setup script for am335x USB recovery

Examples:
	snagrecover -s stm32mp15 -f stm32mp15.yaml
	snagrecover -s stm32mp15 -F "{'tf-a': {'path': 'binaries/tf-a-stm32.bin'}}" -F "{'fip': {'path': 'binaries/u-boot.stm32'}}"

Templates:
am335x-beaglebone-black
am62x-beagle-play
imx28-evk
imx6-colibri-imx6ull
imx6-var-som-mx6
imx7-colibri-imx7d
imx8-dart-mx8m-mini
sama5-sama5d2xplained
sama5-sama5d3xplained
sama5-sama5d4xplained
stm32mp1-stm32mp135f-dk
stm32mp1-stm32mp157f-dk2
sunxi-orangepi-pc

jaufranc@cnx-laptop-4:~$ snagrecover -h

usage: snagrecover [-h] [-s SOC] [-f "templates/colibri-imx7d.yaml"]

[-F "{'fw1': {'path': '/path/to', 'address': 0x00}}"] [--uart /dev/ttyx]

[--baudrate BAUDRATE] [--netns NETNS] [--loglevel {silent,info,debug}] [--logfile LOGFILE]

[--rom-usb vid:pid] [--list-socs] [--version] [-t name] [--udev] [--am335x-setup]

options:

-h, --help show this help message and exit

Mandatory:

-s SOC, --soc SOC soc model

-f "templates/colibri-imx7d.yaml", --firmware-file "templates/colibri-imx7d.yaml"

firmware configurations, passed as a yaml file

-F "{'fw1': {'path': '/path/to', 'address': 0x00}}", --firmware "{'fw1': {'path': '/path/to', 'address': 0x00}}"

firmware configurations, formatted as a python3 dict

Optional:

--uart /dev/ttyx use UART for AM335x recovery

--baudrate BAUDRATE UART baudrate

--netns NETNS network namespace for AM335x USB recovery, defaults to 'snagbootnet'

--loglevel {silent,info,debug}

set loglevel

--logfile LOGFILE set logfile

--rom-usb vid:pid USB ID used by ROM code

Utilities:

--list-socs list supported socs

--version show version

-t name, --template name

get an example firmware configuration file

--udev get required udev rules for snagrecover

--am335x-setup get setup script for am335x USB recovery

Examples:

snagrecover -s stm32mp15 -f stm32mp15.yaml

snagrecover -s stm32mp15 -F "{'tf-a': {'path': 'binaries/tf-a-stm32.bin'}}" -F "{'fip': {'path': 'binaries/u-boot.stm32'}}"

Templates:

am335x-beaglebone-black

am62x-beagle-play

imx28-evk

imx6-colibri-imx6ull

imx6-var-som-mx6

imx7-colibri-imx7d

imx8-dart-mx8m-mini

sama5-sama5d2xplained

sama5-sama5d3xplained

sama5-sama5d4xplained

stm32mp1-stm32mp135f-dk

stm32mp1-stm32mp157f-dk2

sunxi-orangepi-pc

You can get a long list of supported SoCs using the command:

$ snagrecover --list-socs
SoCs that are supported and tested:

a20
a33
a64
am3358
am625
h3
imx28
imx6q
imx6ull
imx7d
imx8mm
r8
sama5d2
sama5d3
sama5d4
stm32mp13
stm32mp15

SoCs that are supported but untested:

a10
...

$ snagrecover --list-socs

SoCs that are supported and tested:

a20

a33

a64

am3358

am625

imx28

imx6q

imx6ull

imx7d

imx8mm

sama5d2

sama5d3

sama5d4

stm32mp13

stm32mp15

SoCs that are supported but untested:

a10

...

snagflash usage:

jaufranc@cnx-laptop-4:~$ snagflash -h
usage: snagflash [-h] [--loglevel {silent,info,debug}] [--logfile LOGFILE] [--version] [-P {dfu,ums,fastboot}]
                 [-p vid:pid] [--timeout TIMEOUT] [-D altsetting:path] [-f cmd:args] [-s SRC] [-d DEST]
                 [-b device] [--size SIZE]

options:
  -h, --help            show this help message and exit

Common:
  --loglevel {silent,info,debug}
                        set loglevel
  --logfile LOGFILE     set logfile
  --version             show version
  -P {dfu,ums,fastboot}, --protocol {dfu,ums,fastboot}
                        Protocol to use for flashing
  -p vid:pid, --port vid:pid
                        USB device address for DFU and Fastboot commands
  --timeout TIMEOUT     USB timeout, sometimes increasing this is necessary when downloading large files

DFU:
  -D altsetting:path, --dfu-config altsetting:path
                        The altsetting and path of a file to download to the board. in DFU mode

Fastboot:
  -f cmd:args, --fastboot-cmd cmd:args
                        A fastboot command.

UMS:
  -s SRC, --src SRC     source file for UMS transfer
  -d DEST, --dest DEST  mounted transfer: set destination file name
  -b device, --blockdev device
                        raw transfer: set destination block device
  --size SIZE           raw transfer: transfer size

Examples:
	# U-Boot: fastboot usb 0
	snagflash -P fastboot -p 0483:0afb -f download:boot.img -f flash:0:1 -f boot
	# U-Boot: ums 0 mmc 0
	snagflash -P ums -s binaries/u-boot.stm32 -b /dev/sdb1
	snagflash -P ums -s binaries/u-boot.stm32 -d /mnt/u-boot.stm32
	# U-Boot: setenv dfu_alt_info "mmc=uboot part 0 1"
	# U-Boot: dfu 0 mmc 0
	snagflash -P dfu -p 0483:df11 -D 0:binaries/u-boot.stm32

jaufranc@cnx-laptop-4:~$ snagflash -h

usage: snagflash [-h] [--loglevel {silent,info,debug}] [--logfile LOGFILE] [--version] [-P {dfu,ums,fastboot}]

[-p vid:pid] [--timeout TIMEOUT] [-D altsetting:path] [-f cmd:args] [-s SRC] [-d DEST]

[-b device] [--size SIZE]

options:

-h, --help show this help message and exit

Common:

--loglevel {silent,info,debug}

set loglevel

--logfile LOGFILE set logfile

--version show version

-P {dfu,ums,fastboot}, --protocol {dfu,ums,fastboot}

Protocol to use for flashing

-p vid:pid, --port vid:pid

USB device address for DFU and Fastboot commands

--timeout TIMEOUT USB timeout, sometimes increasing this is necessary when downloading large files

DFU:

-D altsetting:path, --dfu-config altsetting:path

The altsetting and path of a file to download to the board. in DFU mode

Fastboot:

-f cmd:args, --fastboot-cmd cmd:args

A fastboot command.

UMS:

-s SRC, --src SRC source file for UMS transfer

-d DEST, --dest DEST mounted transfer: set destination file name

-b device, --blockdev device

raw transfer: set destination block device

--size SIZE raw transfer: transfer size

Examples:

# U-Boot: fastboot usb 0

snagflash -P fastboot -p 0483:0afb -f download:boot.img -f flash:0:1 -f boot

# U-Boot: ums 0 mmc 0

snagflash -P ums -s binaries/u-boot.stm32 -b /dev/sdb1

snagflash -P ums -s binaries/u-boot.stm32 -d /mnt/u-boot.stm32

# U-Boot: setenv dfu_alt_info "mmc=uboot part 0 1"

# U-Boot: dfu 0 mmc 0

snagflash -P dfu -p 0483:df11 -D 0:binaries/u-boot.stm32

Bootlin welcomes contributions to add support for more targets.

Jean-Luc Aufranc (CNXSoft)

Jean-Luc started CNX Software in 2010 as a part-time endeavor, before quitting his job as a software engineering manager, and starting to write daily news, and reviews full time later in 2011.