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.