doc/kwboot.1

   1 .TH KWBOOT 1 "2022-03-02"
   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, Avanta, 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 .B "\-b"
  52 Do only handshake on \fITTY\fP without uploading any file. File upload
  53 could be done later via option \fB\-D\fP or via any other Xmodem
  54 application, like \fBsx\fP(1).
  55
  56 .TP
  57 .B "\-d"
  58 Do special handshake on \fITTY\fP for console debug mode.
  59
  60 This will instruct BootROM to enter builtin simple console debug mode.
  61 Should be combined with option \fB\-t\fP.
  62
  63 To get a BootROM help, type this command followed by ENTER key:
  64
  65 .RS 1.2i
  66 .TP
  67 .B ?
  68 .RE
  69 .IP
  70
  71 Armada 38x BootROM has a bug which cause that BootROM's standard output
  72 is turned off on UART when SPI-NOR contains valid boot image. Nevertheless
  73 BootROM's standard input and BootROM's terminal echo are active and working
  74 fine. To workaround this BootROM bug with standard output, it is possible
  75 to manually overwrite BootROM variables stored in SRAM which BootROM use
  76 for checking if standard output is enabled or not. To enable BootROM
  77 standard output on UART, type this command folled by ENTER key:
  78
  79 .RS 1.2i
  80 .TP
  81 .B w 0x40034100 1
  82 .RE
  83
  84 .TP
  85 .BI "\-D" " image"
  86 Upload file \fIimage\fP over \fITTY\fP without initial handshake.
  87
  88 This method is used primary on Dove platforms, where BootROM does
  89 not support initial handshake for entering UART upload mode and
  90 strapping pins (exported via e.g. buttons) are used instead.
  91
  92 .TP
  93 .BI "\-p"
  94 Obsolete. Does nothing.
  95
  96 In the past, when this option was used, the program patched the header
  97 in the image prior upload, to "UART boot" type. This is now done by
  98 default.
  99
 100 .TP
 101 .B "\-q"
 102 Obsolete. Does nothing.
 103
 104 It is unknown whether it did something in the past.
 105
 106 .TP
 107 .BI "\-s" " response-timeout"
 108 Specify custom response timeout when doing handshake. Default value is 50 ms.
 109 It is the timeout between sending two consecutive handshake patterns, meaning
 110 how long to wait for response from BootROM. Affects only option \fB\-b\fP with
 111 image file and option \fB\-d\fP.
 112
 113 Option \fB-a\fP specify response timeout suitable for Armada XP BootROM and
 114 currently it is 1000 ms.
 115
 116 Some testing showed that specifying 24 ms as response timeout make handshake
 117 with Armada 385 BootROM more stable.
 118
 119 .TP
 120 .BI "\-t"
 121 Run a terminal program, connecting standard input and output to
 122 .RB \fITTY\fP.
 123
 124 If used in combination with \fB\-b\fP, \fB\-D\fP or \fB\-d\fP option,
 125 terminal mode is entered immediately following a successful image upload
 126 or successful handshake (if not doing image upload).
 127
 128 If standard I/O streams connect to a console, this mode will terminate
 129 after receiving \fBctrl-\e\fP followed by \fBc\fP from console input.
 130
 131 .TP
 132 .BI "\-B \fIbaudrate\fP"
 133 If used in combination with \fB-b\fP, inject into the image header
 134 code that changes baud rate to \fIbaudrate\fP after uploading image
 135 header, and code that changes the baud rate back to the default
 136 (115200 Bd) before executing payload, and also adjust the baud rate
 137 on \fITTY\fP correspondingly. This can make the upload significantly
 138 faster.
 139
 140 If used in combination with \fB-t\fP, adjust the baud rate to
 141 \fIbaudrate\fP on \fITTY\fP before starting terminal.
 142
 143 If both \fB-b\fP and \fB-t\fP are used, the baud rate is changed
 144 back to 115200 after the upload.
 145
 146 Tested values for \fIbaudrate\fP for Armada 38x include: 115200,
 147 230400, 460800, 500000, 576000, 921600, 1000000, 1152000, 1500000,
 148 2000000, 2500000, 3125000, 4000000 and 5200000.
 149
 150 .SH "EXAMPLES"
 151
 152 Instruct BootROM to enter boot Xmodem boot mode, send \fIu-boot-spl.kwb\fP
 153 kwbimage file via Xmodem on \fI/dev/ttyUSB0\fP at 115200 Bd and run terminal
 154 program:
 155 .IP
 156 .B kwboot -b u-boot-spl.kwb -t /dev/ttyUSB0
 157
 158 .PP
 159 Instruct BootROM to enter boot Xmodem boot mode, send header of
 160 \fIu-boot-spl.kwb\fP kwbimage file via Xmodem at 115200 Bd, then instruct
 161 BootROM to change baudrate to 5200000 Bd, send data part of the kwbimage
 162 file via Xmodem at high speed and finally run terminal program:
 163 .IP
 164 .B kwboot -b u-boot-spl.kwb -B 5200000 -t /dev/ttyUSB0
 165
 166 .PP
 167 Only send \fIu-boot-spl.kwb\fP kwbimage file via Xmodem on \fI/dev/ttyUSB0\fP
 168 at 115200 Bd:
 169 .IP
 170 .B kwboot -D u-boot-spl.kwb /dev/ttyUSB0
 171
 172 .PP
 173 Instruct BootROM to enter console debug mode and run terminal program on
 174 \fI/dev/ttyUSB0\fP at 115200 Bd:
 175 .IP
 176 .B kwboot -d -t /dev/ttyUSB0
 177
 178 .PP
 179 Only run terminal program on \fI/dev/ttyUSB0\fP at 115200 Bd:
 180 .IP
 181 .B kwboot -t /dev/ttyUSB0
 182
 183 .SH "SEE ALSO"
 184 .PP
 185 \fBmkimage\fP(1), \fBsx\fP(1)
 186
 187 .SH "AUTHORS"
 188
 189 Daniel Stodden <daniel.stodden@gmail.com>
 190 .br
 191 Luka Perkov <luka@openwrt.org>
 192 .br
 193 David Purdy <david.c.purdy@gmail.com>
 194 .br
 195 Pali Rohár <pali@kernel.org>
 196 .br
 197 Marek Behún <marek.behun@nic.cz>