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>