Provided by: u-boot-tools_2023.07+dfsg-1ubuntu2_amd64 bug

NAME

       kwboot - Boot Marvell Kirkwood (and others 32-bit) SoCs over a serial link.

SYNOPSIS

       kwboot [-b image] [-t] [-B baudrate] TTY

DESCRIPTION

       The  kwboot  program  boots boards based on Marvell's 32-bit platforms including Kirkwood,
       Dove, Avanta, A370, AXP, A375, A38x and A39x over their integrated UART. Boot image  files
       will  typically  contain  a  second stage boot loader, such as U-Boot. The image file must
       conform to Marvell's BootROM firmware image format (kwbimage v0 or v1),  created  using  a
       tool such as mkimage.

       Following  power-up  or  a  system  reset,  system BootROM code polls the UART for a brief
       period of time, sensing a handshake message which initiates an image upload. This  program
       sends  this  boot  message  until  it  receives  a  positive acknowledgement. The image is
       transferred using Xmodem.

       Additionally, this program implements a minimal terminal mode, which can  be  used  either
       standalone, or entered immediately following boot image transfer completion. This is often
       useful to catch early boot messages, or to manually interrupt  a  default  boot  procedure
       performed by the second-stage loader.

OPTIONS

       -b image
              Handshake; then upload file image over TTY.

              Note  that  for  the  encapsulated  boot code to be executed, image must be of type
              "UART boot" (0x69). The kwboot program changes this type automatically, unless  the
              image is signed, in which case it cannot be changed.

              This  mode  writes handshake status and upload progress indication to stdout. It is
              possible that image contains an optional binary code in it's header which may  also
              print some output via UART (for example U-Boot SPL does this). In such a case, this
              output is also written to stdout after the header is sent.

       -b     Do only handshake on TTY without uploading any file.  File  upload  could  be  done
              later via option -D or via any other Xmodem application, like sx(1).

       -d     Do special handshake on TTY for console debug mode.

              This  will  instruct BootROM to enter builtin simple console debug mode.  Should be
              combined with option -t.

              To get a BootROM help, type this command followed by ENTER key:

                   ?

              Armada 38x BootROM has a bug which cause that BootROM's standard output  is  turned
              off  on  UART  when  default  boot  source  location  contains  valid  boot  image.
              Nevertheless BootROM's standard input and BootROM's terminal echo  are  active  and
              working  fine.  To workaround this BootROM bug with standard output, it is possible
              to manually overwrite BootROM variables  stored  in  SRAM  which  BootROM  use  for
              checking if standard output is enabled or not. To enable BootROM standard output on
              UART, type this command followed by ENTER key:

                   w 0x40034100 1

       -D image
              Upload file image over TTY without initial handshake.

              This method is used primary on Dove  platforms,  where  BootROM  does  not  support
              initial  handshake  for  entering UART upload mode and strapping pins (exported via
              e.g. buttons) are used instead.

       -p     Obsolete. Does nothing.

              In the past, when this option was used, the program patched the header in the image
              prior upload, to "UART boot" type. This is now done by default.

       -q     Obsolete. Does nothing.

              It is unknown whether it did something in the past.

       -s response-timeout
              Specify  custom  response timeout when doing handshake. Default value is 50 ms.  It
              is the timeout between sending two consecutive handshake patterns, meaning how long
              to  wait  for  response  from  BootROM.  Affects only option -b with image file and
              option -d.

              Option -a specify response timeout suitable for Armada XP BootROM and currently  it
              is 1000 ms.

              Some  testing  showed that specifying 24 ms as response timeout make handshake with
              Armada 385 BootROM more stable.

       -t     Run a terminal program, connecting standard input and output to TTY.

              If used in combination  with  -b,  -D  or  -d  option,  terminal  mode  is  entered
              immediately  following  a  successful  image upload or successful handshake (if not
              doing image upload).

              If standard I/O streams connect to  a  console,  this  mode  will  terminate  after
              receiving ctrl-\ followed by c from console input.

       -B baudrate
              If used in combination with -b, inject into the image header code that changes baud
              rate to baudrate after uploading image header, and code that changes the baud  rate
              back  to the default (115200 Bd) before executing payload, and also adjust the baud
              rate on TTY correspondingly. This can make the upload significantly faster.

              If used in combination with -t, adjust the baud rate  to  baudrate  on  TTY  before
              starting terminal.

              If  both  -b  and  -t  are  used, the baud rate is changed back to 115200 after the
              upload.

              Tested values for baudrate for Armada 38x include: 115200, 230400, 460800,  500000,
              576000,  921600,  1000000, 1152000, 1500000, 2000000, 2500000, 3125000, 4000000 and
              5200000.

EXAMPLES

       Instruct BootROM to enter boot Xmodem boot mode, send  u-boot-with-spl.kwb  kwbimage  file
       via Xmodem on /dev/ttyUSB0 at 115200 Bd and run terminal program:

              kwboot -b u-boot-with-spl.kwb -t /dev/ttyUSB0

       Instruct  BootROM  to  enter  boot  Xmodem  boot  mode, send header of u-boot-with-spl.kwb
       kwbimage file via Xmodem at 115200 Bd, then instruct BootROM to change baudrate to 5200000
       Bd,  send  data  part  of the kwbimage file via Xmodem at high speed, then change baudrate
       back to 115200 Bd, and finally run terminal program:

              kwboot -b u-boot-with-spl.kwb -B 5200000 -t /dev/ttyUSB0

       Only send u-boot-with-spl.kwb kwbimage file via Xmodem on /dev/ttyUSB0 at 115200 Bd:

              kwboot -D u-boot-with-spl.kwb /dev/ttyUSB0

       Instruct BootROM to enter console debug mode and run terminal program on  /dev/ttyUSB0  at
       115200 Bd:

              kwboot -d -t /dev/ttyUSB0

       Only run terminal program on /dev/ttyUSB0 at 115200 Bd:

              kwboot -t /dev/ttyUSB0

SEE ALSO

       mkimage(1), sx(1)

AUTHORS

       Daniel Stodden <daniel.stodden@gmail.com>
       Luka Perkov <luka@openwrt.org>
       David Purdy <david.c.purdy@gmail.com>
       Pali Rohár <pali@kernel.org>
       Marek Behún <kabel@kernel.org>

                                            2022-03-02                                  KWBOOT(1)