NAME

       sunxi-fel - controlling USB BootROM protocol for Allwinner CPUs

SYNOPSIS

       sunxi-fel [OPTIONS] COMMAND [ARGS]

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.

OPTIONS

       Those options affect general execution and should be put first, before any actual commands.

       -h, --help
           Print a help message and exit.

       -v, --verbose
           Enable verbose logging.

       -p, --progress
           "write" transfers show a progress bar.

       -l, --list
           Enumerate all (USB) FEL devices and exit.

       -d, --dev bus:devnum
           Use specific USB bus and device number

       --sid SID
           Select a device by its SID key (exact match). The SID key of a particular device can be queried using
           the "sid" command.

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.

       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.

       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.

       spl <filename>
           Load and execute U-Boot SPL.

           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.

           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.

       uboot <u-boot-sunxi-with-spl.bin>
           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.

       hex[dump] <address> <length>
           Hexadecimal memory dump. Dumps <length> bytes of the memory region starting at <address>. The context
           will be displayed as a hexdump, suitable for human inspection.

       dump <address> <length>
           Binary memory dump. Dumps <length> bytes of the memory region starting at <address>. The context will
           be dumped "as is" to the standard output, so it can be redirected to a file and processed  as  binary
           data.

       exe[cute] <address>
           Start executing code at <address> in memory on the device.

       reset64 <address>
           Request  a  warm  reset  of  the  core,  starting execution in the 64-bit AArch64 execution state, at
           <address>.

       memmove <dest> <source> <size>
           Copy <size> bytes within device memory, from <source> to <dest>.

       readl <address>
           Read a 32-bit value from device memory at <address>. The  value  will  be  output  as  a  hexadecimal
           number, prefixed with "0x". The address needs to be 4-byte aligned.

       writel <address> <value>
           Write the given 32-bit <value> to device memory at <address>.

       read <address> <length> <file>
           Write memory contents into file. Reads <length> bytes from memory at <address> and writes the content
           into <file>.

       write <address> <file>
           Store file contents into memory. Writes the entire content of <file> into memory at <address>.

       write-with-progress <addr> <file>
           Display a textual progress bar while writing to the device. Same as "write" with the "-p" parameter.

       write-with-gauge <addr> <file>
           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.

       write-with-xgauge <addr> <file>
           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.

       multi[write] # <addr> <file> ...
           Like "write-with-progress", but with multiple  load  adddresses  and  files,  all  sharing  the  same
           progress bar.

       multi[write]-with-gauge ...
           Like  "write-with-gauge",  but with multiple load adddresses and files, all sharing the same progress
           bar.

       multi[write]-with-xgauge ...
           Like "write-with-xgauge", but with multiple load adddresses and files, all sharing the same  progress
           bar.

       echo-gauge some text
           Update  prompt/caption  for  gauge  output.  This  outputs a command to be interpreted by "dialog" to
           change the caption text.

       ver[sion]
           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.

       sid
           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).

       sid-register
           As  the  "sid" command above, but use the alternative MMIO register access method on the device. Some
           SoCs require this method for reliable results.

       clear <address> <length>
           Clear <length> bytes of memory starting at <address> (filling with zeroes).

       fill <address> <length> <value>
           Fills <length> bytes of memory starting at <address> with the byte <value>.

       spiflash-info
           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.

       spiflash-read <addr> <length> <file>
           Reads <length> bytes starting from offset <addr> of a SPI flash chip, storing the result into <file>.

       spiflash-write <addr> <file>
           Reads <file> and stores its content in the SPI flash, starting at offset <addr>.

EXAMPLES

           $ sunxi-fel -v -p ver

           $ sunxi-fel uboot u-boot-sunxi-with-spl.bin

           $  sunxi-fel  -v  -p  spl  sunxi-spl.bin  write  0x44000 bl31.bin write 0x4a000000 u-boot.bin reset64
           0x44000

AUTHOR

       Andre Przywara <osp@andrep.de>

1.5                                                14 Jan 2022                                      sunxi-fel(1)