tt-flash

This is a utility to flash firmware blobs to tenstorrent devices.

Flash firmware on all devices on a system using one command:

tt-flash <firmware bundle file path>

Official Repository

https://github.com/tenstorrent/tt-flash

Getting started

Install Rust (if you don't already have it)

If Rust isn't already installed on your system, you can install it through either of the following methods:

Using Distribution packages (preferred)

• Fedora / EL9:
  sudo dnf install cargo
• Ubuntu / Debian:
  sudo apt install cargo

Using Rustup

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

User installation

tt-flash is available on PyPI. We recommend running it with uvx, which ensures you always run the latest released version.

Install uv if you don't already have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then run tt-flash:

uvx tt-flash@latest <firmware bundle file path>

Developer installation

Clone the repository

git clone https://github.com/tenstorrent/tt-flash.git
cd tt-flash

Install

uv sync

This creates a .venv and installs tt-flash in editable mode along with its dependencies. Run the local build with uv run tt-flash, or activate the venv (source .venv/bin/activate) and use tt-flash directly.

Help text

Use the -h argument to print the help text.

$ tt-flash -h

usage: tt-flash [-h] [-v] [--sys-config SYS_CONFIG] [--no-color] [--no-tty] {flash,verify} ...

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  --sys-config SYS_CONFIG
                        Path to the pre generated sys-config json
  --no-color            Disable the colorful output
  --no-tty              Force disable the tty command output

command:
  {flash,verify}
    flash               Flash firmware to Tenstorrent devices on the system. Run tt-flash flash -h for further command-specific help.
    verify              Verify the contents of the SPI. Will display the currently running and flashed bundle version of the fw and checksum the fw against either what was flashed previously according
                        the the file system state, or a given fw bundle. In the case where a fw bundle or flash record are not provided the program will search known locations that the flash record
                        may have been written to and exit with an error if it cannot be found or read. Run tt-flash verify -h for further command-specific help.

$ tt-flash flash -h

usage: tt-flash flash [-h] [--sys-config SYS_CONFIG] [--fw-tar FW_TAR] [--skip-missing-fw] [--force] [--no-reset] [--allow-major-downgrades] [--update-boot-images] [fwbundle]

positional arguments:
  fwbundle              Path to the firmware bundle

options:
  -h, --help            show this help message and exit
  --sys-config SYS_CONFIG
                        Path to the pre generated sys-config json
  --fw-tar FW_TAR       Path to the firmware tarball (deprecated)
  --skip-missing-fw     If the fw packages doesn't contain the fw for a detected board, continue flashing
  --force               Force update the ROM
  --no-reset            Do not reset devices at the end of flash
  --allow-major-downgrades
                        Allow major version downgrades
  --update-boot-images  Write the bundle's bootloader and recovery images even if the board already holds the same ones. They are left alone by default so that a power loss during an update cannot corrupt the board's boot path

Typical usage

tt-flash <firmware bundle file path goes here>

Firmware files

Firmware files are licensed and distributed independently, as tt-flash solely acts as a utility to update devices with provided firmware images. You can find firmware bundles in a seperate repo at https://github.com/tenstorrent/tt-firmware.

Example output

This is an example of what you can expect to see when you flash a device.

$ tt-flash ~/tt-firmware/latest.fwbundle

Stage: SETUP
        Searching for default sys-config path
        Checking /etc/tenstorrent/config.json: not found
        Checking ~/.config/tenstorrent/config.json: not found

        Could not find config in default search locations, if you need it, either pass it in explicitly or generate one
        Warning: continuing without sys-config, galaxy systems will not be reset
Stage: DETECT
Stage: FLASH
        Sub Stage: VERIFY
                Verifying fw-package can be flashed: complete
                Verifying Blackhole[0] can be flashed
        Stage: FLASH
                Sub Stage FLASH Step 1: Blackhole[0]
                        ROM version is: (18, 10, 0, 0). tt-flash version is: (18, 12, 0, 0)
                        FW bundle version > ROM version. ROM will now be updated.
                Sub Stage FLASH Step 2: Blackhole[0] {p150a}
                        Writing new firmware... (this may take up to 1 minute)
                        Writing new firmware... SUCCESS
                        Verifying flashed firmware... (this may also take up to 1 minute)
                        Firmware verification... SUCCESS
Stage: RESET
 Starting PCI link reset on BH devices at PCI indices: 0 
 Waiting for up to 60 seconds for asic to come back after reset
 Config space reset completed for device 0 
 Finishing PCI link reset on BH devices at PCI indices: 0 
FLASH SUCCESS

Supported products

tt-flash can be used to flash Wormhole and Blackhole products. The last version that supported flashing Grayskull products was v3.4.7.

License

Apache 2.0 - https://www.apache.org/licenses/LICENSE-2.0.txt