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

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.