feat(ir/dsl): MXFP8/MXFP4 tile DSL ops

[yanghaoran29]

Summary

Depends on #2147 (minimal host-prequant MXFP8 matmul baseline).

This PR stacks on #2147 and adds:

• tile.tquant / tdequant (+ lower_composite 2× scratch)
• tile.matmul_mx_acc / matmul_mx_bias
• MXFP4 packed storage-vs-logical K + FP4 reinterpret
• EmitC ND A-scale rewrite (MX_A_ZZ→MX_A_ND) + AIC PIPE_ALL before mx_a_* tload
• ExpandMixed V2C / Mat→Scale FIFO sticky (moved out of feat(ir/codegen): minimal host-prequant MXFP8 matmul path #2147)

Still rejects FP8E5M2 for MX data (same as #2147); allows FP8E4M3FN / FP4 / tquant INT8.

Docs: operators MX constraints — #2147 baseline tables + #2117 extension tables (en/zh).

ISA / PTOAS extensions (on top of #2147)

Area	Notes
MXFP4 packed K	IR K is storage units; scale groups / K-match use logical K
tquant scratch	max/scaling scratch sized for ISA unroll 2×
ND A-scale	EmitC rewrite + AIC PIPE_ALL (not TPUSH+dsb)
FIFO sticky	Canonicalize chains tpush/tpop + Mat→Scale moves

Test plan

• UT: test_mx_ops / test_mx_ops_codegen / test_mx_scale_memspace
• ST: test_matmul_mx, test_tquant on a5/a5sim
• Docs en/zh parity; no Co-authored-by on tip commits
• Rebased onto updated feat(ir/codegen): minimal host-prequant MXFP8 matmul path #2147

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds MX block-scale support for Ascend950, including FP8E8M0, scale memory spaces, MX matmul and quantization operators, Python APIs, PTO lowering, memory-layout handling, tests, and documentation.

Changes

MX block-scale support

Layer / File(s)	Summary
FP8E8M0 and scale-memory contracts include/pypto/..., python/bindings/..., python/pypto/...	Adds FP8E8M0, LeftScale, and RightScale across C++ types, Python bindings, aliases, stubs, parsing, serialization, and dtype conversion.
MX IR operators and layouts src/ir/op/tile_ops/..., src/ir/transforms/...	Registers MX matmul, quantization, dequantization, scale-address, and MX load operations with validation, type deduction, layouts, memory spaces, and reuse rules.
Python MX APIs python/pypto/ir/op/..., python/pypto/language/...	Adds MX matmul and quantization wrappers, tuple-valued tquant, mx_layout forwarding, and public exports.
PTO lowering and Ascend950 wiring src/backend/..., src/codegen/..., CMakeLists.txt	Emits MX PTO operations, maps FP8 and scale memory to MLIR, updates aliasing and Ascend950 memory topology, and includes the new operator source.
Tests and documentation tests/..., docs/...	Adds dtype, operator, codegen, and compilation coverage and documents MX operators, memory inference, and PTOAS status.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DSL
  participant TileIR
  participant PTOCodegen
  participant Ascend950
  DSL->>TileIR: Load MX tensors and scales
  DSL->>TileIR: Call tget_scale_addr and matmul_mx
  TileIR->>PTOCodegen: Lower registered tile operations
  PTOCodegen->>Ascend950: Emit MX PTO instructions

Loading

Possibly related issues

• Issue 1975 — Covers the MX DSL operation stack implemented by this change, including matmul, quantization, dequantization, scale-address handling, and MX load support.

Poem

A rabbit hops through scales so bright,
FP8 moonbeams guide the night.
Matrices turn, the tiles align,
Quantized carrots taste divine.
PTO winds make kernels fly—
MX stars sparkle in the sky!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 43.16% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main addition of MXFP8/MXFP4 tile DSL ops.
Description check	✅ Passed	The description is directly related to the MX tile DSL, codegen, and documentation changes in the PR.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

pypto/src/backend/common/pto_ops_elementwise.cpp

Line 430 in 8355deb

{"tile.matmul_mx_acc", "pto.tmatmul.mx.acc", 5},

Route MX accumulation through in-place codegen

When users call pl.matmul_mx_acc, adding it to kSimpleOps sends it through MakeNaryCodegenPTO, which emits the IR-level accumulator as an ins(...) operand and the assignment target as a separate outs(...) buffer. The existing accumulator lowering below is custom because PTOAS expects the accumulator operand and output buffer to be the same SSA value; under tile-address/PyPTO-planner paths the result var can be a different tile_buf even when it shares the same MemRef, so this new op can generate invalid or non-accumulating MLIR. Please register it with an accumulator-specific lowering like tile.matmul_acc.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

tests/ut/core/test_dtype.py (1)

248-254: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Cover FP8E8M0’s non-integer invariant.

Line 254 verifies is_float(), but FP8E8M0 is absent from test_is_int and test_type_predicates_mutual_exclusion; a regression reporting both float and integer would pass. Add it to both negative/exclusivity lists.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/ut/core/test_dtype.py` around lines 248 - 254, Add pypto.DT_FP8E8M0 to
the non-integer assertions in test_is_int and to the mutually exclusive
type-predicate checks in test_type_predicates_mutual_exclusion, ensuring it is
validated as floating-point only.

include/pypto/core/dtype.h (1)

71-82: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Preserve FP8E8M0 semantic separation in IsFloat().

kFp8e8m0Code (0x36) falls inside the IEEE float range, so DataType::FP8E8M0.IsFloat() returns true. MX FP8E8M0 is block-scale exponent-only data rather than a general arithmetic float, and generic IsFloat() gates now accept it across arith simplification, constant folding, codegen, type inference, and tensor ops. Use a specific MX/block-scale predicate for MX call sites such as tile.tdequant, rather than relying on the broad range check.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@include/pypto/core/dtype.h` around lines 71 - 82, Update DataType::IsFloat()
so kFp8e8m0Code is excluded from the general IEEE float classification despite
falling within kIeeeFloatRangeStart–kIeeeFloatRangeEnd. Add or use a dedicated
MX/block-scale predicate for FP8E8M0, and update MX-specific callers such as
tile.tdequant to use it instead of IsFloat(), while preserving IsFloat() for
arithmetic floating-point types.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/en/dev/ptoas-op-status.md`:
- Line 124: Update the four PTOAS operation-status matrix entries to mark ST as
❌ and describe the coverage as PTOAS compilation only, not hardware execution:
docs/en/dev/ptoas-op-status.md lines 124-124 and 174-174, and
docs/zh-cn/dev/ptoas-op-status.md lines 117-117 and 167-167. Preserve the
existing frontend/codegen and device-execution-pending details where applicable.

In `@src/backend/common/pto_ops_datamove.cpp`:
- Around line 605-614: The MakeTQuantCodegenPTO lowering currently drops the
validated tile.tquant mode when emitting pto.tquant.mx. Update
MakeTQuantCodegenPTO and its generated PTOAS representation to preserve and emit
the mode attribute, or explicitly reject unsupported modes before lowering; do
not allow MXFP4/MXFP8 selections to reach PTOAS without mode information.

In `@src/ir/op/tile_ops/matmul.cpp`:
- Around line 407-464: Add explicit 2D shape checks in DeduceTileMatMulMxAccType
and DeduceTileMatMulMxBiasType immediately after validating the TileType and
before any shape_[0] or shape_[1] access. Require shape_.size() == 2 and use the
existing sibling non-MX functions’ validation pattern and clear
operator-specific error messages.

In `@src/ir/op/tile_ops/mx.cpp`:
- Around line 37-42: Update GetMxQuantOutDtype to reject unknown mode strings
instead of falling through to DataType::FP8E4M3FN. Preserve the existing
mappings for all five supported modes, and add the established IR-construction
error or validation path so invalid values such as "mxfp8_e5m3" fail fast with a
diagnostic.

---

Outside diff comments:
In `@include/pypto/core/dtype.h`:
- Around line 71-82: Update DataType::IsFloat() so kFp8e8m0Code is excluded from
the general IEEE float classification despite falling within
kIeeeFloatRangeStart–kIeeeFloatRangeEnd. Add or use a dedicated MX/block-scale
predicate for FP8E8M0, and update MX-specific callers such as tile.tdequant to
use it instead of IsFloat(), while preserving IsFloat() for arithmetic
floating-point types.

In `@tests/ut/core/test_dtype.py`:
- Around line 248-254: Add pypto.DT_FP8E8M0 to the non-integer assertions in
test_is_int and to the mutually exclusive type-predicate checks in
test_type_predicates_mutual_exclusion, ensuring it is validated as
floating-point only.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7050f4d6-6da3-4771-af65-bee8b74bd451

📥 Commits

Reviewing files that changed from the base of the PR and between 1c966b5 and 8355deb.

📒 Files selected for processing (45)

• CMakeLists.txt
• docs/en/dev/ir/05-operators.md
• docs/en/dev/passes/16-infer_tile_memory_space.md
• docs/en/dev/ptoas-op-status.md
• docs/zh-cn/dev/ir/05-operators.md
• docs/zh-cn/dev/passes/16-infer_tile_memory_space.md
• docs/zh-cn/dev/ptoas-op-status.md
• include/pypto/core/dtype.h
• include/pypto/ir/memory_space.h
• include/pypto/ir/pipe.h
• include/pypto/ir/tile_view_semantics.h
• include/pypto/ir/transforms/utils/attrs.h
• python/bindings/modules/core.cpp
• python/bindings/modules/ir.cpp
• python/pypto/__init__.py
• python/pypto/backend/pto_backend.py
• python/pypto/ir/__init__.py
• python/pypto/ir/__init__.pyi
• python/pypto/ir/compiled_program.py
• python/pypto/ir/op/tile_ops.py
• python/pypto/ir/type.py
• python/pypto/jit/decorator.py
• python/pypto/jit/specializer.py
• python/pypto/language/__init__.py
• python/pypto/language/op/__init__.py
• python/pypto/language/op/tile_ops.py
• python/pypto/language/parser/type_resolver.py
• python/pypto/pypto_core/__init__.pyi
• python/pypto/pypto_core/ir.pyi
• src/backend/common/pto_ops_datamove.cpp
• src/backend/common/pto_ops_elementwise.cpp
• src/backend/common/soc.cpp
• src/codegen/pto/pto_codegen.cpp
• src/codegen/pto/pto_type_utils.cpp
• src/ir/memref.cpp
• src/ir/op/tile_ops/matmul.cpp
• src/ir/op/tile_ops/memory.cpp
• src/ir/op/tile_ops/mx.cpp
• src/ir/transforms/infer_tile_memory_space_pass.cpp
• src/ir/transforms/memory_reuse_pass.cpp
• tests/st/runtime/ops/test_matmul_mx.py
• tests/ut/codegen/test_mx_ops_codegen.py
• tests/ut/core/test_dtype.py
• tests/ut/ir/operators/test_mx_ops.py
• tests/ut/ir/operators/test_op_registry.py

💤 Files with no reviewable changes (1)

• src/ir/transforms/infer_tile_memory_space_pass.cpp