kwboot.1 6.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198
  1. .TH KWBOOT 1 "2022-03-02"
  2. .SH NAME
  3. kwboot \- Boot Marvell Kirkwood (and others 32-bit) SoCs over a serial link.
  4. .SH SYNOPSIS
  5. .B kwboot
  6. .RB [ "-b \fIimage\fP" ]
  7. .RB [ "-t" ]
  8. .RB [ "-B \fIbaudrate\fP" ]
  9. .RB \fITTY\fP
  10. .SH "DESCRIPTION"
  11. The \fBkwboot\fP program boots boards based on Marvell's 32-bit
  12. platforms including Kirkwood, Dove, Avanta, A370, AXP, A375, A38x
  13. and A39x over their integrated UART. Boot image files will typically
  14. contain a second stage boot loader, such as U-Boot. The image file
  15. must conform to Marvell's BootROM firmware image format
  16. (\fIkwbimage v0\fP or \fIv1\fP), created using a tool such as
  17. \fBmkimage\fP.
  18. Following power-up or a system reset, system BootROM code polls the
  19. UART for a brief period of time, sensing a handshake message which
  20. initiates an image upload. This program sends this boot message until
  21. it receives a positive acknowledgement. The image is transferred using
  22. Xmodem.
  23. Additionally, this program implements a minimal terminal mode, which
  24. can be used either standalone, or entered immediately following boot
  25. image transfer completion. This is often useful to catch early boot
  26. messages, or to manually interrupt a default boot procedure performed
  27. by the second-stage loader.
  28. .SH "OPTIONS"
  29. .TP
  30. .BI "\-b \fIimage\fP"
  31. Handshake; then upload file \fIimage\fP over \fITTY\fP.
  32. Note that for the encapsulated boot code to be executed, \fIimage\fP
  33. must be of type "UART boot" (0x69). The \fBkwboot\fP program changes
  34. this type automatically, unless the \fIimage\fP is signed, in which
  35. case it cannot be changed.
  36. This mode writes handshake status and upload progress indication to
  37. stdout. It is possible that \fIimage\fP contains an optional binary
  38. code in it's header which may also print some output via UART (for
  39. example U-Boot SPL does this). In such a case, this output is also
  40. written to stdout after the header is sent.
  41. .TP
  42. .B "\-b"
  43. Do only handshake on \fITTY\fP without uploading any file. File upload
  44. could be done later via option \fB\-D\fP or via any other Xmodem
  45. application, like \fBsx\fP(1).
  46. .TP
  47. .B "\-d"
  48. Do special handshake on \fITTY\fP for console debug mode.
  49. This will instruct BootROM to enter builtin simple console debug mode.
  50. Should be combined with option \fB\-t\fP.
  51. To get a BootROM help, type this command followed by ENTER key:
  52. .RS 1.2i
  53. .TP
  54. .B ?
  55. .RE
  56. .IP
  57. Armada 38x BootROM has a bug which cause that BootROM's standard output
  58. is turned off on UART when default boot source location contains valid boot image. Nevertheless
  59. BootROM's standard input and BootROM's terminal echo are active and working
  60. fine. To workaround this BootROM bug with standard output, it is possible
  61. to manually overwrite BootROM variables stored in SRAM which BootROM use
  62. for checking if standard output is enabled or not. To enable BootROM
  63. standard output on UART, type this command followed by ENTER key:
  64. .RS 1.2i
  65. .TP
  66. .B w 0x40034100 1
  67. .RE
  68. .TP
  69. .BI "\-D" " image"
  70. Upload file \fIimage\fP over \fITTY\fP without initial handshake.
  71. This method is used primary on Dove platforms, where BootROM does
  72. not support initial handshake for entering UART upload mode and
  73. strapping pins (exported via e.g. buttons) are used instead.
  74. .TP
  75. .BI "\-p"
  76. Obsolete. Does nothing.
  77. In the past, when this option was used, the program patched the header
  78. in the image prior upload, to "UART boot" type. This is now done by
  79. default.
  80. .TP
  81. .B "\-q"
  82. Obsolete. Does nothing.
  83. It is unknown whether it did something in the past.
  84. .TP
  85. .BI "\-s" " response-timeout"
  86. Specify custom response timeout when doing handshake. Default value is 50 ms.
  87. It is the timeout between sending two consecutive handshake patterns, meaning
  88. how long to wait for response from BootROM. Affects only option \fB\-b\fP with
  89. image file and option \fB\-d\fP.
  90. Option \fB-a\fP specify response timeout suitable for Armada XP BootROM and
  91. currently it is 1000 ms.
  92. Some testing showed that specifying 24 ms as response timeout make handshake
  93. with Armada 385 BootROM more stable.
  94. .TP
  95. .BI "\-t"
  96. Run a terminal program, connecting standard input and output to
  97. .RB \fITTY\fP.
  98. If used in combination with \fB\-b\fP, \fB\-D\fP or \fB\-d\fP option,
  99. terminal mode is entered immediately following a successful image upload
  100. or successful handshake (if not doing image upload).
  101. If standard I/O streams connect to a console, this mode will terminate
  102. after receiving \fBctrl-\e\fP followed by \fBc\fP from console input.
  103. .TP
  104. .BI "\-B \fIbaudrate\fP"
  105. If used in combination with \fB-b\fP, inject into the image header
  106. code that changes baud rate to \fIbaudrate\fP after uploading image
  107. header, and code that changes the baud rate back to the default
  108. (115200 Bd) before executing payload, and also adjust the baud rate
  109. on \fITTY\fP correspondingly. This can make the upload significantly
  110. faster.
  111. If used in combination with \fB-t\fP, adjust the baud rate to
  112. \fIbaudrate\fP on \fITTY\fP before starting terminal.
  113. If both \fB-b\fP and \fB-t\fP are used, the baud rate is changed
  114. back to 115200 after the upload.
  115. Tested values for \fIbaudrate\fP for Armada 38x include: 115200,
  116. 230400, 460800, 500000, 576000, 921600, 1000000, 1152000, 1500000,
  117. 2000000, 2500000, 3125000, 4000000 and 5200000.
  118. .SH "EXAMPLES"
  119. Instruct BootROM to enter boot Xmodem boot mode, send \fIu-boot-with-spl.kwb\fP
  120. kwbimage file via Xmodem on \fI/dev/ttyUSB0\fP at 115200 Bd and run terminal
  121. program:
  122. .IP
  123. .B kwboot -b u-boot-with-spl.kwb -t /dev/ttyUSB0
  124. .PP
  125. Instruct BootROM to enter boot Xmodem boot mode, send header of
  126. \fIu-boot-with-spl.kwb\fP kwbimage file via Xmodem at 115200 Bd, then instruct
  127. BootROM to change baudrate to 5200000 Bd, send data part of the kwbimage
  128. file via Xmodem at high speed, then change baudrate back to 115200 Bd,
  129. and finally run terminal program:
  130. .IP
  131. .B kwboot -b u-boot-with-spl.kwb -B 5200000 -t /dev/ttyUSB0
  132. .PP
  133. Only send \fIu-boot-with-spl.kwb\fP kwbimage file via Xmodem on \fI/dev/ttyUSB0\fP
  134. at 115200 Bd:
  135. .IP
  136. .B kwboot -D u-boot-with-spl.kwb /dev/ttyUSB0
  137. .PP
  138. Instruct BootROM to enter console debug mode and run terminal program on
  139. \fI/dev/ttyUSB0\fP at 115200 Bd:
  140. .IP
  141. .B kwboot -d -t /dev/ttyUSB0
  142. .PP
  143. Only run terminal program on \fI/dev/ttyUSB0\fP at 115200 Bd:
  144. .IP
  145. .B kwboot -t /dev/ttyUSB0
  146. .SH "SEE ALSO"
  147. .PP
  148. \fBmkimage\fP(1), \fBsx\fP(1)
  149. .SH "AUTHORS"
  150. Daniel Stodden <daniel.stodden@gmail.com>
  151. .br
  152. Luka Perkov <luka@openwrt.org>
  153. .br
  154. David Purdy <david.c.purdy@gmail.com>
  155. .br
  156. Pali Rohár <pali@kernel.org>
  157. .br
  158. Marek Behún <kabel@kernel.org>