Komorebi tutorial

This tutorial takes you from nothing to a program of your own that runs on a Tenstorrent Blackhole card. It assumes you know C++ and Python. It does not assume you have ever written a kernel for a card like this one.

Every lesson teaches one thing, shows a complete program that uses it, and shows what that program printed when it ran on a card. A word is explained in the lesson where it first appears; no lesson uses a word that an earlier lesson did not explain.

Start with lesson 1, What Komorebi is. Each lesson ends with a link to the next one.

Part 1. One core

You end this part able to run your own code on a core of the card and get a number back.

Lesson	What it teaches
1. What Komorebi is	a whole small program, shown and run but not yet explained, and the list of lessons
2. Setup and the first run	checking the machine with kmr doctor and running the first program
3. The card	the parts of the card that the next lessons use: Tensix cores, L1, DRAM, the network
4. Hello, core	the smallest program, taken apart line by line: one kernel file per role, one Python file, one command
5. Commands	what a command is, who sends it, and that the kernels stay loaded between commands
6. A result	one number from the core back to Python
7. Arguments	numbers from Python into the kernel
8. Handlers	two pieces of work in one kernel, chosen by the command
9. Many commands	submitting several commands and waiting for all of them
10. When it goes wrong	a command that does not finish: the two time limits and what the card reports

Part 2. Many cores

You end this part able to run one program on many cores and give each its share of the work.

Lesson	What it teaches
11. A core group	the same command on several cores, and each core's rank
12. Partitions	splitting a range of work by rank
13. The leader	the core that reports for the whole group, and the one result a group gives
14. Placing groups	choosing the cores of a group: a row, two rows, a panel, a rectangle

Part 3. Data

You end this part able to move tensors between DRAM and the cores and compute on tiles.

Lesson	What it teaches
15. Tiles and tensors	the 32 x 32 tile, and a tensor: an array of numbers kept in the card's DRAM
16. Reading from DRAM	a core copies one tile from DRAM into its own L1
17. Writing to DRAM	a core writes a tile from its L1 to a tensor in DRAM: the first program that changes data
18. The three kernels	the two data-movement kernels as two loops that run at the same time
19. Circular buffers	a buffer of several pages: a queue in L1 that lets the filling kernel run ahead of the draining one
20. Computing on a tile	the compute kernel: unpack two tiles, add them, pack the sum
21. The matrix unit	replacing the addition by a product of two tiles, on the unit the card is built around
22. A whole map	read, compute and write over a core group: every core maps its share of the tiles
23. Both movers	both data-movement CPUs of a core carry one stream: a pattern deals its blocks between them

Part 4. Cores talking to cores

You end this part able to send data between cores without going through DRAM.

Lesson	What it teaches
24. Why cores talk	each core's L1 is its own; sending data between cores, and the lessons of Part 4
25. A port	one core sends a tile into the L1 of one other core, and the receiver waits for it at a port
26. Reduce	many cores send a tile to one core, which adds them: by an owner, and along a tree
27. Broadcast	one core sends each of a series of tiles to the whole row of cores with one write
28. A routed message	send: a message to a core that the data chooses while the program runs
29. Forward and consume	a message that visits several cores, one after the other, until it ends
30. Full buffers	what stops a sender when the receiver is busy, and the quota of messages in a dynamic run
31. Streams and graphs	a chain of commands described once, with dependencies and a loop that ends on a value from the cores

Part 5. X280 threads

You end this part able to write C code that runs on the card's X280 cores and drives the Tensix cores.

Lesson	What it teaches
32. Hello, thread	C code on an X280 core, started from Python: add two numbers and return the sum
33. A thread that submits	the thread sends a command to the Tensix cores, waits for its event, and uses the result word
34. Four cores	one function run on all four cores of an X280 cluster, and a sum that comes out four times faster
35. Sharing memory	regions: Python gives the thread an array, the thread writes another, and Python reads it after the run
36. Twelve cores	the same thread on three clusters: kmx_parallel_all runs one function on all twelve X280 cores
37. A core asks the X280	an X280 port: a Tensix core asks its X280 core a question, the thread answers, and the core tells the answer back

Part 6. Practice

You end this part able to measure, debug and design a program of your own.

Lesson	What it teaches
38. Measuring	the card's clock and the host's clock, why they differ, and how to read many runs of one command
39. Finding a bug	reading the card's report of a command that did not finish: which cores, which kernel, waiting for what
40. A whole program	the sum of 48 tiles, from numpy to a check in numpy: every part of a Komorebi program, in order, in one program
41. Your own kernel	changing a working program by one thing at a time, with the answer worked out in numpy first
42. Every primitive	a look-up list of every call this tutorial used, in the three places a program runs, each with the lesson that explains it