Lattice notes¶

Programming model overview¶

Lattice families do not all use the same non-volatile programming path. The file extension and the target memory selected on the command line matter.

Family	Volatile load	Non-volatile programming
MachXO2	`.bit` to SRAM	`.jed` to internal Flash/NVCM
MachXO3L/MachXO3LF	`.bit` to SRAM	`.jed` to internal NVCM/Flash
MachXO3D	`.bit` to SRAM	`.jed` plus `--flash-sector`
iCE40	`.bin` through SPI	direct SPI flash access
ECP5/Certus-NX/CrossLink-NX	`.bit` to SRAM	`.bit`, `.bin` or `.mcs` to external SPI flash
ECP3	`.bit` to SRAM	external SPI flash write is not supported

For MachXO2/MachXO3 devices, internal Flash/NVCM is programmed through the Lattice JTAG/ISC command flow. Do not provide a --bridge file for this path. The spiOverJtag bridge bitstreams shipped with openFPGALoader are used by other vendor families, or by Lattice families with an external SPI flash path, not by MachXO3 internal Flash/NVCM programming.

For ECP5 and Nexus devices, openFPGALoader can use the FPGA's internal JTAG-to-SPI access path to reach an external SPI flash. For iCE40, the board entry usually describes a direct FTDI-to-SPI flash connection.

MachXO2/MachXO3¶

Flash memory¶

.jed file is the default format generated by Lattice Diamond, so nothing special must be done to generate this file for internal Flash/NVCM programming.

File load:

openFPGALoader [-b yourboard] [--flash-sector CFG0] impl1/*.jed

or with an explicit cable:

openFPGALoader -c yourCable -f impl1/*.jed

where yourboard may be:

machX02EVN
machX03EVN
machXO3SK

and where --flash-sector CFG0 is needed for the MachXO3D Breakout Board.

.bit may also be used for machXO2 internal Flash programming. For MachXO3L/MachXO3LF internal Flash, prefer the Diamond-generated .jed file. A MachXO3 .bit is most commonly used for SRAM load or for an external configuration flash flow, depending on the board and Diamond export settings.

MachXO3 JEDEC files may contain multiple link-field sections:

main configuration data
NOTE EBR_INIT DATA for embedded block RAM initialization
NOTE END CONFIG DATA marking the end of configuration data
NOTE TAG DATA for NVCM1/UFM pages, when present
NOTE FEATURE_ROW for Feature Row and FEABITS

When a design does not use UFM, Diamond may still emit a trailing all-zero TAG DATA block. This should not be treated as user payload.

SRAM¶

To generate a .bit file, Bitstream file must be checked under Exports Files in the Lattice Diamond left panel.

File load:

openFPGALoader [-b yourboard] impl1/*.bit

or:

openFPGALoader -c yourCable impl1/*.bit

where yourboard may be:

machX02EVN
machX03EVN
machXO3SK

iCE40¶

.bin is the default format generated by nextpnr, so nothing special must be done.

Since most ice40 boards uses the same pinout between FTDI and SPI flash a generic ice40_generic board is provided.

For the specific case of the iCE40HXXK-EVB where no onboard programmer is present, please use this:

FTDI	iCE40HXXK-EVB
SI (ADBUS1)	Pin 8
SCK (ADBUS0)	Pin 9
SO (ADBUS2)	Pin 7
CS (ABDUS4)	Pin 10
RST (ADBUS6	Pin 6
DONE (ADBUS7)	Pin 5

Bin file load:

openFPGALoader -b ice40_generic /somewhere/*.bin

Since it's a direct access to the flash (SPI) the -b option is required.

ECP5/ECP3/Certus-NX/CertusPro-NX/Crosslink-NX¶

SRAM¶

openFPGALoader [-b yourBoard] [-c yourCable] -m project_name/*.bit

Hint

By default, openFPGALoader loads bitstream in memory, so the `-m` argument is optional.

SPI Flash¶

Note

SPI Flash write is not supported for ECP3 family.

For ECP5, Certus-NX, CertusPro-NX and CrossLink-NX boards with external SPI flash, -f selects flash programming. This is a different path from MachXO3 internal Flash/NVCM programming.

BIT:

openFPGALoader [-b yourBoard] [-c yourCable] -f project_name/*.bit # or *.bin

MCS:

To generate .mcs file PROM File must be checked under Exports Files in Lattice Diamond left panel.

openFPGALoader [-b yourBoard] [-c yourCable] project_name/*.mcs

Dumping external SPI flash:

openFPGALoader [-b yourBoard] [-c yourCable] --dump-flash flash_dump.bin
openFPGALoader [-b yourBoard] [-c yourCable] --dump-flash -o 0x100000 flash_dump_tail.bin

When the SPI flash is known in openFPGALoader's flash database, the dump size is calculated automatically. The first command dumps the whole SPI flash; the second dumps from offset 0x100000 to the end of flash. Use --file-size only when a shorter dump is wanted, or when the flash chip is unknown and automatic capacity detection is unavailable.

Dumping MachXO2/MachXO3 internal Flash/NVCM:

openFPGALoader [-b yourBoard] [-c yourCable] --dump-flash machxo_internal.bin
openFPGALoader [-b yourBoard] [-c yourCable] --dump-flash -o 0x1000 --file-size 0x2000 machxo_window.bin

For MachXO2, MachXO3L, and MachXO3LF devices, --dump-flash reads the internal non-volatile configuration memory through the Lattice ISC/JTAG path instead of using an external SPI flash bridge. The dump is page based (16 bytes per page) and contains the CFG area followed by the UFM area. When --file-size is omitted or set to 0, openFPGALoader dumps from the selected offset to the end of the known internal flash layout. For example, an LCMXO3LF-9400C dump contains 12539 CFG pages plus 3582 UFM pages, for 257936 bytes total.

Erasing MachXO2/MachXO3 internal Flash/NVCM:

openFPGALoader [-b yourBoard] [-c yourCable] --bulk-erase
openFPGALoader [-b yourBoard] [-c yourCable] --bulk-erase --flash-sector CFG
openFPGALoader [-b yourBoard] [-c yourCable] --bulk-erase --flash-sector UFM

For MachXO2, MachXO3L, and MachXO3LF devices, --bulk-erase uses the Lattice ISC erase flow for internal Flash/NVCM. Without --flash-sector, the erase mask is ALL. To reduce accidental damage, select a sector when only part of the internal memory should be erased. Supported sector names are CFG, UFM, FEATURE, SRAM, and ALL. Be careful with FEATURE and ALL because feature bits control configuration behavior and port enables.