From f3b289413dab2381b5d54de12ff88a1aed756c80 Mon Sep 17 00:00:00 2001
From: Werner Almesberger <werner@almesberger.net>
Date: Tue, 6 Sep 2011 12:29:31 -0300
Subject: [PATCH] m1/jtag-boot/mkboot: added comments with pointers to
 information sources

---
 m1/jtag-boot/mkboot | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/m1/jtag-boot/mkboot b/m1/jtag-boot/mkboot
index b3d624f..5ad1d19 100755
--- a/m1/jtag-boot/mkboot
+++ b/m1/jtag-boot/mkboot
@@ -6,11 +6,31 @@
 # Hacked 2001 by Werner Almesberger
 #
 
-# magic, copied from xilinx_bitstream.c:xlx_bitstream_load_bit
+#
+# 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.
+#
+# To boot the rescue bitstream instead of the regular bitstream, change
+# the value of GENERAL2 from 0x0037 to 0x0005.
+#
+
 @seq = (
 #    0xffff,	# DUMMY
     0xaa99, 	# Sync(1)
@@ -23,6 +43,14 @@ print pack("C*",
     0x000e);	# IPROG
 #    0x2000);	# NOP
 
+#
+# "e" section in bitstream file, with the length in bytes.
+#
+
 print pack("aN", "e", 2*@seq);
 
+#
+# the actual bitstream
+#
+
 print pack("n*", @seq);