diff --git a/docs/architecture/interfaces.md b/docs/architecture/interfaces.md index e51c4668..49718ec1 100644 --- a/docs/architecture/interfaces.md +++ b/docs/architecture/interfaces.md @@ -1,12 +1,5 @@ # LinxCore External Interface Contracts -This document defines the externally consumed LinxCore interface contracts for -model integration, trace generation, and cross-tool synchronization. - -The contracts below are normative for pyCircuit, testbench, trace tooling, -viewer tooling, and any other producer or consumer that observes LinxCore -through non-ISA interfaces. - ## pyCircuit-LinxCore interface contract (LC-IF-PYC-001) The pyCircuit/LinxCore integration contract is versioned and gate-enforced. @@ -20,28 +13,17 @@ Rules: - Contract version follows `MAJOR.MINOR`. - Backward-compatible additions increment `MINOR`. -- Breaking field removals, renames, or semantic redefinitions increment - `MAJOR`. +- Breaking field removals/renames or semantic redefinitions increment `MAJOR`. - Gate tooling rejects unversioned interface breaks. -The pyCircuit interface contract is the required compatibility boundary for: - -- pyCircuit-generated DUTs, -- C++ testbench integration, -- compare tooling, -- commit-trace consumers used by QEMU correlation and bring-up gates. - ## Required commit payload contract (LC-IF-PYC-002) Required commit fields from `pyc_linxcore_interface_contract.json`: - `cycle`, `pc`, `insn` -- `src0_valid`, `src0_reg`, `src0_data` -- `src1_valid`, `src1_reg`, `src1_data` -- `dst_valid`, `dst_reg`, `dst_data` - `wb_valid`, `wb_rd`, `wb_data` -- `mem_valid`, `mem_is_store`, `mem_addr`, `mem_wdata`, `mem_rdata`, `mem_size` -- `trap_valid`, `trap_cause`, `traparg0`, `next_pc` +- `mem_valid`, `mem_addr`, `mem_wdata`, `mem_rdata`, `mem_size` +- `trap_valid`, `trap_cause`, `next_pc` Required environment controls: @@ -50,122 +32,29 @@ Required environment controls: - `PYC_MEM_BYTES` - `PYC_MAX_CYCLES` -Canonical producers and consumers live under: - -- `rtl/LinxCore/tb/` -- `rtl/LinxCore/tools/trace/` -- `tools/bringup/check_pycircuit_interface_contract.py` - -### Commit stream rules - -- Commit payloads describe architecturally retiring work only. -- Multi-commit cycles must retain per-slot ordering semantics. -- Empty placeholder rows are forbidden in the architecturally compared commit - stream. -- Commit-side trap, memory, and writeback payloads must remain coherent with - the retiring uop or macro event they describe. -- Source-operand validity, register identity, and value correlation are - required contract payload, not optional debug metadata. -- Destination correlation must remain explicit even when `wb_*` aliases are - also present for backward consumer convenience. - -### DUT control rules - -- Boot, memory-size, and commit-trace control environment variables are part of - the external contract, not incidental implementation details. -- A contract-visible change in required environment controls must be versioned - the same way as a field-level interface change. - -## Block command fabric contract - -The block-command interface remains part of the externally visible LinxCore -behavior because backend, `BISQ`, `BCTRL`, and engine paths must agree on a -single command envelope. - -Required block-command fields: - -- `cmd_valid` -- `cmd_kind[2:0]` -- `cmd_tag[7:0]` -- `cmd_tile[5:0]` -- `cmd_payload[63:0]` -- `cmd_src_rob` -- `cmd_bid` - -Required rules: - -- `cmd_tag == bid[7:0]` -- response tags route back to the correct `BROB` entry -- `BID` remains visible through enqueue, issue, completion, and flush rollback - -### Block command response rules - -- Command responses must preserve source-to-`BROB` routing correctness. -- Tag reuse must remain synchronized with `BID` lifetime and flush semantics. -- Engine-local completion metadata must not bypass block-level retirement rules. - -Detailed command-lane behavior remains in: - -- `rtl/LinxCore/docs/architecture/block_fabric_contract.md` - -## Memory and MMIO visibility contract - -The external LinxCore memory-visible contract includes: - -- architecturally visible load/store commit payloads, -- committed-store drain visibility where applicable, -- MMIO-visible UART and exit signaling used by canonical bring-up flows. - -Rules: - -- MMIO-visible effects must remain explicit and traceable. -- Memory metadata exported through commit trace must remain sufficient for - architectural compare and debugging flows. -- Memory-side debug metadata may be additive, but it must not redefine the - required commit payload semantics. - ## LinxTrace schema contract (LC-IF-TRACE-001) Trace schema governance: -- canonical schema contract: `docs/bringup/contracts/trace_schema.md` -- runtime format contract: `rtl/LinxCore/docs/trace/linxtrace_v1.md` -- pipeline refresh rule: `rtl/LinxCore/docs/trace/linxtrace_pipeline_refresh_rule.md` +- canonical contract: `docs/bringup/contracts/trace_schema.md` - producer-side schema validation: `tools/bringup/validate_trace_schema.py` - SemVer compatibility gate: `tools/bringup/check_trace_semver_compat.py` Rules: -- LinxTrace output is a single `*.linxtrace` JSONL file. -- The first non-empty record is `{"type":"META", ...}`. - `MAJOR` schema mismatch is a hard failure. -- `MINOR` requires producer version to satisfy consumer expectations. +- `MINOR` must be producer >= consumer expectation. - Breaking trace changes require major bump and migration checks. -### Required trace content - -- The trace must define stage, lane, and row catalogs in-band. -- Unknown stage, lane, or row identifiers are hard errors. -- Stage ownership must come from real producer-side stage state, not - viewer-side reconstruction. -- Trace rows must preserve block and uop identity sufficiently for - LinxCoreSight and compare tooling to render without inventing lifecycle - state. - ## Trace compatibility contract (LC-IF-TRACE-002) - `linxtrace.v1` remains stable for additive changes. -- Major-version bump is mandatory for incompatible field or semantic changes. +- Major-version bump is mandatory for incompatible field/semantics changes. - Compatibility checks must fail fast on major mismatch. -- Producer-side fixes are preferred over compare-tool masking when trace - content diverges from architectural behavior. - -Backward-compatible additions must not silently change the meaning of existing -fields or lifecycle ordering. ## Cross-tool synchronization contract (LC-IF-SYNC-001) -The following must stay synchronized when trace or pipeline contracts change: +The following must stay synchronized when trace/pipeline contracts change: - `rtl/LinxCore/src/common/stage_tokens.py` - `rtl/LinxCore/tb/tb_linxcore_top.cpp` @@ -173,41 +62,28 @@ The following must stay synchronized when trace or pipeline contracts change: - `rtl/LinxCore/tools/linxcoresight/lint_linxtrace.py` - `rtl/LinxCore/tools/linxcoresight/lint_trace_contract_sync.py` -Viewer-side contract sync is validated through LinxTrace gates. - -The published superproject LinxCore mirror pages are part of this -cross-tool/publication contract: they must remain synchronized with the -canonical submodule docs after contract edits. - ## Scope boundary -This document covers external LinxCore interface governance only: +This document covers **external** LinxCore interface governance only: -- pyCircuit contract, -- trace schema contract, -- cross-tool synchronization rules. +- pyCircuit contract +- trace schema contract +- cross-tool synchronization rules -Detailed LinxCore microarchitectural interface contracts, including the -two-layer block machine, `BROB`-facing resolve behavior, raw engine fabric, and -engine/block-type mapping, belong under: +Detailed LinxCore **microarchitectural** interface contracts (two-layer block machine, `BROB`-facing resolve, +raw engine fabric, engine/block-type mapping) belong under: - `rtl/LinxCore/docs/architecture/` -- `rtl/LinxCore/docs/architecture/microarchitecture.md` +- `docs/architecture/linxcore/microarchitecture.md` -The promoted stage contracts from `F0` through the baseline issue/wakeup slice -(`S1`, `S2`, `P1`, `I1`, `I2`, `E1`, `W1`) are captured normatively in the -canonical microarchitecture page, while this document remains limited to -external and tool-facing governance. +For the current architecture-writing pass, the promoted stage contracts from +`F0` through the baseline issue/wakeup slice (`S1/S2/P1/I1/I2/E1/W1`) are +captured normatively in `docs/architecture/linxcore/microarchitecture.md`, +while this document remains limited to external/tool-facing interface +governance. ## Interface change control - Interface-visible changes must update contract artifacts first. -- Gate rows in `rtl/LinxCore/docs/architecture/verification-matrix.md` are the - release blocker for interface promotion. +- Gate rows in `docs/architecture/linxcore/verification-matrix.md` are the release blocker for interface promotion. - Any contract-major bump must include migration notes and dual-lane evidence. -- Published mirrors in `docs/architecture/linxcore/` must be regenerated after - contract edits. - -Deep-dive implementation notes may expand a mechanism, but they must not create -an alternative compatibility contract outside this document and the referenced -machine-readable artifacts. diff --git a/docs/architecture/microarchitecture.md b/docs/architecture/microarchitecture.md index b1d88823..8e566997 100644 --- a/docs/architecture/microarchitecture.md +++ b/docs/architecture/microarchitecture.md @@ -1,8 +1,8 @@ -# LinxCore v0.4 Microarchitecture Contract +# LinxCore v0.56 Microarchitecture Contract ## Baseline superscalar contract -LinxCore is the canonical superscalar out-of-order core for LinxISA `v0.4`. +LinxCore is the canonical superscalar out-of-order core for LinxISA `v0.56`. It retires precisely, executes out of order, and preserves a block-ordered architectural control model across scalar and engine-backed work. @@ -14,14 +14,14 @@ Current baseline limits: - commit width: up to 4 - LSU width: 1 -These limits are the live `v0.4` closure baseline. Wider issue or multi-LSU +These limits are the live `v0.56` closure baseline. Wider issue or multi-LSU scaling is a follow-on track, not part of the normative contract here. ## Architectural state model LinxCore must preserve the following architectural state classes: -- scalar, control, and privilege state defined by LinxISA `v0.4`, +- scalar, control, and privilege state defined by LinxISA `v0.56`, - CSR, trap, MMU, and interrupt-visible state, - block-visible architectural state for `BSTART`, `BSTOP`, and boundary-authoritative redirect, @@ -181,8 +181,6 @@ future canonical updates, but it must not contradict the rules below. - `D2` is the rename request and translation stage. - `D2` preserves decode-slot program order across one decode group. - `D2` resolves boundary metadata and prepares ROB-visible boundary uops. -- `D2` also resolves immediate-only architectural producers that must bypass - IQ allocation and late writeback, including `SETRET` and `C.SETRET`. - `D2` carries the canonical architectural uop shape: ```text @@ -513,7 +511,7 @@ Detailed BROB and block-fabric behavior remains documented in: ## MMU contract (LC-MA-MMU-001) - Translation success and failure must produce deterministic trap envelopes. -- MMU behavior must remain aligned with the `v0.4` privileged contract wording. +- MMU behavior must remain aligned with the `v0.56` privileged contract wording. - MMU fault paths must preserve precise retirement and recovery ordering. ## Interrupt contract (LC-MA-IRQ-001) @@ -565,8 +563,11 @@ Detailed ordering behavior remains documented in: ### Workload-engine composition - `VEC` remains the general programmable SIMT compute engine. -- `TMA`, `CUBE`, and `TAU` integrate into LinxCore through the same block/BID - contract as the rest of the machine. +- `TMA` integrates into LinxCore through the same block/BID contract as the + rest of the machine, but its southbound memory traffic is owned by the CSU + subsystem and targets CSU L2 alongside frontend refill traffic. +- `CUBE` and `TAU` continue to integrate through the same block/BID contract + as peer engines. - Engine issue, completion, exception, and flush behavior must remain visible to ROB, BROB, and trace machinery through the canonical interfaces. diff --git a/docs/architecture/module-catalog.md b/docs/architecture/module-catalog.md index c52cb109..eaecc98d 100644 --- a/docs/architecture/module-catalog.md +++ b/docs/architecture/module-catalog.md @@ -1,7 +1,7 @@ # LinxCore Module Catalog This chapter defines the canonical module structure for LinxCore under the live -`v0.4` superscalar contract. +`v0.56` superscalar contract. It freezes which module families own architectural behavior, which files are the canonical owners of those behaviors, and how those modules compose into the @@ -175,9 +175,6 @@ metadata, and UID allocation required by the stage, block, and trace contracts. - Owns `D2`. - Performs rename request/translation preparation and resolves ROB-visible boundary metadata for `BSTART` and `BSTOP`. -- Also resolves immediate-only return-target producers `SETRET` and - `C.SETRET`, which bypass IQ ownership and complete from the D2 path. - ### `src/bcc/ooo/ren.py` - Owns `D3`. @@ -392,13 +389,25 @@ metadata, and UID allocation required by the stage, block, and trace contracts. ## Engine and accelerator modules +### `src/csu/subsystem.py` + +- Owns the unified CSU parent subsystem that absorbs IFU refill traffic and + CSU-internal TMA transport ownership. + +### `src/csu/{tma_cmd_frontend,tma_ctx_tracker,tma_l2_client,client_arb}.py` + +- Own the CSU-internal TMA command ingress, context tracking, L2-client + translation, and refill-versus-TMA arbitration boundaries. + ### `src/vec/vec.py` - Owns the `VEC` engine boundary. ### `src/tma/tma.py` -- Owns the `TMA` engine boundary. +- Remains the standalone compatibility facade for isolated TMA unit tests. +- Janus top-level integration no longer treats it as the normative southbound + transport owner. ### `src/cube/cube.py` diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 797fb560..b01b5706 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -1,9 +1,9 @@ -# LinxCore v0.4 Superscalar Bring-up Overview +# LinxCore v0.56 Superscalar Bring-up Overview ## Scope This document is the top-level specification overview for LinxCore under the -live LinxISA `v0.4` contract. +live LinxISA `v0.56` contract. LinxCore is specified here as: @@ -13,7 +13,7 @@ LinxCore is specified here as: - the owner of precise retirement, recovery, interrupt, MMU, and trace-visible execution behavior, - the machine that downstream compiler, emulator, pyCircuit, and testbench - work must target for canonical `v0.4` behavior. + work must target for canonical `v0.56` behavior. This specification is not a performance wish-list and not a historical bring-up log. It defines the live contract the implementation must preserve. @@ -25,9 +25,9 @@ glue. ## Normative links -- Base ISA architecture contract: `docs/architecture/v0.4-architecture-contract.md` -- Workload-to-engine model: `docs/architecture/v0.4-workload-engine-model.md` -- Rendering command model: `docs/architecture/v0.4-rendering-command-contract.md` +- Base ISA architecture contract: `docs/architecture/v0.56-architecture-contract.md` +- Workload-to-engine model: `docs/architecture/v0.56-workload-engine-model.md` +- Rendering command model: `docs/architecture/v0.56-rendering-command-contract.md` - LinxCore microarchitecture contract: `rtl/LinxCore/docs/architecture/microarchitecture.md` - LinxCore interface contract: `rtl/LinxCore/docs/architecture/interfaces.md` - LinxCore verification matrix: `rtl/LinxCore/docs/architecture/verification-matrix.md` @@ -57,22 +57,24 @@ stream, completion model, flush rules, and observability rules as scalar work. ## Architectural role in LinxISA -Under `v0.4`, LinxCore is the execution substrate for the multi-workload +Under `v0.56`, LinxCore is the execution substrate for the multi-workload LinxISA model. - BCC and the block fabric provide the architectural control and submission path. - `VEC` is the general programmable SIMT engine for parallel-loop work. -- `TMA`, `CUBE`, and `TAU` are integrated engines selected through the same - block model. +- `TMA` remains selected through the same block model, but its memory transport + is owned by the CSU subsystem rather than by a peer top-level engine shell. +- `CUBE` and `TAU` remain integrated engines selected through the same block + model. - Engine-backed work must retire, cancel, redirect, and trace through LinxCore rules rather than through a separate architectural domain. This composition rule is required for consistency with: -- `docs/architecture/v0.4-architecture-contract.md` -- `docs/architecture/v0.4-workload-engine-model.md` -- `docs/architecture/v0.4-rendering-command-contract.md` +- `docs/architecture/v0.56-architecture-contract.md` +- `docs/architecture/v0.56-workload-engine-model.md` +- `docs/architecture/v0.56-rendering-command-contract.md` ## Current architecture closure slice @@ -143,7 +145,7 @@ expand a mechanism, but they must not weaken or redefine the live contract. The live closure target for this specification is: -- LinxISA `v0.4` architectural behavior, +- LinxISA `v0.56` architectural behavior, - U + S privilege behavior, - MMU and interrupt correctness, - dual-lane reproducibility (`pin` and `external`), @@ -158,6 +160,6 @@ This overview does not freeze: - final frequency, area, or power targets, - future width scaling beyond the current live contract, -- future engine additions not already covered by the LinxISA `v0.4` +- future engine additions not already covered by the LinxISA `v0.56` architecture contract, - historical bring-up strategies that are no longer part of the live behavior. diff --git a/docs/architecture/pipeline-stage-catalog.md b/docs/architecture/pipeline-stage-catalog.md index b0877a80..4f907d68 100644 --- a/docs/architecture/pipeline-stage-catalog.md +++ b/docs/architecture/pipeline-stage-catalog.md @@ -75,9 +75,6 @@ remain backed by a real owner module. - Design role: rename request/translation stage and ROB-visible boundary resolution. - `BSTART` and `BSTOP` become architecturally visible here. -- `SETRET` and `C.SETRET` are also D2-resolved here and must not be sent into - IQ or late writeback ownership. - ### D3 - Owner module: `src/bcc/ooo/ren.py` (`JanusBccOooRen`) @@ -256,8 +253,13 @@ remain backed by a real owner module. ### TMA -- Owner module: `src/tma/tma.py` (`JanusTma`) -- Design role: tile-matrix engine command/response boundary. +- Owner modules: + - `src/csu/subsystem.py` (`JanusCsuSubsystem`) + - `src/csu/tma_cmd_frontend.py` (`JanusCsuTmaCmdFrontend`) + - `src/csu/tma_ctx_tracker.py` (`JanusCsuTmaCtxTracker`) + - `src/csu/tma_l2_client.py` (`JanusCsuTmaL2Client`) +- Design role: tile-matrix command/response boundary remains block-visible, but + southbound transport is owned inside the CSU subsystem. ### CUBE @@ -298,8 +300,13 @@ remain backed by a real owner module. ### TMA -- Owner module: `src/tma/tma.py` (`JanusTma`) -- Design role: matrix/tile accelerator execution boundary under block control. +- Owner modules: + - `src/csu/subsystem.py` + - `src/csu/tma_cmd_frontend.py` + - `src/csu/tma_ctx_tracker.py` + - `src/csu/tma_l2_client.py` +- Design role: matrix/tile accelerator execution boundary under block control + with CSU-owned L2 transport and completion aggregation. ### CUBE diff --git a/docs/architecture/verification-matrix.md b/docs/architecture/verification-matrix.md index 60c834db..fa4b6aa5 100644 --- a/docs/architecture/verification-matrix.md +++ b/docs/architecture/verification-matrix.md @@ -1,4 +1,4 @@ -# LinxCore v0.4 Verification Matrix +# LinxCore v0.56 Verification Matrix This matrix ties LinxCore architecture intent to strict required gates. diff --git a/tests/test_specint_full_xcheck_nightly.sh b/tests/test_specint_full_xcheck_nightly.sh index 82480130..b149ae27 100755 --- a/tests/test_specint_full_xcheck_nightly.sh +++ b/tests/test_specint_full_xcheck_nightly.sh @@ -36,9 +36,9 @@ if not isinstance(obj, dict): policy = obj.get("spec_policy") if not isinstance(policy, dict): raise SystemExit(f"error: missing spec_policy in: {path}") -stage_b = policy.get("stage_b_required") +stage_b = policy.get("promotion_required") if not isinstance(stage_b, list): - raise SystemExit(f"error: spec_policy.stage_b_required must be list in: {path}") + raise SystemExit(f"error: spec_policy.promotion_required must be list in: {path}") excluded = policy.get("excluded_benchmarks", []) excluded_set = set(str(x) for x in excluded) if isinstance(excluded, list) else set() for bench in stage_b: diff --git a/tests/test_specint_stage_a_xcheck.sh b/tests/test_specint_stage_a_xcheck.sh index 28a30d23..85a3c79e 100755 --- a/tests/test_specint_stage_a_xcheck.sh +++ b/tests/test_specint_stage_a_xcheck.sh @@ -9,12 +9,40 @@ SPEC_INPUT_SET="${SPEC_INPUT_SET:-test}" OUT_ROOT="${SPEC_XCHECK_OUT_ROOT:-${REPO_ROOT}/workloads/generated/spec2017/stage_a_xcheck}" POLICY_MANIFEST="${SPEC_POLICY_MANIFEST:-${REPO_ROOT}/docs/bringup/agent_runs/manifest.yaml}" -BENCHES=( - "999.specrand_ir" - "505.mcf_r" - "531.deepsjeng_r" +mapfile -t BENCHES < <(python3 - "${POLICY_MANIFEST}" <<'PY' +import json +import sys +from pathlib import Path + +path = Path(sys.argv[1]) +text = path.read_text(encoding="utf-8") +obj = None +try: + obj = json.loads(text) +except json.JSONDecodeError: + try: + import yaml # type: ignore + except ImportError as exc: + raise SystemExit(f"error: failed to parse policy manifest as JSON and PyYAML is unavailable: {path}") from exc + obj = yaml.safe_load(text) +if not isinstance(obj, dict): + raise SystemExit(f"error: invalid policy manifest root: {path}") +policy = obj.get("spec_policy") +if not isinstance(policy, dict): + raise SystemExit(f"error: missing spec_policy in: {path}") +bringup = policy.get("bringup_subset") +if not isinstance(bringup, list): + raise SystemExit(f"error: spec_policy.bringup_subset must be list in: {path}") +for bench in bringup: + print(str(bench)) +PY ) +if [[ "${#BENCHES[@]}" -eq 0 ]]; then + echo "error: no bringup-subset benches resolved from ${POLICY_MANIFEST}" >&2 + exit 2 +fi + mkdir -p "${OUT_ROOT}" MATRIX_OUT="${OUT_ROOT}/qemu_matrix"