Skip to content

About

Visualize Layout Transformation and bank conflict.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

11 Commits

Folders and files

Repository files navigation

WarpWeaver tensor layout visualization

WarpWeaver

WarpWeaver is a lightweight C++20 tool for inspecting tensor layouts, bitwise swizzles, thread ownership, and shared-memory bank behavior.

Build

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
ctest --test-dir build --output-on-failure

The first version intentionally has no third-party runtime dependencies. The core library is separated from the CLI so a future TUI or Dear ImGui frontend can reuse the same layout and analysis APIs.

A small playground

WarpWeaver is most useful when a layout is treated as an experiment. The following examples are deliberately small enough to run, inspect, and modify. Run them from the repository root after building.

1. Turn a bank-conflict trace into a clean warp access

Start with eight lanes reading one column of an 8x64 f16 tile:

./build/warpweaver analyze \
  --shape 8x64 --dtype f16 \
  --access column:0 --lanes 8 --vector-bytes 16 --no-color

The baseline is intentionally bad: unique_banks=4 and max_transactions_per_bank=8. Now add a 128-byte TMA swizzle:

./build/warpweaver analyze \
  --shape 8x64 --dtype f16 --swizzle tma-128b \
  --access column:0 --lanes 8 --vector-bytes 16 --no-color

The same logical column becomes unique_banks=32 with max_transactions_per_bank=1. This is an address-mapping experiment, not a claim about a particular GPU's full execution time, but it makes the reason for a swizzle visible immediately.

2. Fold a matrix into tiles

./build/warpweaver show \
  --shape 8x16 --tile 4x8 --max-rows 4 --max-cols 8 --no-color

The command inserts the coordinate stages (row,col) -> (tile-row,tile-col,local-row,local-col) before the affine mapping. Try changing 4x8 to 2x4 and compare the physical offsets. The same transformation can be written as a split followed by a permutation:

./build/warpweaver show \
  --shape 8x16 --split 1:8 --permute 1,0,2 \
  --max-rows 4 --max-cols 8 --no-color

3. Ask which lane owns each element

./build/warpweaver owners \
  --shape 8x8 --threads-per-warp 8x4 \
  --ownership-order 1,0 --no-color

Read each cell as cta:warp:lane:register. Swap the ownership order to 0,1 and the lane pattern rotates: the tensor stays the same, but the thread-to-coordinate relationship changes.

4. Make a nested layout readable

./build/warpweaver layout \
  --expr "(2,(3,3)):(21,(6,1))" \
  --dtype f16 --colors 2

This renders two top-level blocks, each containing a nested 3x3 mode. The summary exposes the flattened view as leaf-shape=2x3x3 and leaf-stride=21,6,1, while the cells retain their source index and logical coordinate. For a sliding-window view over a 6x6 grid, try:

./build/warpweaver layout \
  --expr "(16,(3,3)):(1,(6,1))" \
  --grid-shape 6x6 --colors 16

5. Use the terminal as the color renderer

The CLI already emits ANSI colors when stdout is a terminal. Force them for a pipe or a captured session with:

./build/warpweaver layout \
  --expr "(2,(3,3)):(21,(6,1))" --color always

README Markdown cannot portably express arbitrary text colors. GitHub-flavored Markdown supports basic inline HTML, but CSS such as <span style="color: red">...</span> is sanitized or ignored by common renderers. ANSI escape sequences are likewise shown as plain text in a Markdown code block. For documentation that must work everywhere, use code labels, tables, and a generated image; for a local terminal, use --color always.

Documentation

The detailed documentation is organized under docs/:

Use

./build/warpweaver show --shape 8x64 --dtype f16 --swizzle xor:b=3,m=3,s=3
./build/warpweaver analyze --shape 8x64 --dtype f16 --swizzle tma-128b \
  --access column:0 --lanes 8 --vector-bytes 16
./build/warpweaver owners --shape 8x8 \
  --threads-per-warp 8x4 --ownership-order 1,0
./build/warpweaver layout \
  --expr "(2,(3,3)):(21,(6,1))" --dtype f16 --no-color
./build/warpweaver layout \
  --expr "(2,(3,3)):(21,(6,1))" --grid-shape 6x6 --no-color
./build/warpweaver layout \
  --expr "(16,(3,3)):(1,(6,1))" --grid-shape 6x6 --colors 16

show emits a two-dimensional map whose cells are physical-element-offset|shared-memory-bank. analyze builds a single warp access trace and reports the distinct 4-byte bank words served by each bank. --vector-bytes gives each lane a contiguous physical byte range; the command also reports a global-memory coalescing estimate using 32-byte sectors and 128-byte segments. It is an address-transaction model, not a cache-state or instruction-scheduling simulation. Use --color always to retain bank colors when output is not connected to a TTY. The canonical XOR syntax is xor:b=BIT_COUNT,m=LOW_BITS,s=SHIFT_BITS and uses the high-to-low form, requiring S >= B. Explicit positional import forms are also available: xor:bms:B,M,S and xor:cute:M,B,S; the older bare xor:M,B,S spelling remains accepted for compatibility. TMA presets additionally validate the 128-byte shared-memory base alignment and the CUDA requirement that the inner tensor dimension fit inside the selected 32B, 64B, or 128B swizzle width.

Coordinate stages execute in their CLI order before the affine layout:

# Reorder 8x16 logical elements into 4x8 physical tiles.
./build/warpweaver show --shape 8x16 --tile 4x8

# Split the logical column axis and then make the outer column tile major.
./build/warpweaver show --shape 8x16 --split 1:8 --permute 1,0,2

--permute AXES accepts a complete axis order, --split AXIS:FACTOR replaces one axis with outer/inner axes, and --merge AXIS combines one axis with its next neighbor. --tile ROWSxCOLS is a rank-2 shorthand that produces (outer_row, outer_col, inner_row, inner_col). Stage factors must divide the respective dimensions; partial tiles are deliberately not inferred yet.

owners uses a blocked distribution to show logical ownership as cta-coordinate:warp:lane:register. Configure its hierarchy with --size-per-thread, --threads-per-warp, --warps-per-cta, and --ownership-order; the thread tile must multiply to 32 lanes.

layout displays a nested Shape:Stride view. The example above has two top-level rows and a nested 3x3 column mode, so it prints a 2x9 view whose element offsets are 0..14 and 21..35. Tuple nesting is preserved in the summary (leaf-shape=2x3x3, leaf-stride=21,6,1), while each cell shows the source Grid index and logical view coordinate as G<index>@<logical-coordinate>. The command is one-shot and exits after rendering; the interactive session will build on this same model.

Add --grid-shape 6x6 to see the same mapping over the original grid. The command then prints every G<linear>@<logical-coordinate> mapping at each selected original-matrix location; mappings are separated by ;, and . marks an unselected element. --grid-stride R,C overrides the default row-major grid stride when the original grid is padded, transposed, or otherwise non-contiguous.

The view topology still controls coloring: in an (a,(b,c)) view, the a sub-blocks receive distinct colors. For a flat rank-3 (a,b,c) view, colors use (a*b*c) % C; configure C with --colors (1 to 256).

When the layout has the sliding-window form (N,(R,C)):(1,(W,1)), the first mode is interpreted as a row-major window ordinal over a source width W. For example, ordinal 4 in a 6-column source starts at global index 6, not 4. The explicit form ((A,B),(R,C)) is rendered as an (A*R)x(B*C) mosaic, so ((4,4),(3,3)) displays 4x4 colored 3x3 windows in a 12x12 table.

The CLI defaults to Torch-style linear indexing, where the last leaf mode is fastest. Use --order cute to select CuTe's colexicographical indexing and match the ordering used by CuTe's idx2crd and print_layout conventions.

Design

  • AffineTransform (Layout alias): integer coordinate to linear element offset mapping. The first layouts are row-major, column-major, and padded leading-dimension variants.
  • NestedLayout: C++20 template model for recursive shape/stride tuples, with static and dynamic integer leaves plus flattening into AffineTransform.
  • RuntimeLayout: parser-friendly runtime tuple model used by the CLI to render nested shape/stride expressions without losing their topology. The CLI can enumerate it with Torch or CuTe linear-index order.
  • ComposedLayout: lazy A o B view with domain validation and optional affine reconstruction through try_flatten().
  • BitTransform: a GF(2) bit matrix with composition and invertibility checks.
  • SwizzleTransform: identity or named XOR transform; it can expose its GF(2) bit-matrix representation for visualization and testing.
  • LayoutPipeline: applies affine mapping, then swizzle, then dtype/base address conversion. It also owns the validated coordinate-stage chain: permute, split, merge, and 2D tile. Both terminal and future GUI frontends consume this API.
  • BankAnalyzer: maps vector byte ranges to shared-memory bank words and estimates global-memory sector/segment demand.
  • BlockedOwnershipLayout: maps logical coordinates to CTA, warp, lane, and per-thread register ownership using a configurable blocked hierarchy.
  • warpweaver: ANSI terminal frontend. It has no layout logic and can later be joined by an ImGui frontend that consumes the same core results.

About

Visualize Layout Transformation and bank conflict.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages