wernermisc/m1/jtag-boot

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.