Update: align tensormap_and_ringbuffer across A2/A3 and A5

[yanghaoran29]

Summary

• Replay the complete tmr-a2a3-a5-alignment-backup change onto the latest main while retaining fixes that already landed upstream.
• Converge shared TMR runtime structures, dependency handling, orchestrator behavior, scheduler state, and A5 runtime setup while preserving documented hardware and ABI differences.
• Add an A2/A3 versus A5 comparison document and link it from the documentation index.
• Align the AICore swimlane readiness contract at the Phase 2 window-open publication point and fold in the current review corrections.

Validation

• pip install --no-build-isolation -e .
• pre-commit run --hook-stage commit
• C++ no-hardware suite: 97/97 passed
• A5 TMR hardware sweep via task-submit: 58 passed, 1 skipped; all 7 sweep-isolation failures passed in fresh isolated jobs (3 task-timing, 3 Worker L3, and the two-device SDMA case)
• A5 ChipSwimlane DFX smoke via task-submit: 4/4 passed

Follow-up to #1779.
Relates to #1582.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 089060e7-9940-42df-b835-8d8b2f17a779

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The PR updates A2/A3 and A5 documentation for the revised AICore handshake. It replaces Phase 1 readiness references with Phase 2 register-window publication, clarifies task and shutdown signaling, and updates profiling head-resolution timing and API names.

Changes

AICore handshake and profiling protocol

Layer / File(s)	Summary
Handshake protocol and execution sequencing src/a2a3/runtime/..., src/a5/runtime/..., src/a2a3/platform/onboard/aicore/kernel.cpp, src/a5/platform/onboard/aicore/kernel.cpp	Comments now describe readiness reporting, task-pointer publication, register-window opening, DATA_MAIN_BASE polling, completion through COND, shutdown, and initialization ordering. aicpu_ready is documented as unused legacy layout.
Profiling head publication and lazy resolution src/a2a3/platform/include/aicore/aicore_profiling_state.h, src/a5/platform/include/aicore/aicore_profiling_state.h, src/*/platform/{onboard,sim}/aicore/kernel.cpp, src/*/runtime/host_build_graph/aicore/aicore_executor.cpp, src/*/runtime/tensormap_and_ringbuffer/aicore/aicore_executor.cpp	Profiling documentation now places head-slot publication before window opening and permits resolution after Phase 2 exit or during first dispatch. The headers use #pragma once, and the documented accessor name is updated.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• hw-native-sys/simpler#1513: Both update AICore profiling documentation and the aicore_execute flow.
• hw-native-sys/simpler#1718: Both replace include guards with #pragma once in related runtime headers.
• hw-native-sys/simpler#1774: Both update A2/A3 and A5 profiling head-resolution timing.

Poem

A rabbit reads the Phase Two sign,
The head slot waits in ordered line.
The window opens, tasks take flight,
DATA_MAIN_BASE makes it right.
Hop, hop—old handshake words decline!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% 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 identifies the main change: alignment of tensormap_and_ringbuffer across A2/A3 and A5.
Description check	✅ Passed	The description directly covers the alignment work, readiness contract updates, documentation changes, and validation results.

---

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]

Actionable comments posted: 3

🤖 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 `@src/a2a3/platform/onboard/aicore/kernel.cpp`:
- Around line 74-78: Update the readiness comment in the kernel flow to document
`block_idx + 1` as the value assigned to `my_hank->aicore_done`, matching the
implementation while leaving the surrounding polling steps unchanged.

In `@src/a2a3/runtime/host_build_graph/runtime/runtime.h`:
- Around line 70-76: Update the Phase 2 handshake documentation so AICore
reports the initial idle state before reading and caching the published task
pointer. Apply this ordering correction in the runtime handshake sections of
src/a2a3/runtime/host_build_graph/runtime/runtime.h (lines 70-76),
src/a2a3/runtime/tensormap_and_ringbuffer/runtime/runtime.h (lines 72-78),
src/a5/runtime/host_build_graph/runtime/runtime.h (lines 69-75), and
src/a5/runtime/tensormap_and_ringbuffer/runtime/runtime.h (lines 71-77); no
implementation changes are required.

In `@src/a2a3/runtime/tensormap_and_ringbuffer/aicore/aicore_executor.cpp`:
- Around line 50-63: Update the explanatory comment to replace both incorrect
hank->task references with my_hank->task, matching the handshake pointer
declared and used by the implementation.

🪄 Autofix

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: c992a332-6027-4e54-ae14-f1cd50c737cf

📥 Commits

Reviewing files that changed from the base of the PR and between daf581c and 15b92f9.

📒 Files selected for processing (18)

• src/a2a3/platform/include/aicore/aicore_profiling_state.h
• src/a2a3/platform/onboard/aicore/kernel.cpp
• src/a2a3/platform/sim/aicore/kernel.cpp
• src/a2a3/runtime/host_build_graph/aicore/aicore_executor.cpp
• src/a2a3/runtime/host_build_graph/runtime/runtime.h
• src/a2a3/runtime/host_build_graph/runtime/scheduler/scheduler_cold_path.cpp
• src/a2a3/runtime/tensormap_and_ringbuffer/aicore/aicore_executor.cpp
• src/a2a3/runtime/tensormap_and_ringbuffer/runtime/runtime.h
• src/a2a3/runtime/tensormap_and_ringbuffer/runtime/scheduler/scheduler_cold_path.cpp
• src/a5/platform/include/aicore/aicore_profiling_state.h
• src/a5/platform/onboard/aicore/kernel.cpp
• src/a5/platform/sim/aicore/kernel.cpp
• src/a5/runtime/host_build_graph/aicore/aicore_executor.cpp
• src/a5/runtime/host_build_graph/runtime/runtime.h
• src/a5/runtime/host_build_graph/runtime/scheduler/scheduler_cold_path.cpp
• src/a5/runtime/tensormap_and_ringbuffer/aicore/aicore_executor.cpp
• src/a5/runtime/tensormap_and_ringbuffer/runtime/runtime.h
• src/a5/runtime/tensormap_and_ringbuffer/runtime/scheduler/scheduler_cold_path.cpp

[ChaoZheng109]

这是一次范围清晰、验证充分的收敛 PR(CI 全绿,含 a2a3/a5 两条 onboard 硬件通道),整体方向正确。评审后有两处文档一致性问题建议修正,均不影响代码行为:

1. a2a3 的 profiling_levels.md 的 "Code Locations" 被指到了 a5 路径

src/a2a3/runtime/tensormap_and_ringbuffer/docs/profiling_levels.md(434–436 行)为了让两份文档逐字节一致,把 Code Locations 改成了 src/a5/runtime/tensormap_and_ringbuffer/...:

- Scheduler profiling: `src/a5/runtime/tensormap_and_ringbuffer/runtime/scheduler/scheduler_dispatch.cpp` and `scheduler_cold_path.cpp`
- Orchestrator profiling: `src/a5/runtime/tensormap_and_ringbuffer/aicpu/aicpu_executor.cpp`
- TensorMap profiling: `src/a5/runtime/tensormap_and_ringbuffer/runtime/pto_tensormap.h`

结果:阅读 a2a3 这份文档的人,按链接会跳进 a5 代码树——这是为求"字节相同"牺牲了正确性(参见 .claude/rules/doc-consistency.md §1)。建议改用树内相对表述(如 "本 runtime 树内的 scheduler_dispatch.cpp"),而不是硬编码某一 arch 的绝对路径来强求 identical。

2. 新增的差异文档是时点快照,建议加"基准声明"

docs/tensormap-and-ringbuffer-a2a3-vs-a5.md 写死了"逐字节相同文件清单"和具体寄存器偏移(0xA0/0xD0 等)。代码一旦漂移,这些内容会变成新的"陈旧文档"——正是本 PR 修正的 aicpu_ready 陈旧注释的翻版。建议在文首注明"以 commit <sha> 为基准,改动相关文件时同步更新本文",给它一个维护锚点。

以上两点均为文档层面,不阻塞合入;修掉第 1 项后即可 approve。

[yanghaoran29]

@ChaoZheng109 已处理：

• 两份 profiling_levels.md 的 Code Locations 已改为各自 runtime 树内的相对路径；a2a3 与 a5 文档仍保持一致，且所有路径均可解析到对应架构文件。
• 差异文档开头已加入“以 PR 1795 为基准”的维护声明，并注明相关文件或常量变化时需同步更新本文。仓库 check-english-only 要求英文，因此正文采用等义表述 This document uses PR 1795 as its baseline.。
• 分支已 rebase 到最新 main。