| Bitstream format |
| ================ |
| |
| Some documentation on the ECP5 bitstream format is published by Lattice themselves |
| in th ECP5 sysCONFIG Usage Guide (TN1260_). |
| |
| .. _TN1260: http://www.latticesemi.com/~/media/LatticeSemi/Documents/ApplicationNotes/EH/TN1260.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 | |
| +-------------------------------+-----+--------------------------+---------------------------------------------------+ |
| | ``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 data |
| frame 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``. |
| |
| |
| 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 | |
| +-----------+-------------+--------+-----------------------+----------------------+ |
