hw-native-sys · ChaoZheng109 · Aug 3, 2026 · Jul 27, 2026
diff --git a/docs/capability-survey.md b/docs/capability-survey.md
@@ -63,10 +63,10 @@ shared across a device's AICPU/AICore tiers but exclusive per `device_id`.
 | Comm window | Fabric V2 handles, VMM-IPC fallback | VMM shareable handles only |
 
 Two numbers surprise readers who skip the arch docs: the default
-`aicpu_thread_num` is **3** (`src/common/task_interface/call_config.h:112`) —
-neither the per-arch max nor the launch bound — and AICore geometry is not
-selectable at all, because `resolve_block_dim()` unconditionally takes the
-device maximum (`src/common/platform/onboard/host/device_runner_base.cpp:1201-1212`).
+`aicpu_thread_num` is **0 (auto)** — each architecture resolves it against its
+usable AICPU topology — and AICore geometry is not selectable at all, because
+`resolve_block_dim()` unconditionally takes the device maximum
+(`src/common/platform/onboard/host/device_runner_base.cpp:1201-1212`).
 Each arch doc's "three views of how many cores" section explains why the spec
 count, the silicon count, and the runtime-visible count differ
 (`src/a2a3/docs/hardware.md:42-51`).

diff --git a/docs/chip-level-arch.md b/docs/chip-level-arch.md
@@ -148,7 +148,7 @@ worker.init(device_id=0, bins=bins)   # bins = RuntimeBuilder(platform).get_bina
 
 config = CallConfig()
 # A run always takes the whole device; there is no per-call width knob.
-config.aicpu_thread_num = 3
+config.aicpu_thread_num = 0  # auto
 config.enable_pmu = 0
 worker.run(callable, args, config)
 worker.finalize()

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -214,7 +214,7 @@ Runtime behavior is configured via `kernel_config.py` in each example:
 ```python
 RUNTIME_CONFIG = {
     "runtime": "host_build_graph",    # Runtime to use
-    "aicpu_thread_num": 3,            # Number of AICPU scheduler threads
+    "aicpu_thread_num": 0,            # Auto-select AICPU threads
 }
 ```
 

diff --git a/docs/task-flow.md b/docs/task-flow.md
@@ -210,7 +210,7 @@ View does **not** own memory. Valid for the duration of a single
 
 ```cpp
 struct CallConfig {
-    int32_t aicpu_thread_num = 3;
+    int32_t aicpu_thread_num = 0;  // auto
     int32_t enable_l2_swimlane = 0;  // perf_level 0–4 (0=off, 4=full)
     int32_t enable_dump_args = 0;
     int32_t enable_pmu = 0;           // 0 = disabled; >0 selects PMU event type
@@ -683,7 +683,7 @@ w3 = Worker(level=3, child_mode=PROCESS)
 w3.add_worker(NEXT_LEVEL, chip_worker_0)
 w3.init()    # fork chip_0 here
 
-w3.run(my_orch, args, CallConfig(aicpu_thread_num=3))
+w3.run(my_orch, args, CallConfig(aicpu_thread_num=0))
 ```
 
 Step-by-step (one chip worker):

diff --git a/docs/user/reference/python-api.md b/docs/user/reference/python-api.md
@@ -120,7 +120,7 @@ takes a device pointer; `DataType` carries the element types.
 
 | Field | Default | Meaning |
 | ----- | ------- | ------- |
-| `aicpu_thread_num` | `3` | AICPU threads for this run |
+| `aicpu_thread_num` | `0` | AICPU threads for this run; `0` selects the architecture default |
 | `enable_l2_swimlane` | `0` | `0` off; `1`–`4` select detail. L2 only |
 | `enable_dump_args` | `0` | Capture per-task arguments |
 | `enable_pmu` | `0` | `0` off; `>0` selects the event type |

diff --git a/examples/a2a3/tensormap_and_ringbuffer/benchmark_bgemm/test_benchmark_bgemm.py b/examples/a2a3/tensormap_and_ringbuffer/benchmark_bgemm/test_benchmark_bgemm.py
@@ -52,41 +52,35 @@ class TestBenchmarkBgemm(SceneTestCase):
         {
             "name": "Case0",
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "params": {"matmul_add_task_num": 500, "incore_data_size": 128, "incore_loop": 4, "grid_k": 2},
         },
         {
             "name": "Case1",
             "manual": True,
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "params": {"matmul_add_task_num": 64, "incore_data_size": 128, "incore_loop": 4, "grid_k": 2},
         },
         {
             "name": "Case2",
             "manual": True,
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "params": {"matmul_add_task_num": 256, "incore_data_size": 128, "incore_loop": 4, "grid_k": 2},
         },
         {
             "name": "Case3",
             "manual": True,
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "params": {"matmul_add_task_num": 64, "incore_data_size": 128, "incore_loop": 16, "grid_k": 2},
         },
         {
             "name": "Case4",
             "manual": True,
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "params": {"matmul_add_task_num": 64, "incore_data_size": 128, "incore_loop": 4, "grid_k": 4},
         },
         {
             "name": "Bgemm64",
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "params": {"matmul_add_task_num": 32, "incore_data_size": 64, "incore_loop": 1, "grid_k": 4},
         },
     ]

diff --git a/examples/a2a3/tensormap_and_ringbuffer/merge_pipeline_barrier/test_merge_pipeline_barrier.py b/examples/a2a3/tensormap_and_ringbuffer/merge_pipeline_barrier/test_merge_pipeline_barrier.py
@@ -61,7 +61,6 @@ class TestMergePipelineBarrier(SceneTestCase):
             # per-task via launch_spec.set_block_num in merge_orch.cpp).
             "name": "merge",
             "platforms": ["a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "params": {},
         },
     ]

diff --git a/examples/a2a3/tensormap_and_ringbuffer/paged_attention/README.md b/examples/a2a3/tensormap_and_ringbuffer/paged_attention/README.md
@@ -21,9 +21,9 @@ graph is a consequence of the data, not of the code.
 
 ## Cases
 
-Seven, all `platforms=["a2a3"]` with `aicpu_thread_num: 4`: `Case1`–`Case3` at
-production scale (up to batch 256, 16 heads, 8192 context), `CaseSmall1` /
-`CaseSmall2`, and `CaseVarSeq2` / `CaseVarSeq4` for ragged sequence lengths.
+Seven, all for `platforms=["a2a3"]` with automatic AICPU thread selection:
+`Case1`–`Case3` at production scale (up to batch 256, 16 heads, 8192 context),
+`CaseSmall1` / `CaseSmall2`, and `CaseVarSeq2` / `CaseVarSeq4` for ragged sequence lengths.
 The four kernels are registered as sub-callables named `QK`, `SF`, `PV`, `UP`.
 
 ## Run

diff --git a/examples/a2a3/tensormap_and_ringbuffer/paged_attention/test_paged_attention.py b/examples/a2a3/tensormap_and_ringbuffer/paged_attention/test_paged_attention.py
@@ -64,7 +64,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "Case1",
             "platforms": ["a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "params": {
                 "batch": 256,
                 "num_heads": 16,
@@ -79,7 +78,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "Case2",
             "platforms": ["a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 64,
@@ -95,7 +93,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "Case3",
             "platforms": ["a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 64,
@@ -111,7 +108,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "CaseSmall1",
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "params": {
                 "batch": 1,
                 "num_heads": 16,
@@ -126,7 +122,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "CaseSmall2",
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 1,
@@ -142,7 +137,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "CaseVarSeq2",
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 2,
@@ -159,7 +153,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "CaseVarSeq4",
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 4,

diff --git a/...ensormap_and_ringbuffer/paged_attention_manual_scope/test_paged_attention_manual_scope.py b/...ensormap_and_ringbuffer/paged_attention_manual_scope/test_paged_attention_manual_scope.py
@@ -68,7 +68,7 @@ class TestPagedAttentionManualScope(SceneTestCase):
             # MANUAL scope; the default per-ring task window (16384) can fill
             # before the oldest task retires and wedge the orchestrator
             # (FLOW_CONTROL_DEADLOCK / code 3). Double the window for headroom.
-            "config": {"aicpu_thread_num": 4, "runtime_env": {"ring_task_window": 32768}},
+            "config": {"runtime_env": {"ring_task_window": 32768}},
             "params": {
                 "batch": 256,
                 "num_heads": 16,
@@ -83,7 +83,6 @@ class TestPagedAttentionManualScope(SceneTestCase):
         {
             "name": "Case2",
             "platforms": ["a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 64,
@@ -99,7 +98,6 @@ class TestPagedAttentionManualScope(SceneTestCase):
         {
             "name": "Case3",
             "platforms": ["a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 64,
@@ -115,7 +113,6 @@ class TestPagedAttentionManualScope(SceneTestCase):
         {
             "name": "CaseSmall1",
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "params": {
                 "batch": 1,
                 "num_heads": 16,
@@ -130,7 +127,6 @@ class TestPagedAttentionManualScope(SceneTestCase):
         {
             "name": "CaseSmall2",
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 1,
@@ -146,7 +142,6 @@ class TestPagedAttentionManualScope(SceneTestCase):
         {
             "name": "CaseVarSeq2",
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 2,
@@ -163,7 +158,6 @@ class TestPagedAttentionManualScope(SceneTestCase):
         {
             "name": "CaseVarSeq4",
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 4,

diff --git a/...a3/tensormap_and_ringbuffer/paged_attention_ringbuffer/test_paged_attention_ringbuffer.py b/...a3/tensormap_and_ringbuffer/paged_attention_ringbuffer/test_paged_attention_ringbuffer.py
@@ -72,7 +72,6 @@ class TestPagedAttentionRingbuffer(SceneTestCase):
             # ring_heap is bytes per ring. Non power-of-2 sizes are accepted,
             # but 4 MiB keeps the small-ring stress intent compact.
             "config": {
-                "aicpu_thread_num": 4,
                 "runtime_env": {
                     "ring_task_window": 64,
                     "ring_heap": 4 * 1024 * 1024,

diff --git a/...les/a2a3/tensormap_and_ringbuffer/paged_attention_unroll_manual_scope/README.md b/...les/a2a3/tensormap_and_ringbuffer/paged_attention_unroll_manual_scope/README.md
@@ -44,8 +44,8 @@ directory to read for that API on its own, against unchanged kernels.
 
 ## Cases
 
-Three — `Case1`–`Case3`, all `platforms=["a2a3"]` with
-`aicpu_thread_num: 4`. The baseline's small and variable-sequence cases have no
+Three — `Case1`–`Case3`, all for `platforms=["a2a3"]` with automatic AICPU
+thread selection. The baseline's small and variable-sequence cases have no
 counterpart here.
 
 ## Run

diff --git a/...ingbuffer/paged_attention_unroll_manual_scope/test_paged_attention_unroll_manual_scope.py b/...ingbuffer/paged_attention_unroll_manual_scope/test_paged_attention_unroll_manual_scope.py
@@ -64,7 +64,6 @@ class TestPagedAttentionUnrollManualScope(SceneTestCase):
         {
             "name": "Case1",
             "platforms": ["a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "params": {
                 "batch": 256,
                 "num_heads": 16,
@@ -79,7 +78,6 @@ class TestPagedAttentionUnrollManualScope(SceneTestCase):
         {
             "name": "Case2",
             "platforms": ["a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 64,
@@ -95,7 +93,6 @@ class TestPagedAttentionUnrollManualScope(SceneTestCase):
         {
             "name": "Case3",
             "platforms": ["a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 64,

diff --git a/examples/a2a3/tensormap_and_ringbuffer/qwen3_14b_decode/test_qwen3_14b_decode.py b/examples/a2a3/tensormap_and_ringbuffer/qwen3_14b_decode/test_qwen3_14b_decode.py
@@ -427,7 +427,6 @@ class TestQwen314BDecode(SceneTestCase):
             "name": "StressBatch16Seq3500",
             "platforms": ["a2a3"],
             # A run takes the whole device, matching the lib default.
-            "config": {"aicpu_thread_num": 4},
             "params": {"seed": 1234, "seq_len": 3500},
         },
     ]

diff --git a/examples/a2a3/tensormap_and_ringbuffer/scalar_data/README.md b/examples/a2a3/tensormap_and_ringbuffer/scalar_data/README.md
@@ -49,7 +49,8 @@ landing a value in `check[0..8]`:
 
 ## Cases
 
-One, `default`, `platforms=["a2a3"]`, `aicpu_thread_num: 4`.
+One, `default`, for `platforms=["a2a3"]`. The default AICPU configuration uses
+auto selection.
 
 Note the comment on the `check` tensor in `generate_args`: it is **exactly 9
 slots**, matching `check[0..8]`. Output-tensor slots are not seeded from the

diff --git a/examples/a2a3/tensormap_and_ringbuffer/scalar_data/test_scalar_data.py b/examples/a2a3/tensormap_and_ringbuffer/scalar_data/test_scalar_data.py
@@ -49,7 +49,6 @@ class TestScalarData(SceneTestCase):
         {
             "name": "default",
             "platforms": ["a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "params": {},
         },
     ]

diff --git a/examples/a2a3/tensormap_and_ringbuffer/vector_example/test_vector_example.py b/examples/a2a3/tensormap_and_ringbuffer/vector_example/test_vector_example.py
@@ -51,7 +51,6 @@ class TestVectorExample(SceneTestCase):
         {
             "name": "default",
             "platforms": ["a2a3sim", "a2a3"],
-            "config": {"aicpu_thread_num": 4},
             "params": {},
         },
     ]

diff --git a/examples/a5/tensormap_and_ringbuffer/bgemm/test_bgemm.py b/examples/a5/tensormap_and_ringbuffer/bgemm/test_bgemm.py
@@ -64,7 +64,6 @@ class TestBgemm(SceneTestCase):
         {
             "name": "default",
             "platforms": ["a5sim", "a5"],
-            "config": {"aicpu_thread_num": 4},
             "params": {},
         }
     ]

diff --git a/examples/a5/tensormap_and_ringbuffer/paged_attention/test_paged_attention.py b/examples/a5/tensormap_and_ringbuffer/paged_attention/test_paged_attention.py
@@ -70,7 +70,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "Case1",
             "platforms": ["a5"],
-            "config": {"aicpu_thread_num": 4},
             "params": {
                 "batch": 256,
                 "num_heads": 16,
@@ -85,7 +84,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "Case2",
             "platforms": ["a5"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 64,
@@ -101,7 +99,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "Case3",
             "platforms": ["a5"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 64,
@@ -117,7 +114,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "SmallCase1",
             "platforms": ["a5sim", "a5"],
-            "config": {"aicpu_thread_num": 4},
             "params": {
                 "batch": 1,
                 "num_heads": 16,
@@ -132,7 +128,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "SmallCase2",
             "platforms": ["a5sim", "a5"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 1,
@@ -148,7 +143,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "SmallCaseVarSeq2",
             "platforms": ["a5sim", "a5"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 2,
@@ -165,7 +159,6 @@ class TestPagedAttention(SceneTestCase):
         {
             "name": "SmallCaseVarSeq4",
             "platforms": ["a5sim", "a5"],
-            "config": {"aicpu_thread_num": 4},
             "manual": True,
             "params": {
                 "batch": 4,