Enhance documentation for tile operations in the ISA

[ivanmang]

• Added performance metrics, cycle counts, and instruction sequences for pto.tcolexpanddiv, pto.tcolexpandexpdif, pto.tcolexpandmax, pto.tcolexpandmin, pto.tcolexpandmul, and pto.tcolexpandsub.
• Updated related operations and instruction set links for better navigation.
• Improved clarity on layout and shape impacts for various operations.
• Expanded the pto.taxpy documentation to include detailed performance analysis, constraints, and examples.

[gemini-code-assist]

Code Review

This pull request significantly enhances the ISA documentation for communication, system, and tile instructions by adding detailed mechanism descriptions, input/output tables, performance models, and exception handling. The review feedback highlights several inconsistencies where the IR syntax examples do not match the C++ intrinsic signatures or the operation descriptions, particularly regarding missing event return values in the SSA and DPS forms. Additionally, corrections are required for platform-specific support details in the TPOP and TPUSH documentation to accurately reflect A5-only features.

[zhoubot]

Thanks for the documentation expansion. I reviewed the updated PR at af5209df68dc4af4e7b0a35a4214bfd54068fe6f and it is not merge-ready yet.

Findings:

1. docs/isa/system/ops/TFREE.md:41 - [P1] TFREE documents a non-existent tile-operand API

   The page now documents TFREE(PipeT &pipe, TileData &tile, ...), says the tile must come from TPOP, and shows auto tile = TPOP(pipe); ... TFREE(pipe, tile);. That does not match include/pto/common/pto_instr.hpp, where the public forms are TFREE(Pipe &pipe, ...) and the global-tensor overloads, with no tile handle operand. The backend TFREE_IMPL paths are also no-op/placeholders in the current source. This would teach users to call an API that does not exist.

2. docs/isa/tile/ops/irregular-and-complex/thistogram.md:39 - [P1] THISTOGRAM omits the required byte template and index tile

   The documented signature is THISTOGRAM(dst, src, events...), but the actual public API is template <HistByte byte, typename TileDataDst, typename TileDataSrc, typename TileDataIdx, ...> THISTOGRAM(dst, src, idx, events...). The page also describes src as directly producing bins, while the implementation and tests require a separate idx tile and HistByte selection. Please update syntax, inputs, constraints, and examples to include both.

3. docs/isa/tile/ops/tile-scalar-and-immediate/taxpy.md:39 and docs/isa/tile/tile-scalar-and-immediate.md:10 - [P1] TAXPY is documented as four operands but the API has three

   The PR describes dst = src0 * scalar + src1 and documents TAXPY(dst, src0, scalar, src1). The source API is TAXPY(dst, src0, scalar, events...), dispatching to TAXPY_IMPL(dst, src0, scalar), and existing tests call TAXPY(dstTile, src0Tile, scalar). Please align the semantics and examples with the actual API or update the implementation separately.

4. docs/isa/tile/ops/layout-and-rearrangement/tpack.md:37 - [P1] TPACK is documented as declared in pto_instr.hpp, but no public declaration exists there

   I could not find TPACK / TPACK_IMPL in include/pto/common/pto_instr.hpp or backend headers. The page now claims a public intrinsic and gives source/destination packing rules, but the source tree does not expose that instruction contract. Either add the missing API in code or keep the docs constrained to what is actually implemented.

5. Formatting gate: git diff --check origin/main...origin/pr/108 fails on many changed files with new blank line at EOF, including docs/isa/tile/ops/irregular-and-complex/tci.md, tgather.md, tpart*.md, tquant.md, multiple tfillpad* pages, and most reduce-and-expand pages. Please remove those extra trailing blank lines.

Verification:

• /Users/zhoubot/github/pto-isa/.venv-mkdocs/bin/python -m mkdocs build -f docs/mkdocs/mkdocs.yml --strict passed on the PR worktree.
• git diff --check origin/main...origin/pr/108 failed as noted above.
• Source alignment checked against include/pto/common/pto_instr.hpp, include/pto/cpu/THistogram.hpp, include/pto/npu/a5/THistogram.hpp, and the related CPU/NPU tests.

I’m not merging this PR until these documentation/source-contract mismatches and formatting issues are fixed.

[zhoubot]

Triage review (2026-05-08): this PR still needs work before it can be merged. GitHub marks it CHANGES_REQUESTED and UNSTABLE, and the patch adds whitespace warnings when applied to current main (mostly blank-line-at-EOF/trailing whitespace in generated-looking docs pages).

The scope is documentation-only but broad: 46 files across tile op pages and system/comm pages. Please address the requested review, run git diff --check, and rerun the docs/pre-commit jobs after rebasing. I would also keep each page aligned with source contracts rather than adding performance/cycle claims unless the measurement source is named in the page or PR body.