feat(codegen): validate carry op family

[hashiqiqixian]

Summary

• align tile.addc, tile.subc, tile.addsc, and tile.subsc with the current native PTO-ISA dtype, shape, valid-region, scalar, layout, and carry semantics
• preserve the existing Python keyword API while correcting subtraction to src0 - src1/scalar + carry, and emit the four canonical PTOAS ops with exact operand order
• add focused type and in-place MemoryReuse coverage plus same-name runtime ST, and record A2/A3 hardware evidence in both status matrices

Validation

• complete local diff review: passed
• git diff --check: passed
• Ruff check and format check for changed Python files: passed
• serial CMake build and editable install on /data/chenshenai/test2: passed
• focused carry contract UT: 18 passed
• focused carry aliasing UT: 1 passed
• repository header, English-only, and docs parity checks: passed
• A2/A3 codegen-only with latest PTOAS assembly: 8 passed; generated .pto files contain exact pto.taddc, pto.tsubc, pto.taddsc, and pto.tsubsc operand order
• A2/A3 task-submit hardware, one precompile worker and one 8-case batch: 8/8 passed on device 1

The runtime cases cover carry values 0/1, add/subtract, tile/scalar forms, INT32 overflow/borrow behavior, and narrowed valid_shape. A5 hardware validation remains pending and is documented in the status matrix.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR formalizes carry-aware tile arithmetic for addc, subc, addsc, and subsc, adding strict dtype and shape deduction, row-major layout registration, updated documentation, system tests, unit tests, and memory-reuse coverage.

Changes

Carry arithmetic operations

Layer / File(s)	Summary
Carry contracts and type deduction src/ir/op/tile_ops/elementwise.cpp, python/pypto/.../tile_ops.py, docs/{en,zh-cn}/dev/...	Carry operations now use explicit operand names and semantics, allow only selected dtypes, require exact tile and valid-shape matches, and preserve src0 metadata.
Elementwise layout integration src/backend/common/pto_ops_elementwise.cpp	tile.addc and tile.subc are registered as row-major-layout operations.
Carry operation validation and execution coverage tests/st/runtime/ops/test_carry.py, tests/ut/ir/operators/test_tile_ops.py, tests/ut/ir/transforms/test_memory_reuse.py	Tests cover INT32 and FP32 execution, valid regions, overflow and borrow cases, invalid type/shape combinations, and output aliasing for all four operations.

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

Sequence Diagram(s)

sequenceDiagram
  participant TestCarryFamily
  participant tile.addc
  participant MemoryReuse
  TestCarryFamily->>tile.addc: execute carry arithmetic with valid_shapes
  tile.addc-->>TestCarryFamily: produce and validate output
  MemoryReuse->>tile.addc: reuse dead src0 buffer
  tile.addc-->>MemoryReuse: bind destination to src0 MemRef

Loading

Possibly related PRs

• hw-native-sys/pypto#2100: Updates MemoryReuse layout gating and adds related carry-operation reuse tests.

Poem

I’m a bunny with carry tucked tight,
Adding and subtracting just right.
Shapes match, dtypes agree,
Tests hop through each valid degree.
Row-major trails sparkle bright!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 41.30% 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
Title check	✅ Passed	It clearly summarizes the main change: validation updates for the carry op family.
Description check	✅ Passed	The summary matches the changes by describing carry semantics, codegen updates, tests, and hardware validation.
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.

---

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.}

[coderabbitai]

🧹 Nitpick comments (1)

src/ir/op/tile_ops/elementwise.cpp (1)

71-75: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Carry contract duplicates the pre-existing tdiv contract machinery.

IsCarryDataType (71-75) is identical to IsTDivDataType (66-69) — same four dtypes, same body. And CheckCarryTileMatches (717-748) reimplements the exact dtype/shape-rank/shape-extent/valid-shape-rank/valid-shape-extent sequence already inlined in DeduceTileOpElementwiseBinaryType's require_tdiv_contract branch (lines ~137-175), instead of extracting/reusing one shared helper for both contracts. Since these two contracts happen to coincide today, a future divergence in one path without updating the other would silently break parity.

♻️ Suggested consolidation

-static bool IsCarryDataType(DataType dtype) {
-  return dtype == DataType::INT16 || dtype == DataType::INT32 || dtype == DataType::FP16 ||
-         dtype == DataType::FP32;
-}
+// Carry ops (addc/subc/addsc/subsc) currently share the same dtype union as
+// the tdiv contract; reuse it explicitly instead of duplicating the list.
+static bool IsCarryDataType(DataType dtype) { return IsTDivDataType(dtype); }

And in DeduceTileOpElementwiseBinaryType's require_tdiv_contract branch, replace the inline dtype/shape/valid-shape checks with a call to CheckCarryTileMatches(tile_type1, tile_type2, "src1", op_name) (after hoisting its declaration above this function), removing the duplicate block.

Also applies to: 717-748

🤖 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 `@src/ir/op/tile_ops/elementwise.cpp` around lines 71 - 75, Consolidate the
duplicated carry and tdiv contract logic in IsCarryDataType,
CheckCarryTileMatches, and DeduceTileOpElementwiseBinaryType: reuse one shared
dtype predicate and hoist CheckCarryTileMatches so the require_tdiv_contract
branch calls it instead of duplicating dtype, shape, rank, extent, and
valid-shape checks. Preserve the existing contract validation behavior and
diagnostics for both paths.

🤖 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.

Nitpick comments:
In `@src/ir/op/tile_ops/elementwise.cpp`:
- Around line 71-75: Consolidate the duplicated carry and tdiv contract logic in
IsCarryDataType, CheckCarryTileMatches, and DeduceTileOpElementwiseBinaryType:
reuse one shared dtype predicate and hoist CheckCarryTileMatches so the
require_tdiv_contract branch calls it instead of duplicating dtype, shape, rank,
extent, and valid-shape checks. Preserve the existing contract validation
behavior and diagnostics for both paths.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1fb6fd8a-dbf2-44ed-83fc-2caffafd8650

📥 Commits

Reviewing files that changed from the base of the PR and between 478ddad and 59a2e34.

📒 Files selected for processing (11)

• docs/en/dev/codegen/00-pto_codegen.md
• docs/en/dev/ptoas-op-status.md
• docs/zh-cn/dev/codegen/00-pto_codegen.md
• docs/zh-cn/dev/ptoas-op-status.md
• python/pypto/ir/op/tile_ops.py
• python/pypto/language/op/tile_ops.py
• src/backend/common/pto_ops_elementwise.cpp
• src/ir/op/tile_ops/elementwise.cpp
• tests/st/runtime/ops/test_carry.py
• tests/ut/ir/operators/test_tile_ops.py
• tests/ut/ir/transforms/test_memory_reuse.py

[hashiqiqixian]

Review follow-up: I am keeping the carry contract local rather than reusing the division helper. Carry ops have a third carry operand and different output/reuse semantics; coupling them to the division-specific helper would broaden the refactor and make future changes to either instruction family less isolated, without fixing a correctness issue.