Provisioning and startup

Overview

The Glasgow device contains two non-volatile memories, ICE_MEM and FX2_MEM, implemented as I²C EEPROMs. The FX2_MEM memory contains critical device configuration, and must be factory-programmed in a revision-specific way for the device to be usable. The ICE_MEM memory optionally contains FPGA bitstream and is not accessed at all during operation other than when explicitly requested.

The FX2_MEM memory is logically divided into three parts:

  1. FX2 boot configuration (8 bytes);
  2. Glasgow configuration (currently 4 + 64 bytes);
  3. Firmware (rest of the flash).

The FX2 boot configuration can specify one of the two boot modes: the ID-only mode and the firmware mode. The ID-only mode is indicated by the initial byte C0 and the firmware mode is indicated by the initial byte C2. In the firmware mode, immediately after the boot configuration, the memory contains a set of (length, address, data) firmware chunks, which are loaded into on-chip RAM after FX2 reset is deasserted.

Note

The paragraph above is a simplified high-level explanation of the FX2 boot process. For exhaustive documentation, refer to the EZ-USB Technical Reference Manual section 3.4.

The Glasgow configuration is structured as a firmware chunk that is loaded to the very end of on-chip RAM; this is done so that it can be located at a predetermined position in the non-volatile memory without placing a limit on firmware size. It is currently 64 bytes long; if this space is ever exhausted, an additional configuration block may be added using the same basic structure.

The Glasgow configuration contains, most importantly, the revision (as an ASCII letter, A-Z) and serial number (16 ASCII letters, time in ISO 8601 format); these are written during factory configuration and must be preserved at all times, because the revision determines routing for certain signals on the board. The rest of configuration is described below.

Factory programming

With an empty EEPROM, the FX2 chip enumerates with Cypress VID and PID. The glasgow factory command looks for a device with this VID and PID, initializes the FX2 boot block to ID-only mode with Glasgow VID and PID, and writes initial Glasgow configuration block with the provided revision and autogenerated serial number.

In ID-only mode, the FX2 chip enumerates on its own with the provided USB VID and PID, and ignores the rest of EEPROM.

Mode identification

The Device ID field is used to provide the mode and device revision to the host regardless of whether the device contains firmware. The high byte of DID is 00 in a device without loaded FX2 firmware, and 01 in a device with loaded FX2 firmware. The low byte of DID is the board revision, encoded as A → 01, B → 02, etc.

Boot process

There are two FX2 boot flows.

When in firmware boot mode, after reset, the firmware and the configuration block are automatically loaded by FX2 silicon into on-chip RAM. After that, the device enumerates with DID 01xx.

When in ID-only boot mode, after reset, the device enumerates with DID 00xx. Any CLI operation involving the device detects this condition and automatically loads the firmware using FX2 silicon features. The firmware explicitly loads the configuration block from the EEPROM and enumerates with DID 01xx.

Firmware programming

The glasgow flash command, without arguments or with --firmware argument, writes the default or the provided firmware to FX2_MEM and switches the device to firmware mode. The same command with --remove-firmware argument switches the device to ID-only mode.

Bitstream operations

The glasgow run <applet> command loads a bitstream into SRAM and changes bitstream-related fields in the configuration block in RAM.

The glasgow flash <applet> command writes the bitstream into ICE_MEM and changes bitstream-related fields in the configuration block in FX2_MEM. It does not change the FPGA bitstream or configuration in SRAM. The bitstream is loaded on the next reset.

Hot reload

Hot reload (loading the firmware using make -C firmware load) only results in a proper reset when FX2 is configured in ID-only mode, i.e. it is necessary to run glasgow flash --remove-firmware before using a device for developing firmware.

Python API

class glasgow.device.config.GlasgowConfig(revision, serial, bitstream_size=0, bitstream_id=b'x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00', voltage_limit=None)[source]

Glasgow EEPROM configuration data.

Variables:
  • size (int) – Total size of configuration block (currently 64).
  • revision (str[1]) – Revision letter, A-Z.
  • serial (str[16]) – Serial number, in ISO 8601 format.
  • bitstream_size (int) – Size of bitstream flashed to ICE_MEM, or 0 if there isn’t one.
  • bitstream_id (bytes[16]) – Opaque string that uniquely identifies bitstream functionality, but not necessarily any particular routing and placement. Only meaningful if bitstream_size is set.
  • voltage_limit (int[2]) – Maximum allowed I/O port voltage, in millivolts.
encode()[source]

Convert configuration to a byte array that can be loaded into memory or EEPROM.

classmethod decode(data)[source]

Parse configuration from a byte array loaded from memory or EEPROM.

Returns GlasgowConfiguration or raises ValueError if the byte array does not contain a valid configuration.