# Platform reference

Every block and field of a platform YAML, as `helx platform show`, `helx validate platform` and `run.platform` read it. A platform is a SoC plus an energy model and a revision history. The SoC is either `soc:` (a helia-npu id such as `atomiq110`, or a path) with optional `soc_overrides`, or the `SocModel` fields written inline (`name`, `npu`, `macs`, `modes`, `memories`, ...); a platform with an inline SoC is never `golden`. Give exactly one of inline `energy` or `energy_profile` (a version-1 file relative to the platform or absolute, bound to a SoC id/revision). `energy.memories` holds one record per SoC memory, keyed by the memory name, with `read_energy_pj_per_bit`, `write_energy_pj_per_bit` and an optional `provenance`, plus `logic_overhead`; every SoC memory must have one. `energy.core.reference_pj_per_cycle` may be left out only when helia-npu carries an Arm reference figure for the NPU and MAC count. A value without a provenance record counts as `unverified`.

Generated by `scripts/render_references.py` from the models; do not edit by hand.

## `PlatformModel`

What helx adds to a SoC: an energy model and a revision history.

The SoC comes either from ``soc:`` (a packaged helia-npu id such as
``atomiq110``, or a path) with optional ``soc_overrides`` for a derived
variant, or from the SoC fields written inline. Golden parts use the
reference so the silicon facts have exactly one copy.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `soc` | str or null | none | A helia-npu SoC id such as atomiq110, or a path to a SoC YAML. |
| `soc_overrides` | block `SocOverridesModel` or null | none | Changes to the referenced SoC for a derived variant. |
| `energy` | block `EnergyModel` or null | none | Inline energy parameters for a custom or synthetic platform; mutually exclusive with energy_profile. |
| `energy_profile` | str or null | none | Version-1 energy profile path, relative to this platform file or absolute. |
| `revisions` | list[block `RevisionModel`] | empty | Change history, oldest first; the last entry is the revision results record. |
| `name` | str or null | none | Inline SoC: the product name. |
| `id` | str or null | none | Inline SoC: canonical lowercase id; defaults to the lowercased name. |
| `origin` | one of `golden`, `derived`, `custom` or null | none | Inline SoC: derived or custom; golden is reserved for SoCs packaged with helia-npu. |
| `revision` | str or dict[str, Any] or null | none | Inline SoC: which drop or stepping the values describe. |
| `npu` | str or null | none | Inline SoC: NPU family, e.g. ethos-u85. |
| `macs` | int or null | none | Inline SoC: MAC units per cycle, e.g. 256. |
| `axi_bus_width_bits` | int or null | none | Inline SoC: width of one AXI data beat, bits; unset, the NPU's (64 on the Ethos-U55, 128 on the U65, U85). |
| `modes` | dict[str, Any] or null | none | Inline SoC: operating modes by name, each with npu_clock_hz. |
| `memories` | dict[str, Any] or null | none | Inline SoC: memories by name, each with axi_port, latencies in ns, max_outstanding (and optionally max_outstanding_writes), burst_length, ports_used and a clock. |

## `SocOverridesModel`

A diff on top of a base SoC: the what-if and variant mechanism.

Scalars replace the base's. ``modes`` replaces the whole mode table when
given. ``memories`` is merged per memory: a mapping replaces or adds that
memory, ``null`` removes it. The result's ``origin`` is ``derived`` unless
nothing but identity changed.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `name` | str or null | none | Replaces the base SoC's name. |
| `id` | str or null | none | Replaces the base SoC's id; a derived variant should have its own. |
| `origin` | one of `golden`, `derived`, `custom` or null | none | Replaces the origin; when omitted, an override that changes hardware makes the SoC derived, one that only renames keeps the base origin. |
| `revision` | str or block `SocRevisionModel` or null | none | Replaces the revision. |
| `npu` | str or null | none | Replaces the NPU family. |
| `macs` | int or null | none | Replaces the MAC count. |
| `axi_bus_width_bits` | int or null | none | Replaces the beat width; a new npu without one takes that NPU's. |
| `modes` | dict[str, block `ModeModel`] or null | none | Replaces the modes. |
| `memories` | dict[str, block `MemoryModel` or null] or null | none | Memories to add or replace by name; null removes one. A replaced memory keeps its place in the order; when a port's first memory is removed, the next one declared on that port becomes its default. |
| `sram_ports` | block `SramPortsModel` or null | none | Replaces the SRAM port hash. |

## `SocRevisionModel`

| Field | Type | Default | Meaning |
|---|---|---|---|
| `label` | str | required | Revision label, e.g. v8 or A0. |
| `stage` | one of `spec`, `rtl`, `silicon`, `released` | `spec` | Where the revision sits in the part's life: spec, rtl, silicon or released. |
| `date` | date or null | none | Date of the revision. |
| `notes` | str or null | none | What the revision is based on. |

## `ModeModel`

| Field | Type | Default | Meaning |
|---|---|---|---|
| `npu_clock_hz` | float | required | NPU clock in this mode, Hz. |

## `MemoryModel`

| Field | Type | Default | Meaning |
|---|---|---|---|
| `axi_port` | int | required | Port class the memory sits on: 0 (Arm AXI_SRAM, Vela Sram) or 1 (Arm AXI_EXT, Vela Dram). |
| `read_latency_ns` | float | required | Read latency the NPU sees, ns. |
| `write_latency_ns` | float | required | Write latency the NPU sees, ns. |
| `max_outstanding` | int | required | Outstanding read transactions the path sustains; also the write limit unless max_outstanding_writes is set. |
| `max_outstanding_writes` | int or null | none | Outstanding write transactions the path sustains, when it differs from max_outstanding. |
| `burst_length` | int | required | Burst length, bytes. Ethos-U85 FVP runs need 64, 128 or 256: the runner's driver splits AXI bursts at it. |
| `ports_used` | int | `1` | How many ports of this class Vela is told exist, 1 or 2. |
| `axi_clock_hz` | float or null | none | AXI clock of the memory path, Hz; the bandwidth per NPU cycle is derived from it and the NPU clock. |
| `bandwidth_fraction` | float or null | none | Alternative to axi_clock_hz: fraction of one data beat per NPU cycle the port sustains. |
| `provenance` | block `ProvenanceModel` or null | none | Where the memory's values came from. |

## `ProvenanceModel`

Where a value came from and how far it can be trusted.

``status`` is the only required field: ``confirmed`` (measured or reviewed
against measurements by the owning team), ``fitted`` (tuned so the model
reproduces RTL or FPGA measurements), or ``unverified`` (specification,
estimate or placeholder). ``fields`` carries a record per value for the numbers in
the block whose status differs from the block's; the field names are
checked by the block that owns them.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `status` | one of `confirmed`, `fitted`, `unverified` | required | confirmed (measured or reviewed against measurements), fitted (tuned to reproduce measurements) or unverified (spec, estimate or placeholder). |
| `source` | str or null | none | Where the value came from: a document, a measurement, a review. |
| `reviewed_by` | str or null | none | The team that reviewed the value. |
| `reviewed_on` | date or null | none | Date of that review. |
| `notes` | str or null | none | Caveats a reader of the number should know. |
| `fields` | dict[str, block `ProvenanceModel`] or null | none | Per-value records for the numbers in the block whose status differs from the block's. |

## `SramPortsModel`

How the NPU spreads AXI SRAM traffic over its SRAM ports.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `hash` | int | required | Address mask whose parity picks the port for each transaction (the Ethos-U85's HASH0, the Corstone-320 FVP's sram_hash0): 0x80 sends alternate 128 B stripes to alternate ports. Without this block the FVP default applies, 0x100 (address bit 8). |
| `provenance` | block `ProvenanceModel` or null | none | Where the value came from. |

## `EnergyModel`

``energy:``: the core block plus per-memory pJ/bit records keyed by memory name (and ``logic_overhead``).

| Field | Type | Default | Meaning |
|---|---|---|---|
| `core` | block `CoreEnergyModel` | required | Core energy: the reference and its per-mode scaling. |
| `memories` | dict[str, Any] | required | One record per SoC memory, keyed by its name, with read_energy_pj_per_bit, write_energy_pj_per_bit and an optional provenance; plus logic_overhead. |

## `CoreEnergyModel`

Core energy: Arm's reference pJ/cycle for the NPU configuration, scaled per mode.

``reference_pj_per_cycle`` is normally left out and taken from helia-npu's
table for the SoC's NPU and MAC count, so every platform modelling the same
NPU reads the same number. Give it only for a what-if that deliberately
changes it, with its own provenance.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `reference_pj_per_cycle` | float or null | none | Reference core energy for the NPU configuration, pJ per NPU cycle; taken from helia-npu's Arm table when omitted. |
| `scaling` | dict[str, float] | required | Multiplier on the reference per platform mode, mode name to factor; must name every mode of the SoC. |
| `provenance` | block `ProvenanceModel` or null | none | Where the core values came from. |

## `RevisionModel`

One entry in a platform's change history; the last entry is the current revision.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `version` | str | required | Revision label, e.g. v8. |
| `date` | date | required | Date of the revision. |
| `changes` | list[str] | required | What changed, one entry per change. |

## `SocModel`

The SoC half of a definition file. ``id`` defaults to the lowercased name.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `name` | str | required | The product name, e.g. AT110. |
| `id` | str or null | none | Canonical lowercase id used in generated files and results; defaults to the lowercased name. |
| `origin` | one of `golden`, `derived`, `custom` | `custom` | golden (packaged, values reviewed by the owners), derived (a variant of a golden SoC) or custom. |
| `revision` | str or block `SocRevisionModel` or null | none | Which drop or stepping the values describe: a label such as v8 (2026-09-22), or {label, stage, date, notes}. |
| `npu` | str | required | NPU family, e.g. ethos-u85. |
| `macs` | int | required | MAC units per cycle, e.g. 256. |
| `axi_bus_width_bits` | int or null | none | Width of one AXI data beat, bits; the NPU's (64 on the Ethos-U55, 128 on the U65 and U85) when unset. |
| `modes` | dict[str, block `ModeModel`] | required | Operating modes by name, each with its NPU clock. |
| `memories` | dict[str, block `MemoryModel`] | required | Every memory wired to the NPU, by name, each on one port class. A port may list several (HBLRAM, PSRAM and RRAM on AT110's port 1); the first declared is the port's default and a run's memory_placement picks another. |
| `sram_ports` | block `SramPortsModel` or null | none | How the NPU spreads SRAM traffic over its SRAM ports; the FVP default when unset. |

## `EnergyProfileModel`

A versioned energy overlay for one SoC revision; it carries no silicon definition.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `schema_version` | one of `1` | required | Energy-profile document version, currently 1. |
| `id` | str | required | Stable characterization-profile identifier. |
| `revision` | str | required | Energy characterization revision, independent of the silicon/timing revision. |
| `soc` | str | required | Canonical SoC id this profile characterizes. |
| `soc_revision` | str | required | Compatible SoC revision label, without its date. |
| `energy` | block `EnergyModel` | required | Core and physical-memory coefficients, with their evidence. |
| `revisions` | list[block `RevisionModel`] | empty | Retained characterization history; never copied into public guides. |