11343854b6
Fix spelling of "followed" in kwboot.1 manpage. Series: 2 Signed-off-by: Vagrant Cascadian <vagrant@debian.org> Reviewed-by: Marek Behún <marek.behun@nic.cz>
198 lines
6.2 KiB
Groff
198 lines
6.2 KiB
Groff
.TH KWBOOT 1 "2022-03-02"
|
|
|
|
.SH NAME
|
|
kwboot \- Boot Marvell Kirkwood (and others 32-bit) SoCs over a serial link.
|
|
.SH SYNOPSIS
|
|
.B kwboot
|
|
.RB [ "-b \fIimage\fP" ]
|
|
.RB [ "-t" ]
|
|
.RB [ "-B \fIbaudrate\fP" ]
|
|
.RB \fITTY\fP
|
|
.SH "DESCRIPTION"
|
|
|
|
The \fBkwboot\fP 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
|
|
(\fIkwbimage v0\fP or \fIv1\fP), created using a tool such as
|
|
\fBmkimage\fP.
|
|
|
|
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.
|
|
|
|
.SH "OPTIONS"
|
|
|
|
.TP
|
|
.BI "\-b \fIimage\fP"
|
|
Handshake; then upload file \fIimage\fP over \fITTY\fP.
|
|
|
|
Note that for the encapsulated boot code to be executed, \fIimage\fP
|
|
must be of type "UART boot" (0x69). The \fBkwboot\fP program changes
|
|
this type automatically, unless the \fIimage\fP is signed, in which
|
|
case it cannot be changed.
|
|
|
|
This mode writes handshake status and upload progress indication to
|
|
stdout. It is possible that \fIimage\fP 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.
|
|
|
|
.TP
|
|
.B "\-b"
|
|
Do only handshake on \fITTY\fP without uploading any file. File upload
|
|
could be done later via option \fB\-D\fP or via any other Xmodem
|
|
application, like \fBsx\fP(1).
|
|
|
|
.TP
|
|
.B "\-d"
|
|
Do special handshake on \fITTY\fP for console debug mode.
|
|
|
|
This will instruct BootROM to enter builtin simple console debug mode.
|
|
Should be combined with option \fB\-t\fP.
|
|
|
|
To get a BootROM help, type this command followed by ENTER key:
|
|
|
|
.RS 1.2i
|
|
.TP
|
|
.B ?
|
|
.RE
|
|
.IP
|
|
|
|
Armada 38x BootROM has a bug which cause that BootROM's standard output
|
|
is turned off on UART when SPI-NOR 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:
|
|
|
|
.RS 1.2i
|
|
.TP
|
|
.B w 0x40034100 1
|
|
.RE
|
|
|
|
.TP
|
|
.BI "\-D" " image"
|
|
Upload file \fIimage\fP over \fITTY\fP 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.
|
|
|
|
.TP
|
|
.BI "\-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.
|
|
|
|
.TP
|
|
.B "\-q"
|
|
Obsolete. Does nothing.
|
|
|
|
It is unknown whether it did something in the past.
|
|
|
|
.TP
|
|
.BI "\-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 \fB\-b\fP with
|
|
image file and option \fB\-d\fP.
|
|
|
|
Option \fB-a\fP 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.
|
|
|
|
.TP
|
|
.BI "\-t"
|
|
Run a terminal program, connecting standard input and output to
|
|
.RB \fITTY\fP.
|
|
|
|
If used in combination with \fB\-b\fP, \fB\-D\fP or \fB\-d\fP 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 \fBctrl-\e\fP followed by \fBc\fP from console input.
|
|
|
|
.TP
|
|
.BI "\-B \fIbaudrate\fP"
|
|
If used in combination with \fB-b\fP, inject into the image header
|
|
code that changes baud rate to \fIbaudrate\fP 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 \fITTY\fP correspondingly. This can make the upload significantly
|
|
faster.
|
|
|
|
If used in combination with \fB-t\fP, adjust the baud rate to
|
|
\fIbaudrate\fP on \fITTY\fP before starting terminal.
|
|
|
|
If both \fB-b\fP and \fB-t\fP are used, the baud rate is changed
|
|
back to 115200 after the upload.
|
|
|
|
Tested values for \fIbaudrate\fP for Armada 38x include: 115200,
|
|
230400, 460800, 500000, 576000, 921600, 1000000, 1152000, 1500000,
|
|
2000000, 2500000, 3125000, 4000000 and 5200000.
|
|
|
|
.SH "EXAMPLES"
|
|
|
|
Instruct BootROM to enter boot Xmodem boot mode, send \fIu-boot-spl.kwb\fP
|
|
kwbimage file via Xmodem on \fI/dev/ttyUSB0\fP at 115200 Bd and run terminal
|
|
program:
|
|
.IP
|
|
.B kwboot -b u-boot-spl.kwb -t /dev/ttyUSB0
|
|
|
|
.PP
|
|
Instruct BootROM to enter boot Xmodem boot mode, send header of
|
|
\fIu-boot-spl.kwb\fP 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 and finally run terminal program:
|
|
.IP
|
|
.B kwboot -b u-boot-spl.kwb -B 5200000 -t /dev/ttyUSB0
|
|
|
|
.PP
|
|
Only send \fIu-boot-spl.kwb\fP kwbimage file via Xmodem on \fI/dev/ttyUSB0\fP
|
|
at 115200 Bd:
|
|
.IP
|
|
.B kwboot -D u-boot-spl.kwb /dev/ttyUSB0
|
|
|
|
.PP
|
|
Instruct BootROM to enter console debug mode and run terminal program on
|
|
\fI/dev/ttyUSB0\fP at 115200 Bd:
|
|
.IP
|
|
.B kwboot -d -t /dev/ttyUSB0
|
|
|
|
.PP
|
|
Only run terminal program on \fI/dev/ttyUSB0\fP at 115200 Bd:
|
|
.IP
|
|
.B kwboot -t /dev/ttyUSB0
|
|
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
\fBmkimage\fP(1), \fBsx\fP(1)
|
|
|
|
.SH "AUTHORS"
|
|
|
|
Daniel Stodden <daniel.stodden@gmail.com>
|
|
.br
|
|
Luka Perkov <luka@openwrt.org>
|
|
.br
|
|
David Purdy <david.c.purdy@gmail.com>
|
|
.br
|
|
Pali Rohár <pali@kernel.org>
|
|
.br
|
|
Marek Behún <marek.behun@nic.cz>
|