Getting Started
This guide will walk you through setting up your development environment, building and flashing your first firmware.
Prerequisites
If you’re new to Zephyr, we recommend starting with the official Zephyr Getting Started Guide to familiarize yourself with the framework.
Before continuing, ensure you have installed the Zephyr system requirements for your operating system.
Setting Up Your Development Environment
Follow these steps to set up your TT Zephyr Platforms development environment:
# Step 1: Create and activate a virtual environment
python3 -m venv ~/tt-zephyr-platforms-work/.venv
source ~/tt-zephyr-platforms-work/.venv/bin/activate
# Step 2: Install West (Zephyr's meta-tool)
pip install west
# Step 3: Initialize the workspace with TT Zephyr Platforms
west init -m https://github.com/tenstorrent/tt-zephyr-platforms ~/tt-zephyr-platforms-work
# Step 4: Navigate to the workspace directory
cd ~/tt-zephyr-platforms-work
# Step 5: Download all required Zephyr modules
west update
# Step 6: Install additional Python dependencies
west packages pip --install
# Step 7: Install the Zephyr SDK (required for building)
west sdk install
# Step 8: Download binary blobs (firmware components)
west blobs fetch
# Step 9: Apply TT-specific patches
west patch apply
Note
The setup process may take several minutes to complete, especially when downloading the Zephyr SDK and modules.
Building and Flashing SMC Firmware
The System Management Controller (SMC) firmware manages system-level operations. Follow these steps to build and deploy it:
Step 1: Choose your board revision and build the firmware
Select the appropriate command for your board revision:
west build --sysbuild -p -b tt_blackhole@p100a/tt_blackhole/smc app/smc -- -DCONFIG_SHELL=y
west build --sysbuild -p -b tt_blackhole@p150a/tt_blackhole/smc app/smc -- -DCONFIG_SHELL=y
west build --sysbuild -p -b tt_blackhole@p150b/tt_blackhole/smc app/smc -- -DCONFIG_SHELL=y
west build --sysbuild -p -b tt_blackhole@p150c/tt_blackhole/smc app/smc -- -DCONFIG_SHELL=y
west build --sysbuild -p -b tt_blackhole@p300a/tt_blackhole/smc app/smc -- -DCONFIG_SHELL=y
west build --sysbuild -p -b tt_blackhole@p300b/tt_blackhole/smc app/smc -- -DCONFIG_SHELL=y
west build --sysbuild -p -b tt_blackhole@p300c/tt_blackhole/smc app/smc -- -DCONFIG_SHELL=y
Step 2: Complete the deployment process
After the build completes successfully, run these commands to deploy and connect to your board:
# Build the TT console utility (for board communication)
make -j -C scripts/tooling OUTDIR=/tmp tt-console
# Flash the firmware to your board
west flash -r tt_flash --force
# Reset the board and refresh PCIe connectivity
tt-smi -r
./scripts/rescan-pcie.sh
# Connect to the board console
/tmp/tt-console
Tip
The --sysbuild
option automatically builds both SMC and DMC firmware together, which is the recommended approach for most users.
Building DMC Firmware (Advanced Users)
Important
Most users can skip this section. When you build SMC firmware with --sysbuild
(as shown above),
the DMC (Device Management Controller) firmware is automatically built and flashed along with it.
When you might need to build DMC separately:
You’re a developer who needs to update MCUBoot
You’re working specifically on DMC firmware modifications
You need to debug DMC-specific issues
Warning
Updating MCUBoot is not required or recommended for end users. Only proceed if you have specific development needs.
Manual DMC build process:
# Build DMC firmware (replace p100a with your board revision)
west build -b tt_blackhole@p100a/tt_blackhole/dmc app/dmc
# Flash the bootloader and application
west flash
# Open the Real-Time Transfer (RTT) viewer to see output
west rtt
Expected console output:
When DMC firmware boots successfully, you should see output similar to this:
*** Booting MCUboot v2.1.0-rc1-389-g4eba8087fa60 ***
*** Using Zephyr OS build v4.2.0-rc3 ***
I: Starting bootloader
I: Primary image: magic=good, swap_type=0x2, copy_done=0x1, image_ok=0x1
I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
I: Boot source: none
I: Image index: 0, Swap type: none
I: Bootloader chainload address offset: 0xc000
I: Image version: v0.9.99
I: Jumping to the first image slot
.:. .:
.:-----:.. :+++-.
.:------------:. :++++++=:
:------------------:.. :+++++++++
:----------------------:. :+++++++++
:-------------------------:.:+++++++++
:--------: .:-----------:. :+++++++++
:--------: .:----:. :+++++++++
.:-------: . :++++++++-
.:----: :++++=:.
.:: :+=:
.:. ::
.===-: .-===-
.=======:. :-======-
.==================-
.==================-
==================:
:-==========-:.
.:====-.
*** Booting tt_blackhole with Zephyr OS v4.2.0-rc3 ***
*** TT_GIT_VERSION v18.6.0-78-gf104f347ff0f ***
*** SDK_VERSION zephyr sdk 0.17.2 ***
DMFW VERSION 0.9.99
Pulling in New Code from main
After pulling in the latest code from main
, you will avoid many mysterious build / functional issues by executing these commands:
# Clean up any existing patches
west patch clean
# Update Zephyr and other modules to the version in the manifest
west update
# Apply the latest patches
west patch apply
Testing Your Setup
Once you’ve successfully built and flashed firmware, you can run tests to verify everything is working correctly.
Testing SMC firmware:
Note
Some users may need to patch their OpenOCD binaries to support Segger’s RTT on RISC-V and ARC architectures. For more information, see this GitHub PR.
# Run a basic "Hello World" test on SMC (replace p100a with your board revision)
twister -i -p tt_blackhole@p100a/tt_blackhole/smc --device-testing --west-flash \
--device-serial-pty rtt --west-runner /opt/tenstorrent/bin/openocd-rtt \
-s samples/hello_world/sample.basic.helloworld.rtt
Testing DMC firmware:
# Run a basic "Hello World" test on DMC (replace p100a with your board revision)
twister -i -p tt_blackhole@p100a/tt_blackhole/dmc --device-testing --west-flash \
--device-serial-pty rtt --west-runner openocd \
-s samples/hello_world/sample.basic.helloworld.rtt
Tip
If tests pass successfully, your development environment is properly configured and ready for development!
Setting Up Development Tools (Optional)
If you plan to contribute code to the project, we recommend setting up git hooks to automatically check your code for formatting and compliance issues.
Install git hooks:
# Run this script from your workspace directory
tt-zephyr-platforms/scripts/add-git-hooks.sh
Note
These hooks will automatically run before commits and pushes to ensure your code meets project standards.