Skip to content

Komorebi 0.1.0

The first release of Komorebi: a programming model for the Tensix grid and the X280 cores of a Tenstorrent Blackhole card, with its framework, its device headers and its dispatcher. It is early development software, tested on one card.

The packages

Distribution Version Imported as What it carries
komorebi-tt 0.1.0 komorebi the framework and the kmr command; the device and ABI headers; the dispatcher's sources and its image for X280 cluster 0, prebuilt; the native host module, prebuilt for komorebi-runtime
komorebi-runtime 0.81.1.3 komorebi_runtime tt-metal v0.81.1 with our patches, built with its X280 runtime: the libraries, the kernel runtime tree the cores' compiler uses, the X280 runtime pieces, the program that prepares a card's X280 memory, and a locator

pip install "komorebi-tt[runtime]" installs both and numpy; neither ttnn nor torch is needed. kmr setup then fetches the cores' compiler and prepares the card's X280 memory, once. The steps, and how to get the examples and the tutorial's programs, which the wheels do not carry, are on the install page. Running from a clone against a tt-metal tree of your own works as before (from a clone).

What it contains

Grouped as the four concerns of the model (README):

  • Computation. A program is a set of persistent kernels on every Tensix core, with a reader, a compute and a writer loop. Each command names a handler and a core group; several groups are in flight at once, each with its completion and a result word. The cores' waits are timed (the exceptions are under known not to work), and an error names the core it came from.
  • Communication. Cores read and write DRAM, and send each other data through channels: emit, arrive and take, reduces by owner and by tree, broadcasts along a row or a column. Routed messages go to a core chosen at run time, through per-core queues in DRAM. Both data-movement CPUs of a core can carry one stream under a pattern (km::Movement, km::move).
  • Code placement. The same kernels are loaded on every core in advance, compiled into one resident image per program (Session(kernel_bytes=...) sets its size), with an instruction check and an optimisation level per kernel.
  • Execution control. A dispatcher on X280 cluster 0 takes commands from the host ring and runs micro-op streams and graphs on the card. C threads on X280 clusters 1 to 3 (kmx_parallel, kmx_spawn and kmx_join, regions, kmx_parallel_all over twelve cores, kmx_push across banks) run the irregular part of a program and submit commands themselves.

The host side is the komorebi package: Program, Session and Run, uploads and reads by page range, engine events, the stream and graph builders with their checks and CPU simulators, and kmr setup, kmr doctor, kmr build and kmr power. The tutorial teaches it in 42 lessons; eleven examples and five programs (a rasterizer, a ray tracer, matrix products, SwiGLU and attention) use it.

What the programs measured on the card, against Kohaku-TT on the same card and against CUDA on a V100, is the README's table (Measured), with the run behind every row on each program's page.

Experimental

  • Code loading. A core loading a kernel body into its own memory (overlay_probe) or into another core's (remote_load) works as an experiment. The framework does not offer it yet: a thread that carries its own code is not built.
  • The thread language. The manifest and the language a thread is written in are planned, not built (the programming model); komorebi.manifest and komorebi.lang hold no code.

Known not to work

  • Anything but one Blackhole P150A in slow dispatch; grids of up to 128 cores in at most two multicast panels, and one harvesting pattern has been run.
  • One thread per X280 work cluster, three at most; a cluster reads only its own DRAM bank.
  • One dynamic run at a time; no order between routed messages; a message cannot ask for a DRAM fetch.
  • At most 16 commands in flight, ten 32-bit argument words per command, handlers 1 to 239.
  • Reading back from the card runs at about 1 to 2 MB per second.
  • Some failures cost a card reset: a kernel that leaves a compute unit running, a packer that writes past its buffer, an X280 thread that never returns and polls nothing, a dispatcher whose loop has stopped. The compute kernel's waits between its own three threads and the NoC barriers have no timeout.
  • tt-metal's watcher cannot run while the X280 runtime is open.
  • kmr build host and kmr build pymodule need a tt-metal tree with the targets of the tt-x280-dispatch project (development).
  • Three examples are written for a clone and do not run from the wheels alone: 02_merge_tree/merge_fed.py, 03_broadcast and 05_forward.

The README's limitations give the details.

Supported setup

  • One Blackhole P150A, its kernel driver and firmware, the card's X280 memory prepared once; programs run in slow dispatch.
  • Linux on x86-64 with glibc 2.38 or later (the runtime wheel's tag, manylinux_2_38_x86_64).
  • Python 3.13.
  • tt-metal v0.81.1, the version in packaging/tt-metal.pin: inside komorebi-runtime, or a tree of your own built with the X280 runtime when running from a clone.