# HG changeset patch
# User Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
# Date 1366872977 0
# Node ID a52e76c12e6b4e7d9a33ad9b6119a61744f8db39
# Parent  2d9c927cc24b22ead6c490c4d831d9af37f22b3d
boot ROM re: some sensible documentation written up

diff -r 2d9c927cc24b -r a52e76c12e6b bootrom.notes
--- a/bootrom.notes	Thu Apr 25 06:03:27 2013 +0000
+++ b/bootrom.notes	Thu Apr 25 06:56:17 2013 +0000
@@ -53,8 +53,19 @@
 
 <b
 
-Followed by 4 bytes, giving a 32-bit value in MSB-first order.  The value is
-written to 80052C, and the 0x2c8 function returns code 6.
+Branch command.
+
+Followed by 4 bytes, giving the 32-bit branch address in MSB-first order.
+It is a BX-style address, i.e., setting the least significant bit will
+cause the code to be jumped to in the Thumb state.
+
+The address is written to 80052C, and the 0x2c8 function returns code 6.
+
+If the command is accepted, a '>b' response is sent back before the
+jump is performed.  If the command is rejected because the downloader
+is in the wrong state (see below), a '>B' response is sent back, and
+the downloader is reset to its initial state, waiting for commands at
+19200 baud.
 
 <c
 
@@ -70,6 +81,8 @@
 
 <p
 
+Set parameters
+
 Followed by 9 bytes:
 	1 byte: goes into var at 800518, selects the baud rate:
 		0: 115200
@@ -100,6 +113,8 @@
 
 <w
 
+Write data to RAM
+
 Followed by:
 	1 byte: block number (of this block)
 	1 byte: total # of blocks
@@ -128,6 +143,42 @@
 Good response: >w
 Error response: >W <err code byte from 800531>
 
+UART download procedure
+
+Step 1: the external host sends a continuous stream of '<i' beacons at 19200
+baud, waiting for a '>i' response at the same baud rate.  These beacons need
+to be pouring down the wire into the Calypso UART while waiting for the user
+to induce the Calypso target into executing the boot ROM (via battery
+manipulations or other target-specific tricks).
+
+Step 2: when a '>i' response has been received, send a '<p' command with the
+desired parameters.  Expect a '>p' 00 04 response, still at the original
+baud rate of 19200; if this response isn't received, it's an error.
+
+Step 2a: if the '<p' command specified a switch to a higher baud rate (up to
+115200), have the external host switch its serial port configuration at this
+point, after getting the >p response but before sending the next command.
+
+Step 3: send a series of '<w' commands, loading code into IRAM.  (Only the
+internal Calypso RAM may be loaded, not board level RAM.)  Maintain a
+running checksum like the boot ROM does.
+
+Step 4: send a '<c' command with the proper checksum value.  A positive
+response must be received before one can proceed to the branch.
+
+Step 5: send a '<b' command to transfer control to the just-loaded code.
+
+The implementation of this protocol on the boot ROM side contains a state
+machine which enforces the above order:
+
+* a '<p' command is required before '<w' will be accepted
+* after that '<p', one or more '<w's and a '<c' with the correct checksum
+  value must be received in order to enable the '<b' command.
+
+Errors result in the state machine being reset to the initial state;
+the baud rate at which the boot ROM expects to receive commands reverts
+to the initial 19200.
+
 RAM layout:
 
 800000 7 words: