Tenstorrent

Starting Guide

Welcome to Tenstorrent! This guide will walk you through setting up your Tensix Processor(s) and installing necessary software.

Table of Contents

  1. Prerequisites

  2. Unboxing and Hardware Setup

  3. Software Installation

  4. Support & FAQ

1. Prerequisites

Before you begin, ensure you have the following:

  • A compatible host machine with minimum hardware and OS requirements as specified by each product’s minimum system requirements:

  • Network access to download software packages.

  • Administrator privileges on the host machine.

NOTE: The recommended OS for all Tenstorrent software is Ubuntu 20.04 LTS (Focal Fossa). Each SDK may support newer distributions of Ubuntu; however, compatibility should be considered experimental at this time.

2. Unboxing and Hardware Setup

  1. Unpack the hardware and check all components against the provided list.

  2. Install the hardware following the hardware installation manual and safety guidelines by product:

  3. Secure the hardware in place, ensuring it is firmly seated and all connections are stable.

3. Software Installation

To interact with the Tensix Processor(s), you’ll need to install the system-level dependencies on your host machine.

Important!

This Starting Guide will reference each software utility where the latest version is available. However, each SDK will have its own compatibility matrix associated with each release. It is strongly recommended to consult each SDK’s release compatibility matrix to ensure you are installing the correct versions of the system software packages.

Step 1: Install Software Dependencies

Install git, wget, pip, and DKMS (Dynamic Kernel Module Support) by running the following command in your terminal according to your Linux distribution:

Linux Distro

Installation Command

Debian, Ubuntu

sudo apt update && sudo apt install -y wget git python3-pip dkms

Fedora

sudo dnf check-update && sudo dnf install -y wget git python3-pip dkms

Enterprise Linux based

sudo dnf install -y epel-release && sudo dnf check-update && sudo dnf install -y wget git python3-pip dkms

NOTE: Installation on non-Ubuntu distributions should be considered experimental at this time.

Step 2: Install the Kernel-Mode Driver (TT-KMD)

Install the driver (TT-KMD) by running these commands in the terminal:

git clone https://github.com/tenstorrent/tt-kmd.git
cd tt-kmd
sudo dkms add .
sudo dkms install tenstorrent/1.31
sudo modprobe tenstorrent

Step 3: Device Firmware Update (TT-Flash / TT-Firmware)

The TT-Firmware file needs to be installed using the TT-Flash utility.

Install TT-Flash

To install TT-Flash, run this command in the terminal:

pip install git+https://github.com/tenstorrent/tt-flash.git

NOTE: If you are not using a Python virtual environment (venv), you may see an error externally-managed-environment when installing via pip. To resolve this, create and/or activate a venv or use a tool like pipx.

Update Device Firmware

To update Tenstorrent device firmware using TT-Flash, run these commands in the terminal:

wget https://github.com/tenstorrent/tt-firmware/raw/main/fw_pack-80.13.2.0.fwbundle
tt-flash --fw-tar fw_pack-80.13.2.0.fwbundle

If this process worked, reboot the system and go to the next section.

If running that command results in an error that says the firmware is too old, enter the following command:

tt-flash --fw-tar fw_pack-80.13.2.0.fwbundle --force

Then reboot the system.

Step 4: Setup HugePages

HugePages lets your system allocate dedicated memory to accelerate communication with Tenstorrent devices. Setup HugePages by running these commands in the terminal:

# Install `.deb`
wget https://github.com/tenstorrent/tt-system-tools/releases/download/upstream%2F1.1/tenstorrent-tools_1.1-5_all.deb
sudo dpkg -i tenstorrent-tools_1.1-5_all.deb

# Start Services
sudo systemctl enable --now tenstorrent-hugepages.service
sudo systemctl enable --now 'dev-hugepages\x2d1G.mount'

# System Reboot
sudo reboot

NOTE: This is a temporary solution for configuring hugepages. If the above fails, please check the latest available release from TT-System-Tools.

Step 5: Install the System Management Interface (TT-SMI)

Install the Tenstorrent Software Management Interface (TT-SMI) by entering this command in the terminal:

pip install git+https://github.com/tenstorrent/tt-smi

Step 6: Verify System Configuration and Test TT-SMI

Once the hardware and system software are installed, verify that your system has been configured properly.

Run the tt-smi utility.

This should bring up a display that looks as below.

tt-smi

This is the default mode where the user can see device information, telemetry, and firmware. If TT-smi runs without errors, congratulations! You’re ready to use your Tenstorrent device.

Installation

Tenstorrent provides three open-source SDKs for developing on Tensix Processors:

Each SDK will have its own system dependency requirements and installation process.

To help you get started, check out these First 5 Things guides, which include installation steps, for TT-Buda and TT-Metalium.

Support & FAQ

For support, forums, and community, visit Tenstorrent’s Discord channel.

For additional support, file any issues through our Customer Success Platform or you can contact us directly at support@tenstorrent.com.