wolfpine 2.1__tar.gz

wolfpine-2.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Nick Brown
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

wolfpine-2.1/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: wolfpine
+Version: 2.1
+Summary: A framework for simulating AI accelerators, with Tenstorrent Wormhole and Blackhole backends
+Author: Nick Brown
+License-Expression: BSD-3-Clause
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pyyaml
+Requires-Dist: pynng
+Requires-Dist: flatbuffers
+Requires-Dist: pyarrow
+Requires-Dist: pyelftools
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# Wolfpine
+
+**A framework for simulating AI accelerators, in pure Python.**
+
+Wolfpine is a hackable software framework for building cycle-approximate
+simulators of AI accelerator hardware. The core — the memory map, the
+interconnect, the RISC-V cores, the clock and reset fabric, the cost and
+trace machinery — is architecture-agnostic; a target is described by an
+*architecture profile* plus a thin device class, not by a fork.
+
+The framework ships with backends for the Tenstorrent architecture,
+**Wormhole** and **Blackhole**, built from the public
+[Tenstorrent ISA Documentation](https://github.com/tenstorrent/tt-isa-documentation/tree/main).
+Both run real tt-metal programs unmodified, on the full default worker grid —
+72 workers on Wormhole, 130 on Blackhole. Note that it is not cycle accurate
+(or intended to be). The idea was to build a simulator from public
+documentation, so developers can experiment with writing accelerator code
+without needing physical hardware — and, because it is Python all the way
+down, poke at simulator state directly from a driver script.
+
+## Contents
+
+- [Installation](#installation)
+- [Using Wolfpine as a simulator for tt-metal](#using-wolfpine-as-a-simulator-for-tt-metal)
+- [Repository overview](#repository-overview)
+- [What the timing model claims, and what it does not](#what-the-timing-model-claims-and-what-it-does-not)
+- [Key parts of the simulator](#key-parts-of-the-simulator)
+
+Profiling a kernel: [`driver/wormhole/docs/profiling.md`](driver/wormhole/docs/profiling.md)
+walks through every output the simulator can produce.
+Building tooling on those outputs: [`docs/trace-schema.md`](docs/trace-schema.md)
+is the stable, versioned schema — field meanings, units and what you may
+rely on.
+
+## Installation
+
+Wolfpine is pure Python and requires Python ≥ 3.10. Clone the repository and install it in
+editable mode, which pulls in its dependencies (numpy, pyyaml, pynng, flatbuffers,
+pyarrow, pyelftools):
+
+```bash
+git clone https://github.com/hedgehope/wolfpine.git
+cd wolfpine
+pip install -e .           # add [dev] for the ruff + pytest tooling: pip install -e .[dev]
+```
+
+This installs the `framework` simulator library. The example drivers live under `driver/`
+and are run from the repository root, so keep the repo root on your `PYTHONPATH` when
+invoking them directly (the tt-metal flow below wires this up for you automatically):
+
+```bash
+export PYTHONPATH=$PWD:$PYTHONPATH
+```
+
+## Using Wolfpine as a simulator for tt-metal
+
+tt-metal's UMD has a "simulation" chip backend: point `TT_METAL_SIMULATOR` at the
+[`driver/wormhole`](driver/wormhole) directory and UMD launches Wolfpine in place of real
+silicon, so an ordinary tt-metal program runs against the simulator over a socket — no
+code changes, exactly as it would run on hardware. The minimal setup:
+
+```bash
+export TT_METAL_RUNTIME_ROOT=/path/to/tt-metal          # your built tt-metal checkout
+export TT_METAL_SIMULATOR="$PWD/driver/wormhole"        # the switch: route execution to Wolfpine
+export TT_METAL_SLOW_DISPATCH_MODE=1                    # the only launch path the sim models
+export LD_LIBRARY_PATH="$TT_METAL_RUNTIME_ROOT/build/lib:$LD_LIBRARY_PATH"
+
+# then run any tt-metal program, e.g. an upstream example:
+cd "$TT_METAL_RUNTIME_ROOT/build/programming_examples"
+./metal_example_add_2_integers_in_compute
+```
+
+A set of ready-to-run example programs, plus a build-and-run test suite, lives under
+[`examples`](examples). For the full walkthrough — building the
+examples, the `TT_SIM_TENSIX_COORDS` grid-pinning knob, diagnostics, structured tracing and
+the deadlock watchdog — see **[`driver/wormhole/README.md`](driver/wormhole/README.md)**.
+
+## Repository overview
+
+The simulator implementation is in the [framework](https://github.com/hedgehope/wolfpine/tree/main/framework) directory, with the [driver](https://github.com/hedgehope/wolfpine/tree/main/driver) directory providing a range of examples that illustrate running the simulator. These are individually documented, but to summarise:
+
+* [wormhole](https://github.com/hedgehope/wolfpine/tree/main/driver/wormhole) is where you likely want to go to. It provides an implementation of a Wormhole, currently with one DRAM tile and one Tensix block (although this is easy to expand, although will likely be slow!) It holds a set of example tt-metal programs that are built against a local tt-metal checkout and run against the simulator — exactly as they would run on hardware, only the device is the simulator. Each validates its own results, so the examples double as a test suite. See its README for how to build and run them.
+* [blackhole](https://github.com/hedgehope/wolfpine/tree/main/driver/blackhole) is the Blackhole driver: the same wire bridge and machinery as wormhole (all shared in [`framework/bridge`](https://github.com/hedgehope/wolfpine/tree/main/framework/bridge)), pointed at a Blackhole device instead. Point `TT_METAL_SIMULATOR` at `driver/blackhole` to route execution there. Workers are materialised on demand by the wire bridge, so a program gets exactly the grid it launches on, up to the full 130; see its README.
+* [simple](https://github.com/hedgehope/wolfpine/tree/main/driver/simple) are very basic examples, demonstrating the memory subsystem and running codes on a vanilla RV32IM CPU.
+
+### What the timing model claims, and what it does not
+
+The simulator carries a cost model of **documented provenance**: every cycle
+figure is traceable to the ISA documentation or a vendor source, there are
+**zero un-sourced estimates** (asserted by test), and it has been checked
+against real silicon. Stated precisely:
+
+> Runs real tt-metal programs unmodified on both architectures, on the full
+> default grid, with a timing model of documented provenance, corroborated
+> against silicon at the **slope** and **launch** level on both parts, and
+> **by mechanism** for NoC-bound work on both parts.
+
+Four caveats belong with that sentence rather than under it, because three of
+them are permanent:
+
+- **It is a floor.** Every bound is charged at its low end, by rule, so it
+  under-predicts wherever hardware sits above a documented minimum.
+- **Mechanism-level checking is one leg of three.** The RV-bound leg is
+  Blackhole-only (Wormhole documents no CSRs, so there is no retired-instruction
+  count) and currently fails its bar; the Tensix mechanism leg cannot be built
+  at all from the counters the hardware exposes.
+- **That failure has a single, sourced cause** — integer divide, where the
+  documentation gives only a 6–33 cycle range and no algorithm, so a
+  magnitude-dependent term cannot be sourced at any provenance.
+- **Energy is ranking-level only**, and barely beats a model that knows nothing
+  but the cycle count. Absolute joules are out of reach of the instrument.
+
+The full evidence, including what was proven *impossible* rather than merely
+left undone, is in [`ROADMAP.md`](ROADMAP.md).
+
+Optional diagnostic information can be provided by each RISC-V baby core, the NoC, the Tensix co-processor and memory, enabling tracing of the execution of a program. This is currently at the instruction and architectural state level, but could be enhanced in the future to provide feedback to developers around potential code bottlenecks or other issues.
+
+This is written in Python, mainly to make it easy for people to hackaround and experiment with things. If you want to add some functionality, or fix a bug, then please feel free to go ahead and raise a PR. This is still work in progress, so also please raise issues etc as you find them!
+
+## Key parts of the simulator
+
+There are a few of key components which are worth highlighting:
+
+* [tt_device.Wormhole](https://github.com/hedgehope/wolfpine/blob/93da242e8a1a26160afaca43b0772bebc88b9171/tt_sim/device/tt_device.py#L111) creates the Wormhole, currently with a single DRAM tile and a tensix tile. Here you can see the NoC coordinates specified of each, and also the booleans provided to _TensixTile_ are whether to report diagnostic information (the first five for each RISC-V baby core, then next two for each NoC and then the separate Tensix co-processor choices). In the [wormhole](https://github.com/hedgehope/wolfpine/tree/main/driver/wormhole) tt-metal flow these are set from the `TT_SIM_DIAG_*` environment variables (see that directory's README).
+* [tt_device.TensixTile](https://github.com/hedgehope/wolfpine/blob/93da242e8a1a26160afaca43b0772bebc88b9171/tt_sim/device/tt_device.py#L186) plumbs everything together within a Tensix tile, setting all the memory addresses and ranges for each individual component. These are all based on the ISA documentation [memory map](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/BabyRISCV/README.md). 
+* [tt_noc](https://github.com/hedgehope/wolfpine/blob/main/framework/network/tt_noc.py) is the implementation of the NoC, it is not yet complete with all the functionality but is sufficient to communicate between tiles and, for example, read and write between DRAM and the Tensix tile.
+* [rv](https://github.com/hedgehope/wolfpine/tree/main/framework/pe/rv) provides the RV32IM implementation with [.ttinsn extension](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/BabyRISCV/PushTensixInstruction.md#ttinsn-instruction-set-extension). This is fairly self explanatory, providing a pluggable approach to combining ISAs. The [BabyRISCV](https://github.com/hedgehope/wolfpine/blob/main/framework/pe/rv/babyriscv.py) ties this together for the baby RISC-V cores in the Tensix tile, for instance determining the initial PC value after a soft reset as per [here](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/SoftReset.md).
+* [tensix](https://github.com/hedgehope/wolfpine/tree/main/framework/pe/tensix) is the implementation of the Tensix coprocessor as per [here](https://github.com/tenstorrent/tt-isa-documentation/tree/main/WormholeB0/TensixTile/TensixCoprocessor). This is not fully complete, but enough to run a range of codes that use the matrix, vector and scalar units (and all the associated unit implementation required to enable this). 

wolfpine-2.1/README.md

@@ -0,0 +1,128 @@
+# Wolfpine
+
+**A framework for simulating AI accelerators, in pure Python.**
+
+Wolfpine is a hackable software framework for building cycle-approximate
+simulators of AI accelerator hardware. The core — the memory map, the
+interconnect, the RISC-V cores, the clock and reset fabric, the cost and
+trace machinery — is architecture-agnostic; a target is described by an
+*architecture profile* plus a thin device class, not by a fork.
+
+The framework ships with backends for the Tenstorrent architecture,
+**Wormhole** and **Blackhole**, built from the public
+[Tenstorrent ISA Documentation](https://github.com/tenstorrent/tt-isa-documentation/tree/main).
+Both run real tt-metal programs unmodified, on the full default worker grid —
+72 workers on Wormhole, 130 on Blackhole. Note that it is not cycle accurate
+(or intended to be). The idea was to build a simulator from public
+documentation, so developers can experiment with writing accelerator code
+without needing physical hardware — and, because it is Python all the way
+down, poke at simulator state directly from a driver script.
+
+## Contents
+
+- [Installation](#installation)
+- [Using Wolfpine as a simulator for tt-metal](#using-wolfpine-as-a-simulator-for-tt-metal)
+- [Repository overview](#repository-overview)
+- [What the timing model claims, and what it does not](#what-the-timing-model-claims-and-what-it-does-not)
+- [Key parts of the simulator](#key-parts-of-the-simulator)
+
+Profiling a kernel: [`driver/wormhole/docs/profiling.md`](driver/wormhole/docs/profiling.md)
+walks through every output the simulator can produce.
+Building tooling on those outputs: [`docs/trace-schema.md`](docs/trace-schema.md)
+is the stable, versioned schema — field meanings, units and what you may
+rely on.
+
+## Installation
+
+Wolfpine is pure Python and requires Python ≥ 3.10. Clone the repository and install it in
+editable mode, which pulls in its dependencies (numpy, pyyaml, pynng, flatbuffers,
+pyarrow, pyelftools):
+
+```bash
+git clone https://github.com/hedgehope/wolfpine.git
+cd wolfpine
+pip install -e .           # add [dev] for the ruff + pytest tooling: pip install -e .[dev]
+```
+
+This installs the `framework` simulator library. The example drivers live under `driver/`
+and are run from the repository root, so keep the repo root on your `PYTHONPATH` when
+invoking them directly (the tt-metal flow below wires this up for you automatically):
+
+```bash
+export PYTHONPATH=$PWD:$PYTHONPATH
+```
+
+## Using Wolfpine as a simulator for tt-metal
+
+tt-metal's UMD has a "simulation" chip backend: point `TT_METAL_SIMULATOR` at the
+[`driver/wormhole`](driver/wormhole) directory and UMD launches Wolfpine in place of real
+silicon, so an ordinary tt-metal program runs against the simulator over a socket — no
+code changes, exactly as it would run on hardware. The minimal setup:
+
+```bash
+export TT_METAL_RUNTIME_ROOT=/path/to/tt-metal          # your built tt-metal checkout
+export TT_METAL_SIMULATOR="$PWD/driver/wormhole"        # the switch: route execution to Wolfpine
+export TT_METAL_SLOW_DISPATCH_MODE=1                    # the only launch path the sim models
+export LD_LIBRARY_PATH="$TT_METAL_RUNTIME_ROOT/build/lib:$LD_LIBRARY_PATH"
+
+# then run any tt-metal program, e.g. an upstream example:
+cd "$TT_METAL_RUNTIME_ROOT/build/programming_examples"
+./metal_example_add_2_integers_in_compute
+```
+
+A set of ready-to-run example programs, plus a build-and-run test suite, lives under
+[`examples`](examples). For the full walkthrough — building the
+examples, the `TT_SIM_TENSIX_COORDS` grid-pinning knob, diagnostics, structured tracing and
+the deadlock watchdog — see **[`driver/wormhole/README.md`](driver/wormhole/README.md)**.
+
+## Repository overview
+
+The simulator implementation is in the [framework](https://github.com/hedgehope/wolfpine/tree/main/framework) directory, with the [driver](https://github.com/hedgehope/wolfpine/tree/main/driver) directory providing a range of examples that illustrate running the simulator. These are individually documented, but to summarise:
+
+* [wormhole](https://github.com/hedgehope/wolfpine/tree/main/driver/wormhole) is where you likely want to go to. It provides an implementation of a Wormhole, currently with one DRAM tile and one Tensix block (although this is easy to expand, although will likely be slow!) It holds a set of example tt-metal programs that are built against a local tt-metal checkout and run against the simulator — exactly as they would run on hardware, only the device is the simulator. Each validates its own results, so the examples double as a test suite. See its README for how to build and run them.
+* [blackhole](https://github.com/hedgehope/wolfpine/tree/main/driver/blackhole) is the Blackhole driver: the same wire bridge and machinery as wormhole (all shared in [`framework/bridge`](https://github.com/hedgehope/wolfpine/tree/main/framework/bridge)), pointed at a Blackhole device instead. Point `TT_METAL_SIMULATOR` at `driver/blackhole` to route execution there. Workers are materialised on demand by the wire bridge, so a program gets exactly the grid it launches on, up to the full 130; see its README.
+* [simple](https://github.com/hedgehope/wolfpine/tree/main/driver/simple) are very basic examples, demonstrating the memory subsystem and running codes on a vanilla RV32IM CPU.
+
+### What the timing model claims, and what it does not
+
+The simulator carries a cost model of **documented provenance**: every cycle
+figure is traceable to the ISA documentation or a vendor source, there are
+**zero un-sourced estimates** (asserted by test), and it has been checked
+against real silicon. Stated precisely:
+
+> Runs real tt-metal programs unmodified on both architectures, on the full
+> default grid, with a timing model of documented provenance, corroborated
+> against silicon at the **slope** and **launch** level on both parts, and
+> **by mechanism** for NoC-bound work on both parts.
+
+Four caveats belong with that sentence rather than under it, because three of
+them are permanent:
+
+- **It is a floor.** Every bound is charged at its low end, by rule, so it
+  under-predicts wherever hardware sits above a documented minimum.
+- **Mechanism-level checking is one leg of three.** The RV-bound leg is
+  Blackhole-only (Wormhole documents no CSRs, so there is no retired-instruction
+  count) and currently fails its bar; the Tensix mechanism leg cannot be built
+  at all from the counters the hardware exposes.
+- **That failure has a single, sourced cause** — integer divide, where the
+  documentation gives only a 6–33 cycle range and no algorithm, so a
+  magnitude-dependent term cannot be sourced at any provenance.
+- **Energy is ranking-level only**, and barely beats a model that knows nothing
+  but the cycle count. Absolute joules are out of reach of the instrument.
+
+The full evidence, including what was proven *impossible* rather than merely
+left undone, is in [`ROADMAP.md`](ROADMAP.md).
+
+Optional diagnostic information can be provided by each RISC-V baby core, the NoC, the Tensix co-processor and memory, enabling tracing of the execution of a program. This is currently at the instruction and architectural state level, but could be enhanced in the future to provide feedback to developers around potential code bottlenecks or other issues.
+
+This is written in Python, mainly to make it easy for people to hackaround and experiment with things. If you want to add some functionality, or fix a bug, then please feel free to go ahead and raise a PR. This is still work in progress, so also please raise issues etc as you find them!
+
+## Key parts of the simulator
+
+There are a few of key components which are worth highlighting:
+
+* [tt_device.Wormhole](https://github.com/hedgehope/wolfpine/blob/93da242e8a1a26160afaca43b0772bebc88b9171/tt_sim/device/tt_device.py#L111) creates the Wormhole, currently with a single DRAM tile and a tensix tile. Here you can see the NoC coordinates specified of each, and also the booleans provided to _TensixTile_ are whether to report diagnostic information (the first five for each RISC-V baby core, then next two for each NoC and then the separate Tensix co-processor choices). In the [wormhole](https://github.com/hedgehope/wolfpine/tree/main/driver/wormhole) tt-metal flow these are set from the `TT_SIM_DIAG_*` environment variables (see that directory's README).
+* [tt_device.TensixTile](https://github.com/hedgehope/wolfpine/blob/93da242e8a1a26160afaca43b0772bebc88b9171/tt_sim/device/tt_device.py#L186) plumbs everything together within a Tensix tile, setting all the memory addresses and ranges for each individual component. These are all based on the ISA documentation [memory map](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/BabyRISCV/README.md). 
+* [tt_noc](https://github.com/hedgehope/wolfpine/blob/main/framework/network/tt_noc.py) is the implementation of the NoC, it is not yet complete with all the functionality but is sufficient to communicate between tiles and, for example, read and write between DRAM and the Tensix tile.
+* [rv](https://github.com/hedgehope/wolfpine/tree/main/framework/pe/rv) provides the RV32IM implementation with [.ttinsn extension](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/BabyRISCV/PushTensixInstruction.md#ttinsn-instruction-set-extension). This is fairly self explanatory, providing a pluggable approach to combining ISAs. The [BabyRISCV](https://github.com/hedgehope/wolfpine/blob/main/framework/pe/rv/babyriscv.py) ties this together for the baby RISC-V cores in the Tensix tile, for instance determining the initial PC value after a soft reset as per [here](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/SoftReset.md).
+* [tensix](https://github.com/hedgehope/wolfpine/tree/main/framework/pe/tensix) is the implementation of the Tensix coprocessor as per [here](https://github.com/tenstorrent/tt-isa-documentation/tree/main/WormholeB0/TensixTile/TensixCoprocessor). This is not fully complete, but enough to run a range of codes that use the matrix, vector and scalar units (and all the associated unit implementation required to enable this). 

wolfpine-2.1/framework/__init__.py

@@ -0,0 +1,10 @@
+"""Wolfpine — a framework for simulating AI accelerators.
+
+The core here is architecture-agnostic: the memory map, the interconnect, the
+RISC-V cores, the clock and reset fabric, and the cost and trace machinery are
+all parameterised by an :mod:`framework.arch` profile. A target is a profile
+plus a thin device subclass, not a fork.
+
+The backends that ship today are the Tenstorrent architectures, Wormhole and
+Blackhole, in :mod:`framework.device`.
+"""

wolfpine-2.1/framework/behaviour.py

@@ -0,0 +1,387 @@
+"""What *this* Wolfpine gets right — an assertion target for external suites.
+
+Why this is not ``__version__``
+-------------------------------
+The compiler team ran their multicast suite against a Wolfpine that delivered
+correctly-encoded NoC 1 multicasts to nobody and reported success. Every run was
+green because nothing was delivered, not because anything worked, and there was
+no way to tell from the outside. Their question was "is there a version marker
+we can assert on?", and the honest answer is that a version number is the wrong
+shape for it: ``0.7.3`` tells you which build you have, never whether that build
+has the fix, and a consumer who pins ``>= 0.7.3`` has encoded a fact about our
+release history into their test suite rather than a fact about what they need.
+
+So what is published here is **behaviour**: named guarantees an outside suite
+may depend on. A name means the same thing forever; it is either present or it
+is not; and asserting on it says what the suite actually depends on.
+
+Most entries are of one shape — Wolfpine used to get something silently wrong and
+now refuses it — and for a long time that was the whole registry. It is
+deliberately not the definition. ``dram-interleaved-bank-distinctness`` is a
+**modelling property**: nothing raises, no environment variable switches it off,
+and there is no exception class behind it. It is here because the test it
+replaces was one an outside consumer was writing *by hand* — deriving, from our
+internals and our shipped SoC descriptors, that DRAM banks are separate stores
+at separate coordinates — in order to trust their own gate. That derivation is
+precisely what this registry exists to absorb: the question a consumer needs
+answered is "can a run against this build see the thing I am testing?", and a
+substrate that is missing makes a suite vacuous just as surely as a guard that
+does not fire. So the bar for an entry is that a consumer would otherwise have
+to establish it themselves, not that something throws.
+
+The difference does change how such an entry is *used*, and the guarantee text
+says so: a property marker tells you the substrate is there, it does not tell
+you when you have broken your own kernel.
+
+Asserting on it
+---------------
+From Python, in a suite's session setup::
+
+    from framework.behaviour import require
+
+    require("noc1-multicast-corner-order")
+
+which raises :class:`UnsupportedBehaviour` — naming what is missing, what this
+build does have, and where to read about it — rather than letting the suite
+collect another set of vacuous green results. Against a Wolfpine older than this
+module the ``import`` fails instead, which is the same outcome at the same
+moment; a consumer should not wrap it in ``except ImportError``, because a
+checkout without this module is precisely the one whose results are suspect.
+
+From a shell, a Makefile, or a C++ harness's test runner::
+
+    python3 -m framework.behaviour --require noc1-multicast-corner-order
+
+exits 0 when every named behaviour is present and 1 when any is missing, with
+the missing names on stderr. ``python3 -m framework.behaviour`` with no arguments
+lists what this build guarantees, one name per line, so a consumer can record
+the set a run was made against.
+
+:func:`supports` is the non-raising form, for a suite that would rather skip
+than fail.
+
+This module imports nothing from the rest of Wolfpine and nothing outside the
+standard library, so asserting on it costs no simulator construction and cannot
+be broken by an import cycle.
+
+Adding one, and why forgetting is caught
+----------------------------------------
+A registry nobody is forced to update decays into a lie, and this one is worth
+more than the average: its whole purpose is to be trusted by someone who cannot
+see our tree. Two guards hold it to the code.
+
+* **Forward.** Every entry names the test that pins its guarantee, and
+  ``behaviour_test.py`` imports that module and looks the function up. An entry
+  whose test is renamed or deleted fails immediately, so no guarantee can
+  outlive the thing that checks it.
+* **Backward.** The registry is *not* the only place a new guard has to be
+  mentioned, because that is the mention people forget. ``behaviour_test.py``
+  parses every non-test module under ``framework/`` for exception classes and
+  requires each one to be either registered here or listed in
+  ``_NOT_A_GUARANTEE`` with a reason. Adding a loudness guard to the simulator
+  therefore turns the suite red until somebody has decided, in writing, whether
+  an outside consumer would want to assert on it. That decision is the point;
+  the registry is just where the "yes" answers land.
+
+The dates are the day the guarantee first held in ``main``, recorded because it
+is occasionally useful for bisection. They are not a version and nothing should
+compare them.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from types import MappingProxyType
+from typing import NamedTuple
+
+#: Where the prose lives, quoted in the failure message so a consumer who hits
+#: it has somewhere to go.
+DOCS = "docs/running-tt-metal-on-the-simulator.md, section 7"
+
+
+class Behaviour(NamedTuple):
+    """One named, externally assertable guarantee about this simulator."""
+
+    #: Stable identifier. Never renamed and never reused for another meaning —
+    #: a consumer's test file outlives our refactors.
+    name: str
+    #: What a run against this build will do, in terms a consumer can observe
+    #: from outside: what raises, what is delivered, what is counted.
+    guarantee: str
+    #: ``YYYY-MM-DD`` the guarantee first held in ``main``. Informational.
+    since: str
+    #: ``module:function`` of the test that pins it. Checked to exist.
+    pinned_by: str
+
+
+_BEHAVIOURS = (
+    Behaviour(
+        name="noc1-multicast-corner-order",
+        guarantee=(
+            "A NoC multicast whose rectangle corners are ordered for the wrong "
+            "NoC raises framework.network.multicast_order.MulticastOrderError at "
+            "the point of issue. Before this, both wrong orderings completed "
+            "green: low-corner-first on a translated NoC 1 was delivered to "
+            "every destination (silicon delivers it to none and the sender's "
+            "write barrier never retires), and the reverse enumerated an empty "
+            "rectangle, so the barrier retired having sent nothing."
+        ),
+        since="2026-08-19",
+        pinned_by=(
+            "framework.network.multicast_order_test:"
+            "test_a_translated_noc1_multicast_written_low_first_raises"
+        ),
+    ),
+    Behaviour(
+        name="riscv-ebreak-halts",
+        guarantee=(
+            "A baby RISC-V executing ebreak raises "
+            "framework.pe.rv.breakpoint.RiscvBreakpoint naming the core and PC. "
+            "ebreak is what a kernel ASSERT(), an LLK_ASSERT under "
+            "TT_METAL_LLK_ASSERTS=1, and __builtin_trap() all lower to, and "
+            "Wolfpine used to decode it as a no-op — so a program whose own "
+            "authors had declared a state impossible ran past it and reported "
+            "success while the same binary stopped dead on silicon. Set "
+            "TT_SIM_IGNORE_EBREAK=1 to restore the old skip-and-continue."
+        ),
+        since="2026-08-04",
+        pinned_by="framework.pe.rv.breakpoint_test:test_ebreak_names_the_core_and_pc",
+    ),
+    Behaviour(
+        name="dram-interleaved-bank-distinctness",
+        guarantee=(
+            "Every DRAM bank tt-metal can interleave a buffer over is separate "
+            "storage reachable at its own NoC 0 coordinate: 12 banks on "
+            "Wormhole (6 channels x two 1 GiB dram_views), 8 on Blackhole (8 "
+            "channels x one view), counted from the shipped "
+            "driver/<arch>/soc_descriptor.yaml. A write to one bank is "
+            "invisible in every other; each bank's descriptor coordinate is a "
+            "distinct cell that resolves to its own channel's tile (including "
+            "the second worker-visible endpoint of a Wormhole channel); and "
+            "each channel is modelled whole, so every view's range is backed. "
+            "A host scatter and a kernel gather that disagree about page size, "
+            "bank count or a bank's coordinate therefore corrupt data, as they "
+            "do on silicon, instead of aliasing onto one flat store and coming "
+            "back right. NOT covered: which page lands in which bank — that "
+            "arithmetic is tt-metal's on both sides (host "
+            "WriteToDeviceInterleavedContiguous, device InterleavedAddrGen) and "
+            "never Wolfpine's — nor bank ordering, nor any claim about a "
+            "descriptor you supply yourself. Unlike the other entries here, "
+            "nothing raises and no environment variable disables it: this is a "
+            "modelling property, so it says the substrate your gate needs is "
+            "present, not that you will be told when your kernel is wrong."
+        ),
+        since="2026-08-19",
+        pinned_by=(
+            "framework.device.dram_banks_test:"
+            "test_every_bank_is_its_own_storage_at_its_own_coordinate"
+        ),
+    ),
+    Behaviour(
+        name="tensix-latched-wait-survives-stallwait",
+        guarantee=(
+            "A Tensix STALLWAIT issued while an earlier SEMWAIT or STALLWAIT "
+            "is latched and unsatisfied waits at its thread's Wait Gate "
+            "instead of replacing it, so a compute kernel's Dst handshake "
+            "holds however the LLK init calls are ordered around "
+            "tile_regs_wait(). STALLWAIT.md's block-mask table ticks "
+            "STALLWAIT in all nine columns, on both architectures, and it is "
+            "the only instruction whose row is; Wolfpine used to catch it by "
+            "its execution unit (Sync Unit, block bit B1) alone, so a "
+            "STALLWAIT behind a SEMWAIT whose block mask named the TDMA units "
+            "walked past and that semaphore wait was silently forgotten. "
+            "Concretely: pack_untilize_dest_init called after "
+            "tile_regs_wait() rather than before matmul_init dropped the "
+            "packer's wait on MATH_PACK, so a K >= 2 matmul packed a Dst that "
+            "was still mid-accumulation -- wrong values, no fault, and "
+            "correct on silicon and on ttsim. Like "
+            "dram-interleaved-bank-distinctness and unlike the raising "
+            "entries here, nothing throws and no environment variable "
+            "disables it: this is a modelling property, so it says the "
+            "ordering your kernel depends on is honoured, not that you will "
+            "be told when your kernel is wrong."
+        ),
+        since="2026-08-20",
+        pinned_by=(
+            "framework.pe.tensix.waitgate_stallwait_blocked_test:"
+            "test_a_stallwait_does_not_forget_an_unsatisfied_semwait"
+        ),
+    ),
+    Behaviour(
+        name="tensix-semaphore-bounds",
+        guarantee=(
+            "A Tensix SEMPOST that carries a semaphore to or past the Max its "
+            "own SEMINIT declared raises "
+            "framework.pe.tensix.semaphore_contract.SemaphoreContractError, "
+            "naming the semaphore, its value, that Max and the issuing thread; "
+            "so does a SEMPOST at 15 or a SEMGET at 0, on the Tensix "
+            "instructions and on the memory-mapped RISC-V path alike. Max is a "
+            "SEMWAIT C1 threshold and per SEMINIT.md 'has no effect on "
+            "SEMPOST', so hardware increments regardless and Wolfpine still "
+            "models that arithmetic — what the raise says is that the producer "
+            "issued past its own back-pressure, after which the computed "
+            "values depend on thread timing, which Wolfpine does not model. "
+            "Concretely: a compute kernel that hoists tile_regs_acquire() out "
+            "of its output-tile loop over-posts MATH_PACK the moment the "
+            "packer falls behind and wraps onto a Dst bank that has not been "
+            "drained; Wolfpine used to return the corrupted tiles while the "
+            "vendor simulator ttsim stopped. NOT covered: a post above Max on "
+            "a semaphore no SEMINIT configured, or through the memory-mapped "
+            "write, both of which working tt-metal kernels do and neither of "
+            "which raises. Set TT_SIM_DISABLE_SEMAPHORE_CHECKS=1 to restore "
+            "the old silence."
+        ),
+        since="2026-08-20",
+        pinned_by=(
+            "framework.pe.tensix.semaphore_contract_test:"
+            "test_a_sempost_past_a_declared_max_stops_and_names_everything"
+        ),
+    ),
+    Behaviour(
+        name="noc-transfer-alignment",
+        guarantee=(
+            "A NoC transfer whose source and destination addresses are not "
+            "congruent in the low bits the path requires raises "
+            "framework.network.alignment.NoCAlignmentError naming the path and "
+            "both addresses. Hardware neither faults nor completes such a "
+            "transfer correctly — it skews or drops the payload — so before "
+            "this a program with the defect produced plausible wrong numbers. "
+            "Set TT_SIM_DISABLE_ALIGNMENT_CHECKS=1 to switch it off, which "
+            "restores the old silence."
+        ),
+        since="2026-08-02",
+        pinned_by=(
+            "framework.network.alignment_test:"
+            "test_misaligned_transfer_raises_actionable_message"
+        ),
+    ),
+)
+
+#: name -> :class:`Behaviour`, for a consumer that wants to print or record the
+#: whole set. Read-only: a suite must not be able to talk itself into a
+#: guarantee by mutating the registry.
+BEHAVIOURS = MappingProxyType({b.name: b for b in _BEHAVIOURS})
+
+
+#: Exception classes in ``framework/`` that are deliberately *not* published as
+#: behaviours, and why. The backward guard in ``behaviour_test.py`` requires
+#: every exception class in the tree to appear here or in the registry above,
+#: so this is the file where "we thought about it and the answer is no" is
+#: written down rather than left implicit.
+_NOT_A_GUARANTEE = MappingProxyType(
+    {
+        "UnsupportedBehaviour": (
+            "this registry's own failure mode, not a claim about the simulator"
+        ),
+        "NoC1ShadowError": (
+            "warn-by-default and opt-in via TT_SIM_NOC1_SHADOW, so a build "
+            "cannot promise it fires; it guards a device-construction mistake "
+            "rather than a program's behaviour"
+        ),
+        "NoCCoordinateError": (
+            "a request naming a coordinate outside the grid — a malformed "
+            "request rather than a modelling gap that used to pass"
+        ),
+        "NoCResponseError": (
+            "internal NoC bookkeeping; reaching it means Wolfpine is wrong, not "
+            "that the program under test is"
+        ),
+        "UnitWedgedError": (
+            "the deadlock watchdog. Worth publishing once the false-positive "
+            "rate is argued (v3 Strand B says so of every guard); until then a "
+            "consumer asserting on it would be asserting on a heuristic"
+        ),
+        "UnmodelledTileRegisterError": (
+            "names a register Wolfpine does not model. Honest, but the set it "
+            "covers moves with every release, so it is not a stable guarantee"
+        ),
+        "SrcDvalidError": (
+            "a Tensix Src-bank handshake violation: an internal invariant of "
+            "the coprocessor model, not something a kernel author can act on"
+        ),
+        "CSRError": "base class for the CSR errors below",
+        "NoCSRsError": (
+            "a core built without Zicsr meeting a CSR instruction — a "
+            "simulator configuration error, not a program defect"
+        ),
+        "UnknownCSRError": "an encoding no CSR answers for; malformed input",
+        "UnmodelledCSRError": (
+            "a real CSR Wolfpine does not implement. Same objection as "
+            "UnmodelledTileRegisterError: the covered set is not stable"
+        ),
+        "PlanError": (
+            "a malformed congestion-sweep plan; an offline analysis tool's "
+            "input validation, nowhere near the simulated device"
+        ),
+    }
+)
+
+
+class UnsupportedBehaviour(RuntimeError):
+    """This Wolfpine does not guarantee something the caller depends on."""
+
+
+def supports(*names: str) -> bool:
+    """``True`` when every named behaviour is guaranteed by this build."""
+    return all(name in BEHAVIOURS for name in names)
+
+
+def require(*names: str) -> None:
+    """Assert every named behaviour, or raise :class:`UnsupportedBehaviour`.
+
+    The failure names what is missing *and* what this build does have, because
+    the two most likely causes are an old checkout and a typo, and the reader
+    cannot tell which from a bare "not supported".
+    """
+    missing = [name for name in names if name not in BEHAVIOURS]
+    if not missing:
+        return
+    have = ", ".join(sorted(BEHAVIOURS)) or "(none)"
+    raise UnsupportedBehaviour(
+        f"this Wolfpine does not guarantee {', '.join(missing)}. Results from a "
+        f"suite that depends on it are not trustworthy — the failure mode these "
+        f"markers exist for is a green run that exercised nothing. This build "
+        f"guarantees: {have}. See {DOCS}."
+    )
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python3 -m framework.behaviour",
+        description="What this Wolfpine guarantees, for an external test suite.",
+    )
+    parser.add_argument(
+        "--require",
+        metavar="NAME",
+        nargs="+",
+        default=(),
+        help="exit non-zero unless every NAME is guaranteed by this build",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="print each behaviour's guarantee, not just its name",
+    )
+    args = parser.parse_args(argv)
+
+    if args.require:
+        try:
+            require(*args.require)
+        except UnsupportedBehaviour as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+        return 0
+
+    for name in sorted(BEHAVIOURS):
+        if args.verbose:
+            behaviour = BEHAVIOURS[name]
+            print(f"{name}  (since {behaviour.since})")
+            print(f"    {behaviour.guarantee}")
+        else:
+            print(name)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wolfpine-2.1/framework/behaviour_test.py

@@ -0,0 +1,212 @@
+"""The registry is held to the code from both directions.
+
+A published capability marker is only worth what its maintenance is worth. The
+failure it exists to prevent — a consumer's suite running green against a
+simulator that silently does nothing — is exactly the failure a stale registry
+reintroduces, one level up: assert on ``noc1-multicast-corner-order``, get a
+pass, and have the name mean nothing because the guard behind it was deleted
+two refactors ago.
+
+So:
+
+* **Forward** — every entry names a test, and that test has to exist. An entry
+  whose guarantee is no longer checked anywhere cannot survive here.
+* **Backward** — every exception class in ``framework/`` has to be either
+  registered or explicitly declined in ``_NOT_A_GUARANTEE``. This is the guard
+  that stops the scheme decaying, because the omission people actually make is
+  landing a new loudness guard and never telling anyone outside about it. The
+  scan is over the source tree rather than a list, so it covers modules nobody
+  thought about when this was written.
+
+Runs standalone (``python3 -m framework.behaviour_test``) or under pytest.
+"""
+
+import ast
+import importlib
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from framework.behaviour import (
+    _NOT_A_GUARANTEE,
+    BEHAVIOURS,
+    UnsupportedBehaviour,
+    main,
+    require,
+    supports,
+)
+
+_ROOT = Path(__file__).resolve().parent
+
+
+def _exception_classes():
+    """``(class name, path)`` for every exception defined under ``framework/``.
+
+    Parsed rather than imported: importing the whole tree to enumerate its
+    exceptions would make a registry check the slowest test in the suite, and
+    would drag in numpy, pyarrow and the device model to answer a question that
+    is answerable from the text. A class counts as an exception if its own name
+    or any base's ends in ``Error`` or ``Exception``, which is the naming this
+    repo (and the standard library) keeps to.
+    """
+    out = []
+    for path in sorted(_ROOT.rglob("*.py")):
+        if path.name.endswith("_test.py") or "__pycache__" in path.parts:
+            continue
+        tree = ast.parse(path.read_text(), filename=str(path))
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.ClassDef):
+                continue
+            names = [node.name]
+            for base in node.bases:
+                if isinstance(base, ast.Name):
+                    names.append(base.id)
+                elif isinstance(base, ast.Attribute):
+                    names.append(base.attr)
+            if any(n.endswith(("Error", "Exception")) for n in names):
+                out.append((node.name, path.relative_to(_ROOT.parent)))
+    return out
+
+
+# --- forward: an entry cannot outlive the test that checks it ---------------
+
+
+def test_every_behaviour_names_a_test_that_exists():
+    assert BEHAVIOURS, "the registry is empty"
+    for name, behaviour in BEHAVIOURS.items():
+        module_name, _, function = behaviour.pinned_by.partition(":")
+        assert function, f"{name}: pinned_by must be 'module:function'"
+        module = importlib.import_module(module_name)
+        assert callable(getattr(module, function, None)), (
+            f"{name} claims to be pinned by {behaviour.pinned_by}, which does "
+            f"not exist. Either the test was renamed (repoint it) or the "
+            f"guarantee stopped being checked (drop the entry)."
+        )
+
+
+def test_every_behaviour_is_completely_described():
+    for name, behaviour in BEHAVIOURS.items():
+        assert name == behaviour.name
+        assert name == name.lower(), f"{name}: keep names lowercase"
+        assert " " not in name, (
+            f"{name}: names are typed into other people's test files; keep "
+            f"them hyphenated so they survive being pasted anywhere"
+        )
+        assert (
+            len(behaviour.guarantee) > 60
+        ), f"{name}: the guarantee has to say what a run will observably do"
+        assert len(behaviour.since) == 10, f"{name}: since must be YYYY-MM-DD"
+        assert behaviour.since.count("-") == 2, f"{name}: since must be YYYY-MM-DD"
+
+
+# --- backward: a new guard cannot land unmentioned ---------------------------
+
+
+def test_every_exception_is_registered_or_explicitly_declined():
+    """The guard against decay. A new exception class in ``framework/`` turns this
+    red until somebody decides, in writing, whether an outside consumer would
+    want to assert on it."""
+    # A behaviour accounts for an exception only by *naming* it in the
+    # guarantee text, so the registry cannot quietly claim a class without
+    # telling a reader which one it means.
+    guarantees = [behaviour.guarantee for behaviour in BEHAVIOURS.values()]
+    unaccounted = [
+        (name, path)
+        for name, path in _exception_classes()
+        if name not in _NOT_A_GUARANTEE
+        and not any(name in guarantee for guarantee in guarantees)
+    ]
+    assert not unaccounted, (
+        "these exception classes are neither named by a registered behaviour "
+        "nor declined in framework/behaviour.py's _NOT_A_GUARANTEE: "
+        + ", ".join(f"{name} ({path})" for name, path in unaccounted)
+        + ". If an external suite would want to assert that this build raises "
+        "it, register a behaviour; if not, add it to _NOT_A_GUARANTEE with the "
+        "reason."
+    )
+
+
+def test_nothing_is_declined_that_no_longer_exists():
+    """The exemption list is checked in the same direction as the registry, so
+    it cannot accumulate names for classes that were deleted years ago."""
+    defined = {name for name, _ in _exception_classes()}
+    stale = sorted(set(_NOT_A_GUARANTEE) - defined)
+    assert not stale, f"_NOT_A_GUARANTEE names classes that do not exist: {stale}"
+
+
+def test_every_reason_given_is_a_reason():
+    for name, reason in _NOT_A_GUARANTEE.items():
+        assert len(reason) > 20, f"{name}: 'why not' needs an actual answer"
+
+
+# --- the consumer-facing surface --------------------------------------------
+
+
+def test_the_snippet_a_consumer_writes():
+    """Verbatim from the module docstring and the docs section."""
+    require("noc1-multicast-corner-order")
+    assert supports("noc1-multicast-corner-order")
+
+
+def test_an_absent_behaviour_fails_loudly_and_usefully():
+    with pytest.raises(UnsupportedBehaviour) as caught:
+        require("noc1-multicast-corner-order", "no-such-guarantee")
+    message = str(caught.value)
+    assert "no-such-guarantee" in message
+    # Not merely "unsupported": the reader is told what this build does have,
+    # because a typo and an old checkout look identical otherwise.
+    assert "noc1-multicast-corner-order" in message
+    assert "docs/running-tt-metal-on-the-simulator.md" in message
+    assert not supports("no-such-guarantee")
+    assert not supports("noc1-multicast-corner-order", "no-such-guarantee")
+
+
+def test_the_registry_cannot_be_talked_into_a_guarantee():
+    with pytest.raises(TypeError):
+        BEHAVIOURS["invented"] = None
+
+
+def test_the_cli_lists_and_checks(capsys):
+    assert main([]) == 0
+    listed = capsys.readouterr().out.split()
+    assert listed == sorted(BEHAVIOURS)
+
+    assert main(["--require", *sorted(BEHAVIOURS)]) == 0
+    assert main(["--require", "no-such-guarantee"]) == 1
+    assert "no-such-guarantee" in capsys.readouterr().err
+
+
+def test_the_cli_works_for_a_consumer_with_no_python_at_all():
+    """A C++ harness or a Makefile shells out; that path must exit non-zero
+    on a missing behaviour rather than printing something a script has to
+    parse."""
+    ok = subprocess.run(
+        [sys.executable, "-m", "framework.behaviour", "--require"] + sorted(BEHAVIOURS),
+        capture_output=True,
+        text=True,
+        cwd=_ROOT.parent,
+    )
+    assert ok.returncode == 0, ok.stderr
+    bad = subprocess.run(
+        [sys.executable, "-m", "framework.behaviour", "--require", "no-such-guarantee"],
+        capture_output=True,
+        text=True,
+        cwd=_ROOT.parent,
+    )
+    assert bad.returncode == 1
+    assert "no-such-guarantee" in bad.stderr
+
+
+def main_standalone():
+    for name, fn in sorted(globals().items()):
+        if name.startswith("test_") and callable(fn):
+            if fn.__code__.co_argcount:
+                continue  # needs a pytest fixture
+            fn()
+    print("behaviour tests OK")
+
+
+if __name__ == "__main__":
+    main_standalone()

wolfpine-2.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wolfpine"
+version = "2.1"
+description = "A framework for simulating AI accelerators, with Tenstorrent Wormhole and Blackhole backends"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "BSD-3-Clause" 
+authors = [ { name = "Nick Brown" } ]
+classifiers = ["Programming Language :: Python :: 3"]
+dependencies = [
+    "numpy",
+    "pyyaml",
+    "pynng",
+    "flatbuffers",
+    "pyarrow",
+    "pyelftools",
+]
+
+[project.optional-dependencies]
+dev=["ruff", "pytest"]
+
+[tool.setuptools]
+packages = ["framework"]
+
+[tool.ruff]
+target-version = "py310"
+extend-include = ["*.ipynb", "*.pyi"]
+exclude = [".venv", "docs/marimo", "framework/bridge/_flatbuf"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "PT", "TID251", "INP", "PYI"]
+ignore = [
+    "E741",   # https://beta.ruff.rs/docs/rules/ambiguous-variable-name/
+    "PT006",  # https://beta.ruff.rs/docs/rules/pytest-parametrize-names-wrong-type/
+    "PT012",  # https://beta.ruff.rs/docs/rules/pytest-raises-with-multiple-statements/
+    "PYI041", # https://docs.astral.sh/ruff/rules/redundant-numeric-union
+]
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 130

wolfpine-2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wolfpine-2.1/wolfpine.egg-info/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: wolfpine
+Version: 2.1
+Summary: A framework for simulating AI accelerators, with Tenstorrent Wormhole and Blackhole backends
+Author: Nick Brown
+License-Expression: BSD-3-Clause
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pyyaml
+Requires-Dist: pynng
+Requires-Dist: flatbuffers
+Requires-Dist: pyarrow
+Requires-Dist: pyelftools
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# Wolfpine
+
+**A framework for simulating AI accelerators, in pure Python.**
+
+Wolfpine is a hackable software framework for building cycle-approximate
+simulators of AI accelerator hardware. The core — the memory map, the
+interconnect, the RISC-V cores, the clock and reset fabric, the cost and
+trace machinery — is architecture-agnostic; a target is described by an
+*architecture profile* plus a thin device class, not by a fork.
+
+The framework ships with backends for the Tenstorrent architecture,
+**Wormhole** and **Blackhole**, built from the public
+[Tenstorrent ISA Documentation](https://github.com/tenstorrent/tt-isa-documentation/tree/main).
+Both run real tt-metal programs unmodified, on the full default worker grid —
+72 workers on Wormhole, 130 on Blackhole. Note that it is not cycle accurate
+(or intended to be). The idea was to build a simulator from public
+documentation, so developers can experiment with writing accelerator code
+without needing physical hardware — and, because it is Python all the way
+down, poke at simulator state directly from a driver script.
+
+## Contents
+
+- [Installation](#installation)
+- [Using Wolfpine as a simulator for tt-metal](#using-wolfpine-as-a-simulator-for-tt-metal)
+- [Repository overview](#repository-overview)
+- [What the timing model claims, and what it does not](#what-the-timing-model-claims-and-what-it-does-not)
+- [Key parts of the simulator](#key-parts-of-the-simulator)
+
+Profiling a kernel: [`driver/wormhole/docs/profiling.md`](driver/wormhole/docs/profiling.md)
+walks through every output the simulator can produce.
+Building tooling on those outputs: [`docs/trace-schema.md`](docs/trace-schema.md)
+is the stable, versioned schema — field meanings, units and what you may
+rely on.
+
+## Installation
+
+Wolfpine is pure Python and requires Python ≥ 3.10. Clone the repository and install it in
+editable mode, which pulls in its dependencies (numpy, pyyaml, pynng, flatbuffers,
+pyarrow, pyelftools):
+
+```bash
+git clone https://github.com/hedgehope/wolfpine.git
+cd wolfpine
+pip install -e .           # add [dev] for the ruff + pytest tooling: pip install -e .[dev]
+```
+
+This installs the `framework` simulator library. The example drivers live under `driver/`
+and are run from the repository root, so keep the repo root on your `PYTHONPATH` when
+invoking them directly (the tt-metal flow below wires this up for you automatically):
+
+```bash
+export PYTHONPATH=$PWD:$PYTHONPATH
+```
+
+## Using Wolfpine as a simulator for tt-metal
+
+tt-metal's UMD has a "simulation" chip backend: point `TT_METAL_SIMULATOR` at the
+[`driver/wormhole`](driver/wormhole) directory and UMD launches Wolfpine in place of real
+silicon, so an ordinary tt-metal program runs against the simulator over a socket — no
+code changes, exactly as it would run on hardware. The minimal setup:
+
+```bash
+export TT_METAL_RUNTIME_ROOT=/path/to/tt-metal          # your built tt-metal checkout
+export TT_METAL_SIMULATOR="$PWD/driver/wormhole"        # the switch: route execution to Wolfpine
+export TT_METAL_SLOW_DISPATCH_MODE=1                    # the only launch path the sim models
+export LD_LIBRARY_PATH="$TT_METAL_RUNTIME_ROOT/build/lib:$LD_LIBRARY_PATH"
+
+# then run any tt-metal program, e.g. an upstream example:
+cd "$TT_METAL_RUNTIME_ROOT/build/programming_examples"
+./metal_example_add_2_integers_in_compute
+```
+
+A set of ready-to-run example programs, plus a build-and-run test suite, lives under
+[`examples`](examples). For the full walkthrough — building the
+examples, the `TT_SIM_TENSIX_COORDS` grid-pinning knob, diagnostics, structured tracing and
+the deadlock watchdog — see **[`driver/wormhole/README.md`](driver/wormhole/README.md)**.
+
+## Repository overview
+
+The simulator implementation is in the [framework](https://github.com/hedgehope/wolfpine/tree/main/framework) directory, with the [driver](https://github.com/hedgehope/wolfpine/tree/main/driver) directory providing a range of examples that illustrate running the simulator. These are individually documented, but to summarise:
+
+* [wormhole](https://github.com/hedgehope/wolfpine/tree/main/driver/wormhole) is where you likely want to go to. It provides an implementation of a Wormhole, currently with one DRAM tile and one Tensix block (although this is easy to expand, although will likely be slow!) It holds a set of example tt-metal programs that are built against a local tt-metal checkout and run against the simulator — exactly as they would run on hardware, only the device is the simulator. Each validates its own results, so the examples double as a test suite. See its README for how to build and run them.
+* [blackhole](https://github.com/hedgehope/wolfpine/tree/main/driver/blackhole) is the Blackhole driver: the same wire bridge and machinery as wormhole (all shared in [`framework/bridge`](https://github.com/hedgehope/wolfpine/tree/main/framework/bridge)), pointed at a Blackhole device instead. Point `TT_METAL_SIMULATOR` at `driver/blackhole` to route execution there. Workers are materialised on demand by the wire bridge, so a program gets exactly the grid it launches on, up to the full 130; see its README.
+* [simple](https://github.com/hedgehope/wolfpine/tree/main/driver/simple) are very basic examples, demonstrating the memory subsystem and running codes on a vanilla RV32IM CPU.
+
+### What the timing model claims, and what it does not
+
+The simulator carries a cost model of **documented provenance**: every cycle
+figure is traceable to the ISA documentation or a vendor source, there are
+**zero un-sourced estimates** (asserted by test), and it has been checked
+against real silicon. Stated precisely:
+
+> Runs real tt-metal programs unmodified on both architectures, on the full
+> default grid, with a timing model of documented provenance, corroborated
+> against silicon at the **slope** and **launch** level on both parts, and
+> **by mechanism** for NoC-bound work on both parts.
+
+Four caveats belong with that sentence rather than under it, because three of
+them are permanent:
+
+- **It is a floor.** Every bound is charged at its low end, by rule, so it
+  under-predicts wherever hardware sits above a documented minimum.
+- **Mechanism-level checking is one leg of three.** The RV-bound leg is
+  Blackhole-only (Wormhole documents no CSRs, so there is no retired-instruction
+  count) and currently fails its bar; the Tensix mechanism leg cannot be built
+  at all from the counters the hardware exposes.
+- **That failure has a single, sourced cause** — integer divide, where the
+  documentation gives only a 6–33 cycle range and no algorithm, so a
+  magnitude-dependent term cannot be sourced at any provenance.
+- **Energy is ranking-level only**, and barely beats a model that knows nothing
+  but the cycle count. Absolute joules are out of reach of the instrument.
+
+The full evidence, including what was proven *impossible* rather than merely
+left undone, is in [`ROADMAP.md`](ROADMAP.md).
+
+Optional diagnostic information can be provided by each RISC-V baby core, the NoC, the Tensix co-processor and memory, enabling tracing of the execution of a program. This is currently at the instruction and architectural state level, but could be enhanced in the future to provide feedback to developers around potential code bottlenecks or other issues.
+
+This is written in Python, mainly to make it easy for people to hackaround and experiment with things. If you want to add some functionality, or fix a bug, then please feel free to go ahead and raise a PR. This is still work in progress, so also please raise issues etc as you find them!
+
+## Key parts of the simulator
+
+There are a few of key components which are worth highlighting:
+
+* [tt_device.Wormhole](https://github.com/hedgehope/wolfpine/blob/93da242e8a1a26160afaca43b0772bebc88b9171/tt_sim/device/tt_device.py#L111) creates the Wormhole, currently with a single DRAM tile and a tensix tile. Here you can see the NoC coordinates specified of each, and also the booleans provided to _TensixTile_ are whether to report diagnostic information (the first five for each RISC-V baby core, then next two for each NoC and then the separate Tensix co-processor choices). In the [wormhole](https://github.com/hedgehope/wolfpine/tree/main/driver/wormhole) tt-metal flow these are set from the `TT_SIM_DIAG_*` environment variables (see that directory's README).
+* [tt_device.TensixTile](https://github.com/hedgehope/wolfpine/blob/93da242e8a1a26160afaca43b0772bebc88b9171/tt_sim/device/tt_device.py#L186) plumbs everything together within a Tensix tile, setting all the memory addresses and ranges for each individual component. These are all based on the ISA documentation [memory map](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/BabyRISCV/README.md). 
+* [tt_noc](https://github.com/hedgehope/wolfpine/blob/main/framework/network/tt_noc.py) is the implementation of the NoC, it is not yet complete with all the functionality but is sufficient to communicate between tiles and, for example, read and write between DRAM and the Tensix tile.
+* [rv](https://github.com/hedgehope/wolfpine/tree/main/framework/pe/rv) provides the RV32IM implementation with [.ttinsn extension](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/BabyRISCV/PushTensixInstruction.md#ttinsn-instruction-set-extension). This is fairly self explanatory, providing a pluggable approach to combining ISAs. The [BabyRISCV](https://github.com/hedgehope/wolfpine/blob/main/framework/pe/rv/babyriscv.py) ties this together for the baby RISC-V cores in the Tensix tile, for instance determining the initial PC value after a soft reset as per [here](https://github.com/tenstorrent/tt-isa-documentation/blob/main/WormholeB0/TensixTile/SoftReset.md).
+* [tensix](https://github.com/hedgehope/wolfpine/tree/main/framework/pe/tensix) is the implementation of the Tensix coprocessor as per [here](https://github.com/tenstorrent/tt-isa-documentation/tree/main/WormholeB0/TensixTile/TensixCoprocessor). This is not fully complete, but enough to run a range of codes that use the matrix, vector and scalar units (and all the associated unit implementation required to enable this). 

wolfpine-2.1/wolfpine.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+framework/__init__.py
+framework/behaviour.py
+framework/behaviour_test.py
+wolfpine.egg-info/PKG-INFO
+wolfpine.egg-info/SOURCES.txt
+wolfpine.egg-info/dependency_links.txt
+wolfpine.egg-info/requires.txt
+wolfpine.egg-info/top_level.txt

wolfpine-2.1/wolfpine.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

wolfpine-2.1/wolfpine.egg-info/requires.txt

@@ -0,0 +1,10 @@
+numpy
+pyyaml
+pynng
+flatbuffers
+pyarrow
+pyelftools
+
+[dev]
+ruff
+pytest

wolfpine-2.1/wolfpine.egg-info/top_level.txt

@@ -0,0 +1 @@
+framework