123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198 |
- .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 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:
- .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-with-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-with-spl.kwb -t /dev/ttyUSB0
- .PP
- Instruct BootROM to enter boot Xmodem boot mode, send header of
- \fIu-boot-with-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, then change baudrate back to 115200 Bd,
- and finally run terminal program:
- .IP
- .B kwboot -b u-boot-with-spl.kwb -B 5200000 -t /dev/ttyUSB0
- .PP
- Only send \fIu-boot-with-spl.kwb\fP kwbimage file via Xmodem on \fI/dev/ttyUSB0\fP
- at 115200 Bd:
- .IP
- .B kwboot -D u-boot-with-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 <kabel@kernel.org>
|