Tools for exploiting warm/cold boot in iCE40 FPGAs

Therefore a single bitstream can be directly loaded to the FPGA with:

That is, in the iCEstick and similar boards, the FTDI resets the FPGA by asserting CRESET_B and lets it power up in slave SPI mode by keeping SPI_SS_B low. Then, the image is written to the SRAM directly. The flash memory ignores any command, because asserting the communication to the FPGA disables the memory’s chip select. This is explained in detail in [TN1248, pp 17-20].

However, with the option above, the FPGA will lose it’s functionaly as soon as it is powered off. To avoid so, the following command can be used instead:

This time, the FTDI explicitly holds the FPGA in reset state and asserts the chip select signal of the flash memory. Then, the image is written to the flash memory. When the transference is complete, the reset state is released and the FPGA is powered up in master SPI mode. Therefore, the image written just before is loaded from the flash memory. For more information check [TN1248, pp 10-13].

TODO: to pos 0? Is an applet added?

Instead of thoroughly analyzing the details of the format, which is explained at bygone.clairexen.net/icestorm/format, a naive approach was followed. Four bitstreams generated with Yosys and nextpnr were analyzed:

As it is explained below, that is the applet, a table/index of addressable images.

In [TN1248, pp 14-15] the Cold Boot Configuration Option is explained. The procedure is roughly the same as the second one explained in the single bitstream example above, but up to four images can be written at the same time. The advantage is that this allows the user to later change from one image to another without requiring an external processor for transferring it.

To support such a feature, an applet is written to the first addresses of the flash. Then, when the cold boot option is enabled:

Packing images is achieved with a tool named icemulti from the IceStrom toolchain.

For example, to program four images at a time, by setting the first one as the default and not enabling cold boot:

The same pack can be generated with the second image as the default option by changing -p0 to -p1. When programming any of these packs, the transference will last longer than in the single image example, because four full images are being written. However there will be no functional difference, since only the default image will be used by the FPGA. This is a good starting point for understanding how packs are generated.

The size of both packs is the same: 127 KB (130524 bytes), on disk 128KB. As done previously, an hexdump of one of the packs was generated. If we compare it with the hexdump of a single image, the starting point of each of them is easily found. Indeed, looking for ff 7e aa 99 7e is enough. In the following block only the most meaninful parts are shown:

Then, we can derive the following memory map:

These addresses match columns 10-12 in lines 00000020, 00000040, 00000060 and 00000080. Hence, those three bytes tell the warm/cold boot feature where to load the bitstream from. Furthermore, the address of img01 is also present in columns 10-12 at address 0x00000000. That is the power-on reset image.

Every image, except img01 is placed in a 32KB section, which makes sense if no compression is used at all. The space for img01 is smaller, because of the applet. However, since images require 32220 bytes, there are still 292 free bytes. Indeed, there are 3*548+292=1936 free bytes between images in the space 0x00000000-0x0001FFFF, which can be used for user applications, even if cold boot is active.

Moreover, the hexdump of the second pack is equal to the previous one, except for the power-on reset image, which is set to img02 instead of img01. Actually, they differ in a single byte:

Therefore, even though vector addresses (4) are mentioned in [TN1248, Fig. 11], a single one is used when -c option is not passed to icemulti.

The warm boot feature is functionally the same as the cold boot. The same external memory layout is used. The only difference is that warm boot is triggered from inside the FPGA. That is, a hard module/component named SB_WARMBOOT needs to be instantiated in each of the designs which should change to some other under certain conditions. It has two bits for selecting one of the four images, along with an additional bit for triggering the reboot/reload. That replaces the external pins used for cold-boot.

TBW

The configuration defaults to reading pointers in fixed positions and directly jumping to them. Three bytes (24 bits) are reserved for each pointer, so 0xFFFFFF is the largest value they can take. As a result, up to floor((224-1)/215)=511 images can be addressed, if a memory of at least 16MB (128Mb) is used and 32KB are used for each image. The size of the flash memory in the iCEstick is 4MB (32Mb), so up to floor((222-1)/215)=127 images can be addressed. The expression for computing the address corresponding to an image in position x, where x = 0,…​,$number_of_images-1 is x==0 ? 0x000100 ; (x-1)*0x8000.

If images are appended without free space between them, slightly larger packs can fit:

Apparently, this extended memory map can not be addressed through CBSEL. However, either the processor or a component in the FPGA can be used for updating just the pointers (applet), allowing changing between groups of four images in the extended pack.

Cold/warm boot features of Lattice’s iCE40 FPGAs allows mimicking high-performance SoC designs which include programmable logic, such as Xilinx’s Zynq or Intel/Altera’s Arria/Cyclone. The main orchestrator in those systems is expected to be a CPU (either a PC or a microcontroller), which is already true for most of the available open source boards. Furthermore, embedded CPUs can be synthetised. Actually, that’s the case of FOMU, which loads a RISC-V based design as the demo design. That sets a quite large list of devices to choose from. Although not exclusively, examples here are focused on the following:

Depending on the design of the boards, multiple connection schemes might be possible in order to achieve the same functional result. See the specific documentation of each of the examples.

The upstream icemulti allows packing up to four images for using the default cold/warm boot features. It also allows the power on reset image. However, it does not currently support features beyond the default usage.

@juanmard extended both icemulti and iceprog for allowing packing any number of images, up to the size of the target memory. See juanmard/icestorm. It also allowed modifying entries in the header/applet for switching the addressable images efficiently. Moreover, he used some spare bytes at the beginning of each image for writing an string identifier of the bitstream. That allows listing the content of the memory (through iceprog) and getting a human readable output.

@sylefeb complemented @juanmard’s solution by writing a hot-swap HDL core that can manipulate the header/applet in the external memory, so that an external CPU or PC is not required for switching addresses/pointers. Furthermore, he cleverly implemented it by employing an unused region of the external memory as an scratchpad and modifying the header, on the fly (while passing through a reduced footprint HDL). Chunks of 256 bytes are used. The actual HDL is a RISC-V soft core requiring ~2K LUTs. Yet, as he explains in sylefeb/Silice: draft/projects/ice40-dynboot, there is room for improvement there!

When using development boards with iCE40 devices which don’t use FTDI for programming, iceprog cannot be used. That is the case of e.g. FOMU, which uses dfu-util. However, @sylefeb found that dfu-util is happy to upload binary files larger than the default bitstream size. Hence, data can be concatenated and it is the available at address 262144 (warmboot slot) + 104106 (bitstream size) ( see im-tomu/foboot: doc/FLASHLAYOUT.md).

iCE40 FPGAs do have hard SPI modules, which can be instantiated for user applications (see iCE40™ LP/HX/LM Family Handbook, page 62). Hence, it might be possible to prototype a module/component in HDL for overwriting the pointers in the applet without requiring an external CPU. A look-up-table and some FSM would be required, apart from enough BRAM for holding the minimal ammount of data that needs to be read from the flash.

It would also be possible to handle uncompressing some image and overwritting one of the existing addressable locations, instead of modifying the pointers. However, dealing with uncompression algorithms in HDL might be non trivial.

TBW