tenstorrent/tt-isa-documentation

1. This repository is not an implementation repo; it is a documentation atlas for Tenstorrent hardware ISAs and low-level tile behavior. Its architectural purpose is to help software developers reason about the machine below TT-LLK and, by extension, how software interacts with hardware blocks.

2. The top-level split is by architecture family: WormholeB0/ and BlackholeA0/. Each family is a self-contained documentation subtree for a specific shipping product generation, and the README explicitly warns that behavior is similar but not interchangeable across families.

3. Within each architecture, the documentation is organized around hardware subsystems rather than software components. The main subsystems are tiles and fabric: TensixTile, EthernetTile, PCIExpressTile, NoC, and in Wormhole also DRAMTile and ARCTile. These are the primary nodes you would show in an architecture diagram.

4. TensixTile/ is the largest and most important subsystem. It documents the compute tile itself, including local memory (L1.md), control/debug plumbing, soft reset, PIC, and a detailed TensixCoprocessor/ section that breaks the compute pipeline into instruction classes and functional units.

5. The Tensix coprocessor documentation is the deepest microarchitecture layer in the repo. It covers the scalar/vector/matrix units, sync and semaphore primitives, DMA-related instructions, unpack/pack pipelines, and numerous floating-point and tensor operations. For a diagram, this is the “in-tile execution engine” boundary that consumes data from L1 and NoC and produces results back to L1 or outward.

6. Both architectures document a tiny embedded control processor called BabyRISCV/ inside tiles. This is the control plane for tile-local orchestration: instruction fetch/storage, mailboxes, PC buffers, debug interfaces, synchronization, and in Blackhole a push-instruction path. It is distinct from the Tensix compute datapath and should be drawn as the tile’s firmware/control microcontroller rather than a general host CPU.

7. EthernetTile/ documents network-facing tile behavior. In Blackhole it emphasizes RX classification and TX/RX paths plus a sample ethdump program; in Wormhole it adds baseline data movement services, cycle counters, and soft reset. This tile is the boundary between on-chip fabric and Ethernet traffic, and it also hosts a BabyRISCV control core.

8. PCIExpressTile/ documents the host interface boundary. Its key concern is translation and addressing, especially host-to-device TLBs/TLB behavior. In an architecture diagram, this is the ingress/egress path between the host system and the on-chip network/memory spaces.

9. NoC/ is the interconnect layer and should be drawn as the fabric binding all tiles together. The docs cover coordinates, routing paths, counters, atomics, interrupts, ordering/alignment, overlay behaviors, and memory maps. This is the main data-movement backbone connecting compute, network, PCIe, and memory tiles.

10. Wormhole’s DRAMTile/ and ARCTile/ expand the system boundary beyond compute and I/O. DRAMTile represents external memory access, while ARCTile appears to handle reset/telemetry responsibilities. These are lower-frequency infrastructure blocks compared with Tensix, but they matter for system-level data and control flow.

11. The docs are highly layered: each architecture has a coarse README, then tile-level READMEs, then unit/instruction-level markdown pages. That hierarchy itself reflects the intended diagram structure: system, tile, functional unit, instruction/primitive.

12. Diagrams/Src/ and Diagrams/Out/ are the visualization pipeline for the repo. The Lua sources suggest the diagrams are generated assets rather than hand-authored static images, so there is a separate documentation-to-graphic transformation step in the repository. The diagram sources are organized around shared drawing primitives plus architecture-specific modules like Tensix backend/frontend, NoC, and L1.

13. The repository also includes small executable examples under Samples/ and Miscellaneous/, such as Ethernet ethdump.c and an FMA example. These are not core architecture blocks, but they anchor the docs in concrete usage examples of the hardware behavior they describe.

14. Cross-cutting reference material includes Glossary.md, architecture-specific memory maps, and many unit-specific pages for synchronization, atomics, counters, and debug. These are the connective tissue that makes the tile/network diagrams interpretable from software.

15. Overall, the architecture of the repository is a documentation graph of a heterogeneous chip: compute tiles at the center, NoC as the transport layer, Ethernet and PCIe as external interfaces, DRAM/ARC as system infrastructure, and BabyRISCV/TensixCoprocessor as the two key intra-tile execution domains.