From 4f8a4f2ef213bb810220d6db4b96a6785054de43 Mon Sep 17 00:00:00 2001 From: LinxISA Automation Date: Thu, 30 Jul 2026 23:42:21 +0800 Subject: [PATCH 01/22] Bind LinxISA v0.57 to the normative PTO release Project the locked PTO 0.57.1 manifest into the Linx golden catalog and regenerate every checked-in decoder surface so Sail, QEMU, and C consume the same raw ABI. Constraint: PTO-ISA/pto-spec commit 852b537 is the sole source for 120 tile operations and 99 command forms. Rejected: Retain legacy TileOpcode decode or deleted D-class operations | the accepted design requires an explicit ABI break with reserved holes. Confidence: high Scope-risk: broad Reversibility: clean Directive: Use tools/isa/import_pto_v0571.py for future updates and repin leaf submodules only after their semantic gates pass. Tested: full ISA guard suite, Sail freshness and coverage, repository layout, git diff --check, independent code review Not-tested: Full executable Sail semantics and downstream LLVM/QEMU/RTL/kernel/libc migrations remain separate leaf PRs. --- docs/architecture/README.md | 1 + .../pto-isa-v0.57.1-upgrade-plan.md | 200 + isa/generated/codecs/linxisa32.decode | 722 +- isa/generated/codecs/linxisa_opcodes.c | 4747 ++++---- isa/sail/coverage.json | 727 +- isa/sail/model/decode/decode.sail | 800 +- isa/sail/semantics_status.json | 24 +- isa/v0.57/encoding/fields.json | 6 +- isa/v0.57/encoding/retired_encodings.json | 21 +- isa/v0.57/linxisa-v0.57.json | 2 +- isa/v0.57/meta.json | 13 +- isa/v0.57/opcodes/lx_32.opc | 17 +- isa/v0.57/pto-spec.lock.json | 27 + isa/v0.57/release_manifest.json | 515 +- isa/v0.57/state/engine_ops.json | 4188 +++++-- isa/v0.57/state/pto_command_forms.json | 5349 +++++++++ isa/v0.57/state/pto_encoding_map.json | 1460 +-- isa/v0.57/state/pto_ops.json | 9681 ++++++++++------- .../CMD/BLOCK_SPLIT.json | 15 +- tools/isa/build_golden.py | 63 + tools/isa/check_canonical_v057.py | 12 +- tools/isa/check_pto_v057_manifest.py | 372 +- tools/isa/gen_sail_status.py | 2 +- tools/isa/import_pto_v0571.py | 341 + tools/isa/test_gen_sail_decode.py | 22 +- tools/isa/test_golden_contract.py | 19 +- tools/isa/test_v057_profile.py | 77 +- tools/isa/validate_spec.py | 59 + 28 files changed, 20417 insertions(+), 9065 deletions(-) create mode 100644 docs/architecture/pto-isa-v0.57.1-upgrade-plan.md create mode 100644 isa/v0.57/pto-spec.lock.json create mode 100644 isa/v0.57/state/pto_command_forms.json create mode 100644 tools/isa/import_pto_v0571.py diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 64249b2c..c8018019 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -5,6 +5,7 @@ Architecture-facing documentation lives under `docs/architecture/`. ## Canonical contract pages - v0.57 canonical pages: + - `docs/architecture/pto-isa-v0.57.1-upgrade-plan.md` (accepted cross-repository implementation plan; pto-spec remains normative) - `docs/architecture/v0.57-architecture-contract.md` - `docs/architecture/v0.57-encoding-decisions.md` - `docs/architecture/v0.57-hardening-policy.md` diff --git a/docs/architecture/pto-isa-v0.57.1-upgrade-plan.md b/docs/architecture/pto-isa-v0.57.1-upgrade-plan.md new file mode 100644 index 00000000..b800c07b --- /dev/null +++ b/docs/architecture/pto-isa-v0.57.1-upgrade-plan.md @@ -0,0 +1,200 @@ +# PTO ISA 0.57.1 upgrade plan + +Status: accepted implementation plan + +Decision date: 2026-07-30 + +## Authority and release identity + +[`PTO-ISA/pto-spec`](https://github.com/PTO-ISA/pto-spec) is the sole +normative source for PTO ISA 0.57.1. LinxISA and DavinciOO are projections and +implementations of the locked pto-spec release manifest; neither repository may +override an encoding, operation signature, fault rule, or conformance vector. + +The upgrade starts from these fetched upstream commits: + +| Repository | Baseline | +| --- | --- | +| `PTO-ISA/pto-spec` | `8054a21fc7f98318f936b1dff9d2132b2aa990be` | +| `LinxISA/linx-isa` | `98c08198a83ca03a832514b2b5cca27d4c30fa6d` | +| `hengliao1972/DavinciOO` | `da1c1f7bf276b223fc49acf7027a46409620e017` | + +PTO ISA 0.57.1 is an encoding-ABI break despite the patch release number. An +object or executable must carry the architecture release and canonical +encoding-manifest identity. Producers, linkers, loaders, and bare-metal launch +manifests reject missing, old, mixed, or mismatched identities. There is no +untagged dual decoder; legacy source is reassembled or recompiled. + +## Frozen architecture delta + +### Direct operations + +The base inventory is exactly 120 operations: 98 TEPL, 9 TMA, and 13 CUBE, +with zero optional direct operations. + +- Delete and reserve `TFMA`, `TFMOD`, `TFMODS`, `TADDC`, `TSUBC`, `TADDSC`, + `TSUBSC`, `TLRELU`, and `TRANDOM`. +- Use canonical `TTRANS` and `TSORT`; `TTRANSPOSE` and `TSORT32` are + source-migration aliases only. +- Add `TPARTARGMAX`, `TPARTARGMIN`, `TRESHAPE`, `TDEINTERLEAVE`, + `TINTERLEAVE`, `TPUSH`, `TPOP`, `TALLOC`, and `TFREE` at Mode 3 Functions + 21 through 29. +- TMA Functions 0 through 8 are `TLOAD`, `TSTORE`, `TMOV`, `TPREFETCH`, + `MGATHER`, `MSCATTER`, `MGATHER.MASK`, `MSCATTER.MASK`, and `MGATHER.CAS`. +- All 13 CUBE functions are base identities. ACC access is selected by the + CUBE function, not by a B.IOT operand. + +### Raw command formats + +| Form | 0.57.1 contract | +| --- | --- | +| `BSTART.TEPL` | `DataType[31:27]`, `Mode[26:25]`, `Function[24:20]`, fixed low pattern `0x00019181`; mask `0x000fffff` | +| `B.IOT` | `Src1[31:26]`, `Src0[25:20]`, `L[19]`, `imm4[18:15]`, `S1R[11]`, `S0R[10]`, `Dst[9:7]` | +| `B.DATR` | `CMode[31:29]`, `PadValueOrByteId[28:27]`, `Sat[26]`, `Canonicalize[25]`, `DataType[24:20]`, `RMode[17:15]`, `Layout[11:7]` | +| `B.CATR` | `DR[26]`, `trap[19]`, `far[18]`, `atom[17]`, `aq[16]`, `rl[15]`; all other dynamic high fields zero | + +The TEPL logical selector is `(Mode << 5) | Function`. All 128 selector +positions are classified as one of 98 accepted or 30 reserved positions. +DataType code 31 is illegal. Complete `DataType × Mode × Function` evidence +must classify all 4096 header values without collision or fallback. + +`B.IOD`, generic public `BSTART.TLSU`, generic unallocated `BSTART.CUBE`, and +`BSTART.FIXP` are not executable 0.57.1 forms. Typed +`BSTART. DataType` is canonical. TMA descriptors are owned by +the operation schema plus B.IOR, B.DATR, and applicable B.DIM fields, not by +the six legacy TMA-oriented B.ARG forms. + +### State and completion + +- CELL is 128 bytes; each PE exposes exactly 2048 CELL, or 256 KiB, of Tile + capacity. B.IOT size codes 3 through 9 mean 128 B through 8 KiB. Resource + exhaustion is a precise allocation fault; no silent eviction or spill is + architectural. +- `reuse=0` releases a source only after successful consumer commit; + `reuse=1` retains it. Fault, retry, and squash preserve source lifetime. +- ACC is implicit architectural state. B.IOT destination codes 4 through 6 + remain reserved and 7 is illegal. Ordinary/BIAS CUBE functions initialize + ACC, `.ACC` functions read/write it, and ACCCVT publishes a Tile and releases + ACC only after successful commit. Trap context includes ACC. +- NORM layout is mandatory. ND/DN/ZN/NZ conversion codes are capability + gated; an unsupported accepted layout faults precisely before effects. +- A false mask lane performs no access or fault check. Masked gather writes + B.DATR PadValue to inactive destination lanes. Multi-access operations + preflight all active accesses and commit no partial state on failure. +- Non-atomic duplicate-address scatter has an unspecified winning active lane + after complete successful preflight. PTO-TSO and B.CATR define ordering; + dependency metadata is not a fence. +- The hardware conformance profile is IEEE-754 with canonical quiet NaN and + IEEE signed zero. The deterministic raw-carrier model remains a separately + identified reference-test profile. +- TSORT is stable over 32-element groups and produces values plus U32 original + indices. NaNs follow numeric values while retaining input order. + +## Baseline differences that must close + +### pto-spec + +The baseline already has the right 98/9/13 names, but 80 of 98 TEPL selectors +use the old 10-bit layout. B.IOT, B.DATR, and B.CATR are also old. Raw BSTART +decode is not connected to direct Tile execution; reuse fields have no commit +effect; capacity is 512 KiB; ACC and layout capabilities are absent; masked +gather preserves stale destination data; and binary closure omits Tile/catalog +and semantic content. The release PR must close those behaviors in ASL, not +only update catalog rows. + +### LinxISA + +The baseline golden release is 0.57.0. `pto_ops.json` still derives 111 rows +from the old workbook, while `engine_ops.json` has 120 names but 55 pending +semantic records and the old raw ABI. Sail reports zero PTO operations as +architecturally complete. LLVM, PTOAS, QEMU, LinxCore, the C++ models, kernel, +glibc, and musl have independent copies of encodings or ABI assumptions. + +### DavinciOO + +The latest `isa/intrinsic` tree has no delta between its local intrinsic commit +and fetched `origin/main`, but its workbook contains only 87 TEPL, 5 TMA, and +8 CUBE rows. It includes deleted operations, misses retained PTO operations, +contains a duplicate/wrong TSEL assignment, and describes legacy B.IOD, +TPREFETCH, ACC, layout, and descriptor rules. Nearly all authored and generated +intrinsic content contains Linx branding, and generation has neither a locked +pto-spec input nor an exact-file-set check. + +## PR dependency graph + +```mermaid +flowchart TD + PTO["pto-spec: normative 0.57.1 + manifest"] --> GOLDEN["LinxISA golden + validators + Sail"] + PTO --> DAV["DavinciOO neutral intrinsic projection"] + GOLDEN --> PROD["LLVM + PTOAS producers and ABI tags"] + GOLDEN --> EXEC["QEMU + RTL + model consumers"] + PROD --> LOAD["LLD + kernel + glibc + musl identity rejection"] + EXEC --> AVS["AVS differential and semantic gates"] + LOAD --> AVS + AVS --> PIN["Superproject leaf SHA repin and release promotion"] +``` + +The normative pto-spec PR merges first. Every downstream PR locks its exact +commit and manifest hash. The LinxISA superproject repins only leaf commits +whose local gates passed; it never points at unmerged or unverified semantic +work. + +## Repository ownership and gates + +| Lane | Required output | Blocking evidence | +| --- | --- | --- | +| pto-spec | ADR, catalogs, executable ASL, requirements, release manifest, vectors | repository checks, strict ASL typecheck/tests, 4096 totality, zero pending, stable regeneration | +| Linx golden/Sail | locked pto manifest, 0.57.1 golden, decode and architectural semantics | golden validator, 120 raw positives, retired negatives, Sail typecheck/tests | +| LLVM/PTOAS | canonical assembly/IR lowering, release/hash ELF attribute | MC roundtrip, CodeGen, mixed/missing ABI link rejection | +| QEMU | exact decode, preflight/commit, ACC/lifetime/mask behavior | AVS QEMU Tile suites and pto-spec vector parity | +| LinxCore/models | generated identifiers and commit/fault interfaces | unit tests plus QEMU/model differential vectors | +| kernel/libc loaders | release/hash enforcement | matching acceptance and missing/old/mixed/hash-mismatch rejection | +| DavinciOO | neutral locked projection, 120 pages/rows, deterministic site/workbook | exact owned set, zero Linx token including XLSX, selector/vector parity | +| superproject | verified submodule SHAs and run manifest | layout check, pin/external lanes, full benchmark/QEMU/Linux flow | + +## Submodule synchronization matrix + +The following leaf repositories contain an ISA producer, consumer, loader, or +conformance surface and require a reviewed commit before final repin: + +| Submodule | Upgrade responsibility | +| --- | --- | +| `compiler/llvm` | assembler, disassembler, MC/CodeGen, ELF attribute, LLD checks, MLIR PTO dialect | +| `compiler/ptoas` | PTO IR/bytecode identities, typed TMA lowering, manifest gate | +| `emulator/qemu` | decode and executable Tile semantics | +| `rtl/LinxCore` | generated decode/catalog and precise commit/fault interface | +| `tools/model` | generated tables and architectural reference state | +| `tools/LinxCoreModel` | remove D operations and ACC-as-B.IOT assumptions | +| `kernel/linux` | ELF loader identity rejection and trap/context ABI | +| `lib/glibc` | dynamic-loader identity check | +| `lib/musl` | dynamic-loader identity check | +| `workloads/pto_kernels` | recompile and semantic parity vectors | + +`tools/pyCircuit`, `workloads/SuperNPUBench`, and other workload/RTL-facing +submodules are repinned only if their generated artifacts or rebuild evidence +changes. Existing user-owned submodule worktrees are never overwritten by the +upgrade branch. + +## Completion criteria + +The release is complete only when all of the following hold: + +1. All three top-level repositories report the same pto-spec commit, release, + encoding ABI ID, and canonical content hash. +2. The 120 base operations have machine-readable operands, legality, effects, + faults, restart, state-access, semantic handler, and executable evidence; + pending and optional counts are zero. +3. Accepted, reserved, illegal, deleted, old-ABI, and six semantic-collision + raw words are covered by positive or negative evidence without heuristic + decode. +4. Fault/retry/squash preserve Tile lifetime and ACC, and multi-access faults + produce no partial effects. +5. Compiler, assembler, linker, loader, QEMU, RTL/model, Sail, and DavinciOO + projections agree byte-for-byte or effect-for-effect with pto-spec vectors. +6. Generated source, documentation, workbook, and site checks are stable on a + second run and reject extra stale files. +7. DavinciOO public intrinsic content contains no Linx ISA branding, including + compressed XLSX strings. +8. Every required leaf PR is merged or pinned to an explicitly reviewed commit, + the superproject layout gate passes, and the benchmark/QEMU/Linux bring-up + manifest records the final SHA set. diff --git a/isa/generated/codecs/linxisa32.decode b/isa/generated/codecs/linxisa32.decode index 236aa721..0d8eaf62 100644 --- a/isa/generated/codecs/linxisa32.decode +++ b/isa/generated/codecs/linxisa32.decode @@ -4,24 +4,25 @@ # Fields %ACR_ID 15:10 %B_E 15:1 -%CMode 25:3 +%CMode 29:3 %CROSS_BID 25:7 +%Canonicalize 25:1 %DR 26:1 -%DataLayout 7:5 %DataType_20_5 20:5 %DataType_27_5 27:5 %DstBegin 15:5 %DstEnd 20:5 -%DstTile 22:3 +%DstTile 7:3 %DstType 27:5 %Function 20:5 -%L 29:1 +%L 19:1 %LSR_ID 20:12 %L_UL 16:1 +%Layout 7:5 %Mode 25:2 %PRED_IMM 24:4 -%PadValue 15:5 -%RMode 28:3 +%PadValueOrByteId 27:2 +%RMode 15:3 %RRA_Type 20:4 %RST_Type 20:4 %RegDst 7:5 @@ -29,11 +30,11 @@ %RegSrc0 15:5 %RegSrc1 20:5 %RegSrc2 27:5 -%S0R 30:1 -%S1R 31:1 +%S0R 10:1 +%S1R 11:1 %SSR_ID 20:12 %SUCC_IMM 20:4 -%Sat 31:1 +%Sat 26:1 %SrcA 27:5 %SrcBegin 15:5 %SrcD 27:5 @@ -42,26 +43,26 @@ %SrcP 27:5 %SrcR 20:5 %SrcRType 25:2 -%SrcTile0 15:1 7:5 -%SrcTile1 16:6 +%SrcTile0 20:6 +%SrcTile1 26:6 %SrcType 25:2 %SrcZero 20:5 -%TileOpcode 15:10 %V 15:1 +%aq_16_1 16:1 %aq_26_1 26:1 -%aq_29_1 29:1 -%atom 30:1 -%far 27:1 +%atom 17:1 +%far_18_1 18:1 +%far_27_1 27:1 %format 7:5 %imm20 12:20 +%imm4_15_4 15:4 %imm4_24_4 24:4 -%imm4_25_4 25:4 %imml 20:6 %immr 26:6 %imms 26:6 %prefetch_size 20:12 +%rl_15_1 15:1 %rl_25_1 25:1 -%rl_28_1 28:1 %shamt_20_5 20:5 %shamt_20_6 20:6 %shamt_27_5 27:5 @@ -74,7 +75,7 @@ %simm22 7:s5 15:17 %simm25 7:s25 %temp 17:2 -%trap 31:1 +%trap 19:1 %uimm 7:5 25:7 %uimm12 20:12 %uimm17 7:5 20:12 @@ -136,10 +137,10 @@ b_arg_32_c6d5c49a4ad7 0001 1000 0000 0010 0010 0100 0010 0011 b_arg_32_f19d18f2126b 0001 1000 0000 0000 1010 0100 1010 0011 # B.CATR | B.CATR {trap, atomic, , far, dr} | opcodes/lx_32.opc:23 -b_catr_32_e90bd52fa480 .... ..00 0000 0000 0000 0000 0010 0011 %DR aq=%aq_29_1 %atom %far rl=%rl_28_1 %trap +b_catr_32_8f94bdb16d29 0000 0.00 0000 .... .000 0000 0010 0011 %DR aq=%aq_16_1 %atom far=%far_18_1 rl=%rl_15_1 %trap -# B.DATR | B.DATR {layout.{canon, normal}, datatype, padvalue, cmode, rmode, sat} | opcodes/lx_32.opc:24 -b_datr_32_c161a042ff38 .... .... .... .... .001 .... .010 0011 %CMode %DataLayout DataType=%DataType_20_5 %PadValue %RMode %Sat +# B.DATR | B.DATR {layout, datatype, padvalue_or_byteid, cmode, rmode, sat, canonicalize} | opcodes/lx_32.opc:24 +b_datr_32_840f4b8d579d .... .... .... 00.. .001 .... .010 0011 %CMode %Canonicalize DataType=%DataType_20_5 %Layout %PadValueOrByteId %RMode %Sat # B.DIM | B.DIM RegSrc, uimm, ->LB2 | opcodes/lx_32.opc:31 b_dim_32_1caa1aa2944a .... .... .... .... .010 .... .100 0011 %RegSrc %uimm17 @@ -169,19 +170,19 @@ b_hint_32_f7d01d734925 0000 0000 0000 0000 .001 0000 0011 0011 %B_E b_ior_32_c3ea71404eb3 .... .00. .... .... .000 .... .001 0011 %RegDst %RegSrc0 %RegSrc1 %RegSrc2 # B.IOT | B.IOT SrcTile0<.reuse>, , ->DstTile | opcodes/lx_32.opc:41 -b_iot_32_10db6db84f5d 0... .... ..00 0000 .101 .... .001 0011 %DstTile %L %S0R %SrcTile0 imm4=%imm4_25_4 - -# B.IOT | B.IOT SrcTile0<.reuse>, SrcTile1<.reuse>, | opcodes/lx_32.opc:43 -b_iot_32_2c07e7177fad ...0 0001 11.. .... .100 .... .001 0011 %L %S0R %S1R %SrcTile0 %SrcTile1 +b_iot_32_0f23e46d6176 0000 00.. .... .... .101 0... .001 0011 %DstTile %L %S0R %SrcTile0 imm4=%imm4_15_4 # B.IOT | B.IOT SrcTile0<.reuse>, SrcTile1<.reuse>, , ->DstTile | opcodes/lx_32.opc:40 -b_iot_32_8b8bce6bffe8 .... .... .... .... .100 .... .001 0011 %DstTile %L %S0R %S1R %SrcTile0 %SrcTile1 imm4=%imm4_25_4 +b_iot_32_3a6945dec034 .... .... .... .... .100 .... .001 0011 %DstTile %L %S0R %S1R %SrcTile0 %SrcTile1 imm4=%imm4_15_4 # B.IOT | B.IOT SrcTile0<.reuse>, | opcodes/lx_32.opc:44 -b_iot_32_c11eb189dd83 0..0 0001 1100 0000 .101 .... .001 0011 %L %S0R %SrcTile0 +b_iot_32_778f84340400 0000 00.. .... .000 0101 0.00 0001 0011 %L %S0R %SrcTile0 # B.IOT | B.IOT , ->DstTile | opcodes/lx_32.opc:42 -b_iot_32_efa0fe3fe49a 00.. .... ..00 0000 0110 0000 0001 0011 %DstTile %L imm4=%imm4_25_4 +b_iot_32_a06b9b6c1965 0000 0000 0000 .... .110 00.. .001 0011 %DstTile %L imm4=%imm4_15_4 + +# B.IOT | B.IOT SrcTile0<.reuse>, SrcTile1<.reuse>, | opcodes/lx_32.opc:43 +b_iot_32_f1ca66bbcce1 .... .... .... .000 0100 ..00 0001 0011 %L %S0R %S1R %SrcTile0 %SrcTile1 # B.LT | b.lt SrcL, SrcR, label | opcodes/lx_32.opc:45 b_lt_32_2ca5ecd25cfb .... .... .... .... .010 .... .010 0111 %SrcL %SrcR simm12=%simm12_7_s5_25_7 @@ -231,863 +232,860 @@ bstart_call_32_9404418d1ae5 0101 0... ..01 0110 .... .... .... 0010 simm12=%simm # BSTART.ACCCVT | BSTART.ACCCVT DataType | opcodes/lx_32.opc:66 bstart_acccvt_32_56c3ce3838c5 .... .000 1000 0011 0001 0001 1000 0001 DataType=%DataType_27_5 -# BSTART.CUBE | BSTART.CUBE Function, DataType | opcodes/lx_32.opc:67 -bstart_cube_32_bd3f337acb9d .... .00. .... 0011 0001 0001 1000 0001 DataType=%DataType_27_5 %Function - -# BSTART.FIXP | BSTART.FIXP TileOp, DataType | opcodes/lx_32.opc:68 +# BSTART.FIXP | BSTART.FIXP TileOp, DataType | opcodes/lx_32.opc:67 bstart_fixp_32_3b0ae11126a6 .... .00. .... 0011 1001 0001 1000 0001 DataType=%DataType_27_5 %Function -# BSTART.FP | BSTART.FP RET | opcodes/lx_32.opc:69 +# BSTART.FP | BSTART.FP RET | opcodes/lx_32.opc:68 bstart_fp_32_0c671a644214 0000 0000 0000 0000 0111 0001 0000 0001 -# BSTART.FP | BSTART.FP ICALL | opcodes/lx_32.opc:73 +# BSTART.FP | BSTART.FP ICALL | opcodes/lx_32.opc:72 bstart_fp_32_24db3966d6ba 0000 0000 0000 0000 0110 0001 0000 0001 -# BSTART.FP | BSTART.FP COND,