# tenstorrent/tt-isa-documentation architecture

> Architecture diagram of the GitHub repository tenstorrent/tt-isa-documentation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tenstorrent/tt-isa-documentation
- Repository: https://github.com/tenstorrent/tt-isa-documentation

## Overview

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.

Main entry points: [`WormholeB0/README.md`](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/README.md) (Wormhole README), [`BlackholeA0/README.md`](https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/README.md) (Blackhole README), [`WormholeB0/NoC/README.md`](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/NoC/README.md) (NoC), [`README.md`](https://github.com/tenstorrent/tt-isa-documentation/blob/main/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo_root["Repo Root"]
  node_root_readme["README<br/>atlas root<br/>[README.md]"]
  node_glossary["Glossary<br/>reference<br/>[Glossary.md]"]
  node_samples["Samples<br/>examples<br/>[README.md]"]
end

subgraph group_blackhole["BlackholeA0"]
  node_bh_readme["Blackhole README<br/>arch overview<br/>[README.md]"]
  node_bh_tensix["Tensix Tile<br/>compute tile<br/>[README.md]"]
  node_bh_baby(("BabyRISCV<br/>tile control core<br/>[README.md]"))
  node_bh_copro["Tensix Coprocessor<br/>execution engine"]
  node_bh_eth["Ethernet Tile<br/>network tile<br/>[README.md]"]
  node_bh_eth_baby(("BabyRISCV<br/>tile control core<br/>[README.md]"))
  node_bh_pcie["PCIe Tile<br/>host interface tile<br/>[README.md]"]
  node_bh_noc{{"NoC<br/>interconnect fabric<br/>[README.md]"}}
  node_bh_l2cpu["L2 CPU Tile<br/>auxiliary tile<br/>[README.md]"]
end

subgraph group_wormhole["WormholeB0"]
  node_wh_readme["Wormhole README<br/>arch overview<br/>[README.md]"]
  node_wh_tensix["Tensix Tile<br/>compute tile<br/>[README.md]"]
  node_wh_baby(("BabyRISCV<br/>tile control core<br/>[README.md]"))
  node_wh_copro["Tensix Coprocessor<br/>execution engine<br/>[README.md]"]
  node_wh_eth["Ethernet Tile<br/>network tile<br/>[README.md]"]
  node_wh_eth_baby(("BabyRISCV<br/>tile control core<br/>[README.md]"))
  node_wh_pcie["PCIe Tile<br/>host interface tile<br/>[README.md]"]
  node_wh_noc{{"NoC<br/>interconnect fabric<br/>[README.md]"}}
  node_wh_dram[("DRAM Tile<br/>memory tile<br/>[README.md]")]
  node_wh_arc["ARC Tile<br/>infra tile<br/>[README.md]"]
end

subgraph group_diagrams["Diagrams"]
  node_diagram_src["Diagram Src<br/>doc generator"]
  node_diagram_out["Diagram Out<br/>generated assets"]
end

node_root_readme -->|"documents"| node_bh_readme
node_root_readme -->|"documents"| node_wh_readme
node_root_readme -->|"defines terms"| node_glossary
node_root_readme -.->|"generates"| node_diagram_src
node_diagram_src -->|"renders"| node_diagram_out
node_bh_readme -->|"covers"| node_bh_tensix
node_bh_readme -->|"covers"| node_bh_eth
node_bh_readme -->|"covers"| node_bh_pcie
node_bh_readme -->|"binds"| node_bh_noc
node_bh_readme -.->|"includes"| node_bh_l2cpu
node_bh_tensix -->|"controls"| node_bh_baby
node_bh_tensix -->|"executes"| node_bh_copro
node_bh_tensix -->|"connects via"| node_bh_noc
node_bh_eth -->|"controls"| node_bh_eth_baby
node_bh_eth -->|"connects via"| node_bh_noc
node_bh_pcie -->|"connects via"| node_bh_noc
node_wh_readme -->|"covers"| node_wh_tensix
node_wh_readme -->|"covers"| node_wh_eth
node_wh_readme -->|"covers"| node_wh_pcie
node_wh_readme -->|"binds"| node_wh_noc
node_wh_readme -->|"extends to"| node_wh_dram
node_wh_readme -->|"extends to"| node_wh_arc
node_wh_tensix -->|"controls"| node_wh_baby
node_wh_tensix -->|"executes"| node_wh_copro
node_wh_tensix -->|"connects via"| node_wh_noc
node_wh_eth -->|"controls"| node_wh_eth_baby
node_wh_eth -->|"connects via"| node_wh_noc
node_wh_pcie -->|"connects via"| node_wh_noc
node_wh_dram -->|"serviced by"| node_wh_noc
node_wh_arc -.->|"reports via"| node_wh_noc

click node_root_readme "https://github.com/tenstorrent/tt-isa-documentation/blob/main/README.md"
click node_glossary "https://github.com/tenstorrent/tt-isa-documentation/blob/main/Glossary.md"
click node_samples "https://github.com/tenstorrent/tt-isa-documentation/blob/main/Miscellaneous/FMA/README.md"
click node_diagram_src "https://github.com/tenstorrent/tt-isa-documentation/tree/main/Diagrams/Src"
click node_diagram_out "https://github.com/tenstorrent/tt-isa-documentation/tree/main/Diagrams/Out"
click node_bh_readme "https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/README.md"
click node_bh_tensix "https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/TensixTile/README.md"
click node_bh_baby "https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/TensixTile/BabyRISCV/README.md"
click node_bh_copro "https://github.com/tenstorrent/tt-isa-documentation/tree/main/BlackholeA0/TensixTile/TensixCoprocessor"
click node_bh_eth "https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/EthernetTile/README.md"
click node_bh_eth_baby "https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/EthernetTile/BabyRISCV/README.md"
click node_bh_pcie "https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/PCIExpressTile/README.md"
click node_bh_noc "https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/NoC/README.md"
click node_bh_l2cpu "https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/L2CPUTile/README.md"
click node_wh_readme "https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/README.md"
click node_wh_tensix "https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/README.md"
click node_wh_baby "https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/BabyRISCV/README.md"
click node_wh_copro "https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/TensixCoprocessor/README.md"
click node_wh_eth "https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/EthernetTile/README.md"
click node_wh_eth_baby "https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/EthernetTile/BabyRISCV/README.md"
click node_wh_pcie "https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/PCIExpressTile/README.md"
click node_wh_noc "https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/NoC/README.md"
click node_wh_dram "https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/DRAMTile/README.md"
click node_wh_arc "https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/ARCTile/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_readme,node_glossary,node_samples toneBlue
class node_bh_readme,node_bh_tensix,node_bh_baby,node_bh_copro,node_bh_eth,node_bh_eth_baby,node_bh_pcie,node_bh_noc,node_bh_l2cpu toneAmber
class node_wh_readme,node_wh_tensix,node_wh_baby,node_wh_copro,node_wh_eth,node_wh_eth_baby,node_wh_pcie,node_wh_noc,node_wh_dram,node_wh_arc toneMint
class node_diagram_src,node_diagram_out toneRose
```

## Components

### Repo Root

Top-level documentation, glossary, and examples

- [README](https://github.com/tenstorrent/tt-isa-documentation/blob/main/README.md): atlas root · Repository entry point and documentation overview · `README.md`
- [Glossary](https://github.com/tenstorrent/tt-isa-documentation/blob/main/Glossary.md): reference · Shared terminology for interpreting the hardware docs · `Glossary.md`
- [Samples](https://github.com/tenstorrent/tt-isa-documentation/blob/main/Miscellaneous/FMA/README.md): examples · Small runnable examples that anchor the documentation · `Miscellaneous/FMA/README.md`

### BlackholeA0

Documentation subtree for the BlackholeA0 architecture family

- [Blackhole README](https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/README.md): arch overview · BlackholeA0 architecture landing page · `BlackholeA0/README.md`
- [Tensix Tile](https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/TensixTile/README.md): compute tile · Blackhole compute tile and local memory/control boundary · `BlackholeA0/TensixTile/README.md`
- [BabyRISCV](https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/TensixTile/BabyRISCV/README.md): tile control core · Tile-local firmware/control microcontroller inside Tensix · `BlackholeA0/TensixTile/BabyRISCV/README.md`
- [Tensix Coprocessor](https://github.com/tenstorrent/tt-isa-documentation/tree/main/BlackholeA0/TensixTile/TensixCoprocessor): execution engine · In-tile scalar/vector/matrix datapath and instruction set · `BlackholeA0/TensixTile/TensixCoprocessor`
- [Ethernet Tile](https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/EthernetTile/README.md): network tile · On-chip to Ethernet boundary and tile-local control plane · `BlackholeA0/EthernetTile/README.md`
- [BabyRISCV](https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/EthernetTile/BabyRISCV/README.md): tile control core · Ethernet tile control processor · `BlackholeA0/EthernetTile/BabyRISCV/README.md`
- [PCIe Tile](https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/PCIExpressTile/README.md): host interface tile · Host-to-device boundary and TLB/address translation docs · `BlackholeA0/PCIExpressTile/README.md`
- [NoC](https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/NoC/README.md): interconnect fabric · Routing and transport fabric connecting tiles and memory spaces · `BlackholeA0/NoC/README.md`
- [L2 CPU Tile](https://github.com/tenstorrent/tt-isa-documentation/blob/main/BlackholeA0/L2CPUTile/README.md): auxiliary tile · Additional Blackhole tile documentation for caches, memory map, and MSI/RNMI behavior · `BlackholeA0/L2CPUTile/README.md`

### WormholeB0

Documentation subtree for the WormholeB0 architecture family

- [Wormhole README](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/README.md): arch overview · WormholeB0 architecture landing page · `WormholeB0/README.md`
- [Tensix Tile](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/README.md): compute tile · Wormhole compute tile and local memory/control boundary · `WormholeB0/TensixTile/README.md`
- [BabyRISCV](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/BabyRISCV/README.md): tile control core · Tile-local firmware/control microcontroller inside Tensix · `WormholeB0/TensixTile/BabyRISCV/README.md`
- [Tensix Coprocessor](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/TensixCoprocessor/README.md): execution engine · In-tile scalar/vector/matrix datapath and instruction set · `WormholeB0/TensixTile/TensixCoprocessor/README.md`
- [Ethernet Tile](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/EthernetTile/README.md): network tile · Ethernet boundary plus embedded control plane · `WormholeB0/EthernetTile/README.md`
- [BabyRISCV](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/EthernetTile/BabyRISCV/README.md): tile control core · Ethernet tile control processor · `WormholeB0/EthernetTile/BabyRISCV/README.md`
- [PCIe Tile](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/PCIExpressTile/README.md): host interface tile · Host-facing translation and addressing boundary · `WormholeB0/PCIExpressTile/README.md`
- [NoC](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/NoC/README.md): interconnect fabric · Routing and transport fabric connecting tiles and memory spaces · `WormholeB0/NoC/README.md`
- [DRAM Tile](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/DRAMTile/README.md): memory tile · External memory access subsystem · `WormholeB0/DRAMTile/README.md`
- [ARC Tile](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/ARCTile/README.md): infra tile · Reset and telemetry-oriented infrastructure block · `WormholeB0/ARCTile/README.md`

### Diagrams

Lua sources and generated diagram outputs

- [Diagram Src](https://github.com/tenstorrent/tt-isa-documentation/tree/main/Diagrams/Src): doc generator · Lua sources that generate repository diagrams · `Diagrams/Src`
- [Diagram Out](https://github.com/tenstorrent/tt-isa-documentation/tree/main/Diagrams/Out): generated assets · Rendered diagram outputs · `Diagrams/Out`

## Connections

- README → Blackhole README: documents · Repository root links into the Blackhole documentation subtree
- README → Wormhole README: documents · Repository root links into the Wormhole documentation subtree
- README → Glossary: defines terms · Shared vocabulary used across the hardware docs
- README → Diagram Src: generates · Diagram sources describe the visualization pipeline
- Diagram Src → Diagram Out: renders · Lua sources produce generated diagram assets
- Blackhole README → Tensix Tile: covers · Blackhole architecture centers on the compute tile
- Blackhole README → Ethernet Tile: covers · Blackhole architecture includes the Ethernet tile boundary
- Blackhole README → PCIe Tile: covers · Blackhole architecture includes the PCIe host boundary
- Blackhole README → NoC: binds · NoC is the shared transport fabric for the architecture
- Blackhole README → L2 CPU Tile: includes · Auxiliary tile documentation in the Blackhole subtree
- Tensix Tile → BabyRISCV: controls · BabyRISCV provides tile-local orchestration
- Tensix Tile → Tensix Coprocessor: executes · Tensix coprocessor is the main compute datapath
- Tensix Tile → NoC: connects via · Tile traffic enters and leaves through NoC
- Ethernet Tile → BabyRISCV: controls · Ethernet tile hosts a BabyRISCV control core
- Ethernet Tile → NoC: connects via · Ethernet traffic is bridged through the fabric
- PCIe Tile → NoC: connects via · Host traffic enters the chip through the fabric
- Wormhole README → Tensix Tile: covers · Wormhole architecture centers on the compute tile
- Wormhole README → Ethernet Tile: covers · Wormhole architecture includes the Ethernet tile boundary
- Wormhole README → PCIe Tile: covers · Wormhole architecture includes the PCIe host boundary
- Wormhole README → NoC: binds · NoC is the shared transport fabric for the architecture
- Wormhole README → DRAM Tile: extends to · Wormhole includes external memory infrastructure
- Wormhole README → ARC Tile: extends to · Wormhole includes reset and telemetry infrastructure
- Tensix Tile → BabyRISCV: controls · BabyRISCV provides tile-local orchestration
- Tensix Tile → Tensix Coprocessor: executes · Tensix coprocessor is the main compute datapath
- Tensix Tile → NoC: connects via · Tile traffic enters and leaves through NoC
- Ethernet Tile → BabyRISCV: controls · Ethernet tile hosts a BabyRISCV control core
- Ethernet Tile → NoC: connects via · Ethernet traffic is bridged through the fabric
- PCIe Tile → NoC: connects via · Host traffic enters the chip through the fabric
- DRAM Tile → NoC: serviced by · DRAM access is mediated through the interconnect
- ARC Tile → NoC: reports via · Infrastructure control/telemetry ties back into the fabric