.. _dsl_introduction: .. |DC| replace:: dynamic compilation .. |IR| replace:: IR .. |DSL| replace:: CuTe DSL

Introduction

Overview

|DSL| is a Python-based domain-specific language (DSL) designed for |DC| of high-performance GPU kernels. It evolved from the C++ CUTLASS library and is now available as a decorator-based DSL.

Its primary goals are:

• Zero-cost abstraction, DSL is a zero-cost abstraction thanks to Hybrid DSL approach.
• Consistent with CuTe C++, allowing users to express GPU kernels with full control of the hardware.
• JIT compilation for both host and GPU execution.
• DLPack <https://github.com/dmlc/dlpack>_ integration, enabling seamless interop with frameworks (e.g., PyTorch, JAX).
• JIT caching, so that repeated calls to the same function benefit from cached |IR| modules.
• Native types and type inference to reduce boilerplate and improve performance.
• Optional lower-level control, offering direct access to GPU backends or specialized |IR| dialects.

Decorators

|DSL| provides two main Python decorators for generating optimized code via |DC|:

1. @jit — Host-side JIT-compiled functions
2. @kernel — GPU kernel functions

Both decorators can optionally use a preprocessor that automatically expands Python control flow (loops, conditionals) into operations consumable by the underlying |IR|.

@jit

Declares JIT-compiled functions that can be invoked from Python or from other |DSL| functions.

**Decorator Parameters**:

* ``preprocessor``:

  * ``True`` (default) — Automatically translate Python flow control (e.g., loops, if-statements) into |IR| operations.
  * ``False`` — No automatic expansion; Python flow control must be handled manually or avoided.

**Call-site Parameters**:

- ``no_cache``:

  - ``True`` — Disables JIT caching, forcing a fresh compilation each call.
  - ``False`` (default) — Enables caching for faster subsequent calls.

``@kernel``

Defines GPU kernel functions, compiled as specialized GPU symbols through |DC|.

Decorator Parameters:

• preprocessor:

  • True (default) — Automatically expands Python loops/ifs into GPU-compatible |IR| operations.
  • False — Expects manual or simplified kernel implementations.

Kernel Launch Parameters:

• grid Specifies the grid size as a list of integers.

• block Specifies the block size as a list of integers.

• cluster Specifies the cluster size as a list of integers.

• smem Specifies the size of shared memory in bytes (integer).

  • None (default) — Automatically calculates the kernel's shared memory usage via utils.SmemAllocator. Recommended unless manual control is required.
  • int — Manually specifies the size of shared memory in bytes.

Additional Kernel Launch Parameters:

• fallback_cluster Specifies the minimum-guaranteed cluster size. When set, cluster becomes the preferred size, enabling graceful degradation when hardware cannot satisfy the preferred dimensions.

  • None (default) — No fallback; cluster is used directly.
  • list[int] — Three-element list [x, y, z].

• max_number_threads Specifies the maximum thread count per block (maxntid).

  • [0, 0, 0] (default) — Auto-generate reqntid from block.
  • list[int] — Three-element list [x, y, z].

• min_blocks_per_mp Specifies the minimum blocks per multiprocessor (minctasm).

  • 0 (default) — No minimum occupancy hint.
  • int — Minimum number of blocks per multiprocessor.

• use_pdl Enables Programmatic Dependent Launch (PDL) to overlap dependent kernel launches in the same stream.

  • False (default) — PDL disabled.
  • True — PDL enabled.

• cooperative Enables cooperative kernel launch; all thread blocks launch cooperatively with grid-wide synchronization support.

  • False (default) — Standard kernel launch.
  • True — Cooperative kernel launch.

• smem_merge_branch_allocs Enables mutually exclusive control flow branches (sequentially executed if-else) to reuse the same shared memory.

  • False (default) — Shared memory is allocated additively across all branches (default CUDA C++ behavior).
  • True — Merge shared-memory allocations across branches (experimental feature, recommended for mega-kernels).

Calling Conventions

.. list-table:: :header-rows: 1 :widths: 20 20 15 25

• • Caller
  • Callee
  • Allowed
  • Compilation/Runtime
• • Python function
  • @jit
  • ✅
  • DSL runtime
• • Python function
  • @kernel
  • ❌
  • N/A (error raised)
• • @jit
  • @jit
  • ✅
  • Compile-time call, inlined
• • @jit
  • Python function
  • ✅
  • Compile-time call, inlined
• • @jit
  • @kernel
  • ✅
  • Dynamic call via GPU driver or runtime
• • @kernel
  • @jit
  • ✅
  • Compile-time call, inlined
• • @kernel
  • Python function
  • ✅
  • Compile-time call, inlined
• • @kernel
  • @kernel
  • ❌
  • N/A (error raised)