Skip to content

Add: restore marked args for L0 swimlane replay - #1567

Open
indigo1973 wants to merge 1 commit into
hw-native-sys:mainfrom
indigo1973:l0_0727
Open

Add: restore marked args for L0 swimlane replay#1567
indigo1973 wants to merge 1 commit into
hw-native-sys:mainfrom
indigo1973:l0_0727

Conversation

@indigo1973

@indigo1973 indigo1973 commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Level 3 args dump keeps complete args_dump.json metadata for Core (L0)
swimlane replay while reusing the existing Level 1
CoreTaskArgs::dump(...) mask to write only marked tensor payloads. This
preserves Level 1 behavior and avoids a parallel task/slot selector path.

  • Add --restore-arg SLOT to initialize selected replay tensors from
    their captured before_dispatch bytes for structured inputs in #1532.
  • Add --msprof-timeout MINUTES to bound op-simulator collection.
  • Keep args.bin optional when Level 3 has no marked tensor payload.
  • Reject a5 payload restoration while #1560 remains open; completing
    that platform scope depends on fixing #1560.
  • Cover payload capture, restoration, strided views, and error paths.

@coderabbitai

coderabbitai Bot commented Jul 29, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

Adds selective level-3 tensor payload capture and --restore-arg replay support. The change extends the payload-filter wire contract, dump collection and manifests, replay materialization, CLI validation, platform guidance, and automated coverage.

Changes

Selective dump and replay

Layer / File(s) Summary
Payload filter contract and propagation
src/common/task_interface/..., python/bindings/task_interface.cpp, python/simpler/worker.py, simpler_setup/scene_test.py
Adds validated function-ID and slot selectors to CallConfig, Python bindings, mailbox decoding, and SceneTest execution.
Filtered collection
src/common/platform/..., src/a2a3/..., src/a5/...
Passes filters through device runners and collectors, selectively copies tensor payloads, and records filter and binary-output metadata in manifests.
Replay restoration and tooling
simpler_setup/tools/l0_swimlane.py, simpler_setup/tools/dump_viewer.py, conftest.py
Adds --restore-arg, payload validation/materialization, generated memcpy initialization, zero-fill fallback, extra include handling, and configurable profiler timeouts.
Validation coverage
tests/ut/..., tests/st/...
Covers wire layouts, selector validation, filtered payload capture, manifest output, restoration failures, strided tensors, CLI conflicts, and generated replay code.
Documentation
.claude/skills/..., docs/dfx/...
Documents selector usage, restoration constraints, SPMD behavior, oversized replays, output schemas, and A5 payload limitations.

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

Possibly related issues

Possibly related PRs

Poem

A rabbit found bytes in a tensor-lined trail,
Chose only the slots that the filters unveil.
With memcpy hops and zeroes in tow,
The replay now knows which real controls flow.
“A5,” said the hare, “wait for your fix—
For now, metadata does the tricks!”

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 25.88% 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 'Add: restore marked args for L0 swimlane replay' directly describes the main feature addition: restoring marked tensor arguments during L0 swimlane replay, which is the central objective of this changeset.
Description check ✅ Passed The description clearly explains the purpose, key features (--restore-arg, --msprof-timeout, optional args.bin), platform limitations (a5 rejection), and issue references. It relates directly to the changeset across documentation, bindings, tools, and tests.

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

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

Caution

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

⚠️ Outside diff range comments (1)
simpler_setup/scene_test.py (1)

1703-1715: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

--rounds > 1 disable leaks stale payload-filter CLI args into dispatched children, crashing them.

This block clears args.dump_args and args.dump_args_payload_filter when rounds > 1, but not args.dump_args_payload_func_id / args.dump_args_payload_slot. Those two raw attributes are what _dispatch_test_phases_standalone's common list construction (Lines 1899-1904) actually forwards to spawned child subprocesses — independently of args.dump_args_payload_filter. Since if args.dump_args: is now false, --dump-args is omitted from common, but --dump-args-payload-func-id/--dump-args-payload-slot are still appended (their own guards only check the raw attrs). Each child re-parses argv and calls _resolve_dump_args_payload_filter(0, <leaked func-id>, <leaked slots>), which raises ValueError("... requires --dump-args 3")parser.error()SystemExit(2), failing every L2 fan-out job instead of silently disabling dump-args as intended (and as already happens correctly on the pytest side, and on the single-group inline-execution path which reuses the already-cleared args.dump_args_payload_filter).

🐛 Proposed fix
         if args.rounds > 1 and args.dump_args:
             logger.warning("Dump args disabled: --rounds > 1")
             args.dump_args = 0
             args.dump_args_payload_filter = None
+            args.dump_args_payload_func_id = None
+            args.dump_args_payload_slot = []
🤖 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 `@simpler_setup/scene_test.py` around lines 1703 - 1715, When disabling
dump-args for args.rounds > 1 in the argument-normalization block, also clear
the raw args.dump_args_payload_func_id and args.dump_args_payload_slot
attributes used by _dispatch_test_phases_standalone when building its common
child-argument list. Keep the existing dump_args_payload_filter reset so spawned
children receive no stale payload-filter options and dump-args remains fully
disabled.
🤖 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/dfx/l0-swimlane-profiling.md`:
- Around line 683-685: Update the replay-data statement in the profiling
documentation to say that only unselected tensor payloads are zero-filled;
preserve the clarification that scalar values and tensor descriptors retain
dump-derived values.
- Around line 71-72: Update the tensor restoration scope statement in the
profiling documentation to include both a2a3 and a2a3sim, while preserving the
existing availability of a5 metadata-only and zero-filled replays.

In `@src/a5/platform/sim/host/device_runner.cpp`:
- Around line 694-697: Update the A5 initialization path in device_runner around
dump_collector_.initialize to prevent selective payload capture: pass the
disabled payload-filter value instead of dump_args_payload_filter_, or reject
enabled filters with a clear error before initialization. Preserve the existing
collector setup for all other dump options.

---

Outside diff comments:
In `@simpler_setup/scene_test.py`:
- Around line 1703-1715: When disabling dump-args for args.rounds > 1 in the
argument-normalization block, also clear the raw args.dump_args_payload_func_id
and args.dump_args_payload_slot attributes used by
_dispatch_test_phases_standalone when building its common child-argument list.
Keep the existing dump_args_payload_filter reset so spawned children receive no
stale payload-filter options and dump-args remains fully disabled.
🪄 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: d4123f79-b2b6-4407-8c63-b7d6ec6bba38

📥 Commits

Reviewing files that changed from the base of the PR and between 321954b and d077787.

📒 Files selected for processing (30)
  • .claude/skills/l0-swimlane/SKILL.md
  • conftest.py
  • docs/dfx/args-dump.md
  • docs/dfx/l0-swimlane-profiling.md
  • python/bindings/task_interface.cpp
  • python/simpler/worker.py
  • simpler_setup/scene_test.py
  • simpler_setup/tools/dump_viewer.py
  • simpler_setup/tools/l0_swimlane.py
  • src/a2a3/platform/onboard/host/device_runner.cpp
  • src/a2a3/platform/sim/host/device_runner.cpp
  • src/a5/platform/onboard/host/device_runner.cpp
  • src/a5/platform/sim/host/device_runner.cpp
  • src/common/platform/include/common/args_dump.h
  • src/common/platform/include/host/args_dump_collector.h
  • src/common/platform/onboard/host/device_runner_base.cpp
  • src/common/platform/onboard/host/device_runner_base.h
  • src/common/platform/shared/aicpu/args_dump_aicpu.cpp
  • src/common/platform/shared/host/args_dump_collector.cpp
  • src/common/platform/sim/host/device_runner_base.cpp
  • src/common/platform/sim/host/device_runner_base.h
  • src/common/task_interface/args_dump_config.h
  • src/common/task_interface/call_config.h
  • tests/st/a2a3/tensormap_and_ringbuffer/dfx/args_dump/test_args_dump.py
  • tests/ut/cpp/a2a3/test_args_dump.cpp
  • tests/ut/cpp/common/test_args_dump_collector.cpp
  • tests/ut/cpp/types/test_call_config.cpp
  • tests/ut/py/test_chip_worker.py
  • tests/ut/py/test_l0_swimlane.py
  • tests/ut/py/test_scene_test_dump_args.py

Comment thread docs/dfx/core-swimlane-profiling.md
Comment thread docs/dfx/l0-swimlane-profiling.md Outdated
Comment thread src/a5/platform/sim/host/device_runner.cpp
@indigo1973
indigo1973 force-pushed the l0_0727 branch 6 times, most recently from 3b07894 to a029fd4 Compare July 30, 2026 08:49

@ChaoZheng109 ChaoZheng109 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

补充 4 条定位到具体代码行的评论(编号沿用此前整体评审中的 Should fix #2、Consider #6/#9/#10)。均非阻塞性缺陷,核心逻辑与 wire 布局我已逐条核对,未发现正确性问题。

Comment thread tests/ut/py/test_chip_worker.py
Comment thread src/common/platform/include/common/args_dump.h Outdated
Comment thread src/common/platform/include/common/args_dump.h
Comment thread src/common/task_interface/call_config.h Outdated
@indigo1973
indigo1973 force-pushed the l0_0727 branch 4 times, most recently from f33aba3 to 8a3bdee Compare August 3, 2026 04:35
@ChaoZheng109

Copy link
Copy Markdown
Collaborator

设计建议:L3 的选择性 payload 应复用 L1 通路,而非新起一条并行过滤器

整体实现质量很高(wire 结构静态断言齐全、双层校验、测试覆盖到位),但对 L3 的改造方向建议调整一下:这条"按 task/arg 槽位选 payload"的能力,L1(PARTIAL / Arg::dump())已经有完整通路,且在 a2a3/a5 × host_build_graph/tmr 全矩阵布好线了。本 PR 另起了一条并行路径,和 L1 产生了重复。

重复点

L1 已有(args_dump_aicpu) 本 PR 新造
ArgsDumpArgMask = uint64_t(每 slot 一位的掩码) DumpArgsPayloadFilter.arg_mask(又一个 64-bit slot 掩码)
has_dump_arg_flag(mask, idx) / should_dump_arg(...)(mask & (1<<idx)) payload_filter_matches 里的 slot 位测试
set_dump_args_task_mask / get_dump_args_task_masks(per-task 掩码表,已全矩阵布线) DumpArgsPayloadFilterCallConfig → DumpDataHeader 再下发一遍

payload_filter_matches 的 slot 判定本质就是 has_dump_arg_flag 的重写,DumpArgsPayloadFilter.arg_mask 就是 ArgsDumpArgMask 的第二份。复用 L1 反而能省掉CallConfig / DumpDataHeader / worker.py / bindings 各处新加 wire 字段的那一摊。

唯一的真实分歧点,以及它的解法

复用 L1 的顾虑是:L1 的掩码门控的是"整条记录要不要产生"(元数据+payload 一起丢),直接套到 L3 会让 L3 的 JSON 不再全量。

解法很简单——设备侧 g_dump_args_level 本来就在手边,加一个 level 分支即可:L3 时掩码只管 bin(payload),不管 json(元数据)。

dump_arg_record 里的落点(替换掉新造的 payload_filter_matches 分支):

bool copy_payload_l3 = false;
if (g_dump_args_level == FULL_JSON_ONLY) {
    ArgsDumpArgMask mask, flags;
    get_dump_args_task_masks(info.task_id, &mask, &flags);   // L1 已有的 per-task 查表
    copy_payload_l3 = has_dump_arg_flag(mask, info.arg_index); // L1 已有的纯位测试(无模式短路)
}
if (is_scalar || (g_dump_args_level == FULL_JSON_ONLY && !copy_payload_l3)) {
    copy_bytes = 0;
}
  • L3 的 per-task 循环仍对每个 arg 调 dump_arg_record,元数据照旧全量;
  • 掩码只决定 copy_bytes——命中才拷 payload;
  • L1(PARTIAL)那条完全不变(掩码仍在上层 dump_task_args 门控整条记录);
  • 同一个掩码、同一个 has_dump_arg_flag,靠 g_dump_args_level 分流作用对象。这里用 has_dump_arg_flag 而非 should_dump_arg,因为后者在非 PARTIAL 模式会 return true 把掩码短路掉。

于是整个设计塌缩成

  1. DumpArgsPayloadFilter + payload_filter_matches + CallConfig/DumpDataHeader/worker.py/bindings 里的新 wire 字段;
  2. 消费侧全部复用 L1:get_dump_args_task_masks + has_dump_arg_flag,外加上面的 level 分支(3~4 行);
  3. 剩下唯一的新东西:把"运行期按 func-id 集合选中的 task"喂进 L1 已有的注入点 set_dump_args_task_mask(task_id, mask, 0)——放 orchestrator,它提交每个 task 时本来就算好了 active_fids,func-id 集合匹配在这里判一次(per-task,比现在 per-arg 判还省),命中就调这个既有接口,而不是新开一路。

这样 tensor 掩码通路从头到尾就是 L1 的,L3 与 L1 的差别被压到"掩码管 record 还是只管 bin"这一个 level 分支上,语义清楚、surface 最小。

其余部分(--restore-arg 的 strided 散射还原、msprof-timeout、docs、测试)都没问题,可以保留。另外 a5 侧"payload 消费限制"目前只是文档,没有代码护栏,建议在 a5 onboard 上对 payload 消费硬报错,避免 #1560 未修复期间静默消费错误字节。

@ChaoZheng109

Copy link
Copy Markdown
Collaborator

补充:复用 L1 方案的覆盖范围

复用 L1 后,L3 选择性 payload 的覆盖面直接继承 L1 的注入点现状。确认 scope 如下:

runtime L1 现状 L3 payload 是否覆盖
a2a3 host_build_graph ✅ 有 set_dump_args_task_mask 注入 ✅ 覆盖
a2a3 tensormap_and_ringbuffer ✅ 覆盖
a5 tensormap_and_ringbuffer 必须覆盖,不能漏
a5 host_build_graph ❌ 无 orchestrator / 无注入(未完成的临时占位) 先不支持(有意的边界)

改动量:

  • 消费侧:common 的 args_dump_aicpu.cpp 改一处(level 分支),上表前三个 runtime 共用这份文件,自动覆盖。
  • 注入侧:在有 orchestrator 的三个 runtime 各加"运行期按 func-id 集合注入掩码"分支——a2a3 hbg / a2a3 tmr / a5 tmr

a5 hbg 先不支持是明确的 scope 边界(要覆盖需先补齐 a5 hbg 的 orchestrator dump 通路,超出本 PR);且 a5 payload 消费本就被 #1560 标为不受支持,这个边界是自洽的。请在 PR 描述里显式写明,避免被当成遗漏。

@indigo1973 indigo1973 changed the title Support: restore selected args payloads in L0 replay Support: capture selected level-3 payloads for L0 replay Aug 4, 2026
@indigo1973
indigo1973 force-pushed the l0_0727 branch 2 times, most recently from 4ff360d to f82e04a Compare August 4, 2026 03:27
@indigo1973 indigo1973 changed the title Support: capture selected level-3 payloads for L0 replay Support: capture selected level-3 payloads for L0 swimlane replay Aug 4, 2026
@indigo1973

indigo1973 commented Aug 4, 2026

Copy link
Copy Markdown
Contributor Author

现在,匹配后通过现有的 set_dump_args_task_mask(task_id, mask, 0) 写入 L1 已有的 per-task mask table。L3的 dump_arg_record() 消费侧也改为使用 get_dump_args_task_masks() 和 has_dump_arg_flag(),mask 只控制 args.bin payload 是否复制,args_dump.json 的记录仍然完整输出。原有 L1 PARTIAL 模式的 record 过滤语义没有变化。原来的 per-record payload_filter_matches() 路径已经移除,因此不再存在第二套 payload 判定或 mask table。与建议字面上唯一的差异是没有完全删除 DumpArgsPayloadFilter。它现在只负责把 CLI 中尚未解析的“func-id 集合 + slot mask”从 host 传到 AICPU。因为此时还没有运行期 task_id,现有 L1 table 只能存放解析后的 task_id -> mask,无法直接携带这个 selector。selector 到达 orchestrator、解析成具体 task 后,后续数据通路完全复用 L1。
消费侧统一位于 common args_dump_aicpu.cpp,因此前三个 runtime 共用同一套 L3 payload 消费逻辑。

@indigo1973 indigo1973 closed this Aug 4, 2026
@indigo1973 indigo1973 reopened this Aug 4, 2026
@indigo1973 indigo1973 changed the title Support: capture selected level-3 payloads for L0 swimlane replay Add: restore marked args for L0 swimlane replay Aug 4, 2026
Level 3 args dump keeps complete args_dump.json metadata for Core (L0)
swimlane replay while reusing the existing Level 1
CoreTaskArgs::dump(...) mask to write only marked tensor payloads. This
preserves Level 1 behavior and avoids a parallel task/slot selector path.

- Add --restore-arg SLOT to initialize selected replay tensors from
  their captured before_dispatch bytes for structured inputs in hw-native-sys#1532.
- Add --msprof-timeout MINUTES to bound op-simulator collection.
- Keep args.bin optional when Level 3 has no marked tensor payload.
- Reject a5 payload restoration while hw-native-sys#1560 remains open; completing
  that platform scope depends on fixing hw-native-sys#1560.
- Cover payload capture, restoration, strided views, and error paths.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants