sunxi-tools and the low level work of talking to an Allwinner board

A toolset for one family of ARM SoCs, and the x in the name

sunxi-tools exists because Allwinner boards ship configuration data in a format that ordinary Linux tooling does not understand. The project describes itself as command line utilities to work with devices based on Allwinner SoCs, covering sun4i, sun5i and the rest of the family, which is where the x in the package name comes from. The audience is narrow and technical: embedded developers, hobbyists restoring a board, and people who need to read or write the Allwinner-specific boot configuration that sits between the vendor SDK and the running kernel. The home page points at linux-sunxi.org, and the project is written in C with the source in the top of the repository, one file per tool, for example fel.c, fexc.c, pio.c, script.c and nand-part.c. That flat layout is telling. These are small programs with one job each, written to be compiled on a host, cross-compiled for the target, or both.

sunxi-fexc compiles the .fex blobs the vendor SDK uses

The centerpiece is sunxi-fexc, described as a .fex file compiler and decompiler. The Allwinner SDK stores board configuration in a text-like .fex format, and the kernel and bootloader consume the binary form of it. The tool handles both directions, and its usage line is short enough to quote in full:

	Usage: ./sunxi-fexc [-vq] [-I <infmt>] [-O <outfmt>] [<input> [<output>]]

	infmt:  fex, bin  (default:fex)
	outfmt: fex, bin  (default:bin)

The default behaviour is compile a .fex into a binary, and the format flags let you go the other way. Two convenience wrappers exist for people who already know the two formats by name: bin2fex is a shortcut to decompile a script.bin blob back into .fex, and fex2bin compiles a .fex into the binary form used by the legacy 3.4 kernel. The Makefile confirms these are not separate programs but links to the same executable, with a FEXC_LINKS variable pointing at bin2fex and fex2bin. That matters if you script around them: the behaviour, the options and the bugs are all one binary.

FEL mode is how you reach a board that will not boot

The FEL handler is a boot mode built into Allwinner silicon itself, and sunxi-fel is a script interface for USB communication with it. You normally reach it by holding the uboot or recovery button at power-on, or by letting the device fail over to FEL when no other boot option works. With no arguments the tool prints a short usage summary. The default selection rule is worth knowing before you plug in a board: unless you pick a specific device with the --dev or --sid options, the tool will access the first Allwinner device in FEL mode that it finds. To see what is currently connected, the README documents a listing mode:

    ./sunxi-fel --list --verbose

The two mechanisms are separate: FEL is a USB-level protocol, and it is the only way to talk to a board whose bootloader is broken or whose flash is empty. That is the practical value of the tool. It also explains the build dependency. Compiling requires the development version of libusb-1.0 with headers and library, and unless you pass LIBUSB_CFLAGS and LIBUSB_LIBS to make, pkg-config is needed as well, with development versions of zlib and libfdt also required. The library dependency is a good signal: this is USB plumbing, not a file format library.

Bare metal helpers for boards stuck on the SD port

Several tools in the collection are ARM native boot helpers rather than host utilities, and they exist for specific debugging situations. fel-sdboot is an ARM native SD card bootloader whose only job is to force the device into FEL mode. uart0-helloworld-sdboot prints a short hello message to the UART0 serial console, and because it relies on runtime SoC type detection, the single image is bootable on a wide range of Allwinner devices and can be used for testing, and the README suggests it can serve as a template for developing simple bare metal code such as LED blinking. jtag-loop.sunxi is an ARM native boot helper that forces the SD port into JTAG and then stops, which eases debugging of bootloaders. There are also shell-level helpers: fel-gpio is a simple wrapper around sunxi-pio and sunxi-fel so that GPIO can be manipulated while the device is in FEL mode, and fel-remotefunc-compiler.rb alongside the fel-remotefunc-spi-data-transfer sources suggest work on driving peripherals remotely over FEL. Two of these run on a rooted Android device rather than on your workstation: sunxi-script_extractor dumps the script.bin blob from RAM by reading /dev/mem, and sunxi-meminfo reads DRAM settings from registers, compiled as a static binary.

Building the tools needs libusb, zlib, libfdt and a cross toolchain

On Ubuntu 20.04 the README gives the dependency install as a single line:

sudo apt install libusb-1.0-0-dev libz-dev libfdt-dev

The Makefile separates the outputs into host tools and target tools, with the host set named explicitly:

TOOLS = sunxi-fexc sunxi-bootinfo sunxi-fel sunxi-nand-part sunxi-pio

The host group is the one most people want, and it is the default when you invoke make with no arguments. The target group holds sunxi-meminfo, which is meant to run on the Allwinner SoC itself, so it needs a cross-compiler. The Makefile tries to auto-detect a suitable toolchain prefix and falls back to arm-none-eabi- otherwise, and you can override that with the CROSS_COMPILE variable. For the two tools that must run on the device itself, the README shows the form to use:

	make CROSS_COMPILE=arm-linux-gnueabihf- sunxi-meminfo

	make CROSS_COMPILE=arm-linux-gnueabihf- sunxi-script_extractor

If you compile natively on the target platform, an empty toolchain prefix is enough. Two more details matter for portability. The compiler defaults to gcc with a C99 standard and a set of feature macros, and the Makefile detects the operating system through uname, adding _NETBSD_SOURCE specifically for NetBSD so that the endian conversions are exposed. There is a find-arm-gcc.sh helper in the tree for toolchain discovery, and an autoversion.sh script, which together with the release tags suggests the version string is derived during the build rather than written by hand.

NAND and boot image handling live in a separate misc target

Some of the collection sits outside the standard suite. The README describes a misc target for miscellaneous host utilities that are not part of the standard suite, and names them: phoenix_info, which gives information about a phoenix image created by the phoenixcard utility and can optionally extract the embedded boot code and firmware file from their hidden partitions, and sunxi-nand-image-builder, a tool used to create raw NAND images including boot0 images. Partition handling has its own tool, sunxi-nand-part, for manipulating Allwinner NAND partition tables, and the source tree carries version-specific partition headers such as nand-part-a10.h and nand-part-a20.h. Boot information has its own dumper, sunxi-bootinfo, which reads from Allwinner boot files boot0 and boot1 and takes a type flag, where --type=sd includes SD boot info and --type=nand includes NAND boot info. The README marks the NAND variant as not implemented, which is a good example of how much of this project is a set of independent utilities rather than one coherent product. Any of them can be exactly what you need, or exactly the wrong tool.

Ten years between a tag and the last commit, and a GPL that follows your fork

The maintenance picture needs care. The last push to the default branch was on 2026-10-19 and the repository is not archived, so work continues. The releases, however, stop early: v1.4 was tagged on 2016-10-26 and v1.3 on 2015-11-20, and there is no newer tag in the listed history. Ten years separate the newest release from the most recent commit, which usually means the project is maintained on master as a rolling source tree rather than through releases. If you package this for a distribution, expect to build from git rather than to pull a versioned tarball. The licence is GPLv2+ as defined by the Free Software Foundation, with the details in the LICENSE.md file. The original copyright is Alejandro Mery from 2012, with later contributions credited in the file headers to Henrik Nordstrom, Patrick Wood and Pat Wood, and the full contributor list is available through the standard git shortlog. GPLv2+ is a meaningful constraint for anyone who wants to embed these tools in a proprietary product, and it also means a fork must stay open. The Travis CI badge and the .travis.yml file point at a continuous integration setup from an era before most projects used hosted runners, another sign of the project's age.

Editorial conclusion

sunxi-tools is worth adopting for anyone working on Allwinner hardware, particularly to unpack and repack .fex configuration blobs, to recover a board that will not boot, or to reach a SoC over FEL without the vendor SDK. It is the wrong choice for a modern mainline board, for a non-Allwinner ARM SoC, or for a workflow that needs supported release packaging rather than a source tree you build yourself. Before depending on it, build the host tools and check that sunxi-fel detects your device, since the tool reaches the first Allwinner device it finds in FEL mode unless you select one with the device or serial options, and remember that the newest tag is v1.4 from 2016-10-26 even though the last push to master was on 2026-10-19. The licence is GPLv2+, so anything you derive from these sources carries the same terms.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. linux-sunxi/sunxi-tools on GitHub
3. Project website
4. README
5. Releases