m1/jtag-boot/: moved explanation from mkboot to README and added more details

m1/jtag-boot/README

@@ -0,0 +1,63 @@
+jtag-boot (for Milkymist One)
+=============================
+
+This collection of scripts talks via JTAG to the FPGA of a Milkymist One.
+It makes the FPGA load a bitstream (FPGA configuration) from NOR.
+
+
+Elements involved
+-----------------
+
+The mkboot script generates a very short bitstream that instructs the
+configuration subsystem of the FPGA to perform the boot operation.
+
+A bitstream is a sequence of instructions for the configuration subsystem.
+Bitstreams are used for various purposes, for example, the configuration
+data of the FPGA is also contained in a (much larger) bitstream.
+
+mkboot also adds the minimum set of headers of the ".bit" format to the
+bitstream. This allows the bitstream to be transferred to the FPGA via
+JTAG, using the UrJTAG utility.
+
+UrJTAG is controlled via the boot.jtag script, which performs the basic
+initialization of the JTAG system, defines a few chip-specific constants,
+and then loads and executes the bitstream generated by mkboot.
+
+
+Bitstream content and format
+----------------------------
+
+The bitstream instructs the configuration subsystem of the to erase the
+present FPGA configuration, load a new one from NOR, and then let the
+FPGA "run" it.
+
+The structure of this kind of bitstream is described on Table 7-1 on page
+126, section "IPROG Reconfiguration", of [1]. The format of the bitstream
+is described in the section "Configuration packets" starting at page 88
+of [1].
+
+The NOR address from where the configuration bitstream will be loaded was
+obtained from the M1 standby bitstream, starting around line 205 of [2].
+
+Finally, the format of the .bit file was simply taken from the function
+xlx_bitstream_load_bit of [3]. This is the same function in UrJTAG that
+loads the file with the "pld load" command.
+
+[1] Xilinx. "Spartan-6 FPGA Configuration User Guide"
+    http://www.xilinx.com/support/documentation/user_guides/ug380.pdf
+[2] https://github.com/milkymist/milkymist/blob/master/boards/milkymist-one/standby/standby.v
+[3] http://urjtag.git.sourceforge.net/git/gitweb.cgi?p=urjtag/urjtag;a=blob_plain;f=urjtag/src/pld/xilinx_bitstream.c;hb=HEAD
+
+
+System state and behaviour
+--------------------------
+
+This process differs from a regular boot in that it should be able to
+boot the FPGA into the "regular" bitstream (or the "rescue" bitstream)
+from any state, including after a failed attempt to load the "standby"
+bitstream.
+
+The successful booting of FlickerNoise with jtag-boot does therefore not
+mean that the M1 would be able to boot regularly. E.g., if the standby
+bitstream is corrupted, the M1's FPGA initialization - without using
+JTAG - would fail at this first step.

m1/jtag-boot/mkboot

@@ -9,20 +9,11 @@
 #
 # bitstream file magic, copied from xilinx_bitstream.c:xlx_bitstream_load_bit
 #
-# here is the source:
-# http://urjtag.git.sourceforge.net/git/gitweb.cgi?p=urjtag/urjtag;a=blob_plain;f=urjtag/src/pld/xilinx_bitstream.c;hb=HEAD
-#
 
 print pack("C*",
     0x00, 0x09, 0x0f, 0xf0, 0x0f, 0xf0, 0x0f, 0xf0,
     0x0f, 0xf0, 0x00, 0x00, 0x01);
 
-#
-# "bitstream" according to Table 7-1 (page 126) of
-# http://www.xilinx.com/support/documentation/user_guides/ug380.pdf
-#
-# and the M1 standby bitstream:
-# https://github.com/milkymist/milkymist/blob/master/boards/milkymist-one/standby/standby.v#L205
 #
 # The 0xffff dummy and the 0x2000 NOP seem to be unnecessary in this case,
 # so we omit them.