Tenstorrentのアクセラレータで開発する TT-Metalium による開発環境の構築

前回

ハードウェアセットアップ

開発環境の構築

TT-Metaliumについて

TT-Metalium™ is Tenstorrent’s open source, low level AI hardware SDK, getting you as close to the metal as possible for custom kernel development, experimentation, and more. No black boxes, encrypted APIs, or hidden functions.

TT-Metalium™ is great for development customers who want to customize their models, write new ones, or even run non-machine learning code.

TT-Metaliumでは新しくモデルを書いたり、Custom-OPを作成してTT-NNから呼び出したり、機械学習以外のコードを書くこともできるということです。したがって「汎用計算機」として扱うこともできるわけです。

今後の開発をTT-Metaliumで行うにあたって、開発環境を依存関係や破壊時の復元を考えてDocker(Podmanでも可)で作ります。

準備

アクセラレータは他のPCIeデバイスと同様にDMAを使ってホストシステムのメモリとデータをやりとりしますが、ページサイズが4KBとかだとアドレス変換がボトルネックになってしまうのでHugepagesの利用が推奨されています。

デフォルトでは、tt-installer実行時にHugepagesがインストールされますが念のため確認しておきます。
0以上になっていれば設定されています。

$ cat /sys/kernel/mm/hugepages/hugepages-1048576kB/nr_hugepages
4

コンテナの用意

作業開始にあたり、以下のファイルを用意します。

└── tt-metal-container
    ├── Dockerfile
    ├── docker-compose.yml
    └── shared
        └── tt-metal(git)

まず適当な名前のディレクトリを掘り(ここではtt-metal-container)、その下にDockerfile, docker-compose.yml, shareディレクトリを作成します。

Metalium リポジトリ

githubに公式のリポジトリがあるので(ホスト側から)cloneしてきます。

~/tt-metal-container/share$ git clone github.com/tenstorrent/tt-metal

Dockerfile

Metaliumをビルドするためのパッケージ類を入れたいので、記述します。
VS Codeのサーバーとかを入れておけばコンテナ内のファイルを編集したりするのに便利なので書いています。

./tt-metal-container/Dockerfile

FROM ghcr.io/tenstorrent/tt-metal/tt-metalium-ubuntu-22.04-release-amd64:latest-rc

RUN rm -f /etc/apt/sources.list.d/kitware*.list && \
    apt-get update && apt-get install -y --no-install-recommends \
        openssh-server sudo python3-pip git curl wget \
        build-essential g++-12 gcc-12 pkg-config libssl-dev \
        cargo rustc \
        xfce4 xfce4-terminal \
        tigervnc-standalone-server tigervnc-common \
        novnc websockify \
        dbus-x11 x11-xserver-utils \
    && update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 100 \
    && update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-12 100 \
    && echo "root:tt-metal" | chpasswd \
    && useradd -m -s /bin/bash -G sudo user \
    && echo "user:BlackHole" | chpasswd \
    && echo "user ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers \
    && rm -rf /var/lib/apt/lists/*

# clang-20: LLVM 公式リポジトリから追加
RUN wget -qO /tmp/llvm.sh https://apt.llvm.org/llvm.sh && \
    chmod +x /tmp/llvm.sh && \
    /tmp/llvm.sh 20 && \
    apt-get install -y --no-install-recommends \
        clang-20 lld-20 clang-format-20 clang-tidy-20 \
    && update-alternatives --install /usr/bin/clang   clang   /usr/bin/clang-20   100 \
    && update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-20 100 \
    && rm -rf /var/lib/apt/lists/* /tmp/llvm.sh

# SSH: パスワード認証を有効化、userのみ許可、ポート2222で起動
RUN mkdir -p /run/sshd && \
    sed -i 's/^#\?Port .*/Port 2222/' /etc/ssh/sshd_config && \
    sed -i 's/^#\?PasswordAuthentication .*/PasswordAuthentication yes/' /etc/ssh/sshd_config && \
    sed -i 's/^#\?PermitRootLogin .*/PermitRootLogin no/' /etc/ssh/sshd_config && \
    echo "AllowUsers user" >> /etc/ssh/sshd_config

# ブラウザ VS Code サーバー（外部スクリプトのため分離）
RUN curl -fsSL https://code-server.dev/install.sh | sh

# Filebrowser: シングルバイナリのWebファイルマネージャー
RUN curl -fsSL https://raw.githubusercontent.com/filebrowser/get/master/get.sh | bash && \
    filebrowser config init --database /etc/filebrowser.db && \
    filebrowser config set --database /etc/filebrowser.db --address 0.0.0.0 --port 8082 --root /work && \
    filebrowser users add admin BlackHole2222 --perm.admin --database /etc/filebrowser.db && \
    chown user:user /etc/filebrowser.db

# Python 開発ツールと tt-smi
RUN pip3 install --no-cache-dir \
    jupyterlab ipython ipykernel debugpy \
    tt-smi

WORKDIR /work

# ポート一覧:
#   2222 - SSH (user:BlackHole でログイン)
#   6080 - noVNC (WebTop) ← ブラウザで http://host:6080/vnc.html
#   8081 - code-server (ブラウザ VS Code)
#   8888 - JupyterLab
#   8082 - Filebrowser (Webファイルマネージャー)
EXPOSE 2222 6080 8081 8888 8082

# code-server のパスワード設定（ブラウザ VS Code のログインに使用）
ENV PASSWORD=BlackHole

# 起動スクリプト: sshd + VNC + noVNC + JupyterLab + code-server
# VNC は -SecurityTypes None でパスワードなし起動（ローカル開発環境用）
# Xstartup は実行時に生成（xfce4 セッション管理のため）
RUN printf '%s\n' \
    '#!/bin/bash' \
    '/usr/sbin/sshd' \
    '# user の VNC xstartup を準備' \
    'mkdir -p /home/user/.vnc' \
    'printf "%s\n" "#!/bin/bash" "unset SESSION_MANAGER" "unset DBUS_SESSION_BUS_ADDRESS" "exec dbus-launch --exit-with-session startxfce4" > /home/user/.vnc/xstartup' \
    'chmod +x /home/user/.vnc/xstartup' \
    'chown -R user:user /home/user/.vnc' \
    '# /work を user が書き込めるように' \
    'chown user:user /work' \
    '# VNC と code-server を user として起動' \
    'su - user -c "vncserver :1 -geometry 1920x1080 -depth 24 -SecurityTypes None" &' \
    'sleep 2' \
    'websockify --web /usr/share/novnc 6080 localhost:5901 &' \
    'jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root --NotebookApp.token="" --NotebookApp.password="" --notebook-dir=/work &' \
    'su - user -c "PASSWORD=${PASSWORD} code-server --bind-addr 0.0.0.0:8081 --auth password /work" &' \
    'su - user -c "filebrowser --database /etc/filebrowser.db" &' \
    'wait' \
    > /usr/local/bin/entrypoint.sh && chmod +x /usr/local/bin/entrypoint.sh

CMD ["/usr/local/bin/entrypoint.sh"]

docker-compose.yml

Tenstorrentのデバイスは/dev/tenstorrentからアクセス可能であるからして、これをDockerコンテナから透過的に扱えるよう設定すればDocker上のMetalium環境からプログラムを実行できるようになります。

./tt-metal-container/docker-compose.yml

services:
  tt-metal-dev:
    image: localhost/tt-metal-webtop:latest
    build: .
    container_name: tt_shared_workspace
    privileged: true      # 物理デバイスへの全アクセス権
    ipc: host             # 【必須】ホストの共有メモリ空間を共有
    network_mode: host
    devices:
      - /dev/tenstorrent:/dev/tenstorrent
    ulimits:
      stack: 67108864     # スタックサイズ拡張（念のため）
    volumes:
      - /dev/hugepages-1G:/dev/hugepages-1G
      - ./share:/work:Z
    environment:
      - ARCH_NAME=blackhole  # デフォルトでBlackholeとして動作させる
    # network_mode: host のためポートマッピング不要
    # SSH接続: ssh -p 2222 user@<ホストIP>  パスワード: BlackHole
    restart: unless-stopped

ビルド

コンテナのビルド

ビルドしてコンテナに入ります。

$ docker compose build
podman-compose version: 1.0.6
['podman', '--version', '']
using podman version: 4.9.3
podman build -f ./Dockerfile -t localhost/tt-metal-webtop:latest --ulimit stack=67108864 .
...

$ docker compose -d up
$ docker exec -it tt_shared_workspace bash

/work# 

Metaliumのビルド

推奨のツールを利用してスクリプトでビルドすることもできますし、Cmakeとninjaを自分で叩いてフラグとかコンパイラを手動指定してビルドすることもできます。

スクリプト

./install_dependencies.sh
./build_metal.sh --build-programming-examples 

手動

cmake -B build -S . -DCMAKE_CXX_COMPILER=g++
cd build
ninja
ninja install

clang++でもg++でもビルドできますが、コンパイラはC++20に準拠していなければなりません。

Programming-examplesでのテスト

ここではDRAM Loopbackを試します。

./build_Release/programming_examples/metal_example_loopback

Test Passedと表示されれば成功です。

..
2026-06-12 00:55:11.329 | info     |           Metal | DPRINT Server attached device 0 (dprint_server.cpp:1103)
2026-06-12 00:55:11.488 | info     |           Metal | DPRINT: dispatch DRAM aggregation running on device 0 (dprint_server.cpp:648)
Test Passed
2026-06-12 00:55:11.495 | info     |    BuildKernels | JIT cache stats: 17/17 hits (100.0%) [17 cached, 0 build-once dedup, 0 merged artifacts, 0 merged genfiles] (build_cache_telemetry.cpp:207)
2026-06-12 00:55:11.495 | info     |    BuildKernels | JIT telemetry: 3 registered TelemetryTokens (build_cache_telemetry.cpp:230)
...

次回

カスタムカーネルの記述その1を予定しています。