Gateware Library

The Squishy gateware library is broken into three main parts. The first is the squishy.gateware.core module, this contains all of the core infra for Squishy. Next is the squishy.gateware.platform module, this contains the torii platform definitions for various bits of Squishy hardware. Finally there is the squishy.gateware.scsi module, this is where all of the SCSI machinery is for use in torii HDL projects.

class squishy.gateware.SquishyPlatform

Base Squishy Hardware platform

This represents all the common properties and methods that all Squishy hardware platforms are required to have.

This also implements the applet bitstream cache mechanisms.

Variables:

  • revision (tuple[int, int]) – The revision of the hardware this platform supports, in the form of (major, minor).

  • revision_str (str) – The canonicalize revision as a string in the form of ‘major.minor’.

  • bitstream_suffix (str) – The suffix of the FPGA bitstream that is generated when gateware is built for this platform.

  • flash (FlashConfig) – The configuration of the attached SPI boot flash.

  • pll_cfg (PLLConfig) – The PLL configuration that is passed to the clk_domain_generator of this platform when instantiated.

  • clk_domain_generator (type[torii.Elaboratable]) – The type of clock domain generator for this platform. It is instantiated and hooked up to the gateware on elaboration.

  • ephemeral_slot (int | None) – If this platform supports ephemeral applet flashing, then this is the DFU alt-mode to use, otherwise None

Important

Platforms are also still required to inherit from the appropriate torii.vendor.platform in order to properly be used.

abstract property revision: tuple[int, int]

The hardware revision of this platform in the form of (major, minor)

property revision_str: str

The canonicalize revision as a string in the form of ‘major.minor’

abstract property bitstream_suffix: str

The suffix of the FPGA bitstream that is generated when gateware is built for this platform

abstract property flash: FlashConfig

The attached SPI boot flash configuration

abstract property pll_cfg: ECP5PLLConfig | ICE40PLLConfig

PLL Configuration for the platforms clock domain generator

abstract property clk_domain_generator: type[Elaboratable]

The Torii Elaboratable used to setup the PLL and clock domains for the platform

property ephemeral_slot: int | None

If this platform supports ephemeral applet flashing, then this is the DFU alt-mode to use

abstract pack_artifact(artifact: bytes) → bytes

Pack a signal bitstream image into a device appropriate artifact.

Parameters:

artifact (bytes) – The input data of the result of gateware elaboration, typically the raw FPGA bitstream file.

Returns:

The result of the artifact packing process

Return type:

bytes

abstract build_image(name: str, build_dir: Path, boot_name: str, products: BuildProducts) → Path

Build a platform compatible flash image for provisioning.

Parameters:

  • name (str) – The name of the flash image to produce.

  • build_dir (Path) – Output directory for the finalized flash image.

  • boot_name (str) – The name of the bootloader in the build products

  • products (BuildProducts) – The resulting build products from the bootloader build.

Returns:

The path to the resulting image file.

Return type:

Path

all_resources_by_name(name: str) → list[Resource]

Get all resources sharing a common root name, e.g. all LEDs

Parameters:

name (str) – The base name of the resources to collect.

Returns:

A list of all of the found Torii resources matching the given base name.

Return type:

list[Resources]

class squishy.gateware.Squishy(*args, src_loc_at: int = 0, **kwargs)

Squishy applet gateware superstructure.

Parameters:
class squishy.gateware.SquishyBootloader(*args, src_loc_at: int = 0, **kwargs)

Squishy DFU Bootloader

This is the “top” module representing a Squishy DFU capable bootloader.

It provides DFU alt-modes for each flash slot, including the bootloader, as well as dispatch to the appropriate programming interface for the given platform.

For SquishyRev1 platforms, the method of programming is direct SPI flash, followed by an SB_WARMBOOT trigger.

For SquishyRev2 this is more complicated, as we have the supervisor MCU in the mix. First the image is written to the SPI PSRAM, a signal is then sent to the supervisor to reboot us and re-program us with the new bitstream.

Note

There needs to be some consideration for hardware platforms that support ephemeral programming, any transfers to that slot must be distinguished from a normal slot transfer, for Rev1 platforms this is not an issue, as there is no way of doing an ephemeral applet, however for Rev2, in order to try to tide wearing out flash with write cycles (even though they’re good for like, 100k cycles) we have an (optional?) onboard PSRAM that acts as both a cache for doing flash updates as well as doing hot-loading without actually touching flash.

This can be done mostly opaquely from the root of the bootloader module itself, other than having to properly name the ephemeral DFU slot, as all the machinery for updating the platform is within the target module for that anyway.

Warning

Currently there is no flash protection for the bootloader slot (slot 0), it is exposed by default, and treated like any other applet slot.

We also don’t have any checksums, which might be a bit problematic, but due to some platform limitations specifically due to Rev1 where we write directly into flash and don’t have a buffer that can be used and discarded, we write-over the slot as we update. This is particularly dangerous for the bootloader.

Parameters:

  • serial_number (str) – The device serial number to use.

  • revision (tuple[int, int]) – The device revision.

Variables:

serial_number (str) – The device serial number assigned.