diff options
Diffstat (limited to 'docs/format.html')
-rw-r--r-- | docs/format.html | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/docs/format.html b/docs/format.html new file mode 100644 index 0000000..654a75d --- /dev/null +++ b/docs/format.html @@ -0,0 +1,151 @@ +<title>Project IceStorm – Bitstream File Format Documentation</title> +<h1>Project IceStorm – Bitstream File Format Documentation</h1> + +<p> +<i><a href=".">Project IceStorm</a> aims at documenting the bitstream format of Lattice iCE40 +FPGAs and providing simple tools for analyzing and creating bitstream files. +This is work in progress.</i> +</p> + +<h2>General Description of the File Format</h2> + +<p> +The bitstream file starts with the bytes 0xFF 0x00, followed by a sequence of +zero-terminated comment strings, followed by 0x00 0xFF. However, there seems to be +a bug in the Lattice "bitstream" tool that moves the terminating 0x00 0xFF a few +bytes into the comment string in some cases. +</p> + +<p> +After the comment sections the token 0x7EAA997E (MSB first) starts the actual +bit stream. The bitstream consists of one-byte commands, followed by a payload +word, followed by an optional block of data. The MSB nibble of the command byte +is the command opcode, the LSB nibble is the length of the command payload in +bytes. The commands that do not require a payload are using the opcode 0, with +the command encoded in the payload field. Note that this "payload" in this +context refers to a single integer argument, not the blocks of data that +follows the command in case of the CRAM and BRAM commands. +</p> + +<p> +The following commands are known: +</p> + +<p align="center"> +<table cellpadding="3" border> +<tr><th>Opcode</th><th>Description</th></tr> +<tr><td>0</td><td>payload=0: CRAM Data<br/> + payload=3: BRAM Data<br/> + payload=5: Reset CRC<br/> + payload=6: Wakeup</td></tr> +<tr><td>1</td><td>Set bank number</td></tr> +<tr><td>2</td><td>CRC check</td></tr> +<tr><td>5</td><td>Set internal oscillator frequency range<br/> + payload=0: low<br/> + payload=1: medium<br/> + payload=2: high</td></tr> +<tr><td>6</td><td>Set bank width</td></tr> +<tr><td>7</td><td>Set bank height</td></tr> +<tr><td>8</td><td>Set bank offset</td></tr> +<tr><td>9</td><td>payload=0: Disable warm boot<br/> + payload=32: Enable warm boot</td></tr> +</table> +</p> + +<p> +Use <tt>iceunpack -vv</tt> to display the commands as they are interpreted by the tool. +</p> + +<p> +Note: The format itself seems to be very flexible. At the moment it is unclear what the FPGA +devices will do when presented with a bitstream that use the commands in a different way +than the bitstreams generated by the lattice tools. +</p> + +<h2>Writing SRAM content</h2> + +<p> +Most bytes in the bitstream are SRAM data bytes that should be written to the various SRAM banks +in the FPGA. The following sequence is used to program an SRAM cell: +</p> + +<p><ul> +<li>Set bank width (opcode 6)</li> +<li>Set bank height (opcode 7)</li> +<li>Set bank offset (opcode 8)</li> +<li>Set bank number (opcode 1)</li> +<li>CRAM or BRAM Data Command</li> +<li>(width * height / 8) data bytes</li> +<li>two zero bytes</li> +</ul></p> + +<p> +The bank width and height parameters reflect the width and height of the SRAM bank. A large SRAM can +be written in smaller junks. In this case height parameter may be smaller and the offset parameter +reflects the vertical start position. +</p> + +<p> +There are four CRAM and four BRAM banks in an iCE40 FPGA. The different devices from the family +use different widths and heights, but the same number of banks. +</p> + +<p> +The CRAM banks hold the configuration bits for the FPGA fabric and hard IP blocks, the BRAM +corresponds to the contents of the block ram resources. +</p> + +<p> +The ordering of the data bits is in MSB first row-major order. +</p> + +<h2>Organization of the CRAM</h2> + +<p><a href="checkerboard.png"><img style="float:right; padding:1em; padding-top:0" height="200" src="checkerboard.png" border="0"></a></p> + +<p> +The chip is organized into four quadrants. Each CRAM memory bank contains the configuration bits for one quadrant. +The address 0 is always the corner of the quadrant, i.e. in one quadrant the bit addresses increase with the tile x/y +coordinates, in another they increase with the tile x coordinate but decrease with the tile y coordinate, and so on. +</p> + +<p> +For an iCE40 1k device, that has 12 x 16 tiles (not counting the io tiles), the CRAM bank 0 is the one containing the corner tile (1 1), +the CRAM bank 1 contains the corner tile (1 16), the CRAM bank 2 contains the corner tile (12 1) and the CRAM bank 3 contains the +corner tile (12 16). The entire CRAM of such a device is depicted on the right (bank 0 is in the lower left corner in blue/green). +</p> + +<p> +The checkerboard pattern in the picture visualizes which bits are assoziated +with which tile. The height of the configuration block is 16 for all tile +types, but the width is different for each tile type. IO tiles have +configurations that are 18 bits wide, LOGIC tiles are 54 bits wide, and +RAM tiles are 42 bits wide. (Notice the two slightly smaller columns for the RAM tiles.) +</p> + +<p> +The IO tiles on the top and bottom of the chip use a strange permutation pattern for their bits. It can be seen in the picture that +their columns are spread out horizontally. What cannot be seen in the picture is the columns also are not in order and the bit +positions are vertically permutated as well. The <tt>CramIndexConverter</tt> class in <tt>icepack.cc</tt> encapsulates the calculations +that are neccessary to convert between tile-relative bit addresses and CRAM bank-relative bit addresses. +</p> + +<p> +The black pixels in the image correspond to CRAM bits that are not assoziated with any IO, LOGIC or RAM tile. +Some of them are unused, others are used by hard IPs or other global resources. The <tt>iceunpack</tt> tool reports +such bits, when set, with the "<tt>.extra_bit <i>bank x y</i></tt>" statement in the ASCII output format. +</p> + +<h2>Organization of the BRAM</h2> + +<p> +This part of the documentation has not been written yet. +</p> + +<h2>CRC Check</h2> + +<p> +The CRC is a 16 bit CRC. The (truncated) polynomial is 0x1021 (CRC-16-CCITT). The "Reset CRC" command sets +the CRC to 0xFFFF. No zero padding is performed. +</p> + |