19.15.0

Migration Guide

This document lists recommended and required changes for those migrating from the previous v19.14.0 firmware release to the new 19.15.0 firmware release.

Required: second-source SPI flash interlock

Blackhole Galaxy may now ship a second-source SPI EEPROM. Firmware older than 19.15 only speaks the Micron MT25QU512ABB command set. Writing that image onto a second-source board leaves firmware that cannot read itself back, including recovery.

19.15 adds an interlock so tt-flash will not write an image that cannot support the board in front of it. There are three participants:

Firmware bundle — each image declares the board variables it knows and the values it supports, in compat-variables.json.
tt-flash — checks those values against the running firmware (today: SPI EEPROM JEDEC ID from telemetry tag 80) and refuses an incompatible image.
Running firmware — FLASH_UNLOCK carries a bitmap of the variables tt-flash checked. Firmware refuses to unlock if a required variable is missing, so an older tt-flash that does not know about board variables cannot flash a second-source board.

The first board variable is SPI EEPROM JEDEC ID (BOARD_VAR_SPI_JEDEC_ID = 0).

What you must do

Original Micron MT25QU512ABB boards (JEDEC ID 0x20bb20): no tool change is required. Firmware exempts this part from the JEDEC-ID unlock check, so existing tt-flash continues to work.
Second-source SPI boards (any other JEDEC ID): you need both
- a 19.15.0 (or later) firmware bundle, which includes compat-variables.json, and
- a tt-flash that implements the board-variable interlock (tt-flash#112).
Galaxy bin6 (board type 0x202): tt-flash 3.11.0 or later, in addition to the interlock above if the board is second-source.

Until tt-flash#112 is in a numbered release, flashing a second-source board requires a tt-flash build that includes that change.

Compatibility matrix

x means the version of that participant does not matter. “new” means 19.15 firmware / a bundle that carries compat-variables.json / a tt-flash that implements the interlock. Observed messages are from qualification.

fwbundle	tt-flash	running FW	Result	Observed
x	x	old	Not applicable / don’t care	(old firmware does not implement the interlock)
x	old	new	No app support; firmware must not unlock	`Error: Failed to unlock spi`
old	new	new	Bundle does not declare hardware support; firmware must not unlock	`Error: The firmware on this board will not allow a flash until these are verified against the image: board variable 0. This firmware bundle does not say which hardware it supports; use a newer bundle.`
new but incompatible	new	new	tt-flash rejects before write	`Error: This firmware is not compatible with this board: SPI EEPROM is 0x20bb20; this firmware supports 0x20bb21`
new	new	new	Flash unlocks; new image is written	successfully flashed

The incompatible-bundle example above is the error shape (actual JEDEC IDs depend on the fitted part and the image).

Supported SPI EEPROM JEDEC IDs

19.15 images that include the Galaxy flash mux accept:

JEDEC ID	Part
`0x20bb20`	Micron MT25QU512ABB
`0xc2253a`	Macronix MX25U51245G
`0xc8631a`	GigaDevice GD25LF512MF
`0xef6020`	Winbond W25Q51RW-Q/-N, W25Q512NW-IQ/IN

An unrecognized chip still enumerates on a single-I/O fallback so the card stays readable. Flashing it still requires a bundle that lists that JEDEC ID. tt-flash --force does not override this check.

Downgrade

On a second-source board that is already running 19.15:

Old tt-flash cannot unlock the flash (Failed to unlock spi).
A new tt-flash will not write a pre-19.15 bundle, because that bundle has no compat-variables.json.

You cannot return those boards to pre-19.15 firmware with the old tools. Stay on 19.15+ bundles and an interlock-aware tt-flash.

On an MT25 board, existing tools and older bundles continue to work.

See board variables for the protocol.

Recommended: Tensix clock gating now honors `cg_en`

feature_enable.cg_en was inverted: firmware skipped Tensix clock gating when the flag was set, and applied it when the flag was clear. 19.15 corrects this.

Every production firmware table ships cg_en: true, so after upgrade Tensix clock gating is on. Idle and light-load Tensix power should drop; full-load power is largely unchanged. If you had cleared cg_en to enable gating under the old inverted logic, that board will now run with gating off — set cg_en to the intended polarity.

Optional: PCIe max generation override

pci0_property_table.max_pcie_speed and pci1_property_table.max_pcie_speed can be overridden with bh-mod and persist across firmware upgrades. Valid values are {0, 1, 2, 3, 4, 5}; 0 is unconstrained (Gen 5 default). bh-mod res restores the cmfwcfg value. Set the instance whose pcie_mode is EP. This requires tt-flash 3.8.0 or later to preserve ccfgovr across flashes.

Galaxy bin6

Galaxy bin6 is a new UBB board type (0x202, tt_blackhole@galaxy_bin6). Host tools that switch on board type need to treat 0x202 as a Galaxy/UBB variant (one harvested DRAM instance; SPI tables based on Galaxy Rev C). tt-flash 3.11.0 adds this type.