[lang][nfc] Add execution and metaprogramming documentation - #100
Draft
robobryce wants to merge 1 commit into
Draft
[lang][nfc] Add execution and metaprogramming documentation#100robobryce wants to merge 1 commit into
robobryce wants to merge 1 commit into
Conversation
Signed-off-by: Bryce Adelstein Lelbach <brycelelbach@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
The experimental
cuda.langdocumentation currently moves from its introductoryexample 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
main
cuda.tileguide, adapted forcuda.lang's explicit SIMT model. It describesthe 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
rangelimitation.compile-time facilities
cl.static_eval,cl.static_iter,cl.static_assert,cl.ensure_constant, and@cl.static_def.in the hidden root toctree.
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.tileexecution guide describes block-level collective tile execution anddoes not expose individual threads. Copying that prose would be incorrect for
cuda.lang, where each thread executes the kernel body and warp, block, and clusteroperations are explicit. This guide therefore preserves the main documentation's
concept-first structure while replacing those semantics with the
cuda.langmodel.The new metaprogramming APIs remain hand-written literals rather than generated API
links because their shared docstrings currently use
cuda.tileterminology. Thiskeeps the skeleton accurate without publishing misleading
cuda.langAPI pages.This is a documentation-only change and does not affect runtime behavior.
Validation
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH="$PWD/experimental/cuda-lang/src" make -C experimental/cuda-lang/docs VENV="$PWD/experimental/cuda-lang/docs/venv" htmlpython3 scripts/check_license.py.git diff --check.documentation server.
Checklist