facebookexperimental AutoWS Documentation
AutoWS has comprehensive design docs that live alongside the source code at:
third_party/nvidia/hopper/lib/Transforms/WarpSpecialization/docs/
CRITICAL: Read docs BEFORE reading source
When investigating or planning changes to AutoWS code, always read the relevant docs first before exploring the source files. The docs explain the design intent, invariants, and relationships between passes — information that is difficult to reconstruct from code alone. Reading docs first will:
- Give you the correct mental model before diving into implementation details
- Identify which files are relevant so you search less
- Surface invariants and edge cases that aren't obvious from code
How to find the right doc
Use the file map below to match your task to the relevant doc(s):
| If you're working on... | Read this doc first |
|---|---|
| Overall pipeline, pass ordering | docs/Overview.md |
| Task ID assignment (Hopper) | docs/TaskPartitionAndPropagation.md |
| Splitting ops across warp groups | docs/DataPartition.md |
| Channel insertion, async copies, barriers | docs/CodePartition.md |
| Code specialization / cloning into regions | docs/CodeSpecialization.md |
| SMEM/TMEM allocation, multi-buffering | docs/BufferAllocation.md, docs/AccumulationCounters.md, docs/SmemAllocationDesign.md |
| Memory planner liveness analysis | docs/MemoryPlannerVisualization.md |
| Memory lowering (global/shared/tensor) | docs/MemoryLowering.md |
| Token/barrier lowering to hardware | docs/TokenBarrierLowering.md |
| Ping-pong scheduling | docs/PingPongScheduling.md |
| Barrier fusion/merging | docs/BarrierFusion.md |
| Operand D / accumulator handling | docs/OperandDHandling.md |
| Reuse groups for buffer sharing | docs/ReuseGroups.md |
| TMEM allocation heuristics | docs/TMEMAllocationHeuristics.md |
| Utility functions | docs/Utilities.md |
Workflow
- Read the matching doc(s) from the table above.
- Then explore source files, guided by what the docs describe.
- If no doc matches your task, read
docs/Overview.mdfor the pipeline context and file map, then proceed to source.
CRITICAL: Update docs AFTER non-trivial code changes
When you make changes to AutoWS code that go beyond a simple bug fix, you must update the corresponding documentation. Specifically, update docs when:
- Adding a new pass or file: Add an entry to
docs/Overview.md(file map and pipeline diagram) and create a new doc if the pass is substantial. - Changing pass behavior or invariants: Update the doc that describes that pass to reflect the new behavior.
- Adding or changing data structures: Update the doc that references those structures.
- Changing the pipeline order: Update
docs/Overview.md. - Adding new concepts or terminology: Document them in the relevant doc or create a new one if no existing doc fits.
Do NOT update docs for:
- Pure bug fixes that don't change documented behavior
- Code style / refactoring that preserves semantics
Doc conventions
- Docs live in
third_party/nvidia/hopper/lib/Transforms/WarpSpecialization/docs/ - Each doc covers one logical area (one pass or closely related group of passes)
- Docs should explain why, not just what — design rationale matters
- Include the file(s) the doc covers at the top
- Use code snippets or IR examples to illustrate transformations