feat(cccl): integrate missing CCCL directories — python/, ci/, .agent/, docs/, test/
Sparse-checkout from NVIDIA/cccl main branch to complete cccl_upstream: Added: - python/cuda_cccl/ (226 files) — Python bindings for device-level algorithms Critical for muh toolchain: cuda.compute.reduce_into, scan, radix_sort, etc. Includes 204 .py files with full test coverage for all 27 algorithms - ci/ (163 files) — Build/test infrastructure build_cub.sh, test_cub.sh, build_and_test_targets.sh, matrix.yaml Directly maps to our [INFRA-CI] and [INFRA-BUILD] items - .agent/skills/ (7 files) — NVIDIA's own agent skills for CCCL cccl-style/SKILL.md, cccl-test/SKILL.md, sass-diff/SKILL.md - docs/ (491 files) — Official CCCL documentation CI references, CMake guides, Python compute docs, libcudacxx PTX docs - test/ (12 files) — Top-level integration tests (cuda_smoke, stdpar) - Root configs: .clang-format, .clang-tidy, CONTRIBUTING.md, pyproject.toml - CLAUDE.md symlink → AGENTS.md (NVIDIA's standard) cccl_upstream now mirrors full NVIDIA/cccl structure: Before: 42M (cub + thrust + libcudacxx + cudax + c + examples + benchmarks) After: 53M (+python +ci +docs +.agent +test +configs) This completes the CCCL base needed for: - [muh-bench] items: ci/util/build_and_test_targets.sh for targeted builds - [CCCL-verify] items: python/cuda_cccl/tests/ as reference implementations - [CCCL-test] items: ci/test_cub.sh, ci/test_thrust.sh - Agent workflow: .agent/skills/ for consistent style and test patterns
This commit is contained in:
137
cccl_upstream/docs/libcudacxx/index.rst
Normal file
137
cccl_upstream/docs/libcudacxx/index.rst
Normal file
@@ -0,0 +1,137 @@
|
||||
.. _libcudacxx-module:
|
||||
|
||||
libcu++
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 3
|
||||
|
||||
Overview <self>
|
||||
setup
|
||||
standard_api
|
||||
extended_api
|
||||
runtime
|
||||
ptx_api
|
||||
tile
|
||||
API reference <api/index>
|
||||
|
||||
``libcu++`` (``libcudacxx``) provides fundamental, idiomatic C++ abstractions that aim to make the lives of CUDA C++
|
||||
developers easier.
|
||||
|
||||
Specifically, ``libcu++`` provides:
|
||||
- C++ Standard Library features usable in both host and device code
|
||||
- Extensions to C++ Standard Library features
|
||||
- Fundamental, CUDA-specific programming model abstractions
|
||||
|
||||
C++ Standard Library Features
|
||||
-----------------------------
|
||||
|
||||
If you are a C++ developer, then you know the C++ Standard Library (`sometimes referred to as "The
|
||||
STL" <https://stackoverflow.com/questions/5205491/whats-the-difference-between-stl-and-c-standard-library>`_)
|
||||
as what comes along with your compiler and provides things like ``std::string`` or ``std::vector`` or ``std::atomic``.
|
||||
It provides the fundamental abstractions that C++ developers need to build high quality applications and libraries.
|
||||
|
||||
By default, these abstractions aren't available when writing CUDA C++ device code because they don't have the necessary
|
||||
``__host__ __device__`` decorators, and their implementation may not be suitable for using in and across host and device
|
||||
code.
|
||||
|
||||
libcu++ aims to solve this problem by providing an opt-in, incremental, heterogeneous implementation of C++
|
||||
Standard Library features:
|
||||
|
||||
1. **Opt-in**: It does not replace the Standard Library provided by your host compiler (aka anything in ``std::``)
|
||||
2. **Incremental**: It does not provide a complete C++ Standard Library implementation
|
||||
3. **Heterogeneous**: It works in both host and device code, as well as passing between host and device code.
|
||||
|
||||
If you know how to use things like the ``<atomic>`` or ``<type_traits>`` headers from the C++ Standard Library, then
|
||||
you know how to use libcu++.
|
||||
|
||||
All you have to do is add ``cuda/std/`` to the start of your includes and ``cuda::`` before any uses of ``std::``:
|
||||
|
||||
.. code:: cuda
|
||||
|
||||
#include <cuda/std/atomic>
|
||||
cuda::std::atomic<int> x;
|
||||
|
||||
.. note::
|
||||
|
||||
libcu++ does not provide its own documentation for Standard Library features. Instead, libcu++
|
||||
:ref:`documents which Standard Library headers <libcudacxx-standard-api>` are made available, and defers documentation of
|
||||
individual features within those headers to other sources like `cppreference <https://en.cppreference.com/w/>`_.
|
||||
|
||||
C++ Standard Library Extensions
|
||||
-------------------------------
|
||||
|
||||
libcu++ provides CUDA C++ developers with familiar Standard Library utilities to improve productivity and flatten the
|
||||
learning curve of learning CUDA. However, there are many aspects of writing high-performance CUDA C++ code that cannot
|
||||
be expressed through purely Standard conforming APIs. For these cases, libcu++ also provides *extensions* of Standard
|
||||
Library utilities.
|
||||
|
||||
For example, libcu++ extends ``atomic<T>`` and other synchronization primitives with the notion of a "thread scope"
|
||||
that controls the strength of the memory fence.
|
||||
|
||||
To use utilities that are extensions to Standard Library features, drop the ``std``:
|
||||
|
||||
.. code:: cuda
|
||||
|
||||
#include <cuda/atomic>
|
||||
cuda::atomic<int, cuda::thread_scope_device> x;
|
||||
|
||||
See the :ref:`Extended API <libcudacxx-extended-api>` section for more information.
|
||||
|
||||
Fundamental CUDA-specific Abstractions
|
||||
--------------------------------------
|
||||
|
||||
Some abstractions that libcu++ provides have no equivalent in the C++ Standard Library, but are fundamental to the CUDA
|
||||
C++ programming model. They include CUDA-specific vocabulary types, device-side APIs for certain hardware features, and
|
||||
abstractions for the CUDA Runtime APIs.
|
||||
|
||||
For example, :ref:`cuda::memcpy_async <libcudacxx-extended-api-asynchronous-operations-memcpy-async>` is a vital abstraction
|
||||
for asynchronous data movement between global and shared memory. This abstracts hardware features such as ``LDGSTS`` on
|
||||
Ampere, and the Tensor Memory Accelerator (TMA) on Hopper.
|
||||
|
||||
See the :ref:`Extended API <libcudacxx-extended-api>` and :ref:`Runtime API <libcudacxx-runtime-api>` sections for more information.
|
||||
|
||||
Summary: ``std::``, ``cuda::`` and ``cuda::std::``
|
||||
--------------------------------------------------
|
||||
|
||||
- ``std::`` / ``<*>``: This is your host compiler's Standard Library that works in ``__host__`` code only, although you
|
||||
can use the ``--expt-relaxed-constexpr`` flag to use any ``constexpr`` functions in ``__device__`` code.
|
||||
libcu++ does not replace or interfere with host compiler's Standard Library.
|
||||
- ``cuda::std::`` / ``<cuda/std/*>``: Conforming implementations of facilities from the Standard Library that work in
|
||||
``__host__`` and ``__device__`` code.
|
||||
- ``cuda::`` / ``<cuda/*>``: Conforming extensions to the Standard Library that work in ``__host__`` and ``__device__`` code.
|
||||
- ``cuda::device`` / ``<cuda/device/*>``: Conforming extensions to the Standard Library that work only in
|
||||
``__device__`` code.
|
||||
- ``cuda::ptx``: C++ convenience wrappers for inline PTX that work only in ``__device__`` code.
|
||||
|
||||
Any libcu++ feature that works in ``__host__`` code also works when being compiled by a non-CUDA compiler (e.g., GCC).
|
||||
|
||||
.. code:: cuda
|
||||
|
||||
// Standard C++, __host__ only.
|
||||
#include <atomic>
|
||||
std::atomic<int> x;
|
||||
|
||||
// CUDA C++, __host__ __device__.
|
||||
// Strictly conforming to the C++ Standard.
|
||||
#include <cuda/std/atomic>
|
||||
cuda::std::atomic<int> x;
|
||||
|
||||
// CUDA C++, __host__ __device__.
|
||||
// Conforming extensions to the C++ Standard.
|
||||
#include <cuda/atomic>
|
||||
cuda::atomic<int, cuda::thread_scope_block> x;
|
||||
|
||||
Licensing
|
||||
---------
|
||||
|
||||
libcu++ is an open source project developed on `GitHub <https://github.com/nvidia/cccl>`_. It is NVIDIA's variant of
|
||||
`LLVM's libc++ <https://libcxx.llvm.org>`_. libcu++ is distributed under the `Apache License v2.0 with LLVM
|
||||
Exceptions <https://llvm.org/LICENSE.txt>`_.
|
||||
|
||||
Conformance
|
||||
-----------
|
||||
|
||||
libcu++ aims to be a conforming implementation of the C++ Standard, `ISO/IEC IS 14882 <https://eel.is/c++draft>`_,
|
||||
Clause 16 through 32.
|
||||
Reference in New Issue
Block a user