Skip to content

Fix: remove redundant scene run configuration - #1915

Merged
ChaoZheng109 merged 1 commit into
hw-native-sys:mainfrom
yanghaoran29:fix/remove-redundant-scene-run-configuration
Aug 21, 2026
Merged

Fix: remove redundant scene run configuration#1915
ChaoZheng109 merged 1 commit into
hw-native-sys:mainfrom
yanghaoran29:fix/remove-redundant-scene-run-configuration

Conversation

@yanghaoran29

@yanghaoran29 yanghaoran29 commented Aug 20, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Remove redundant default aicpu_thread_num and obsolete top-level block_dim from ordinary HBG/TMR scene cases, examples, and the prewarm benchmark
  • Keep explicit thread counts only where tests depend on scheduler/DFX topology, with a nearby explanation for every retained override
  • Reject unknown CASES[*]["config"] and nested runtime_env keys when scene-test classes are imported
  • Fix whitebox helpers that assumed CASES[*]["config"] always existed after config cleanup
  • Update scene-test guidance and the A5 runtime documentation to match the current five-thread/four-scheduler topology

Test plan

  • Pre-commit hooks pass on all changed files
  • Config-validation unit tests (5 passed)
  • A2/A3 and A5 full scene-test collection
  • A2/A3 sim resource, HBG, and TMR suites
  • A5 sim resource, HBG, and TMR suites
  • A5 cold prewarm benchmark runs through worker.run() without AttributeError
  • Full Python unit suite: 1681 passed, 6 skipped; two GCC setup tests are incompatible with the locally installed /usr/bin/g++-15, and one worker child-reaping case passed on isolated rerun
  • Onboard-only cases (Qwen decode, async worker) — not run; npu-smi is unavailable on this machine

@coderabbitai

coderabbitai Bot commented Aug 20, 2026

Copy link
Copy Markdown

Review Change Stack

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: 2ca3564a-2ebb-4215-b2ae-f7e01b110593

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

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 47b4584d-d569-40b6-877e-e39848fabb2b

📥 Commits

Reviewing files that changed from the base of the PR and between 43e61c6 and 6f20709.

📒 Files selected for processing (22)
  • .claude/skills/testing/SKILL.md
  • docs/getting-started.md
  • docs/testing.md
  • docs/user/how-to/write-and-run-a-kernel.md
  • examples/a2a3/host_build_graph/qwen3_14b_decode/test_qwen3_14b_decode.py
  • examples/workers/l4/vector_add_mixed_l3/main.py
  • tests/st/a2a3/host_build_graph/graph_execution/test_graph_execution.py
  • tests/st/a2a3/host_build_graph/graph_execution/test_graph_execution_aic_aiv.py
  • tests/st/a2a3/host_build_graph/graph_execution/test_graph_execution_mix_spmd.py
  • tests/st/a2a3/host_build_graph/graph_predicated_dispatch/test_graph_predicated_dispatch.py
  • tests/st/a2a3/host_build_graph/native_run_lifecycle/test_native_run_lifecycle.py
  • tests/st/a2a3/host_build_graph/run_stream_reuse/test_run_stream_reuse.py
  • tests/st/a2a3/host_build_graph/worker_async_endpoint/test_worker_async_endpoint.py
  • tests/st/a2a3/host_build_graph/worker_async_fifo/test_worker_async_fifo.py
  • tests/st/a2a3/tensormap_and_ringbuffer/pipeline_slots/test_pipeline_slots.py
  • tests/st/a2a3/tensormap_and_ringbuffer/test_l3_launch_acceptance.py
  • tests/st/a5/host_build_graph/graph_execution/test_graph_execution.py
  • tests/st/a5/host_build_graph/graph_execution/test_graph_execution_aic_aiv.py
  • tests/st/a5/host_build_graph/graph_execution/test_graph_execution_mix_spmd.py
  • tests/st/a5/host_build_graph/graph_predicated_dispatch/test_graph_predicated_dispatch.py
  • tests/st/a5/tensormap_and_ringbuffer/mx_fp_gemm/test_mx_fp_gemm.py
  • tests/st/a5/tensormap_and_ringbuffer/pipeline_slots/test_pipeline_slots.py
💤 Files with no reviewable changes (10)
  • tests/st/a5/host_build_graph/graph_execution/test_graph_execution.py
  • examples/a2a3/host_build_graph/qwen3_14b_decode/test_qwen3_14b_decode.py
  • tests/st/a2a3/host_build_graph/graph_execution/test_graph_execution_aic_aiv.py
  • tests/st/a2a3/host_build_graph/graph_execution/test_graph_execution_mix_spmd.py
  • tests/st/a5/host_build_graph/graph_execution/test_graph_execution_aic_aiv.py
  • tests/st/a2a3/host_build_graph/graph_execution/test_graph_execution.py
  • examples/workers/l4/vector_add_mixed_l3/main.py
  • tests/st/a2a3/host_build_graph/graph_predicated_dispatch/test_graph_predicated_dispatch.py
  • tests/st/a5/host_build_graph/graph_predicated_dispatch/test_graph_predicated_dispatch.py
  • tests/st/a5/host_build_graph/graph_execution/test_graph_execution_mix_spmd.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.


📝 Walkthrough

Walkthrough

The change makes AICPU thread configuration optional by default. Documentation and testing guidance now use architecture defaults. Examples and scene tests remove unnecessary thread and block-dimension overrides. Runtime helpers accept cases without a config entry.

Changes

Runtime Configuration Defaults

Layer / File(s) Summary
Configuration guidance
.claude/skills/testing/SKILL.md, docs/getting-started.md, docs/testing.md, docs/user/how-to/write-and-run-a-kernel.md
Documentation and testing instructions now omit default aicpu_thread_num settings and reserve explicit values for topology-dependent tests.
Override removal
examples/workers/l4/vector_add_mixed_l3/main.py, tests/st/a2a3/host_build_graph/..., tests/st/a2a3/tensormap_and_ringbuffer/..., tests/st/a5/host_build_graph/..., tests/st/a5/tensormap_and_ringbuffer/...
Examples and test cases remove unnecessary aicpu_thread_num and block_dim overrides while retaining required configuration values.
Optional configuration handling
tests/st/a2a3/host_build_graph/native_run_lifecycle/test_native_run_lifecycle.py, tests/st/a2a3/host_build_graph/run_stream_reuse/test_run_stream_reuse.py, tests/st/a2a3/tensormap_and_ringbuffer/pipeline_slots/test_pipeline_slots.py
Runtime configuration lookups use {} when a case does not define config.

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

Merge Risk: ⚪ Minimal · up to 6f207

The change removes redundant scene settings and keeps a specialized thread override; no actionable merge-blocking risk remains after normal checks, though the owner should confirm that the two-thread setting is required.

Suggested labels: code health

Poem

I’m a rabbit with defaults in my nest,
No extra thread knobs—just architecture’s best.
Empty configs now hop through the run,
Block dimensions retreat from the sun.
Tests stay tidy, and the kernels all hum.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 40.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 and concisely describes the main change: removing redundant scene run configuration.
Description check ✅ Passed The description is directly related to the changes and explains configuration cleanup, validation, documentation, and testing.

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.

@yanghaoran29
yanghaoran29 force-pushed the fix/remove-redundant-scene-run-configuration branch 3 times, most recently from 8bc28c2 to 6f20709 Compare August 20, 2026 08:45
@ChaoZheng109

Copy link
Copy Markdown
Collaborator

整体方向认同:block_dim 确认是死键(_build_config() 不读、CallConfig 无该字段),.get("config", {}) 的修复也核对完整。CI 三个真机任务全绿。以下是建议一并处理的几处,以及两项后续跟进。

建议本 PR 内处理

1. tests/st/a5/tensormap_and_ringbuffer/bench_prewarm_timing.py:99 —— 唯一一处会崩的 block_dim

run_cfg.block_dim = config_dict.get("block_dim", 1)

CallConfig 是 nanobind 类且没有 nb::dynamic_attr(),实测:

AttributeError: 'CallConfig' object has no attribute 'block_dim'

该行位于 _run_scenario() 的无条件主路径(worker.init() 之后、worker.run() 之前),所以这个 bench #1451(2026-07-28)加入起就没跑通过一次 —— #1309 在两天前(07-26)已删除该 knob。因为文件名不匹配 test_*.py,CI 从不收集它,所以一直没暴露。

CASES 里那些的区别:dict 里的 block_dim_build_config(),被 dict.get() 静默丢弃,只是空转;这一行直接对 nanobind 对象赋值,会真的抛异常。建议单行删除 —— 删后 block_dim 作为配置键的残留就归零了。

2. docs/getting-started.md:211-222 —— 新增说明悬空在一段废弃文档上

这段描述的 kernel_config.py 配置机制已于 2026-04-15(#541 / #548)被 @scene_test 取代,RUNTIME_CONFIG 也没有任何 Python 代码读取(git grep RUNTIME_CONFIG -- '*.py' 零命中)。本 PR 从这个代码块里删掉了 aicpu_thread_num,又在下面新增了 "Omitting aicpu_thread_num selects the architecture default" —— 这句话的主语已不在上方代码块中。建议改写为指向 CASES[*]["config"],或整段删除。

3. src/a5/runtime/tensormap_and_ringbuffer/docs/RUNTIME_LOGIC.md —— 与本 PR 同源的 a5 半迁移

a5 的 PLATFORM_DEFAULT_AICPU_THREAD_NUM 是 5(1 orch + 4 sched),该文件把几何适配成了 a5,线程拓扑却留在 a2a3:

现文 应为
:55-56 "the common four-thread configuration uses 3 schedulers" a5 默认五线程 / 4 调度器
:545-556 "With aicpu_thread_num=4…",3 调度线程 × 12 AIC + 24 AIV(36÷3) 4 调度线程 × 9 AIC + 18 AIV(36÷4)
:909-913 RUNTIME_CONFIG = {"aicpu_thread_num": 4, "block_dim": 24} 机制已废弃 + 线程数应为 5 + block_dim: 24 是 a2a3 的 PLATFORM_MAX_BLOCKDIM,a5 是 36

:545 尤其说明问题:cluster 数已经从 24 改成了 a5 的 36,唯独线程数没改 —— 和本 PR 修的那 6 个 a5 用例成因一致。

4. src/common/task_interface/call_config.h:59 —— 同一文件内两条注释互相矛盾

:22   * There is no block_dim knob: a run always takes the whole device.
:59  // ...distinct configuration tier from the top-level execution knobs (block_dim, aicpu_thread_num).

#1309 删字段时漏了 :59,删掉 block_dim, 即可。

5. tests/st/a5/tensormap_and_ringbuffer/dfx/chip_swimlane/test_chip_swimlane.py:71(可选)

注释写 "the low-thread cases exercise a shard layout the 4-thread default never reaches" —— 与 a2a3 同名文件逐字相同,在 a5 上默认是 5。该文件本 PR 未改动,顺带修与否都可以。

建议后续单独 PR

6. 给 CASES[*]["config"] 加未知键校验 —— 这是 block_dim 反复回潮的根因

配置分两层,只有下层有类型:CallConfig(C++ POD + nanobind)删得很干净,直接赋值会报错(上面第 1 条就是撞上它);但上层 CASES[*]["config"] 是裸 dict,_build_config() 用一串 dict.get(k, default) 白名单拉取 —— 只问"有没有我认识的键",从不问"有没有我不认识的键",未知键连被看一眼的机会都没有。

后果:#1309 删字段并清理了 213 处,此后 18 天内被 8 个 PR 重新写回 8 次#1464 就在删除当天,另有 #1473 / #1451 / #1540 / #1444 / #1678 / #1733 / #1819)。原因很朴素 —— 新增 scene test 的标准做法是复制现成文件,而没有任何东西会报错。本 PR 是第二次人肉清理。

而且 block_dim 还算最轻的(空转)。同一机制下:

  • ring_heap 拼成 ring_heep → 静默取 0 → 落到 PTO2_RING_* 环境变量 / 编译期默认这条 fallback 链 → 测试照常通过,但跑的是完全不同的 ring 尺寸
  • device_count 拼错 → 静默按 1 卡跑,双卡测试变单卡测试,依然绿。

这两类是"在错误配置下通过",比死键危险得多。

设计上有几点已经查实,可以直接用:

  • config / runtime_env 命名空间完全由框架拥有(全仓库没有测试从 case["config"] 读自定义键),可以严格校验。合法键集:aicpu_thread_num / runtime_env / device_count / num_sub_workersruntime_env 子键 ring_task_window / ring_heap / ring_dep_pool
  • case 顶层不能严格校验 —— required_sched_phases 是测试自有的合法扩展键(a5/.../test_chip_swimlane.py:116 真实消费)。要覆盖顶层需要额外的 EXTRA_CASE_KEYS 之类声明机制。
  • 拦截点建议放在 @scene_test 装饰器(scene_test.py:1246,目前对 CASES 零校验):import 期失败,一次覆盖 pytest 收集(_select_cases,:841)和 standalone run_module(:1698)两条路径。
  • 合法键集目前散在两个消费者(_build_config() :1386/:1392 与 session 分组 :1986/2097/2269/2273),从未写在一处 —— 校验器第一步就是把它收拢成单一事实源。

时机很好:全仓库 AST 扫描下来,config 层唯一的未知键就是 block_dim(8 处)。本 PR 清完后存量归零,校验器可以直接上,不会打出一堆历史失败。

7. 给保留下来的 aicpu_thread_num 覆盖补注释

本 PR 在 .claude/skills/testing/SKILL.md:185 新增了"必须覆盖时加就近注释说明依赖"的规则,但保留的绝大多数覆盖(dummy_task / predicated_dispatch / dep_gen_chain 等的 =2)都没有注释,新规则落地即处于自相矛盾状态。scope_statschip_swimlane 是有注释的正面例子。至少在 PR 描述里记为后续项。

@yanghaoran29
yanghaoran29 force-pushed the fix/remove-redundant-scene-run-configuration branch from 6f20709 to d48811d Compare August 20, 2026 12:17
@yanghaoran29

Copy link
Copy Markdown
Contributor Author

@ChaoZheng109 感谢详细核对,1–7 项都已在本 PR 一并处理:

  1. 删除了 prewarm benchmark 对不存在的 CallConfig.block_dim 的赋值,并实际跑通 cold 路径到 worker.run()
  2. getting-started.md 已改为当前的 @scene_test / CASES[*]["config"] 配置方式,并补充 programmatic Worker / CallConfig 入口。
  3. A5 runtime 文档已改为默认 5 线程(4 scheduler + 1 orchestrator)、每 scheduler 9 AIC + 18 AIV,并移除废弃的 kernel_config.py / RUNTIME_CONFIG / block_dim 示例。
  4. call_config.h 中残留的 top-level block_dim 注释已删除。
  5. A5 chip-swimlane 注释已改为 5-thread default。
  6. @scene_test 装饰器增加了 import-time 严格校验:configruntime_env 只接受列出的框架键,未知键和非 mapping 层都会直接报错;case 顶层自定义键仍允许。新增 5 个单测覆盖合法键、block_dimring_heep 以及非 mapping 输入。
  7. 对仓库中保留的 topology-specific aicpu_thread_num 覆盖完成审计,并为此前缺说明的覆盖补了就近注释;当前 AST 扫描为 40 个覆盖、19 个文件,均有拓扑说明。

另外同步修正了 testing 文档/skill 中的合法键说明,并完成 A2/A3、A5 全量 sim sweep 与 pre-commit。

@yanghaoran29
yanghaoran29 force-pushed the fix/remove-redundant-scene-run-configuration branch from d48811d to 9ace656 Compare August 20, 2026 12:21
- Drop default aicpu_thread_num and obsolete top-level block_dim from ordinary HBG/TMR scene cases, examples, and the prewarm benchmark
- Reject unknown CASES config and runtime_env keys when scene-test classes load
- Keep topology-specific thread counts and document what each override covers
- Use case.get("config", {}) where whitebox helpers assumed config existed
- Update scene-test guidance and A5 scheduler topology documentation
@ChaoZheng109
ChaoZheng109 merged commit 3e5f8eb into hw-native-sys:main Aug 21, 2026
19 checks passed
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