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

Provided by: u-boot-tools_2025.01-0ubuntu0.24.04.1_amd64

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

AUTHORS