1 files changed, 198 insertions, 0 deletions
diff --git a/doc/kwboot.1 b/doc/kwboot.1
new file mode 100644
index 00000000000..32d324f0550
--- /dev/null
+++ b/doc/kwboot.1
@@ -0,0 +1,198 @@
+.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>