flydsl

name	flydsl
description	Use when working with FlyDSL kernels (`@flyc.kernel` / `flydsl.compiler`) on AMD GPUs. Covers three complementary workflows: writing new tile-programmed kernels, optimizing existing kernels for performance, and debugging correctness issues (NaN, wrong results, compilation errors, hangs).

FlyDSL Kernel Skills

This skill covers the full lifecycle of FlyDSL GPU kernels on AMD GPUs: write (tile programming), optimize (performance tuning), and debug (correctness triage).

Choose your entry point based on the task:

Task	Start with
Write a new @flyc.kernel from scratch or port from Triton	Tile Programming (below)
Improve performance of an existing kernel	Optimization (below)
Fix NaN, wrong results, compilation errors, or hangs	Debugging (below)

---

Tile Programming

Use this workflow to design the first correct kernel structure with FlyDSL's tile programming model (CuTe-style layout algebra).

Scope: Start here for a new kernel structure. Switch to Debugging once you have runnable code, then to Optimization once correctness is established.

Kernel Type Classification

Pattern	Examples	Key Primitives
Elementwise	vecadd, scale, relu, abs	logical_divide + copy_atom_call
Reduction	sum, max, softmax, layernorm	buffer_load + warp shuffle + LDS
Tiled Copy	transpose, permute, gather	zipped_divide + TiledCopy
GEMM	matmul, batched gemm	TiledMma + TiledCopy + LDS
Fused	fused attention, GEMM+epilogue	Combine GEMM + elementwise

Design Steps

1. Classify the kernel type using the table above
2. Generate the appropriate skeleton from pattern templates
3. Fill in compute logic using FlyDSL arith ops on vectors
4. Add synchronization and shared memory if needed
5. Test and debug using the common error table

Full tile programming guide with kernel skeletons, compute recipes, control flow, LDS usage, and MFMA reference: docs/flydsl_tile_programming.md

---

Optimization

Use this workflow when optimizing an existing FlyDSL kernel for performance. Parameter tuning alone yields marginal gains. Prioritize structural optimizations in early patches, then fall back to tuning in later patches.

Optimization Priority

1. Structural (highest impact): kernel fusion, fast-path relaxation, loop restructuring, redundant work elimination, algorithm replacement
2. Memory hierarchy (medium): LDS utilization, vectorized access, load/compute overlap, data layout
3. Compute (medium): MFMA instruction selection, software pipelining, scheduler tuning
4. Parameter tuning (low): block size, tile dimensions, unroll factors

Bottleneck Classification

• Memory-bound → reduce data movement (fusion, LDS caching, vectorization)
• Compute-bound → improve instruction throughput (MFMA selection, software pipelining)
• Latency-bound (small shapes) → reduce kernel launch count (fusion)

Full optimization workflow and detailed strategies: docs/flydsl_optimization.md

---

Debugging

Use this workflow for correctness, stability, and hang triage on runnable FlyDSL kernels.

Debug Strategy (classify → isolate → fix)

1. Cache check: If a fix looks ineffective, rerun with FLYDSL_RUNTIME_ENABLE_CACHE=0
2. Classify the error using the table below
3. Isolate with diagnostic workflow (all-1s test, single-partition, host-side prints)
4. Fix using the pattern-specific guidance in the debug doc

Error Classification

Symptom	Likely Cause
All NaN output	Softmax -inf/-inf, division by zero
All zeros output	Wrong output address, uninitialized buffer
>50% mismatch	Wrong partition count, layout mismatch
1-5% mismatch	FP8 quantization, scale factor
Compilation error	Type mismatch, range vs range_constexpr
GPU hang	Infinite loop, barrier deadlock

Common Pitfalls Checklist

• range_constexpr() for compile-time loops (not range())
• No Python if on runtime GPU values
• buffer_load offset units match dtype
• vector.store uses vector type (not scalar)
• scf.for state packed with raw SSA values
• MFMA operand order: mfma(LHS, RHS, acc)

Full debugging guide with detailed fixes and diagnostic workflow: docs/flydsl_debug_kernel.md

---

Reference Documentation

The docs/ subdirectory contains detailed guides:

• flydsl_tile_programming.md — Kernel skeletons, compute recipes, control flow, LDS, MFMA reference
• flydsl_optimization.md — Optimization workflow, tier-by-tier strategies, correctness constraints, key APIs
• flydsl_debug_kernel.md — NaN/zeros debugging, mismatch triage, compilation errors, GPU hangs