blackhole​-py

00What is this thing?

A reverse-engineered, dependency-free replacement for Tenstorrent's entire tt-metal software stack — written in Python, talking straight to the silicon.

Tenstorrent's Blackhole is an AI accelerator. A normal program reaches it through tt-metal: tens of thousands of lines of C++, an LLVM-based RISC-V toolchain, a kernel-mode driver, and a host runtime. blackhole-py throws all of that out and asks a harder question: what is the absolute minimum you need to make this chip compute?

The answer, built up commit by commit, is a stack of pure-Python layers. At the bottom it opens a character device and fires raw ioctls; at the top it lets you write a Tensix compute kernel in a Python DSL, assembles it to RISC-V machine code in-process, uploads the firmware over PCIe, and launches it across the whole chip. No C++. No external assembler. No tt-metal.

The layer cake (as it stands at HEAD)

01The one dependency it couldn't fake: tt-metal-deps

Even a "from scratch" project needs ground truth. tt-metal-deps is the carved-out skeleton of tt-metal that blackhole-py measured itself against — and eventually outgrew.

For most of the project, tt-metal-deps was the lifeline: a ~219 MB extraction of just the pieces of Tenstorrent's stack that the Python code genuinely couldn't reproduce — chiefly a real RISC-V toolchain and the header definitions that describe the hardware's mailboxes and memory map.

Three things mattered here. The include/ headers (dev_msgs.h and friends) define the host↔device contract — the exact byte layout of launch messages, go-signals and mailboxes the firmware reads. The toolchain/blackhole/*.ld linker scripts encode each core's memory map. And sfpi-toolchain/ was the actual compiler used while firmware was still C++.

The whole arc of the back half of the project is the story of shedding this dependency. The setup script marched through tt-metal-deps v0.7.0 → v0.8.0, and then on Apr 21 came the line that changed everything: "…no more tt-metal-deps. not functional". Once the Python assembler could emit RISC-V directly, the GCC toolchain became dead weight. The headers' knowledge got absorbed into ttk/addrs.py and ttk/_cfg_regs.py. Today tt-metal-deps survives only in the old snapshot next door — kept around as an oracle to diff against, not a thing the live code needs.

02The shape of the code over time

Python LOC tracked at ten checkpoints. The story isn't a line going up — it's a mountain. The codebase grew to almost 19k lines, then the author deleted more than half of it.

LOC counted as raw wc -l across all .py files present at each commit (includes emulator & tests at the peak). Directional, not exact.

03Eight phases of bring-up

Reading the commit log front to back, the project moves through distinct epochs — each one a layer of the stack coming alive, breaking, and getting rebuilt.

04The commit that defines the project

Every from-scratch project has a moment of conviction. For blackhole-py it's d463403.

// firmware/cq/cq_prefetch.cpp — 1608 lines
// compiled with riscv-tt-elf-g++,
// linked against firmware_brisc.ld,
// from tt-metal-deps/

from dsl import TTPACR, TTUNPACR, jal, sw
class Asm(Tensix, Noc, Cb, Flow, Debug):
  def emit(self, *insns): ...
# asm.py: labels, fixups, segments
# every instruction → 4 little-endian bytes

05How the assembler actually works

The crown jewel: ~1,400 lines of Python replacing an entire LLVM/GCC RISC-V toolchain.

dsl.py (566 LOC) is a metaclass-driven instruction encoder. Each RISC-V format — RType, IType, SType, BType, UType, JType — is a class whose fields are BitField descriptors that pack/sign-extend into a 32-bit word. On top of the base ISA sit the Tensix custom ops the matrix engine speaks: TTUNPACR (unpack), TTPACR (pack), TTSFPLOADI (vector-engine load-immediate), TTSEMWAIT, TTZEROACC, and dozens more — each one a bitfield struct that emits a single instruction word.

class BitField:
  def encode(self, val): # pack into [hi:lo], sign-extend if signed
class SType(Inst):       # split immediate: imm[11:5] | imm[4:0]
  def imm(self): return _sext((self.imm11_5 << 5) | self.imm4_0, 12)
class JType(Inst):       # the gnarly scrambled jump immediate
  def imm(self): return _sext((self.imm20<<20)|(self.imm19_12<<12)|(self.imm11<<11)|(self.imm10_1<<1), 21)

asm.py (469 LOC) is the assembler proper. The Asm class inherits from five ttk mixins — Tensix, Noc, Cb, Flow, Debug — so a kernel author writes self.write32(addr, val), self.delay_cycles(n), self.cb_wait_front(...) instead of raw instructions. It tracks register constants for peephole optimization (_reg_const, _const_delta), resolves label()/Fixup references in a second pass, and emits raw bytes. program.py (407 LOC) handles ELF-like ptload segments, dtypes and tile sizes.

The result is that examples/add1.py — the canonical kernel — is written entirely in this DSL: MOP (macro-op) expander templates of TTPACR/TTUNPACR/TTNOP slots, semaphore handshakes between TRISC cores, and circular-buffer bookkeeping, all in Python that compiles to machine code with no external tool in the loop.

06The commit log as a diary

339 messages, one author, no filter. The log reads like a lab notebook — triumph, defeat, and dry self-awareness, often in the same line.

07Where it stands at HEAD

6afb021 · May 30, 2026 · ~8,079 lines of Python across 23 files.