Doc: document swimlane / dep_gen split workflow for perf-sensitive runs

[hw-native-sys-bot]

Why

The two-launch workflow (one --enable-dep-gen capture per topology + N --enable-l2-swimlane runs, joined by swimlane_converter --deps-json) is already supported end-to-end — swimlane_converter.load_deps_json docstring even calls it "the typical workflow". But the user-facing docs/dfx/l2-swimlane-profiling.md doesn't mention dep_gen anywhere. Result:

• Users wonder why their Perfetto trace has no fanout arrows.
• The converter's "no deps.json — re-run dep_gen and pass --deps-json" hint flies by unnoticed.
• People doing strict perf measurement pair both flags by default and lose ~10 µs/round that they could have isolated by splitting.

Confirmed against paged_attention_unroll Case1 in the previous session: swimlane level 4 + dep_gen combined adds < 10 µs per round on onboard a2a3; for default usage paired is fine, the split is for the strict-perf case only.

What changes

• docs/dfx/l2-swimlane-profiling.md §3.5 "Dependency arrows from dep_gen" — new subsection between §3.4 and §4. Covers:
  • Why the device hot path omits fanout (PR Refactor: drop fanout from L2PerfRecord hot path #863 — out of the AICPU critical path).
  • Two artifacts + one join, in a table.
  • Default workflow (paired flags) vs split workflow (two launches) side by side, with criteria for choosing.
  • The converter's auto-detect / --deps-json flag and the missing-deps.json hint message.
  • What you do not need to script (input shape coupling, per-run dep_gen).
• docs/dfx/dep_gen.md §3 — cross-link forward to the split-workflow subsection so someone arriving at dep_gen first sees the alternative.

What doesn't change

No code. The workflow is already supported and the converter already prints the right discovery breadcrumb when deps.json is missing — the doc is the only gap.

Test plan

• pre-commit clean (markdownlint compact + aligned-delimiter table)
• internal anchor l2-swimlane-profiling.md#35-dependency-arrows-from-dep_gen matches GitHub's heading-slug derivation

[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

Run ID: d81136bb-77d1-4aee-9f4d-b10d97be8bce

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

This PR adds documentation explaining how dependency arrows are generated in L2 swimlane profiling. It introduces a reference note in dep_gen.md pointing to a split workflow, and adds a new subsection in l2-swimlane-profiling.md detailing how deps.json and l2_swimlane_records.json are joined via swimlane_converter to produce Perfetto dependency arrows.

Changes

Dependency Generation and Swimlane Profiling Documentation

Layer / File(s)	Summary
Dependency arrow generation and split workflow documentation docs/dfx/dep_gen.md, docs/dfx/l2-swimlane-profiling.md	Added a reference in dep_gen.md pointing to the split workflow section, and added section 3.5 in l2-swimlane-profiling.md explaining how dependency arrows are generated by joining deps.json with l2_swimlane_records.json using swimlane_converter, with guidance on default paired vs split workflows and converter behavior when deps.json is unavailable.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A graph is born when arrows dance,
deps and swimlanes in their prance,
Split or paired, the choice is clear—
Perfetto flows shall soon appear! 🎯

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: documenting the swimlane/dep_gen split workflow for performance-sensitive runs, which is the core focus of both documentation updates.
Description check	✅ Passed	The description clearly explains the motivation, detailed changes, and rationale for documenting the two-launch workflow with concrete examples and performance considerations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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 and usage tips.}

[gemini-code-assist]

Code Review

This pull request updates the documentation for L2 swimlane profiling and dependency generation, adding a new section that explains how dependency arrows are integrated into swimlane records. It describes both the default paired-flag workflow and the split workflow recommended for performance-sensitive measurements. There are no review comments, and I have no feedback to provide.

[coderabbitai]

Actionable comments posted: 1

🤖 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/l2-swimlane-profiling.md`:
- Around line 220-296: The doc is inconsistent: dependency arrows come from
deps.json produced by dep_gen and joined by swimlane_converter (as described in
this section), but earlier text still claims arrows follow fanout[]; update all
earlier references (mentions of fanout[], any statements in the intro or the
L2SwimlaneAicpuTaskRecord comment) to state that swimlane records carry timing
only and that visual arrows are derived from deps.json/dep_gen and merged by
swimlane_converter (and optionally via --deps-json), clarifying that fanout[] is
not embedded per-task in l2_swimlane_records.json but instead is represented in
deps.json.

🪄 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

Run ID: f712e7d7-2db6-4bcb-a02e-2b8cd7c8366a

📥 Commits

Reviewing files that changed from the base of the PR and between 1eec5c1 and a8e3e9b.

📒 Files selected for processing (2)

• docs/dfx/dep_gen.md
• docs/dfx/l2-swimlane-profiling.md