• Stars
    star
    204
  • Rank 192,010 (Top 4 %)
  • Language
    Python
  • License
    GNU General Publi...
  • Created over 1 year ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Generic recovery and reflashing tool for embedded platforms

Snagboot

Snagboot intends to be an open-source and generic replacement to the vendor-specific, sometimes proprietary, tools used to recover and/or reflash embedded platforms. Examples of such tools include STM32CubeProgrammer, SAM-BA ISP, UUU, and sunxi-fel. Snagboot is made of two separate parts:

  • snagrecover uses vendor-specific ROM code mechanisms to initialize external RAM and run U-Boot, without modifying any non-volatile memories.
  • snagflash communicates with U-Boot to flash system images to non-volatile memories, using either DFU, UMS or Fastboot.

animated

The currently supported SoC families are ST STM32MP1, Microchip SAMA5, NXP i.MX6/7/8, TI AM335x, Allwinner SUNXI and TI AM62x. Please check supported_socs.yaml or run snagrecover --list-socs for a more precise list of supported SoCs.

Installation

Requirements:

  • One of the libhidapi backends. On Debian, you can install the libhidapi-hidraw0 package or the libhidapi-libusb0 package. On OSX you can install the hidapi package.
  • The ensurepip Python package. On Debian, you can install the python[your python version]-venv package

Snagboot is available on pip: python3 -m pip install --user snagboot.

This package provides two CLI tools:

$ snagrecover -h
$ snagflash -h

You also need to install udev rules so that snagrecover has read and write access to the USB devices exposed by the SoCs.

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

These rules work by adding the "uaccess" tag to the relevant USB devices. Systemd will then add an ACL to give access to currently logged in users. More info here.

Warning: If your distro does not use systemd, the "uaccess" method could possibly not work. In this case, make sure to customize the provided udev rules for your specific system.

Alternatively, Snagboot can be installed as a local Python wheel. An installation script is provided to automatically build and install the package.

$ cd snagboot
$ ./install.sh

There is also an AUR package available.

Usage guide

Note: Running snagboot as root is not recommended and will typically not work, since it is probably installed for the current user only

To recover and reflash a board using snagboot:

  1. Check that your SoC is supported in snagrecover by running: snagrecover --list-socs
  2. Setup your board for recovery
  3. Build or download the firmware binaries necessary for recovering and reflashing the board.
  4. Run snagrecover and check that the recovery was a success i.e. that U-Boot is running properly.
  5. Run snagflash to reflash the board

If you encounter issues, please take a look at the troubleshooting section.

You can play the snagrecover tutorial in your terminal!

sudo apt install asciinema
asciinema play -s=2 docs/tutorial_snagrecover.cast

Contributing

Contributions are welcome! Since Snagboot includes many different recovery techniques and protocols, we try to keep the code base as structured as possible. Please consult the contribution guidelines.

License

Snagboot is released under the GNU General Public License version 2

More Repositories

1

elixir

The Elixir Cross Referencer
C
852
star
2

training-materials

Bootlin embedded Linux and kernel training materials
TeX
516
star
3

toolchains-builder

Shell
83
star
4

simplest-yocto-setup

Working example of a yocto setup without unnecessary complications
BitBake
75
star
5

libva-v4l2-request

LibVA implementation for the Linux Video4Linux2 Request API
C
68
star
6

linux-cedrus

Mainline Kernel repository for the Allwinner VPU reverse engineering effort
C
55
star
7

mali-blobs

Mali OpenGL ES userspace libraries for Allwinner SoCs
C
54
star
8

buildroot-external-st

External Buildroot tree for STMicroelectronics boards configurations
Python
51
star
9

buildroot-toolchains

The fork of Buildroot used for building toolchains.
Makefile
22
star
10

v4l2-request-test

A standalone tool to test the Linux Video4Linux2 Request API
Objective-C
22
star
11

lavabo

Remote control boards in a LAVA setup.
Python
21
star
12

pdf-link-checker

Checks for broken hyperlinks in PDF documents
Python
19
star
13

mali-driver

C
15
star
14

v4l2-hantro-h264-encoder

V4L2 Hantro H264 encoder userspace
C
13
star
15

toolchains-webpage

The webpage of http://toolchains.bootlin.com/
Jinja
11
star
16

cedrus

Code to deal with the Allwinner VPU on top of a mainline kernel
C
11
star
17

buildroot

Makefile
8
star
18

kernel-builder

A simple kernel autobuilder, mostly borrowed from KernelCI's one.
Python
6
star
19

libva-dump

libVA implementation to dump metadata and slices from videos
C
6
star
20

libdrm-sun4i

libdrm with support for Allwinner's MB32 modifier and associated GEM buffer creation
C
5
star
21

spear_usbloader

USB boot image loader for SPEAr SOC
C
4
star
22

buildroot-ci

Makefile
4
star
23

v4l2-cedrus-enc-test

V4L2 cedrus H.264 encoder userspace
C
4
star
24

kvm-manager

Scripts to manage Linux KVM virtual machines
Shell
3
star
25

test_suite

Shell
3
star
26

pcimem

devmem like tool but for PCI resources access from userspace (BAR)
C
3
star
27

lava-server

2
star
28

squashfs-utils

C
2
star
29

custom_tests_tool

Python
2
star
30

ci-scripts

Our CI scripts
Shell
2
star
31

update-wordpress-page

Python
2
star
32

lava-devices-configs

2
star
33

video-scripts

Scripts used by Bootlin to produce videos, in particular encoding to the VP8 and Ogg/Theora formats.
Python
2
star
34

android-training-vendor-ti-beagleboneblack

Makefile
1
star
35

android-training-hardware-ti-sgx

C
1
star
36

android-training-manifest

1
star
37

odf-tools

Various tools for manipulating, checking and converting ODF (LibreOffice) documents
Python
1
star