Komorebi
Move the data, move the thread, or move the code.
A programming model for a network of independently programmable processors, in which a thread reads what it needs or goes to where it is. Today it runs on the Tensix grid and the X280 cores of a Tenstorrent Blackhole card.
Komorebi explores how to program a network of independently programmable processors, where computation, communication, code placement and execution control are all the program's own concern. It sees a program as threads, and a thread meets its data in one of two ways:
- The data comes to the thread. A processor reads what it needs from shared memory, or receives it from other processors.
- The thread goes to the data. A message carries a thread's state to the processor that holds what it needs next, and that processor is chosen while the program runs, from the data.
A thread needs its code where it arrives: placed there in advance, or loaded when it is needed. Nothing in this asks for one particular chip. It asks for processors with their own memory and a network on which any of them can reach any other, so other grids of this kind, and several cards joined together, fit the same description. None of those has been tried.
On a Blackhole card, today
This repository is the model built for one machine, a Tenstorrent Blackhole card (developed on a P150A): 120 Tensix cores in a grid, 16 X280 cores in four clusters, and the card's network between them.
| Concern | On the card |
|---|---|
| Computation | A program is a set of persistent kernels on every Tensix core. Each command they receive names a handler of code and a core group, and every core of the group works on its partition. |
| Communication | Cores read and write DRAM, and send each other data through ports, reduces and broadcasts. A routed message goes to a core chosen at run time. Both data-movement CPUs of a core can carry one stream (Movement). |
| Code placement | The same kernels are loaded on every core in advance. A core loading a kernel body into itself (overlay_probe) or into another core (remote_load) works as an experiment; a thread that carries its own code is not built yet. |
| Execution control | A dispatcher on one X280 cluster submits the commands and runs streams and graphs of them on the card. C threads on the other three X280 clusters run the irregular part of a program. |
Status: early development; 0.1.0 is a first release, for one card model. Everything below runs on one P150A, from the two wheels on PyPI or from a clone against a tt-metal source tree. It has run on no other hardware.
At a glance
One P150A, 2026-11-13 and 2026-11-14; every number is a row of Measured, from the program's page and its committed results.
| Program | Shape | Komorebi | Reference | Reference / Komorebi |
|---|---|---|---|---|
| Matrix product | 128 x 896 x 128 | 6.0 µs | Kohaku-TT, same card: 28.7 µs | 4.75 |
| Matrix product | 8192 cubed | 8608.3 µs | Kohaku-TT, same card: 11797.6 µs | 1.37 |
| Matrix product | 16,384 cubed | 87944.5 µs | Kohaku-TT, same card: 75522.5 µs | 0.86 |
| SwiGLU | 256 x 256 x 512 | 42.6 µs | Kohaku-TT, same card: 181.6 µs | 4.26 |
| SwiGLU | 16,384 x 384 x 384 | 161.7 µs | Kohaku-TT, same card: 458.1 µs | 2.83 |
| Attention | 2 x 8 x 1024 x 128, 2 K / V heads | 149.9 µs | Kohaku-TT, same card: 261.8 µs | 1.75 |
| Attention | 1 x 8 x 1024 x 64, causal | 58.1 µs | Kohaku-TT, same card: 53.7 µs | 0.92 |
| Rasterizer, whole frame | 10^6 triangles, 1024 x 1024 | 6.34 ms | CUDA on a V100: 4.42 ms | 0.70 |
| Ray tracer, whole frame | Sponza close, 1024 x 1024 | 359.86 ms | CUDA on a V100: 102.00 ms | 0.28 |
Above 1, Komorebi takes less time. The neural workloads are on parallel with or ahead of Kohaku-TT on most shapes; the rasterizer and the ray tracer run whole frames on the card, bit-exact against numpy, today at 0.4 to 0.9 of the V100's speed from 10^5 triangles up (the rasterizer) and a third or less (the ray tracer).
A kernel
A kernel is loaded once on its core and stays there: run calls the function below for
every command the core receives, and the command's handler says which piece of work it
asks for. Two kernels show how cores talk to each other. A core's two data-movement
CPUs run the roles of the easy layout, the reader and the writer; they are roles, not
"the CPU that reads" and "the CPU that writes": either CPU can read, write and send to
other cores. What differs is the NoC each uses, that a circular buffer has one CPU
filling it and the other draining it, and that the writer reports the command.
A reader kernel that broadcasts along a row. The host lays the rows out, and each core finds its place in its row in its own arguments. One core of the row reads a block from DRAM and sends it to the whole row in one multicast; the others wait for it in L1 (reduced from 03_broadcast):
// Reader kernel: one core of each row reads blocks from DRAM and broadcasts them along
// the row; the other cores of the row wait for them.
void kernel_main() {
constexpr auto row_args = TensorAccessorArgs<0>();
km::Reader reader; // stays loaded; runs once per command
reader.run([&](const km_command_t& command) {
if (km::handler(command) != kHandlerBroadcast) {
return;
}
// The command's arguments, each read once: where the row is, how many blocks.
const uint32_t row_address = command.a0;
const uint32_t blocks = command.a3;
// This core's row, and whether it sends or receives, from its own arguments.
km::Broadcast broadcast(reader, command, kArgBroadcast);
const auto row_source = TensorAccessor(row_args, row_address);
for (uint32_t block = 0; block < blocks; block++) {
if (!broadcast.sender()) {
broadcast.arrive(block); // wait until the block is in my L1
continue;
}
const uint32_t address = broadcast.reserve(block);
noc_async_read_page(block, row_source, address);
broadcast.cast(block); // one multicast to the whole row
}
broadcast.finish();
});
}
A compute kernel whose messages choose their next core at run time. Every core first
sends its own messages, then handles whatever arrives: a message is either finished
here or forwarded to the core it names (reduced from
05_forward; visit stands for the
program's own work on a message):
// Compute kernel: messages that choose their next core at run time.
void kernel_main() {
km::Compute compute;
compute.run([&](const km_command_t& command) {
km::Messages messages(compute, command); // routed messages for this command
uint32_t message[kMessageWords] = {};
if (messages.seeding()) { // first, every core sends its own
messages.send(messages.rank(), message);
messages.seeded();
}
while (km::Packet packet = messages.next()) { // then handle whatever arrives
for (uint32_t index = 0; index < packet.count; index++) {
const uint32_t next_core = visit(packet[index], message);
if (next_core == kFinished) {
messages.consume(); // the message ends here
} else {
messages.forward(next_core, message);
}
}
messages.done(packet);
}
});
}
A third kind of kernel only computes. The merge-tree example adds up a job's input tiles over a core group, the parts meeting at one owner or along a tree (02_merge_tree/kernels/compute.cpp).
For that example the host declares the program (program() in
merge.py: the three kernels, three circular buffers,
the handler header) and submits one MERGE command per job to its group (launch(),
lines 110 to 114 and 130 to 136):
run = session.load(
program(args, inputs[0], out),
deadline=args.deadline if stall < 0 else 4 * args.wait,
wait=args.wait,
)
# ... the command words of job `job` (lines 115 to 129)
group = (first, count)
handles.append(run.submit("merge", group, words, exclusive=True, result=True))
log(f"{run.drain(timeout=30.0)} events")
host_seconds = time.perf_counter() - start
run.stop()
It checks every total against numpy and prints one JSON line with ok: 1,000 jobs on
random groups, 0 wrong; 36.7 µs a job on 8 cores and 51.8 µs on 119, each command
returning a checksum of its total
(02_merge_tree).
The irregular part of a program is C on an X280 work cluster, where kmx_parallel runs a
function on the cluster's four cores (cores). A two-pass prefix sum over chunks of the
input, 2.48 ms for 262,144 words on four cores, exact against numpy
(08_parallel_thread/thread/parallel.c,
lines 160 to 215 without nothing, an empty function for timing kmx_parallel; the job
struct and the chunk helpers are above them):
/* (c) prefix, pass 1: each chunk's sum. */
static void sum_chunks(int core, void* arg) {
const job_t* job = (const job_t*)arg;
/* my chunks of CHUNK words: core, core + partitions, ... (partitions: the cores in
* use) */
for (
uint64_t chunk = first(job, core); chunk < chunks(job); chunk += job->partitions
) {
uint32_t total = 0;
for (uint64_t word = chunk * CHUNK; word < end(job, chunk); word++) {
total += job->input[word];
}
chunk_sums[chunk] = total;
}
}
/* Pass 2: output[word] = the chunk's base + the chunk's words before it. */
static void chunk_prefix(int core, void* arg) {
const job_t* job = (const job_t*)arg;
for (
uint64_t chunk = first(job, core); chunk < chunks(job); chunk += job->partitions
) {
uint32_t running_total = chunk_sums[chunk];
for (uint64_t word = chunk * CHUNK; word < end(job, chunk); word++) {
job->output[word] = running_total;
running_total += job->input[word];
}
(void)arg;
}
/* Runs `function` on core 0 alone or on all four; KMX_OK, or kmx_parallel's error. */
static int run_on_cores(void (*function)(int, void*), job_t* job) {
if (job->partitions == 1) {
function(0, job);
return KMX_OK;
}
return kmx_parallel(function, job);
}
/* The two-pass exclusive prefix sum (mod 2^32); between the passes core 0 turns the
* chunk sums into bases. */
static int prefix(job_t* job) {
const int error = run_on_cores(sum_chunks, job);
uint32_t base = 0;
for (uint64_t chunk = 0; chunk < chunks(job); chunk++) {
const uint32_t chunk_sum = chunk_sums[chunk];
chunk_sums[chunk] = base;
base += chunk_sum;
}
return error != KMX_OK ? error : run_on_cores(chunk_prefix, job);
}
The programming model
The card as Komorebi runs it
The grid is the card's real one in NoC0 coordinates; the numbers in the Tensix cores are Komorebi's core index. A command is one 64-byte line: the handler, the group (a contiguous range of cores, whose first core is its leader) and ten 32-bit argument words. Every core sees every command and skips those whose group does not hold it; cores report to the leader, which acknowledges to the dispatcher, with a result word when the command asks for one.
A thread has a program counter and a place
A breakpoint is a point where a thread must deal with another core; between two breakpoints it runs on its core. Today a program is written as the handler bodies of its kernels, as above; the thread language in the first column is planned:
| Planned thread language | What is sent | On the card today |
|---|---|---|
at X[i]: block |
the thread's state | a dynamic handler: the state as a 64-byte message, messages.forward (dynamic handlers, 05_forward) |
emit v -> thread(j) |
the value | km::emit into a fixed slot, reduce by owner or by tree (ports, 02_merge_tree) |
v = wait(n) |
nothing | km::arrive: a timed wait until n values have landed |
| a block to a row or a column | the block, once per broadcast | a broadcast (broadcasts, 03_broadcast) |
Groups and commands in time
Up to 16 commands are in flight at once. A command that must run after an earlier one
on overlapping cores is submitted with run.submit(..., exclusive=True).
One program on the grid
What exists
| Part | On main | Page | Example |
|---|---|---|---|
| Persistent kernel: commands, 16 mailbox slots per core, the reader, compute and writer loops, every wait with a timeout, the trace | implemented | Tensix runtime | 01_mapcollect |
| Groups per command, several in flight, completion per group, a result word per command | implemented | Tensix runtime | 01_mapcollect |
Channels: emit, arrive, take, groups, reduce by owner and by tree |
implemented | ports | 02_merge_tree |
| Channels: broadcast along a row or a column, two broadcasts at once | implemented | broadcasts | 03_broadcast |
| Routed messages: messages through per-core queues in DRAM, a send quota, the quiet end found by the dispatcher | implemented; one dynamic run at a time | dynamic handlers | 05_forward |
| The dispatcher on X280 cluster 0: host ring, slots, deadlines, events | implemented | dispatcher | all |
| Micro-op streams and the job queue in the dispatcher | implemented; builder, check and simulator on the CPU | streams | 04_uop_stream |
| Graphs in the dispatcher: command nodes, CPU-task nodes, joins, a kept graph run again | implemented; also host-fed | graphs | 06_graph |
X280 threads: kmx_parallel, kmx_spawn / kmx_join, regions, the command ring, a host fallback in Python; a thread on each of work clusters 1 to 3, regions shared on one bank; kmx_parallel_all over twelve cores and kmx_push across banks |
implemented | X280 threads | 07_work_cluster, 08_parallel_thread |
The host package: Program, Session, Run, uploads and engine events, reads by page range, errors that name the core |
implemented | host API | all |
Hardening: the kernel instruction check, an optimisation level per kernel, Session(kernel_bytes=...), an exit with a timeout |
implemented | host API | |
| The thread language; homes declared | planned | manifest, lang |
Measured
Whole programs on one P150A, every row from the program's page and its committed results, all dated 2026-11-13: AICLK 1,350 MHz nominal (the card lowers it under its power limit in the long matrix loops; each page gives the clock it sampled) and the X280 at the session's 1,000 MHz. Power is the whole card's mean over the loop.
Rasterizer and ray tracer: whole frames
Both programs run the whole frame on the card, 1024 x 1024, and both are far below half of a V100's speed today. The V100 and C++ columns are the reference's whole frame (the same algorithm in CUDA on one idle Tesla V100 32 GB, and in C++ on a shared 96-thread AMD EPYC 7K62); none of the three counts the scene's upload or the image's read-back.
The rasterizer: the passes and the counting run on the 120 cores, the serial rest of
the middle pass between them on a thread on the X280 work cluster; the image is bit-exact
against numpy. Median of 5 loads, each about 1 s of frames; card 1
(raster, results in
projects/raster/results/,
reference):
| Scene | Triangles | Frame | Card frame, ms | of which the X280 step | Card W | C++ 96 threads, ms | V100, ms | V100 / card |
|---|---|---|---|---|---|---|---|---|
| tiny | 398 | first | 0.987 | 0.436 | 61.9 | 2.66 | 0.29 | 0.29 |
| tiny | 398 | settled | 0.987 | 0.436 | 63.4 | 2.66 | 0.29 | 0.29 |
| 10^4 | 11,994 | first | 0.982 | 0.440 | 67.0 | 3.32 | 0.25 | 0.25 |
| 10^4 | 11,994 | settled | 0.952 | 0.453 | 65.8 | 3.32 | 0.25 | 0.26 |
| 10^5 | 102,308 | first | 2.050 | 0.753 | 68.0 | 4.08 | 0.79 | 0.39 |
| 10^5 | 102,308 | settled | 1.967 | 0.772 | 68.2 | 4.08 | 0.79 | 0.40 |
| 10^6 | 997,806 | first | 6.894 | 0.807 | 68.9 | 17.87 | 4.42 | 0.64 |
| 10^6 | 997,806 | settled | 6.339 | 0.823 | 70.2 | 17.87 | 4.42 | 0.70 |
| Sponza, overview | 262,266 | first | 5.770 | 0.457 | 68.8 | 7.88 | 2.31 | 0.40 |
| Sponza, overview | 262,266 | settled | 3.795 | 0.466 | 71.6 | 7.88 | 2.31 | 0.61 |
| Bistro interior, overview | 1,020,903 | first | 8.762 | 0.736 | 66.9 | 14.10 | 5.99 | 0.68 |
| Bistro interior, overview | 1,020,903 | settled | 6.503 | 0.753 | 69.4 | 14.10 | 5.99 | 0.92 |
"First" is a scene's first frame, with COUNT's and SETUP's ranges cut into equal parts: what a single image costs. "Settled" is a later frame of the same camera, whose ranges are cut by the frame before's predicted costs. Where the time goes (settled frame): at 10^6 FILL 2.1 ms, SETUP 1.9 ms, COUNT 1.1 ms and the X280 step 0.8 ms; on Bistro SETUP and FILL 2.1 ms each and COUNT 1.3 ms. The fill alone is ahead of the V100's fill stage (10^6: 2.1 against 3.3 ms; Bistro: 2.1 against 5.6 ms).
The ray tracer: ray generation, four traces and shading are eight commands on the 120 cores; trees larger than L1 are read from DRAM as treelets. Card 1. A cold frame has no history and is submitted by the host. A warm frame is the second or third of the same camera, submitted by a thread on the X280. Before each trace the thread cuts the rays into the cores' ranges by the frame before's costs; its plan time counts in the frame (raytrace):
| Scene | Frame | Card frame, ms | of which the X280 plan | Card W | C++ all threads, ms | V100, ms | V100 / card | Pixels differing from numpy |
|---|---|---|---|---|---|---|---|---|
| tiny (tree in L1) | cold and warm | 23.20 | - | 63.0 | 20.59 | 2.59 | 0.11 | 0 |
| 10^4 | cold | 57.91 | - | 63.0 | 26.44 | 4.16 | 0.07 | 0 |
| 10^4 | warm | 70.63 | 5.27 | 61.0 | 26.44 | 4.16 | 0.06 | 0 |
| 10^5 | cold | 81.51 | - | 63.0 | 35.47 | 6.57 | 0.08 | 0 |
| 10^5 | warm | 93.01 | 5.34 | 66.9 | 35.47 | 6.57 | 0.07 | 0 |
| 10^6 | cold | 154.21 | - | 63.0 | 53.66 | 11.61 | 0.08 | 1 |
| 10^6 | warm | 192.50 | 5.32 | 70.4 | 53.66 | 11.61 | 0.06 | 1 |
| Sponza, close | cold | 359.86 | - | 63.0 | 264.78 | 102.00 | 0.28 | 244 |
| Sponza, close | warm | 323.38 | 3.64 | 71.0 | 264.78 | 102.00 | 0.32 | 244 |
| Sponza, overview | cold | 348.53 | - | 69.2 | 230.36 | 95.52 | 0.27 | 234 |
| Sponza, overview | warm | 313.63 | 4.14 | 68.2 | 230.36 | 95.52 | 0.30 | 234 |
| Bistro interior, close | cold | 596.97 | - | 61.0 | 401.87 | 211.42 | 0.35 | 2 |
| Bistro interior, close | warm | 596.86 | 4.35 | 70.0 | 401.87 | 211.42 | 0.35 | 3 |
| Bistro interior, overview | cold | 523.72 | - | 73.1 | 336.80 | 153.94 | 0.29 | 2 |
| Bistro interior, overview | warm | 477.48 | 4.57 | 70.5 | 336.80 | 153.94 | 0.32 | 2 |
Where the time goes: the four traces take 67 % (10^4) to 97 % (Bistro) of the frame, the bounce trace alone 36 to 59 %; each core sorts its bounce and second-shadow rays (about 15 ms a frame) and reads the treelets its rays need from DRAM. In the traces, box tests on packets with few live broadcasts come first (61 % on Sponza's overview), then the wait for each command's slowest core. The differing pixels are ties between two triangles at the same float32 distance, but for one or two on each Bistro view. The plan by the frame before takes 35 to 46 ms off Sponza and Bistro's overview, nothing off Bistro's close view, and costs 12 to 38 ms on 10^4 to 10^6: it cuts the traces into up to 8 commands, and the cores read more treelets.
Read back from the card, 512 x 512 downscales of 1024 x 1024 frames. Top: rasterized, both bit-exact against numpy, Sponza overview (3.80 ms a settled frame above) and Bistro interior overview (6.50 ms). Bottom: ray traced, Sponza close (359.86 ms a frame above) and Bistro interior close (596.97 ms). Crytek Sponza, (c) 2010 Frank Meinl, Crytek, CC BY 3.0; Amazon Lumberyard Bistro, (c) 2017 Amazon Lumberyard, CC BY 4.0 (Open Research Content Archive); both from the McGuire Computer Graphics Archive.
Matrix product, attention and SwiGLU against Kohaku-TT
The same card, ours and Kohaku-TT (at ac81ff2) one after the other in one session; bf16 operands, fp32 accumulation; time per call in a loop of calls, uploads and read-back outside it. "Kohaku-TT / ours" above 1 means ours is faster. Ours was measured again on 2026-11-14 with the programs' own bench scripts (best of three runs); a row that moved by less than 3 % keeps its value of 2026-11-13, and Kohaku-TT's columns were not run again. Replaced: four matrix product rows, three attention rows and the one SwiGLU cell in its page that moved.
Matrix product, HiFi2, Kohaku-TT's fastest of its
three routes (results/<preset>-ours.json, -ktt-<route>.json):
| M x K x N | Ours, µs | W | Kohaku-TT, µs | W | Kohaku-TT / ours |
|---|---|---|---|---|---|
| 128 x 896 x 128 | 6.0 | 71 | 28.7 | 63 | 4.75 |
| 16,384 x 384 x 384 | 61.2 | 130 | 94.1 | 116 | 1.54 |
| 16,384 x 1024 x 1024 | 393.5 | 128 | 389.9 | 136 | 0.99 |
| 4096 cubed | 958.3 | 138 | 957.0 | 151 | 1.00 |
| 8192 cubed | 8608.3 | 141 | 11797.6 | 139 | 1.37 |
| 16,384 cubed | 87944.5 | 137 | 75522.5 | 142 | 0.86 |
| 32 x 4096 x 4096, K split | 92.4 | 83 | 81.0 | 91 | 0.88 |
From 4096 cubed up both sides are bound by the card's power limit in a loop (ours ran in a slower mode in most loops of 4096 and 8192 cubed on 2026-11-14, see the page; the table shows the fastest run); the last row is the K split of the page (14,1,16,5 tree, groups of 16 cores to an output block), bound by reading W from DRAM: 363 GB/s in the call against Kohaku-TT's 414.
Attention, K and V multicast down broadcasts of
cores, the same compute body as Kohaku-TT's flash kernel
(results/ours-<preset>.json, ktt-<preset>.json):
| B x H x S x D | Ours, µs | W | Kohaku-TT, µs | W | Kohaku-TT / ours |
|---|---|---|---|---|---|
| 1 x 32 x 4096 x 64 | 2675.3 | 138 | 2918.5 | 135 | 1.09 |
| 1 x 24 x 4096 x 128 | 2328.3 | 144 | 3001.8 | 132 | 1.29 |
| 8 x 16 x 256 x 64 | 76.7 | 123 | 80.7 | 110 | 1.05 |
| 1 x 8 x 1024 x 64, causal | 58.1 | 103 | 53.7 | 99 | 0.92 |
| 2 x 8 x 1024 x 128, 2 K / V heads | 149.9 | 136 | 261.8 | 105 | 1.75 |
The causal row is behind per call (58.1 against 53.7) and ahead per pass (48.3): the cost of a command.
SwiGLU, silu(x W1) * (x W3) then W2, HiFi2,
ours in its faster form (results/swiglu-<preset>-<form>-hifi2.json, -ktt-<route>.json):
| M x D x H | Ours, µs | W | Kohaku-TT, µs | W | Kohaku-TT / ours |
|---|---|---|---|---|---|
| 256 x 256 x 512 | 42.6 | 76 | 181.6 | 73 | 4.26 |
| 4096 x 256 x 512 | 73.7 | 114 | 183.5 | 95 | 2.49 |
| 16,384 x 256 x 512 | 180.2 | 137 | 542.1 | 109 | 3.01 |
| 16,384 x 384 x 384 | 161.7 | 142 | 458.1 | 108 | 2.83 |
The examples' own timings (commands per microsecond, broadcasts, forwards, streams, graphs and threads) are in each example's README.
Install
Komorebi 0.1.0 is on PyPI as two distributions, komorebi-tt (the framework) and
komorebi-runtime (the pinned tt-metal build), with the GitHub release v0.1.0. It is a
first release, for one card model, the Blackhole P150A. Komorebi is used from those
wheels (the two wheels) or from a clone
(packaging, from a wheel), on
Linux x86-64 with Python 3.13:
git clone <this repository> komorebi && cd komorebi
uv venv -p 3.13 && source .venv/bin/activate && uv pip install -e ".[dev]"
kmr doctor # the Python, the tt-metal tree and its X280 runtime
The CPU tests and the stream and graph tools need nothing else. To run on a card: a
Blackhole P150A whose X280 memory is prepared for the X280 runtime, a tt-metal source
tree at the version in packaging/tt-metal.pin (v0.81.1) built
with its X280 runtime, and TT_METAL_HOME naming that tree (neither ttnn nor
torch is needed). The dispatcher image and the native module are
built from the tree on first use (python -m komorebi.native builds them ahead).
Details: install.
The distribution is named komorebi-tt; the package is imported as komorebi and the
command is kmr. pip install "komorebi-tt[runtime]" installs it with
komorebi-runtime, the pinned tt-metal build, and a program runs on a card with no
tt-metal tree (the two wheels); kmr setup
prepares the card once.
Usage
Every example runs on its own, checks its output against numpy and prints one JSON
line with ok (examples); each program's page lists its
commands (projects):
cd examples/02_merge_tree
python merge.py --jobs 20 --count 8 --form both
python merge.py --group-list 0:8,0:119 --form both --stall-rank 3
cd ../..
python -m projects.raytrace.frame --scene tiny --reps 16
The second command adds a load in which rank 3 of job 1 never sends: the host raises
km.CommandTimeout naming the handle and the cores that did not report, and the next
load in the same session runs exact.
Repository map
src/komorebi/ the Python package: Program, Session, Run, layout, power, kmr
engines/ micro-op streams and graphs: builders, encodings, checks,
simulators; the host-fed executor
thread.py X280 threads: declaration, regions, results, host fallback
manifest/ lang/ reserved: homes and handlers declared; the thread language
src/komorebi_native/
include/komorebi/abi/ the command, the event and the stream format, shared by all
include/komorebi/device/ the persistent kernel, groups, ports, groups, broadcasts, dynamic
handlers, the trace
kernels/ the generic reader and writer of dynamic handlers
x280/kernel/ the dispatcher for X280 cluster 0
x280/engines/ x280/kmx/ the plain-C graph engine; the X280 thread library
csrc/host/ the native module: X280 runtime, commands, events
examples/ 01_mapcollect to 08_parallel_thread
projects/ raster, raytrace, dense (with SwiGLU), attention
experiments/ hardware and design probes (see its README)
reference/ CPU, C++ and CUDA references the programs are checked against
tests/core/ tests/projects/ tests with no card: the framework; the programs
tests/hardware/ card tests (KMR_CARD=1)
docs/ concepts, references, install, development
Limitations
- One Blackhole P150A, in slow dispatch. Grids of up to 128 cores in at most two multicast panels; one harvesting pattern has been run.
- One thread per X280 work cluster, three at most. A cluster reads only its own DRAM
bank (6 for cluster 1, 7 for clusters 2 and 3); data for the other bank is pushed
(
kmx_push), so twelve cores gain over four only where the work computes more than it moves. - Dynamic handlers: one dynamic run at a time; messages travel through queues in DRAM, also to a core's own queue; a message cannot ask for a DRAM fetch; no order between messages (dynamic handlers).
- 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
(
Session.read_chunksreads in 2 MB chunks with a line per chunk); a rendered frame of 20 MB takes 10 to 18 s to read back. - The X280 runs at 1,000 MHz by default: at the 1,750 MHz opt-in the dispatcher trapped in 9 of 18 runs under full matrix load (the card lowers its core voltage), and in 0 of 23 at 1,000 MHz. One PLL clocks all four clusters.
- A stuck RISC thread is recovered by the next device open. A kernel that leaves a compute unit running, a packer that writes past its buffer, an X280 thread that never returns and polls nothing, or a dispatcher whose loop has stopped costs a card reset. 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; debugging is by the cores' state words, "where" codes and the per-core trace, read after the stop.
kmr build hostandkmr build pymoduletake their compile flags from two targets that the tt-x280-dispatch project adds to a tt-metal build (development).
Roadmap
Planned, in order:
- The rasterizer and the ray tracer faster on the card, where their pages say the time goes.
- The manifest and the thread language.
Documentation
| Page | Read it for |
|---|---|
| docs index | every concept and reference page |
| the thread language (planned) | threads, breakpoints, homes, space and time |
| Tensix runtime | the device headers, the command, timed waits, the control block |
| ports, broadcasts, dynamic handlers | messages between cores |
| streams, graphs | deciding on the card in the dispatcher |
| X280 threads | C on a work cluster with kmx |
| host API | Program, Session, Run, errors, builds |
| examples, projects | runnable examples; the five programs and their results |
| install, development | building from a clone; layout, checks, conventions |
Contributing
Open an issue first for a feature. Before a pull request, from the repository in the environment of install:
python -m pytest tests/core
python -m pytest tests/projects
python -m komorebi.tools.cxx_format --check
python -m komorebi.tools.comment_lint --check src tests examples experiments packaging tutorial projects
ruff check . && black --check . && blacken-docs -t py313 -l 88 $(git ls-files '*.md')
Conventions: development.
Licence
Apache-2.0; see LICENSE.
Metadata
Release files for komorebi-tt 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| komorebi_tt-0.1.0-cp312-abi3-manylinux_2_32_x86_64.whl | CPython 3.12 | abi3 | Linux glibc 2.32+ x86-64 | Details for komorebi_tt-0.1.0-cp312-abi3-manylinux_2_32_x86_64.whl |
Release files / komorebi_tt-0.1.0-cp312-abi3-manylinux_2_32_x86_64.whl
| Download URL | komorebi_tt-0.1.0-cp312-abi3-manylinux_2_32_x86_64.whl |
|---|---|
| Size | 706.8 kB |
| Tags | CPython 3.12 Linux glibc 2.32+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
bb0061860f1c320a7f152a903b4344103e51ad43bf1b468b30a18ca5134f8771
|
|
BLAKE2b-256 checksum How to use checksums |
e4762fac3763902e19b47954a7c95447dd2ad6ef491beed1988bab0165beba7d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for komorebi-tt 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
1 file in this release has been uploaded with provenance metadata.
Attestation for komorebi_tt-0.1.0-cp312-abi3-manylinux_2_32_x86_64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.