Skip to content

[lang][nfc] Add execution and metaprogramming documentation - #100

Draft
robobryce wants to merge 1 commit into
NVIDIA:mainfrom
robobryce:robobryce/enh-lang-model-docs
Draft

[lang][nfc] Add execution and metaprogramming documentation#100
robobryce wants to merge 1 commit into
NVIDIA:mainfrom
robobryce:robobryce/enh-lang-model-docs

Conversation

@robobryce

Copy link
Copy Markdown

Description

The experimental cuda.lang documentation currently moves from its introductory
example directly into the data model and API inventories. Readers can find
individual operations, but there is no conceptual explanation of how a kernel is
executed or how Python participates in compile-time specialization.

This PR adds top-level Execution Model and Metaprogramming guides so those concepts
are introduced before the Data Model.

What changed

  • Added an Execution Model page based on the organization and writing style of the
    main cuda.tile guide, adapted for cuda.lang's explicit SIMT model. It describes
    the grid, optional cluster, block, warp, and thread hierarchy; host and SIMT
    execution spaces; helper functions and kernel entry points; the supported Python
    subset; argument lifetimes; and the positive-step range limitation.
  • Added a Metaprogramming page introducing constant-embedded parameters and the
    compile-time facilities cl.static_eval, cl.static_iter, cl.static_assert,
    cl.ensure_constant, and @cl.static_def.
  • Ordered the conceptual guides as Execution Model, Metaprogramming, then Data Model
    in the hidden root toctree.
  • Added a stable anchor to the existing SIMT Model API section so the execution guide
    can link readers directly to the thread-hierarchy operations.

For example, the Execution Model now presents the hierarchy as a top-down list from
grid to thread, while separately explaining where shared-memory communication and
cluster-scoped synchronization are available.

Design decisions

The cuda.tile execution guide describes block-level collective tile execution and
does not expose individual threads. Copying that prose would be incorrect for
cuda.lang, where each thread executes the kernel body and warp, block, and cluster
operations are explicit. This guide therefore preserves the main documentation's
concept-first structure while replacing those semantics with the cuda.lang model.

The new metaprogramming APIs remain hand-written literals rather than generated API
links because their shared docstrings currently use cuda.tile terminology. This
keeps the skeleton accurate without publishing misleading cuda.lang API pages.

This is a documentation-only change and does not affect runtime behavior.

Validation

  • Built the experimental documentation with Sphinx warnings treated as errors:
    PYTHONDONTWRITEBYTECODE=1 PYTHONPATH="$PWD/experimental/cuda-lang/src" make -C experimental/cuda-lang/docs VENV="$PWD/experimental/cuda-lang/docs/venv" html
  • Ran python3 scripts/check_license.py.
  • Ran git diff --check.
  • Verified the rendered Execution Model and Metaprogramming pages over the local HTTP
    documentation server.

Checklist

  • I am familiar with the Contributing Guidelines.
  • New or existing tests cover these changes.
  • The documentation is up to date with these changes.

Signed-off-by: Bryce Adelstein Lelbach <brycelelbach@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants