[u-boot-marvell,08/10] tools: kwboot: Update manpage

Document -D, -b, -d, -q and -s options.

Add common examples how to use kwboot.

Add information about Armada 38x BootROM bug for debug console mode and how
to workaround it.

Signed-off-by: Pali Rohár <pali@kernel.org>
---
 doc/kwboot.1 | 103 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 99 insertions(+), 4 deletions(-)

On 3/2/22 11:49, Pali Rohár wrote:
> Document -D, -b, -d, -q and -s options.
> 
> Add common examples how to use kwboot.
> 
> Add information about Armada 38x BootROM bug for debug console mode and how
> to workaround it.
> 
> Signed-off-by: Pali Rohár <pali@kernel.org>

Reviewed-by: Stefan Roese <sr@denx.de>
Tested-by: Stefan Roese <sr@denx.de>

Thanks,
Stefan

> ---
>   doc/kwboot.1 | 103 +++++++++++++++++++++++++++++++++++++++++++++++++--
>   1 file changed, 99 insertions(+), 4 deletions(-)
> 
> diff --git a/doc/kwboot.1 b/doc/kwboot.1
> index acdea891d9f0..bda049bde56f 100644
> --- a/doc/kwboot.1
> +++ b/doc/kwboot.1
> @@ -1,4 +1,4 @@
> -.TH KWBOOT 1 "2021-08-25"
> +.TH KWBOOT 1 "2022-03-02"
>   
>   .SH NAME
>   kwboot \- Boot Marvell Kirkwood (and others 32-bit) SoCs over a serial link.
> @@ -47,6 +47,48 @@ 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 folled 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.
> @@ -55,13 +97,33 @@ 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, terminal mode is entered
> -immediately following a successful image upload.
> +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.
> @@ -85,9 +147,42 @@ 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)
> +\fBmkimage\fP(1), \fBsx\fP(1)
>   
>   .SH "AUTHORS"
>   

Viele Grüße,
Stefan Roese