.\" Manpage for sunxi-fel .\" Copyright (C) 2018 by Andre Przywara .TH sunxi-fel 1 "14 Jan 2022" "1.5" "sunxi-fel man page" .SH NAME sunxi-fel \- controlling USB BootROM protocol for Allwinner CPUs .SH SYNOPSIS sunxi-fel [OPTIONS] COMMAND [ARGS] .SH DESCRIPTION sunxi-fel is a script interface for USB communication with the BootROM of Allwinner CPUs. On explicit request (typically by pressing a button often labeled "uboot" or "recovery"), or when all other booting methods fail, the CPU's early ROM code enters the so called FEL mode, where it will wait for USB commands sent by some host to the Allwinner CPU's USB OTG interface. sunxi-fel implements this FEL protocol and communicates with the ROM code, to download or upload data and to start code execution. Besides simply allowing to write to or to read from device memory, sunxi-fel also helps with more complex things, which involve uploading code, executing it and then returning to FEL mode, to allow further data transfer or inspection. In particular it supports loading and executing U-Boot, including the primary SPL stage. .SH "OPTIONS" Those options affect general execution and should be put first, before any actual commands. .sp .B \-h, \-\-help .RS 4 Print a help message and exit. .RE .sp .B \-v, \-\-verbose .RS 4 Enable verbose logging. .RE .sp .B \-p, \-\-progress .RS 4 "write" transfers show a progress bar. .RE .sp .B \-l, \-\-list .RS 4 Enumerate all (USB) FEL devices and exit. .RE .sp .B \-\-list-socs .RS 4 Print a list of all supported SoCs and exit. .RE .sp .B \-d, \-\-dev bus:devnum .RS 4 Use specific USB bus and device number .RE .sp .B \-\-sid SID .RS 4 Select a device by its SID key (exact match). The SID key of a particular device can be queried using the "sid" command. .RE .SH "SUNXI-FEL COMMANDS" sunxi-fel can take several commands, each followed by their parameters, and will execute them in order. The only exception is the "uboot" command, which will delay launching U-Boot until all other commands have been executed. .sp Please note that accessing any part of the DRAM will not work until the DRAM controller has been initialized. This can be achieved by uploading and executing a suitable U-Boot SPL image, using the "spl" command. Trying to access DRAM before that will most likely hang. .sp Any numbers given as parameters to those commands can be prefixed with "0x" to denote hexadecimal notation or "0" to start an octal number. They are interpretated as decimal numbers otherwise. .PP .B spl .RS 4 Load and execute U-Boot SPL. .sp Upload the given binary file to the appropriate SRAM location, carefully moving the FEL stack out of the way in the process. The binary is then executed. When it returns, the FEL stack is restored and execution is transferred back to the BootROM's FEL routine. .sp If the file additionally contains a main U-Boot binary (u-boot-sunxi-with-spl.bin), this command also transfers that to memory, using the load address stored in the image file, but won't execute it. .RE .PP .B uboot .RS 4 like "spl", but actually starts U-Boot. U-Boot execution will take place when the fel utility exits. This allows combining "uboot" with further "write" commands, to transfer other files possibly needed for the boot. .RE .PP .B hex[dump]
.RS 4 Hexadecimal memory dump. Dumps bytes of the memory region starting at
. The context will be displayed as a hexdump, suitable for human inspection. .RE .PP .B dump
.RS 4 Binary memory dump. Dumps bytes of the memory region starting at
. The context will be dumped "as is" to the standard output, so it can be redirected to a file and processed as binary data. .RE .PP .B exe[cute]
.RS 4 Start executing code at
in memory on the device. .RE .PP .B reset64
.RS 4 Request a warm reset of the core, starting execution in the 64-bit AArch64 execution state, at
. .RE .PP .B wdreset .RS 4 Reset the device by triggering the watchdog with the shortest possible period. This will reset the whole SoC, including all on-SoC peripherals, but might not affect on-board devices like PMICs or PHYs. .RE .PP .B memmove .RS 4 Copy bytes within device memory, from to . .RE .PP .B readl
.RS 4 Read a 32-bit value from device memory at
. The value will be output as a hexadecimal number, prefixed with "0x". The address needs to be 4-byte aligned. .RE .PP .B writel
.RS 4 Write the given 32-bit to device memory at
. .RE .PP .B read
.RS 4 Write memory contents into file. Reads bytes from memory at
and writes the content into . .RE .PP .B write
.RS 4 Store file contents into memory. Writes the entire content of into memory at
. .RE .PP .B write-with-progress .RS 4 Display a textual progress bar while writing to the device. Same as "write" with the "-p" parameter. .RE .PP .B write-with-gauge .RS 4 Same as write, but write the progress in percentages to the standard output. This can be piped to any "dialog" compatible program, when using the --gauge widget. .RE .PP .B write-with-xgauge .RS 4 Same as write-with-gauge, but with extended gauge output. This can be piped to any "dialog" compatible program, using the --gauge widget. Aside from updating the current progress in percents, it also updates the number of bytes written and gives an estimated time to completion. .RE .PP .B multi[write] # ... .RS 4 Like "write-with-progress", but with multiple load adddresses and files, all sharing the same progress bar. .RE .PP .B multi[write]-with-gauge ... .RS 4 Like "write-with-gauge", but with multiple load adddresses and files, all sharing the same progress bar. .RE .PP .B multi[write]-with-xgauge ... .RS 4 Like "write-with-xgauge", but with multiple load adddresses and files, all sharing the same progress bar. .RE .PP .B echo-gauge "some text" .RS 4 Update prompt/caption for gauge output. This outputs a command to be interpreted by "dialog" to change the caption text. .RE .PP .B ver[sion] .RS 4 Show the BROM version. This prints some static data, among other things containing the detected SoC. Can be used to verify a FEL connection is working. .RE .PP .B sid .RS 4 Retrieve and output the 128-bit SID key. This key contains some form of serial number, which should be unique to each chip (although there have been reports of same SIDs for particular batches of chips). .RE .PP .B sid-registers .RS 4 As the "sid" command above, but use the alternative MMIO register access method on the device. There are SoCs that require this method due to bugs in the SID implementation, those known will automatically choose this workaround when using the "sid" command. This command here is to test new SoCs for compliance. .RE .PP .B sid-dump .RS 4 Read the entire SID eFuses array and dump its content. For SoCs with a known eFuses layout, this will annotate the known regions. .RE .PP .B clear
.RS 4 Clear bytes of memory starting at
(filling with zeroes). .RE .PP .B fill
.RS 4 Fills bytes of memory starting at
with the byte . .RE .PP .B spiflash-info .RS 4 Retrieves basic information about a SPI flash chip attached to the SPI0 pins. This is using the same method as the BootROM does, to accesses the same storage that the device could boot from. Prints the manufacturer of the flash chip and its capacity. Should also be used to detect the presence of a SPI flash chip. .RE .PP .B spiflash-read .RS 4 Reads bytes starting from offset of a SPI flash chip, storing the result into . .RE .PP .B spiflash-write .RS 4 Reads and stores its content in the SPI flash, starting at offset . .RE .SH EXAMPLES .RS 4 \fB$\fR sunxi-fel -v -p ver .RE .sp .RS 4 \fB$\fR sunxi-fel uboot u-boot-sunxi-with-spl.bin .RE .sp .RS 4 \fB$\fR sunxi-fel -v -p spl sunxi-spl.bin write 0x44000 bl31.bin write 0x4a000000 u-boot.bin reset64 0x44000 .RE .SH AUTHOR Andre Przywara