Bitstream format
================

Some documentation on the ECP5 bitstream format is published by Lattice themselves
in the ECP5 sysCONFIG Usage Guide (FPGA-TN-02039_).

.. _FPGA-TN-02039: https://www.latticesemi.com/-/media/LatticeSemi/Documents/ApplicationNotes/EH/FPGA-TN-02039-1-7-ECP5-and-ECP5-5G-sysCONFIG.pdf

Basic Structure
----------------

The ECP5 is primarily byte oriented and always byte aligned. Multi-byte words are always in big endian format.

Before the start of the bitstream itself is a comment section, which starts with FF 00 and 00 FF.
Inside it are several null-terminated strings used as metadata by Lattice. The start of the bitstream
is demarcated by a preamable, 0xFFFFBDB3. This is then followed by a 0xFFFFFFFF dummy section and then the
start of functional commands.

At minimum, a bitstream command is an 8 bit command type field, then 24 bits of command information.
The MSB of command information is set to 1 if a CRC16 follows the command. The other 23 bits are command-specific,
but usually zeros. Then follows a command-specific number of payload bytes, and the CRC16 if applicable.

The CRC16 is accumulated over all commands until a CRC16 check is reached. It is not reset at the end of commands
without a CRC16 check - except the ``LSC_RESET_CRC`` command, and after the actual bitstream payload
(``LSC_PROG_INCR_RTI`` or ``LSC_PROG_INCR_CMP``).

The CRC16 is calculated using the polynomial 0x8005 with no bit reversal. This algorithm is sometimes known as
"CRC16-BUYPASS".

    NB: Lattice's documents talk about the CRC16 being flipped. This is based on standard
    CRC16 code with reversal, effectively performing double bit reversal. CRC16 code with no
    bit reversal at all matches the actual format.

Control Commands
------------------
Control commands seen in a typical uncompressed, unencrypted bitstream are:

+-------------------------------+-----+--------------------------+---------------------------------------------------+
| Command                       | Hex | Parameters               | Description                                       |
+==========================+====+=====+==========================+===================================================+
| Dummy                         | FF  | N/A                      | Ignored, used for padding                         |
+-------------------------------+-----+--------------------------+---------------------------------------------------+
| ``LSC_RESET_CRC``             | 3B  | 24 bit info: all 0       | Resets the CRC16 register                         |
+-------------------------------+-----+--------------------------+---------------------------------------------------+
| ``VERIFY_ID``                 | E2  | - 24 bit info: all 0     | This checks the actual device ID against the given|
|                               |     | - 32 bit device JTAG ID  | value and fails if they do not match.             |
+-------------------------------+-----+--------------------------+---------------------------------------------------+
| ``LSC_WRITE_COMP_DIC``        | 02  | - 24 bit info: all 0     | This stores the 8 most common bytes in the frames |
|                               |     | - 8 bit Pattern7         |                                                   |
|                               |     | - ... (6 more patterns)  |                                                   |
|                               |     | - 8 bit Pattern0         |                                                   |
+-------------------------------+-----+--------------------------+---------------------------------------------------+
| ``LSC_PROG_CNTRL0``           | 22  | - 24 bit info: all 0     | This sets the value of device control register 0  |
|                               |     | - 32 bit CtlReg0 value   | Normally 0x40000000                               |
+-------------------------------+-----+--------------------------+---------------------------------------------------+
| ``LSC_INIT_ADDRESS``          | 46  | 24 bit info: all 0       | Resets the frame address register                 |
+-------------------------------+-----+--------------------------+---------------------------------------------------+
| ``LSC_WRITE_ADDRESS``         | B4  | - 24 bit info: all 0     | Loads the frame address register                  |
|                               |     | - 32 bit frame address   |                                                   |
+-------------------------------+-----+--------------------------+---------------------------------------------------+
| ``ISC_PROGRAM_SECURITY``      | CE  | 24 bit info: all 0       | Program the security bit (prevents readback (?) ) |
+-------------------------------+-----+--------------------------+---------------------------------------------------+
| ``ISC_PROGRAM_USERCODE``      | C2  | - CRC bit set, 23 bits 0 | Sets the value of the USERCODE register           |
|                               |     | - 32 bit USERCODE value  |                                                   |
+-------------------------------+-----+--------------------------+---------------------------------------------------+
| ``ISC_PROGRAM_DONE``          | 5E  | 24 bit info: all 0       | End of bitstream, set DONE high                   |
+-------------------------------+-----+--------------------------+---------------------------------------------------+

Configuration Data
-------------------
The FPGA configuration data itself is programmed by using command ``LSC_PROG_INCR_RTI`` (0x82) if no compression is
used and command ``LSC_PROG_INCR_CMP`` (0xB8) when using compression. Following either of these commands,
there are some setup bits:

 - 1 bit: CRC16 comparison flag, normally set
 - 1 bit: CRC16 comparison at end flag, normally cleared = CRC check after every frame
 - 1 bit: dummy bits setting, normally cleared = include dummy bits in bitstream
 - 1 bit: dummy byte setting, normally cleared = use following bits as number of dummy bytes
 - 4 bits: number of dummy bytes between frames, usually 1
 - 16 bits: number of configuration frames

This is then followed by a number of frames, each in the following format:

 - The configuration frame itself (compressed in the case of the  ``LSC_PROG_INCR_RTI`` command),
   such that bit 0 bit 0 of the first byte is the MSB of the frame, bit 7 of the first byte the
   MSB-7 and bit 0 of the last byte (if there are no dummy bits) being the LSB of the frame.
 - Any dummy bits needed to pad the frame to a whole number of bytes.
 - If the second flag is cleared (see above) a CRC-16 checksum:
    - For the first frame, this also covers any other commands sent before the programming command
      but after a CRC reset, and the programming command itself.
    - For subsequent frames, this excludes dummy bytes between frames
 - Dummy 0xFF bytes, usually only 1

The highest numbered frame in the chip is sent first.

If the second flag is set there's no CRC sent in between frames but there's still one CRC-16 checksum
after all the frames (this also covers any other commands sent before the programming command but after a CRC reset,
and the programming command itself.).

Separate commands are used if EBR needs to be configured in the bitstream. EBR data can't use compression.
``EBR_ADDRESS`` (0xF6) is used to select the EBR to program and the starting address in the EBR;
and ``LSC_EBR_WRITE`` (0xB2) is used to program the EBR itself using 72-bit frames. The specifics of these
still need to be documented.

Compression Algorithm
------------------------------

 - Before compression, the frame is left padded with zeroes (0) to make the data frame 64-bit bounded.
 - After compressing the frame data, the resulting bits are right padded with zeroes (0)
   to make the dataframe byte bounded.

After padding, every byte in the bitstream is compressed by a simple prefix-free code with just 4 cases:

+--------------+--------------+--------+---------------------+
| Code         | Argument     | Length | Encoded byte        |
+==============+==============+========+=====================+
| 0            |              | 1      | zero                |
+--------------+--------------+--------+---------------------+
| 100xxx       | bit position | 6      | byte with 1 bit set |
+--------------+--------------+--------+---------------------+
| 101xxx       | byte index   | 6      | stored byte         |
+--------------+--------------+--------+---------------------+
| 11xxxxxxxx   | lit. byte    | 10     | all others          |
+--------------+--------------+--------+---------------------+

- The first case is for the byte zero (``00000000``).  That's just represented by a single zero bit (``0``).
- The second case is for bytes with just one bit set.  After a ``100`` the set bit position is encoded
  in the following 3 bits.  For example the byte ``00100000`` is encoded as ``100101`` because only the
  bit 5 is set (with 0 being the lsb and 7 the msb).
- The third case is for selecting one of the bytes stored by the ``LSC_WRITE_COMP_DIC`` instruction.  Those
  bytes are selected as the 8 most common bytes (ignoring the zero bytes and the bytes with just one bit set,
  because those are encoded with the two previous cases).  After a ``101`` the number of the selected pattern
  is encoded with 3 bits.  For example to select pattern3 the code would be ``101011``.
- The fourth case is for all remaining bytes.  In that case after a ``11`` the complete byte is copied.  For example
  byte ``11001010`` would be encoded as ``1111001010``.

Partial Bitstreams
------------------------------

``LSC_WRITE_ADDRESS`` can be used to make partial bitstreams. Combined with background reconfiguration and
the ability to reload frames glitchlessly; partial reconfiguration is possible on ECP5.

``LSC_WRITE_ADDRESS`` takes a frame address; however frame addressing is not strictly linear. It has only
been fully documented for the 45k device and is as follows:

 - the first 7 bits are always between 0 and 105 (each group of 106 frames is a column)
 - the next 5 bits are the column index within a tap region
 - the MSBs from bit 12 onwards are the tap region index

To enable loading of partial bitstreams the ``BACKGROUND_RECONFIG`` sysCONFIG option must be set. Then, to
avoid reinitialising the whole device, instructions 0x79 with no data and 0x74 followed by 0x00 must be
sent over JTAG before the partial bitstream data.

Device-Specific Information
------------------------------

+-----------+-------------+--------+-----------------------+----------------------+
| Device    | Device ID   | Frames | Config Bits per Frame | Dummy Bits per Frame |
+===========+=============+========+=======================+======================+
| LFE5U-25  | 0x41111043  | 7562   | 592                   | 0                    |
+-----------+-------------+--------+-----------------------+----------------------+
| LFE5UM-25 |  0x01111043 | 7562   | 592                   | 0                    |
+-----------+-------------+--------+-----------------------+----------------------+
| LFE5U-45  | 0x41112043  | 9470   | 846                   | 2                    |
+-----------+-------------+--------+-----------------------+----------------------+
| LFE5UM-45 | 0x01112043  | 9470   | 846                   | 2                    |
+-----------+-------------+--------+-----------------------+----------------------+
| LFE5U-85  | 0x41113043  | 13294  | 1136                  | 0                    |
+-----------+-------------+--------+-----------------------+----------------------+
| LFE5UM-85 | 0x01113043  | 13294  | 1136                  | 0                    |
+-----------+-------------+--------+-----------------------+----------------------+