doc/kwboot.1

   1 .TH KWBOOT 1 "2021-08-25"
   2
   3 .SH NAME
   4 kwboot \- Boot Marvell Kirkwood (and others 32-bit) SoCs over a serial link.
   5 .SH SYNOPSIS
   6 .B kwboot
   7 .RB [ "-b \fIimage\fP" ]
   8 .RB [ "-t" ]
   9 .RB [ "-B \fIbaudrate\fP" ]
  10 .RB \fITTY\fP
  11 .SH "DESCRIPTION"
  12
  13 The \fBkwboot\fP program boots boards based on Marvell's 32-bit
  14 platforms including Kirkwood, Dove, A370, AXP, A375, A38x
  15 and A39x over their integrated UART. Boot image files will typically
  16 contain a second stage boot loader, such as U-Boot. The image file
  17 must conform to Marvell's BootROM firmware image format
  18 (\fIkwbimage v0\fP or \fIv1\fP), created using a tool such as
  19 \fBmkimage\fP.
  20
  21 Following power-up or a system reset, system BootROM code polls the
  22 UART for a brief period of time, sensing a handshake message which
  23 initiates an image upload. This program sends this boot message until
  24 it receives a positive acknowledgement. The image is transferred using
  25 Xmodem.
  26
  27 Additionally, this program implements a minimal terminal mode, which
  28 can be used either standalone, or entered immediately following boot
  29 image transfer completion. This is often useful to catch early boot
  30 messages, or to manually interrupt a default boot procedure performed
  31 by the second-stage loader.
  32
  33 .SH "OPTIONS"
  34
  35 .TP
  36 .BI "\-b \fIimage\fP"
  37 Handshake; then upload file \fIimage\fP over \fITTY\fP.
  38
  39 Note that for the encapsulated boot code to be executed, \fIimage\fP
  40 must be of type "UART boot" (0x69). The \fBkwboot\fP program changes
  41 this type automatically, unless the \fIimage\fP is signed, in which
  42 case it cannot be changed.
  43
  44 This mode writes handshake status and upload progress indication to
  45 stdout. It is possible that \fIimage\fP contains an optional binary
  46 code in it's header which may also print some output via UART (for
  47 example U-Boot SPL does this). In such a case, this output is also
  48 written to stdout after the header is sent.
  49
  50 .TP
  51 .BI "\-p"
  52 Obsolete. Does nothing.
  53
  54 In the past, when this option was used, the program patched the header
  55 in the image prior upload, to "UART boot" type. This is now done by
  56 default.
  57
  58 .TP
  59 .BI "\-t"
  60 Run a terminal program, connecting standard input and output to
  61 .RB \fITTY\fP.
  62
  63 If used in combination with \fB-b\fP, terminal mode is entered
  64 immediately following a successful image upload.
  65
  66 If standard I/O streams connect to a console, this mode will terminate
  67 after receiving \fBctrl-\e\fP followed by \fBc\fP from console input.
  68
  69 .TP
  70 .BI "\-B \fIbaudrate\fP"
  71 If used in combination with \fB-b\fP, inject into the image header
  72 code that changes baud rate to \fIbaudrate\fP after uploading image
  73 header, and code that changes the baud rate back to the default
  74 (115200 Bd) before executing payload, and also adjust the baud rate
  75 on \fITTY\fP correspondingly. This can make the upload significantly
  76 faster.
  77
  78 If used in combination with \fB-t\fP, adjust the baud rate to
  79 \fIbaudrate\fP on \fITTY\fP before starting terminal.
  80
  81 If both \fB-b\fP and \fB-t\fP are used, the baud rate is changed
  82 back to 115200 after the upload.
  83
  84 Tested values for \fIbaudrate\fP for Armada 38x include: 115200,
  85 230400, 460800, 500000, 576000, 921600, 1000000, 1152000, 1500000,
  86 2000000, 2500000, 3125000, 4000000 and 5200000.
  87
  88 .SH "SEE ALSO"
  89 .PP
  90 \fBmkimage\fP(1)
  91
  92 .SH "AUTHORS"
  93
  94 Daniel Stodden <daniel.stodden@gmail.com>
  95 .br
  96 Luka Perkov <luka@openwrt.org>
  97 .br
  98 David Purdy <david.c.purdy@gmail.com>
  99 .br
 100 Pali Rohár <pali@kernel.org>
 101 .br
 102 Marek Behún <marek.behun@nic.cz>