Add: directory indexes for examples/, examples/a2a3/, examples/a5/ - #1564
Merged
ChaoWao merged 1 commit intoJul 29, 2026
Merged
Conversation
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThe PR expands documentation for the examples directory, adds detailed a2a3 and a5 tensormap/ringbuffer guides, and updates the root references section to point to the general examples index. ChangesExamples documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
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 `@examples/a2a3/tensormap_and_ringbuffer/README.md`:
- Around line 37-39: Update the scope statement in the README to exempt
deferred_notify_demo from the onboard-only classification, while keeping the
statement that the other examples require onboard hardware and transfer demos
need two dies.
In `@examples/README.md`:
- Around line 10-11: Complete the sentence in the example introduction by
changing the kernel-examples clause to say “if kernels are new to you,” while
preserving the existing runtime guidance and sentence structure.
- Around line 15-20: Revise the examples/README.md description so it claims
pytest collects the relevant test files and cases, not everything under
examples/. Keep standalone worker examples and their script-based invocations
documented separately from the pytest commands, while preserving the simulator
and hardware command details.
🪄 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: 6588ce55-9f9d-4919-9ef2-01fe58ff55a4
📒 Files selected for processing (4)
README.mdexamples/README.mdexamples/a2a3/tensormap_and_ringbuffer/README.mdexamples/a5/tensormap_and_ringbuffer/README.md
ChaoWao
force-pushed
the
docs/examples-directory-indexes
branch
from
July 29, 2026 04:26
3f64b0c to
4d9e3f8
Compare
Of the three branches under `examples/`, only `workers/` had an index. The 22 `@scene_test` examples under `a2a3/tensormap_and_ringbuffer/` and `a5/tensormap_and_ringbuffer/` were reachable only by listing the directory, and nothing said what distinguished one from the next. `examples/README.md` states the organizing principle, which is not visible from the tree: `workers/` teaches how the runtime works through the raw `Worker` API and is split by level, while `a2a3/` and `a5/` teach how to write and validate a kernel through `@scene_test` and are split by architecture. The two per-architecture indexes group their examples by what each one adds — first kernel, compute, asynchronous completion and cross-card transfer — and record which platforms each is marked for and how many dies it needs, since most are onboard-only and that is invisible until a run silently deselects. The exceptions are named rather than generalized over: `deferred_notify_demo` runs the simulator path on both architectures, and `prefetch_async_demo` is the one async demo that needs a single die. Two facts that were previously undiscoverable: - `docs/INCORE_ORCHESTRATION_GUIDE.md` explains the AICPU-side orchestration model every example in both trees depends on, and had no inbound link from anywhere in the repo. Both indexes now open by pointing at it. - Seven examples exist under both architectures with the same name and are ports of each other, differing mainly in tile shapes and platform strings (`vector_example` differs by two lines). Each index names the seven and the ones unique to it, so a change to one side is not made without seeing the other. The root README's `examples/a2a3/` reference is retargeted at the new index. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Of the three branches under
examples/, onlyworkers/had an index. The 22@scene_testexamples undera2a3/tensormap_and_ringbuffer/anda5/tensormap_and_ringbuffer/were reachable only by listing the directory, with nothing to say what distinguished one from the next.examples/README.md— states the organizing principle, which the tree does not show:workers/teaches how the runtime works through the rawWorkerAPI and is split by level;a2a3/anda5/teach how to write and validate a kernel through@scene_testand are split by architecture.examples/a2a3/tensormap_and_ringbuffer/README.mdandexamples/a5/tensormap_and_ringbuffer/README.md— group each tree's examples by what they add (first kernel → compute → asynchronous completion and cross-card transfer) and record the platforms each is marked for. Most are onboard-only, which is invisible until a run silently deselects them.Two things that were previously undiscoverable:
docs/INCORE_ORCHESTRATION_GUIDE.mdhad no inbound link from anywhere in the repo. It is the one document explaining the AICPU-side orchestration model that every example in both trees depends on — orchestration runs on the AICPU, TensorMap discovers dependencies from tensor overlap, task memory comes from ring buffers. Both indexes now open by pointing at it.vector_example,paged_attention,paged_attention_manual_scope,paged_attention_unroll_manual_scope,async_notify_demo,deferred_notify_demo,sdma_async_completion_demo. They differ mainly in tile shapes and platform strings —vector_examplediffers by two lines of 72. Each index names the shared seven and the ones unique to it, so a change to one side is not made without seeing the other. This documents the duplication; it does not attempt to remove it.The root README's
examples/a2a3/reference is retargeted at the new index.Testing
markdownlint-cli2 --config tests/lint/.markdownlint.yaml— 0 errors on all four files@scene_testCASES[*]["platforms"]or@pytest.mark.platforms, and device counts againstdevice_countmarkersDocs only; no code, test, or build files touched.