diff --git a/README.md b/README.md index ffec7ad..d503c3f 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,15 @@ # Linx TileOP API -Header-only C++ TileOP bindings for the LinxISA / PTO ISA 0.59.0 architectural contract. -The checked-in catalog and documentation are generated against the reviewed -PTO ISA 0.59.0 development golden (`development-not-published`, ABI -`pto-isa-0.58.7-mode-function-v1`). +Header-only C++ TileOP bindings for the LinxISA / PTO ISA 0.59.0 architectural +contract. The checked-in catalog and documentation are generated against the +published PTO ISA `v0.59.0.0` release (commit `b016532`, ABI +`pto-isa-0.59.0-mode-function-v1`). The release manifest records +`specification_status: draft` and limits implementation conformance to +`b-fpatr-and-tcvt-e8m0-asl-proven-other-numeric-domains-unproven`; this binding +carries that identity without claiming a finalized specification or full +numeric conformance. The semantic engine inventory remains the LinxISA v0.58 +authority projection, whose 119-operation Tile catalog is byte-identical to the +release catalog. Installed headers expose their provenance through ``. `PTO_TILEOP_API_VERSION` and @@ -13,7 +19,7 @@ Installed headers expose their provenance through allow consumers to reject toolchains that predate a required fix. The normative operation inventory comes from the checked-in PTO catalog at -[`contracts/pto-isa-0.58.7-tile-operations.json`](contracts/pto-isa-0.58.7-tile-operations.json). +[`contracts/pto-isa-0.59.0-tile-operations.json`](contracts/pto-isa-0.59.0-tile-operations.json). The public bindings retain the unique compiled `BSTART.TEPL` carrier for VEC/SFU source compatibility and emit the named TLSU/CUBE operation forms accepted by the current Linx compiler. The generated engine index is a wrapper compatibility @@ -44,12 +50,14 @@ historical migration fixtures under `test/tileop_api` and `docs/tileop-usage/migration/pto-0583-migration.md`; it is not the current API baseline. Run the catalog and documentation checks before target compilation. -To refresh the pinned projection from the clean, exact reviewed LinxISA -authority commit recorded by the generator: +To refresh the pinned projection, provide the clean, exact reviewed LinxISA +v0.58 authority commit together with a clean checkout of `PTO-ISA/pto-spec` at +the `v0.59.0.0` release commit: ```sh -python3 tools/sync_linxisa_v058_contract.py \ - /path/to/linx-isa/isa/v0.58/linxisa-v0.58.json +python3 tools/sync_pto_isa_0590_contract.py \ + /path/to/linx-isa/isa/v0.58/linxisa-v0.58.json \ + --pto-root /path/to/pto-spec python3 tools/generate_engine_docs.py make check ``` diff --git a/contracts/README.md b/contracts/README.md index 95a1be8..2d2eef6 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -1,17 +1,23 @@ # LinxISA contract projections -`pto-isa-0.58.7-tile-operations.json` is the checked-in machine-readable snapshot -of the reviewed PTO ISA 0.58.7 development Tile catalog. It records all 119 accepted direct +`pto-isa-0.59.0-tile-operations.json` is the checked-in machine-readable snapshot +of the published PTO ISA 0.59.0.0 release Tile catalog. It records all 119 accepted direct operations plus the catalog's deleted and rejected inventories. Its source of truth is `PTO-ISA/pto-spec/spec/catalog/tile-operations.json`; refresh it only -from commit `f0a876e449a95d26841c5ee7affb4c905ebc5f5b` and review the resulting diff. +from the `v0.59.0.0` release commit `b0165320a4b575b18d2f4d93faf40178f661ab49` +and review the resulting diff. These bytes are identical to the PTO 0.58.7 +development golden catalog (SHA-256 533db9b8...); only the surrounding encoding +identity moved to the release. -`linxisa-v0.58-engine-ops.json` is a generated, provenance-pinned LinxISA/PTO -0.58.7 development projection. It records operation ownership and encodings; -it does not claim that this repository implements every projected operation: +`linxisa-v0.58-engine-ops.json` is a generated, provenance-pinned projection of +the LinxISA v0.58 authority onto the PTO ISA 0.59.0.0 release encoding identity. +It records operation ownership and encodings; it does not claim that this +repository implements every projected operation. There is no LinxISA 0.59 +profile, so the LinxISA `source` stays v0.58 and the development-golden lock it +carried is preserved under `pto_source.development_lock`: ```bash -python3 tools/sync_linxisa_v058_contract.py \ +python3 tools/sync_pto_isa_0590_contract.py \ /path/to/linx-isa/isa/v0.58/linxisa-v0.58.json \ --pto-root /path/to/pto-spec ``` diff --git a/contracts/linxisa-v0.58-engine-ops.json b/contracts/linxisa-v0.58-engine-ops.json index 0481f29..3da686e 100644 --- a/contracts/linxisa-v0.58-engine-ops.json +++ b/contracts/linxisa-v0.58-engine-ops.json @@ -110,23 +110,36 @@ ], "profile": "v0.58", "pto_source": { - "commit": "f0a876e449a95d26841c5ee7affb4c905ebc5f5b", - "development_manifest": { - "path": "spec/development-manifest.json", - "sha256": "0c6d0b2a1ec0b49e32e13971e751a5ea19946351a3880bfdfcef0f50351944f7" - }, - "encoding_abi": "pto-isa-0.58.7-mode-function-v1", - "encoding_projection_sha256": "a5f78ecd707bde4a014542158ea257c783796b95fa4fbcce37742e41fee6a881", - "publication": null, - "release": "0.58.7", + "commit": "b0165320a4b575b18d2f4d93faf40178f661ab49", + "content_sha256": "a3e71975e7f753864f7ec09c57515e60f5a6e3e72dfdbce8e444c815a20b2835", + "development_lock": { + "catalog_sha256_matches_release": true, + "commit": "f0a876e449a95d26841c5ee7affb4c905ebc5f5b", + "development_manifest": { + "path": "spec/development-manifest.json", + "sha256": "0c6d0b2a1ec0b49e32e13971e751a5ea19946351a3880bfdfcef0f50351944f7" + }, + "note": "The LinxISA v0.58 authority locked the PTO development golden; its Tile catalog bytes equal the 0.59.0.0 release Tile catalog (both SHA-256 533db9b8...), so the v0.58 engine projection remains valid against the published release.", + "release": "0.58.7", + "tree": "fe9e8e050375fbce3f526d08acca13c37cd15830" + }, + "encoding_abi": "pto-isa-0.59.0-mode-function-v1", + "encoding_projection_sha256": "91509080ca656eb124f47830dcb09c50389dc177266b3b8df9d2d11dc37d5697", + "publication_version": "0.59.0.0", + "release": "0.59.0", + "release_manifest": { + "path": "spec/release-manifest.json", + "sha256": "3c6b20623e73822c0bd26021c10beb233b8809328b5515f57609eadad1749dc4" + }, + "release_tag": "v0.59.0.0", "repo": "https://github.com/PTO-ISA/pto-spec.git", - "status": "development-not-published", + "specification_status": "draft", "tile_catalog": { "count": 119, "path": "spec/catalog/tile-operations.json", "sha256": "533db9b8f31f118af5978de813cfaa3fa738de820ee24655faa2ee71f343a706" }, - "tree": "fe9e8e050375fbce3f526d08acca13c37cd15830" + "tree": "31ff0c2d39cbed714baf5be7929bfd06887be9fb" }, "schema": "linx-tileop-api.engine-ops-projection.v2", "semantic_engine_counts": { diff --git a/contracts/pto-isa-0.58.7-tile-operations.json b/contracts/pto-isa-0.59.0-tile-operations.json similarity index 100% rename from contracts/pto-isa-0.58.7-tile-operations.json rename to contracts/pto-isa-0.59.0-tile-operations.json diff --git a/docs/tileop-usage/README.md b/docs/tileop-usage/README.md index 7da9568..164dfc3 100644 --- a/docs/tileop-usage/README.md +++ b/docs/tileop-usage/README.md @@ -6,16 +6,20 @@ ## 版本与兼容性 -本目录当前以 PTO-ISA/pto-spec 的 **0.59.0** 架构规范为对照基线： +本目录当前以 PTO-ISA/pto-spec 的 **0.59.0.0** 发布规范为对照基线： - architecture version：`0.59.0` - publication version：`0.59.0.0` -- stable release commit：`de57af400cf607f03730aa522a4e9bfb160596de` - release tag：`v0.59.0.0` -- encoding ABI：`pto-isa-0.58.7-mode-function-v1` - -PTO `main` 是开发分支；需要可复现构建时应锁定上面的 release commit。本文档描述 -的是架构规范和本仓库 wrapper 的交集，并不表示 wrapper 已实现 0.59.0 的全部操作。 +- release commit：`b0165320a4b575b18d2f4d93faf40178f661ab49` +- encoding ABI：`pto-isa-0.59.0-mode-function-v1` +- specification status：`draft`（发布 manifest 自身记为 draft，实现 conformance 限定为 + `b-fpatr-and-tcvt-e8m0-asl-proven-other-numeric-domains-unproven`） + +PTO `main` 是开发分支；需要可复现构建时应锁定上面的 release commit。119 个操作的 +Tile catalog 与 PTO 0.58.7 development golden 逐字节一致，只是 encoding identity 移到了 +发布版本。本文档描述的是架构规范和本仓库 wrapper 的交集，并不表示 wrapper 已实现 +0.59.0 的全部操作，也不表示该发布规范已最终定稿或数值 conformance 已全部证明。 每个操作页中的 C++ 签名以本仓库头文件为准，PTO ASL/NDF 是架构合法性的权威来源。 [0.58.3 迁移说明](migration/pto-0583-migration.md)是历史文档，保留用于迁移旧 @@ -153,7 +157,7 @@ clang++ --target=linx64v5-unknown-linux-musl -mlxbc -fenable-matrix \ 也在该页面说明。 - 常规逐元素算子从 [TADD](elementwise-tile-tile/arithmetic/TADD.md) 开始；按目录选择 算术、逻辑、转换、归约、布局和不规则操作。 -- PTO ISA v0.59.0 的 CUBE layout 重排操作从 +- PTO ISA 0.59.0 的 CUBE layout 重排操作从 [TPERMUTE](layout-and-rearrangement/layout/TPERMUTE.md) 开始； [TSHUF](layout-and-rearrangement/layout/TSHUF.md)、 [TPACK](layout-and-rearrangement/layout/TPACK.md)、 diff --git a/docs/tileop-usage/generated/engines.md b/docs/tileop-usage/generated/engines.md index e5f379e..e91aa8f 100644 --- a/docs/tileop-usage/generated/engines.md +++ b/docs/tileop-usage/generated/engines.md @@ -1,13 +1,14 @@ -# LinxISA / PTO ISA v0.59.0 wrapper engine compatibility view +# LinxISA v0.58 / PTO ISA 0.59.0.0 wrapper engine compatibility view 架构定义的引擎类别只有 **VEC**, **TLSU**, **CUBE**, and **SFU**。 VEC 只包含逐元素操作；SFU 包含归约、广播、变换、排序以及其他需要更复杂硬件的操作。 TEPL 仍是唯一的编译 carrier 标识。`BSTART.VEC` 和 `BSTART.SFU` 是特定引擎的汇编别名； inline wrapper 保留 `BSTART.TEPL`，以兼容之前的工具链源码。 -下表根据本仓库固定的 LinxISA/PTO development golden 投影生成，数据记录在 +下表根据本仓库固定的 LinxISA v0.58 authority 投影生成（其操作清单与 PTO ISA 0.59.0.0 +发布 catalog 逐字节一致），数据记录在 [`contracts/linxisa-v0.58-engine-ops.json`](../../../contracts/linxisa-v0.58-engine-ops.json) 中。 -Golden 共 119 项；其中 119 项在 `include/` 有名称引用， +投影共 119 项；其中 119 项在 `include/` 有名称引用， 0 项明确没有 wrapper。名称引用不证明 ASL/NDF 语义完整实现。 ## VEC @@ -152,7 +153,8 @@ Golden 共 119 项；其中 119 项在 `include/` 有名称引用， ## 分类语义 PTO ISA 0.59.0 将执行引擎与操作分类解耦。本表是 wrapper compatibility view； -其底层投影记录当前 development golden selector 数据。`elementwise-tile-tile` +其底层投影记录 LinxISA v0.58 authority 的 selector 数据（与 0.59.0.0 发布 catalog 一致）。 +`elementwise-tile-tile` 和 `tile-scalar-and-immediate` 类别在 VEC 上执行逐元素操作，但其中的 `TEXP`、`TLOG`、`TRECIP`、`TSQRT`、`TRSQRT` 由 SFU 执行。 `reduce-and-expand`、`layout-and-rearrangement` 和 `irregular-and-complex` 类别由 SFU 执行。 diff --git a/docs/tileop-usage/support-status.md b/docs/tileop-usage/support-status.md index fd9da05..772a4a5 100644 --- a/docs/tileop-usage/support-status.md +++ b/docs/tileop-usage/support-status.md @@ -1,6 +1,6 @@ # PTO ISA 0.59.0 wrapper 支持状态 -本表以 `contracts/pto-isa-0.58.7-tile-operations.json` 的 119 个 +本表以 `contracts/pto-isa-0.59.0-tile-operations.json` 的 119 个 `accepted-direct-operation` 为操作清单。它描述 Linx TileOP C++ wrapper 的 公开实现状态，不替代 PTO-ISA/pto-spec 的 ASL/NDF 合法性、fault、completion、 rollback、definedness 或 memory-order 语义。 @@ -17,23 +17,34 @@ rollback、definedness 或 memory-order 语义。 | PTO catalog 范围 | 状态 | 说明 | | --- | --- | --- | | TEPL elementwise、scalar、reduce/expand、irregular（除 `TLEA`） | 已实现 | 逐操作页面和 `jcore/template_asm.hpp` 为 wrapper 权威；dtype、valid region、padding 和 selector 仍受 ASL 约束。 | -| `TLEA` | 尚无 wrapper | PTO development golden 已分配 SFU selector 31；本仓库尚无公开 C++ wrapper，不以相近操作代替。 | -| `TEXPDIF` | CPU simulator、JCORE inline-asm 已实现；LLVM MC catalog 已实现；LLVM compiler lowering 尚未完成；AArch64/SME 不支持 | PTO 0.59.0 selector 29。已有 wrapper 不等于 LLVM compiler 已具备从 IR/builtin 到 TEXPDIF 的端到端 lowering。 | +| `TLEA` | JCORE inline-asm wrapper 已实现（RowMajor 与 CUBE_M32）；CPU simulator 未实现；AArch64/SME 未实现；LLVM MC / compiler lowering 分别判断 | PTO catalog 将 TLEA 列为 `accepted-direct-operation`（`BSTART.TEPL`，**VEC** 引擎，selector `0x2E`=46，function 14/mode 1）；操作数为 S32/U32/S64/U64 element index、per-PE element-width 标量与 S64/U64 byte-offset 目标。`include/jcore/template_asm.hpp` 的 wrapper 以编译期约束限定 dtype/layout/logical-shape（RowMajor/CUBE_M32，Shared/CUBE_N8/CUBE_M16 拒绝）；signed→S64/unsigned→U64 的严格配对由 ASL `lea-operands.asl` 要求，当前 wrapper 仅校验目标为 S64/U64，配对以指令 legality 为准。element-width 的运行时合法性（8/16/32/64）由指令 legality 检查，不是编译期静态拒绝。wrapper 存在不代表 CPU simulator、AArch64 或 LLVM 端到端已具备 TLEA 支持。 | +| `TEXPDIF` | CPU simulator、JCORE inline-asm 已实现；LLVM MC catalog 已实现；LLVM compiler lowering 尚未完成；AArch64/SME 不支持 | PTO selector 29。已有 wrapper 不等于 LLVM compiler 已具备从 IR/builtin 到 TEXPDIF 的端到端 lowering。 | | TLSU `TLOAD`/`TSTORE`/`TMOV`/`TPREFETCH`/`GMOV` | 已实现 | 传输、peer move 和 prefetch 有独立 C++ 入口；layout conversion 仅对页面列出的组合开放。 | | TLSU `MGATHER`/`MSCATTER` 及 atomic/reduction variants | 仅部分 layout 支持 | wrapper 覆盖当前公开 selector；ColumnMajor selector、mask/索引 dtype 和不同 atomic 组合不得由普通 gather/scatter 重载推断。 | | CUBE TMATMUL/TGEMV 及 bias/acc/MX variants | 仅部分 layout 支持 | CUBE_M16/CUBE_M32、Shared physical shape、scale layout 和 InternalAcc 由具体 wrapper/操作页限制。 | | TEPL layout/rearrangement（`TPERMUTE`、`TSHUF`、`TPACK`、`TUNPACK`、`TGPR2T`） | 仅部分 layout 支持 | 只覆盖已实现的 CUBE/Local 路径和控制字段；未列出的组合保持拒绝。 | -| 0.59.0 `MGATHER`/`MSCATTER` family | 已适配 | 0.59.0 removes the GM row-stride operand and interprets index tiles as explicit byte displacements；wrapper 与 contract test 已改为 base-only `B.IOR`。 | -| 0.59.0 `TROWEXPAND*`/`TCOLEXPAND*` roles | 已适配 | Source roles 使用 row-broadcast/column-broadcast operation view；wrapper 约束、注释及操作文档已同步。 | +| `MGATHER`/`MSCATTER` family（byte-displacement 索引） | 已适配 | 自 PTO 0.58.7 起 GM row-stride 操作数被移除、index tile 解释为显式 byte displacement，该语义在 0.59.0.0 发布 catalog 中保持不变；wrapper 与 contract test 使用 base-only `B.IOR`。 | +| `TROWEXPAND*`/`TCOLEXPAND*` roles | 已适配 | Source roles 使用 row-broadcast/column-broadcast operation view；wrapper 约束、注释及操作文档已同步。 | | `deleted_names`、`rejected_names`，以及 `TTRANS`/`TFILLPAD` 等历史页面 | 仅历史参考 | 不属于 active catalog；页面必须保留明确的 retired 标识。 | ## 版本边界 -- 当前 API/spec 基线：PTO ISA development golden `0.59.0`，状态 - `development-not-published`，publication 为空，ABI - `pto-isa-0.58.7-mode-function-v1`。 +- 当前 API/spec 基线：已发布的 PTO ISA `v0.59.0.0` release（commit `b016532`），ABI + `pto-isa-0.59.0-mode-function-v1`、encoding projection SHA-256 + `91509080…`、ELF release 字段 `0.59.0`（见 `contracts/pto-isa-0.59.0-tile-operations.json`、 + `contracts/linxisa-v0.58-engine-ops.json` 的 `pto_source` 与 provenance 测试）。 +- 发布 manifest（`spec/release-manifest.json`）自身记为 + `specification_status: draft`，并把 implementation conformance 限定为 + `b-fpatr-and-tcvt-e8m0-asl-proven-other-numeric-domains-unproven`；本页据此 + 不宣称该规范已最终定稿或全部数值域已证明。119 个操作的 Tile catalog 与 PTO 0.58.7 + development golden 逐字节一致（SHA-256 `533db9b8…`），因此 `TLEA` 等条目在两者之间保持一致， + 只是 encoding identity 移到了发布版本。 +- 语义 authority 仍是 LinxISA v0.58 profile（无 0.59 profile）与 PTO ASL/NDF： + engine-ops 投影保留真实 LinxISA v0.58 来源，并在 `pto_source.development_lock` + 记录其曾锁定的 PTO development golden，不把旧来源伪标为 v0.59。 - backend 能力必须分别判断：CPU simulator/JCORE wrapper、LLVM MC assembler/parser、LLVM compiler lowering 以及 AArch64/SME 并不是同一个状态。 + `TLEA` 目前只有 JCORE inline-asm wrapper（RowMajor 与 CUBE_M32），没有 CPU simulator 语义。 - `TEXPDIF` 当前已有 CPU simulator 实现、JCORE inline-asm wrapper 和 LLVM MC catalog 条目；LLVM compiler lowering 尚未完成，因此当前不能宣称 LLVM 端到端支持。 diff --git a/test/test_v058_engine_contract.py b/test/test_v058_engine_contract.py index 0212171..a26049e 100644 --- a/test/test_v058_engine_contract.py +++ b/test/test_v058_engine_contract.py @@ -1,5 +1,8 @@ #!/usr/bin/env python3 -# PTO ISA 0.58.7 development engine-contract tests for the jcore inline-asm surface. +# Engine-contract tests for the jcore inline-asm surface. The semantic engine +# inventory is the LinxISA v0.58 authority projection; the active PTO encoding +# identity is the published PTO ISA 0.59.0.0 release (see +# test_contract_carries_release_provenance). # # Rebuilt per handoff Work Package B6: the assertions reflect the current # real toolchain ABI (Tr Tile constraints + %Z TileSize printer; the %q/%D @@ -54,9 +57,9 @@ def _active_impl(self) -> str: if path.is_file() ) - # --- catalog/development-golden provenance --- + # --- catalog/release provenance --- - def test_contract_carries_development_golden_provenance(self) -> None: + def test_contract_carries_release_provenance(self) -> None: self.assertEqual(self.contract["profile"], "v0.58") self.assertEqual( self.contract["semantic_engine_counts"], @@ -74,21 +77,45 @@ def test_contract_carries_development_golden_provenance(self) -> None: src.get("sha256"), "51ca9be275518d29ec48bed570b7a9bd441a65b9c5e6d4f79072f650ee732925", ) + # The active PTO encoding identity is the published 0.59.0.0 release. pto = self.contract.get("pto_source", {}) - self.assertEqual(pto.get("release"), "0.58.7") - self.assertEqual(pto.get("status"), "development-not-published") - self.assertIsNone(pto.get("publication")) + self.assertEqual(pto.get("release"), "0.59.0") + self.assertEqual(pto.get("publication_version"), "0.59.0.0") + self.assertEqual(pto.get("release_tag"), "v0.59.0.0") + # The release manifest is itself still a draft specification; record + # that faithfully rather than claiming a finalized specification. + self.assertEqual(pto.get("specification_status"), "draft") self.assertEqual( - pto.get("commit"), "f0a876e449a95d26841c5ee7affb4c905ebc5f5b" + pto.get("commit"), "b0165320a4b575b18d2f4d93faf40178f661ab49" ) self.assertEqual( - pto.get("tree"), "fe9e8e050375fbce3f526d08acca13c37cd15830" + pto.get("tree"), "31ff0c2d39cbed714baf5be7929bfd06887be9fb" + ) + self.assertEqual( + pto.get("encoding_abi"), "pto-isa-0.59.0-mode-function-v1" ) self.assertEqual( pto.get("encoding_projection_sha256"), - "a5f78ecd707bde4a014542158ea257c783796b95fa4fbcce37742e41fee6a881", + "91509080ca656eb124f47830dcb09c50389dc177266b3b8df9d2d11dc37d5697", + ) + self.assertEqual( + pto.get("release_manifest", {}).get("sha256"), + "3c6b20623e73822c0bd26021c10beb233b8809328b5515f57609eadad1749dc4", ) self.assertEqual(pto.get("tile_catalog", {}).get("count"), 119) + self.assertEqual( + pto.get("tile_catalog", {}).get("sha256"), + "533db9b8f31f118af5978de813cfaa3fa738de820ee24655faa2ee71f343a706", + ) + # The LinxISA v0.58 authority locked the PTO development golden; its + # Tile catalog bytes equal the release catalog, which is why this v0.58 + # engine projection is valid against the 0.59.0.0 release. + lock = pto.get("development_lock", {}) + self.assertEqual(lock.get("release"), "0.58.7") + self.assertEqual( + lock.get("commit"), "f0a876e449a95d26841c5ee7affb4c905ebc5f5b" + ) + self.assertTrue(lock.get("catalog_sha256_matches_release")) def test_0587_engine_mapping_is_exact(self) -> None: engines = {row["name"]: row["engine"] for row in self.contract["tepl_ops"]} @@ -103,7 +130,7 @@ def test_0587_engine_mapping_is_exact(self) -> None: def test_engine_projection_covers_the_exact_pto_catalog(self) -> None: catalog = json.loads( - (ROOT / "contracts" / "pto-isa-0.58.7-tile-operations.json").read_text( + (ROOT / "contracts" / "pto-isa-0.59.0-tile-operations.json").read_text( encoding="utf-8" ) ) @@ -1216,10 +1243,10 @@ def test_compile_all_aggregates_active_object_failures(self) -> None: def test_pto_identity_verifier_rejects_hostile_elf_notes(self) -> None: verifier = ROOT / "test" / "tileop_api" / "verify_pto_identity.py" expected = ( - b'{"encoding_abi":"pto-isa-0.58.7-mode-function-v1",' + b'{"encoding_abi":"pto-isa-0.59.0-mode-function-v1",' b'"encoding_projection_sha256":' - b'"a5f78ecd707bde4a014542158ea257c783796b95fa4fbcce37742e41fee6a881",' - b'"release":"0.58.7"}' + b'"91509080ca656eb124f47830dcb09c50389dc177266b3b8df9d2d11dc37d5697",' + b'"release":"0.59.0"}' ) def make_elf(desc: bytes = expected, owner: bytes = b"PTO\0", @@ -1276,11 +1303,11 @@ def make_note(note_desc: bytes) -> bytes: "missing": make_elf(owner=b"GNU\0"), "corrupt": make_elf(magic=b"BAD!"), "wrong-machine": make_elf(machine=0x3E), - "wrong-identity": make_elf(desc=expected.replace(b"0.58.7", b"0.58.6")), + "wrong-identity": make_elf(desc=expected.replace(b"0.59.0", b"0.59.1")), "trailing-nul": make_elf(desc=expected + b"\0"), "duplicate-segment": make_elf(extra_desc=expected), "conflicting-segment": make_elf( - extra_desc=expected.replace(b"0.58.7", b"0.58.6")), + extra_desc=expected.replace(b"0.59.0", b"0.59.1")), } for name, contents in variants.items(): path = temporary_path / f"{name}.elf" diff --git a/test/tileop_api/verify_pto_identity.py b/test/tileop_api/verify_pto_identity.py index 2f7b52d..05a52d0 100644 --- a/test/tileop_api/verify_pto_identity.py +++ b/test/tileop_api/verify_pto_identity.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Fail-closed validation of the exact PTO 0.58.7 development ELF note.""" +"""Fail-closed validation of the exact PTO 0.59.0 release ELF note.""" from __future__ import annotations @@ -12,10 +12,10 @@ PT_NOTE = 4 SHT_NOTE = 7 EXPECTED_DESC = ( - b'{"encoding_abi":"pto-isa-0.58.7-mode-function-v1",' + b'{"encoding_abi":"pto-isa-0.59.0-mode-function-v1",' b'"encoding_projection_sha256":' - b'"a5f78ecd707bde4a014542158ea257c783796b95fa4fbcce37742e41fee6a881",' - b'"release":"0.58.7"}' + b'"91509080ca656eb124f47830dcb09c50389dc177266b3b8df9d2d11dc37d5697",' + b'"release":"0.59.0"}' ) @@ -138,7 +138,7 @@ def validate(path: Path) -> None: require(not identity_desc.endswith(b"\0"), "PTO JSON must not have a trailing NUL") require(identity_desc == EXPECTED_DESC, - "PTO identity JSON is not the exact 0.58.7 development identity") + "PTO identity JSON is not the exact 0.59.0 release identity") require(len(identities) == 1, "PTO identity must have exactly one note range") @@ -157,7 +157,7 @@ def main(argv: list[str]) -> int: except (OSError, IdentityError, struct.error) as error: print(f"FAIL PTO identity: {error}", file=sys.stderr) return 1 - print("PTO ISA 0.58.7 development ELF identity: PASS") + print("PTO ISA 0.59.0 release ELF identity: PASS") return 0 diff --git a/tools/check_pto_catalog_alignment.py b/tools/check_pto_catalog_alignment.py index 93e35ff..6d2d9e8 100644 --- a/tools/check_pto_catalog_alignment.py +++ b/tools/check_pto_catalog_alignment.py @@ -1,8 +1,11 @@ #!/usr/bin/env python3 -"""Fail-closed checks for the pinned PTO ISA 0.58.7 Tile catalog. +"""Fail-closed checks for the pinned PTO ISA 0.59.0 Tile catalog. This check deliberately verifies inventory and provenance, not the full ASL/NDF -semantics. The latter remains owned by PTO-ISA/pto-spec. +semantics. The latter remains owned by PTO-ISA/pto-spec. The 119-operation Tile +catalog is byte-identical between the PTO 0.58.7 development golden and the +published PTO ISA 0.59.0.0 release (both SHA-256 533db9b8...), so the pinned +bytes did not change when the active encoding identity moved to the release. """ from __future__ import annotations @@ -14,7 +17,7 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[1] -CATALOG = ROOT / "contracts" / "pto-isa-0.58.7-tile-operations.json" +CATALOG = ROOT / "contracts" / "pto-isa-0.59.0-tile-operations.json" INCLUDE = ROOT / "include" DOCS = ROOT / "docs" / "tileop-usage" EXPECTED_TILE_CATALOG_SHA256 = "533db9b8f31f118af5978de813cfaa3fa738de820ee24655faa2ee71f343a706" @@ -28,7 +31,7 @@ def main() -> int: catalog = json.loads(CATALOG.read_text(encoding="utf-8")) failures: list[str] = [] if hashlib.sha256(CATALOG.read_bytes()).hexdigest() != EXPECTED_TILE_CATALOG_SHA256: - failures.append("catalog bytes do not match the reviewed PTO development golden") + failures.append("catalog bytes do not match the reviewed PTO 0.59.0.0 release Tile catalog") if catalog.get("operation_count") != 119: failures.append("catalog operation_count is not 119") operations = catalog.get("operations", []) @@ -92,13 +95,13 @@ def main() -> int: failures.append(f"TEXPDIF support status is missing backend dimension: {marker}") if failures: - print("FAIL: PTO 0.58.7 catalog alignment", file=sys.stderr) + print("FAIL: PTO 0.59.0 catalog alignment", file=sys.stderr) for failure in failures: print(f" - {failure}", file=sys.stderr) return 1 print( - "PASS: PTO 0.58.7 development catalog alignment " - f"({len(names)} golden operations; {len(source_referenced)} source-referenced; " + "PASS: PTO 0.59.0.0 release catalog alignment " + f"({len(names)} release operations; {len(source_referenced)} source-referenced; " f"{len(explicitly_unsupported)} explicitly unsupported)" ) return 0 diff --git a/tools/generate_engine_docs.py b/tools/generate_engine_docs.py index 3ebc4a7..ffa6b43 100644 --- a/tools/generate_engine_docs.py +++ b/tools/generate_engine_docs.py @@ -1,15 +1,17 @@ #!/usr/bin/env python3 """Generate the wrapper engine compatibility view from the pinned projection. -The output mirrors the reviewed PTO ISA 0.59.0 development catalog +The output mirrors the PTO ISA 0.59.0.0 release Tile catalog (spec/catalog/tile-operations.json) for the four architectural engine -classes: **VEC**, **SFU**, **TLSU**, and **CUBE**. Engine and -classification are decoupled (per ADR 0057): TEXP/TLOG/... are SFU-executed -elementwise operations, TGATHER/TSCATTER/TCONCAT are SFU-executed -layout/irregular operations, and TMOV is a TLSU-executed layout operation. -TEPL is the unique compiled carrier identity. `BSTART.VEC` / `BSTART.SFU` are -engine-specific assembly aliases; current inline wrappers retain TEPL so the -same source also compiles with the preceding 0.58 toolchain. +classes: **VEC**, **SFU**, **TLSU**, and **CUBE**. The engine inventory is the +LinxISA v0.58 authority projection; its 119-operation catalog is byte-identical +to the published PTO ISA 0.59.0.0 release. Engine and classification are +decoupled (per ADR 0057): TEXP/TLOG/... are SFU-executed elementwise +operations, TGATHER/TSCATTER/TCONCAT are SFU-executed layout/irregular +operations, and TMOV is a TLSU-executed layout operation. TEPL is the unique +compiled carrier identity. `BSTART.VEC` / `BSTART.SFU` are engine-specific +assembly aliases; current inline wrappers retain TEPL so the same source also +compiles with the preceding 0.58 toolchain. """ from __future__ import annotations @@ -47,16 +49,17 @@ def wrapper_status(name: str) -> str: source_referenced = sum(wrapper_status(name).startswith("源码有引用") for name in operation_names) lines = [ - "# LinxISA / PTO ISA v0.59.0 wrapper engine compatibility view", + "# LinxISA v0.58 / PTO ISA 0.59.0.0 wrapper engine compatibility view", "", "架构定义的引擎类别只有 **VEC**, **TLSU**, **CUBE**, and **SFU**。", "VEC 只包含逐元素操作；SFU 包含归约、广播、变换、排序以及其他需要更复杂硬件的操作。", "TEPL 仍是唯一的编译 carrier 标识。`BSTART.VEC` 和 `BSTART.SFU` 是特定引擎的汇编别名；", "inline wrapper 保留 `BSTART.TEPL`，以兼容之前的工具链源码。", "", - "下表根据本仓库固定的 LinxISA/PTO development golden 投影生成，数据记录在", + "下表根据本仓库固定的 LinxISA v0.58 authority 投影生成（其操作清单与 PTO ISA 0.59.0.0", + "发布 catalog 逐字节一致），数据记录在", "[`contracts/linxisa-v0.58-engine-ops.json`](../../../contracts/linxisa-v0.58-engine-ops.json) 中。", - f"Golden 共 {len(operation_names)} 项；其中 {source_referenced} 项在 `include/` 有名称引用，", + f"投影共 {len(operation_names)} 项；其中 {source_referenced} 项在 `include/` 有名称引用，", f"{len(operation_names) - source_referenced} 项明确没有 wrapper。名称引用不证明 ASL/NDF 语义完整实现。", "", ] @@ -104,7 +107,8 @@ def wrapper_status(name: str) -> str: "## 分类语义", "", "PTO ISA 0.59.0 将执行引擎与操作分类解耦。本表是 wrapper compatibility view；", - "其底层投影记录当前 development golden selector 数据。`elementwise-tile-tile`", + "其底层投影记录 LinxISA v0.58 authority 的 selector 数据（与 0.59.0.0 发布 catalog 一致）。", + "`elementwise-tile-tile`", "和 `tile-scalar-and-immediate` 类别在 VEC 上执行逐元素操作，但其中的", "`TEXP`、`TLOG`、`TRECIP`、`TSQRT`、`TRSQRT` 由 SFU 执行。", "`reduce-and-expand`、`layout-and-rearrangement` 和 `irregular-and-complex` 类别由 SFU 执行。", diff --git a/tools/generate_tileop_usage_docs.py b/tools/generate_tileop_usage_docs.py index 33aac90..11f10b9 100644 --- a/tools/generate_tileop_usage_docs.py +++ b/tools/generate_tileop_usage_docs.py @@ -15,7 +15,7 @@ DOC_ROOT = ROOT / "docs/tileop-usage" SPEC_DOC_ROOT = SPEC_ROOT / "docs/tile" ASL_ROOT = SPEC_ROOT / "asl/tile" -PTO_SPEC_REF = "v0.59.0" +PTO_SPEC_REF = "v0.59.0.0" # Names used by the TileDataType encoding. Keeping this list here makes the # documentation generator independent of prose wording in individual SPEC diff --git a/tools/sync_linxisa_v058_contract.py b/tools/sync_pto_isa_0590_contract.py similarity index 58% rename from tools/sync_linxisa_v058_contract.py rename to tools/sync_pto_isa_0590_contract.py index f7ffe82..1a34025 100644 --- a/tools/sync_linxisa_v058_contract.py +++ b/tools/sync_pto_isa_0590_contract.py @@ -1,5 +1,24 @@ #!/usr/bin/env python3 -"""Project the reviewed LinxISA and PTO development golden into this API.""" +"""Project the reviewed LinxISA v0.58 authority and the published PTO ISA +0.59.0.0 release into this API. + +Provenance model +---------------- +* The LinxISA v0.58 authority is unchanged: it still owns the semantic engine + projection (VEC/SFU/TLSU/CUBE operation inventory and selectors) and it + locked the PTO *development* golden through ``pto-scalar-proposal.lock.json``. +* The active PTO *encoding identity* (ABI, encoding-projection SHA-256 and ELF + ``release`` field) is the published PTO ISA ``v0.59.0.0`` release, read from a + clean ``spec/release-manifest.json``. +* There is no LinxISA ``0.59`` profile, so this tool does not fabricate one: + the LinxISA ``source`` stays ``v0.58`` and the development-golden lock is + recorded verbatim. The 119-operation Tile catalog is byte-identical between + the development golden and the 0.59.0.0 release (both SHA-256 533db9b8...), + which is what makes the v0.58 engine projection valid against the release. + +The release manifest records ``specification_status: draft``; this tool carries +that status faithfully rather than claiming a finalized specification. +""" from __future__ import annotations @@ -12,19 +31,36 @@ ROOT = Path(__file__).resolve().parents[1] DEFAULT_OUTPUT = ROOT / "contracts" / "linxisa-v0.58-engine-ops.json" -DEFAULT_PTO_OUTPUT = ROOT / "contracts" / "pto-isa-0.58.7-tile-operations.json" +DEFAULT_PTO_OUTPUT = ROOT / "contracts" / "pto-isa-0.59.0-tile-operations.json" EXPECTED_COUNTS = {"CUBE": 12, "SFU": 47, "TLSU": 28, "VEC": 32} + +# LinxISA v0.58 authority (unchanged). EXPECTED_COMMIT = "f77a8960f61f97c264a90b7aee757f99891b0943" EXPECTED_TREE = "da085d3f000a5b92031c9694024dc9a7f3cdaa89" EXPECTED_CATALOG_SHA256 = "51ca9be275518d29ec48bed570b7a9bd441a65b9c5e6d4f79072f650ee732925" -EXPECTED_PTO_COMMIT = "f0a876e449a95d26841c5ee7affb4c905ebc5f5b" -EXPECTED_PTO_TREE = "fe9e8e050375fbce3f526d08acca13c37cd15830" -EXPECTED_PTO_MANIFEST_SHA256 = "0c6d0b2a1ec0b49e32e13971e751a5ea19946351a3880bfdfcef0f50351944f7" + +# PTO development golden that the LinxISA v0.58 authority locked. +EXPECTED_DEV_COMMIT = "f0a876e449a95d26841c5ee7affb4c905ebc5f5b" +EXPECTED_DEV_TREE = "fe9e8e050375fbce3f526d08acca13c37cd15830" +EXPECTED_DEV_MANIFEST_SHA256 = "0c6d0b2a1ec0b49e32e13971e751a5ea19946351a3880bfdfcef0f50351944f7" + +# Published PTO ISA 0.59.0.0 release (the active encoding identity). +EXPECTED_PTO_COMMIT = "b0165320a4b575b18d2f4d93faf40178f661ab49" +EXPECTED_PTO_TREE = "31ff0c2d39cbed714baf5be7929bfd06887be9fb" +EXPECTED_PTO_RELEASE_MANIFEST_SHA256 = ( + "3c6b20623e73822c0bd26021c10beb233b8809328b5515f57609eadad1749dc4" +) EXPECTED_PTO_TILE_SHA256 = "533db9b8f31f118af5978de813cfaa3fa738de820ee24655faa2ee71f343a706" -EXPECTED_IDENTITY = { - "release": "0.58.7", - "encoding_abi": "pto-isa-0.58.7-mode-function-v1", - "encoding_projection_sha256": "a5f78ecd707bde4a014542158ea257c783796b95fa4fbcce37742e41fee6a881", +EXPECTED_RELEASE_IDENTITY = { + "release": "0.59.0", + "publication_version": "0.59.0.0", + "encoding_abi": "pto-isa-0.59.0-mode-function-v1", + "encoding_projection_sha256": ( + "91509080ca656eb124f47830dcb09c50389dc177266b3b8df9d2d11dc37d5697" + ), + "content_sha256": ( + "a3e71975e7f753864f7ec09c57515e60f5a6e3e72dfdbce8e444c815a20b2835" + ), } @@ -47,7 +83,7 @@ def require_clean_exact_repo(repo: Path, commit: str, tree: str, label: str) -> raise SystemExit(f"refusing dirty {label} source tree: {repo}") actual = (git(repo, "rev-parse", "HEAD"), git(repo, "rev-parse", "HEAD^{tree}")) if actual != (commit, tree): - raise SystemExit(f"{label} source identity does not match the reviewed golden") + raise SystemExit(f"{label} source identity does not match the reviewed pin") def load_sources( @@ -57,31 +93,43 @@ def load_sources( linx_repo = Path(git(source.parent, "rev-parse", "--show-toplevel")) require_clean_exact_repo(linx_repo, EXPECTED_COMMIT, EXPECTED_TREE, "LinxISA v0.58.7") if sha256(source) != EXPECTED_CATALOG_SHA256: - raise SystemExit("LinxISA catalog bytes do not match the reviewed golden") + raise SystemExit("LinxISA catalog bytes do not match the reviewed authority") pto_repo = Path(git(pto_root.resolve(), "rev-parse", "--show-toplevel")) - require_clean_exact_repo(pto_repo, EXPECTED_PTO_COMMIT, EXPECTED_PTO_TREE, "PTO ISA") - manifest_path = pto_repo / "spec" / "development-manifest.json" + require_clean_exact_repo( + pto_repo, EXPECTED_PTO_COMMIT, EXPECTED_PTO_TREE, "PTO ISA 0.59.0.0 release" + ) + manifest_path = pto_repo / "spec" / "release-manifest.json" tile_catalog_path = pto_repo / "spec" / "catalog" / "tile-operations.json" - if sha256(manifest_path) != EXPECTED_PTO_MANIFEST_SHA256: - raise SystemExit("PTO development manifest bytes do not match the reviewed golden") + if sha256(manifest_path) != EXPECTED_PTO_RELEASE_MANIFEST_SHA256: + raise SystemExit("PTO release manifest bytes do not match the reviewed release") if sha256(tile_catalog_path) != EXPECTED_PTO_TILE_SHA256: - raise SystemExit("PTO Tile catalog bytes do not match the reviewed golden") + raise SystemExit("PTO Tile catalog bytes do not match the reviewed release") linx_data = json.loads(source.read_text(encoding="utf-8")) manifest = json.loads(manifest_path.read_text(encoding="utf-8")) tile_catalog = json.loads(tile_catalog_path.read_text(encoding="utf-8")) if linx_data.get("isa") != "LinxISA" or linx_data.get("version") != "0.58.7": raise SystemExit("source is not the reviewed LinxISA 0.58.7 catalog") - if manifest.get("status") != "development-not-published" or manifest.get("publication") is not None: - raise SystemExit("PTO golden must remain an unpublished development identity") - if manifest.get("identity") != EXPECTED_IDENTITY: - raise SystemExit("unexpected PTO development identity") - if manifest.get("catalog_counts", {}).get("tile_operations") != 119: - raise SystemExit("unexpected PTO development Tile operation count") + + release_identity = { + "release": manifest.get("release"), + "publication_version": manifest.get("publication_version"), + "encoding_abi": manifest.get("encoding_abi"), + "encoding_projection_sha256": manifest.get("encoding_projection_sha256"), + "content_sha256": manifest.get("content_sha256"), + } + if release_identity != EXPECTED_RELEASE_IDENTITY: + raise SystemExit("unexpected PTO 0.59.0.0 release identity") + counts = manifest.get("catalog_counts", {}).get("tile_operations_total") + if counts != 119: + raise SystemExit("unexpected PTO release Tile operation count") if tile_catalog.get("operation_count") != 119 or len(tile_catalog.get("operations", [])) != 119: raise SystemExit("unexpected PTO Tile catalog inventory") + # The LinxISA v0.58 authority locked the PTO development golden. Keep that + # lock fail-closed and additionally require its Tile catalog bytes to equal + # the release Tile catalog, which is what makes this projection valid. lock_path = source.parent / "pto-scalar-proposal.lock.json" lock = json.loads(lock_path.read_text(encoding="utf-8")) lock_identity = ( @@ -89,16 +137,14 @@ def load_sources( lock.get("source", {}).get("commit"), lock.get("source", {}).get("tree"), lock.get("development_manifest", {}).get("sha256"), - lock.get("identity"), lock.get("catalogs", {}).get("tile_operations", {}).get("sha256"), lock.get("catalogs", {}).get("tile_operations", {}).get("count"), ) expected_lock_identity = ( "development-not-published", - EXPECTED_PTO_COMMIT, - EXPECTED_PTO_TREE, - EXPECTED_PTO_MANIFEST_SHA256, - EXPECTED_IDENTITY, + EXPECTED_DEV_COMMIT, + EXPECTED_DEV_TREE, + EXPECTED_DEV_MANIFEST_SHA256, EXPECTED_PTO_TILE_SHA256, 119, ) @@ -113,7 +159,7 @@ def build_projection(source: Path, pto_root: Path) -> tuple[dict[str, object], b if engine_ops["semantic_engine_counts"] != EXPECTED_COUNTS: raise SystemExit("unexpected LinxISA v0.58.7 engine counts") if sum(EXPECTED_COUNTS.values()) != 119: - raise SystemExit("engine counts do not cover the PTO development Tile catalog") + raise SystemExit("engine counts do not cover the PTO release Tile catalog") linx_repo = Path(git(source.resolve().parent, "rev-parse", "--show-toplevel")) relative = source.resolve().relative_to(linx_repo).as_posix() @@ -130,22 +176,43 @@ def build_projection(source: Path, pto_root: Path) -> tuple[dict[str, object], b }, "pto_source": { "repo": "https://github.com/PTO-ISA/pto-spec.git", - "status": manifest["status"], - "publication": manifest["publication"], - "release": EXPECTED_IDENTITY["release"], + "release": EXPECTED_RELEASE_IDENTITY["release"], + "publication_version": EXPECTED_RELEASE_IDENTITY["publication_version"], + "release_tag": "v0.59.0.0", + "specification_status": manifest["specification_status"], "commit": EXPECTED_PTO_COMMIT, "tree": EXPECTED_PTO_TREE, - "development_manifest": { - "path": "spec/development-manifest.json", - "sha256": EXPECTED_PTO_MANIFEST_SHA256, + "release_manifest": { + "path": "spec/release-manifest.json", + "sha256": EXPECTED_PTO_RELEASE_MANIFEST_SHA256, }, - "encoding_abi": EXPECTED_IDENTITY["encoding_abi"], - "encoding_projection_sha256": EXPECTED_IDENTITY["encoding_projection_sha256"], + "encoding_abi": EXPECTED_RELEASE_IDENTITY["encoding_abi"], + "encoding_projection_sha256": EXPECTED_RELEASE_IDENTITY[ + "encoding_projection_sha256" + ], + "content_sha256": EXPECTED_RELEASE_IDENTITY["content_sha256"], "tile_catalog": { "path": "spec/catalog/tile-operations.json", "sha256": EXPECTED_PTO_TILE_SHA256, "count": 119, }, + "development_lock": { + "release": "0.58.7", + "commit": EXPECTED_DEV_COMMIT, + "tree": EXPECTED_DEV_TREE, + "development_manifest": { + "path": "spec/development-manifest.json", + "sha256": EXPECTED_DEV_MANIFEST_SHA256, + }, + "catalog_sha256_matches_release": True, + "note": ( + "The LinxISA v0.58 authority locked the PTO development " + "golden; its Tile catalog bytes equal the 0.59.0.0 release " + "Tile catalog (both SHA-256 533db9b8...), so the v0.58 " + "engine projection remains valid against the published " + "release." + ), + }, }, "semantic_engine_counts": engine_ops["semantic_engine_counts"], "tepl_carrier": { @@ -195,7 +262,12 @@ def render(projection: dict[str, object]) -> str: def main() -> int: parser = argparse.ArgumentParser() parser.add_argument("source", type=Path, help="reviewed isa/v0.58/linxisa-v0.58.json") - parser.add_argument("--pto-root", type=Path, required=True) + parser.add_argument( + "--pto-root", + type=Path, + required=True, + help="clean checkout of PTO-ISA/pto-spec at the v0.59.0.0 release commit", + ) parser.add_argument("--output", type=Path, default=DEFAULT_OUTPUT) parser.add_argument("--pto-output", type=Path, default=DEFAULT_PTO_OUTPUT) parser.add_argument("--check", action="store_true") @@ -207,7 +279,7 @@ def main() -> int: if not args.output.exists() or args.output.read_text(encoding="utf-8") != expected: raise SystemExit(f"stale LinxISA v0.58 projection: {args.output}") if not args.pto_output.exists() or args.pto_output.read_bytes() != tile_catalog: - raise SystemExit(f"stale PTO development Tile catalog: {args.pto_output}") + raise SystemExit(f"stale PTO 0.59.0.0 release Tile catalog: {args.pto_output}") return 0 args.output.parent.mkdir(parents=True, exist_ok=True)