Skip to content

Commit c558850

Browse files
fbusatodavebayer
fbusato
authored and
davebayer
committed
CCCL Internal macro documentation (NVIDIA#3238)
1 parent 8c65dfa commit c558850

File tree

3 files changed

+343
-0
lines changed

3 files changed

+343
-0
lines changed

‎docs/cccl_development/index.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. _cccl-development-module:
2+
3+
CCCL Development Guide
4+
======================
5+
6+
.. toctree::
7+
:hidden:
8+
:maxdepth: 1
9+
10+
macro
11+
12+
This living document serves to describe the internal details and the development process of CCCL libraries.
13+
14+
Documentation:
15+
16+
- `CCCL Internal Macros <https://nvidia.github.io/cccl/cccl_development/macro/>`__

‎docs/cccl_development/macro.rst‎

Lines changed: 326 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,326 @@
1+
.. _cccl-development-module-macros:
2+
3+
CCCL Internal Macros
4+
====================
5+
6+
The document describes the main *internal* macros used by CCCL. They are not intended to be used by end users, but for development of CCCL features only. We reserve the right to change them at any time without warning.
7+
8+
----
9+
10+
Compiler Macros
11+
---------------
12+
13+
**Host compiler macros**:
14+
15+
+-----------------------------+--------------------------------+
16+
| ``_CCCL_COMPILER(CLANG)`` | Clang |
17+
+-----------------------------+--------------------------------+
18+
| ``_CCCL_COMPILER(GCC)`` | GCC |
19+
+-----------------------------+--------------------------------+
20+
| ``_CCCL_COMPILER(NVHPC)`` | Nvidia HPC compiler |
21+
+-----------------------------+--------------------------------+
22+
| ``_CCCL_COMPILER(MSVC)`` | Microsoft Visual Studio |
23+
+-----------------------------+--------------------------------+
24+
| ``_CCCL_COMPILER(MSVC2017)`` | Microsoft Visual Studio 2017 |
25+
+-----------------------------+--------------------------------+
26+
| ``_CCCL_COMPILER(MSVC2019)`` | Microsoft Visual Studio 2019 |
27+
+-----------------------------+--------------------------------+
28+
| ``_CCCL_COMPILER(MSVC2022)`` | Microsoft Visual Studio 2022 |
29+
+-----------------------------+--------------------------------+
30+
31+
The ``_CCCL_COMPILER`` function-like macro can also be used to check the version of a compiler.
32+
33+
.. code:: cpp
34+
35+
_CCCL_COMPILER(MSVC, <, 19, 24)
36+
_CCCL_COMPILER(GCC, >=, 9)
37+
38+
*Pitfalls*: ``_CCCL_COMPILER(GCC, >, 9)`` internally expands ``_CCCL_COMPILER(GCC, >, 9, 0)`` to matches any GCC 9.x. Avoid using ``>`` and rather use ``>=``
39+
40+
**CUDA compiler macros**:
41+
42+
+--------------------------------+-------------------------+
43+
| ``_CCCL_CUDA_COMPILER(NVCC)`` | Nvidia compiler |
44+
+--------------------------------+-------------------------+
45+
| ``_CCCL_CUDA_COMPILER(NVHPC)`` | Nvidia HPC compiler |
46+
+--------------------------------+-------------------------+
47+
| ``_CCCL_CUDA_COMPILER(NVRTC)`` | Nvidia Runtime Compiler |
48+
+--------------------------------+-------------------------+
49+
| ``_CCCL_CUDA_COMPILER(CLANG)`` | Clang |
50+
+--------------------------------+-------------------------+
51+
52+
The ``_CCCL_CUDA_COMPILER`` function-like macro can also be used to check the version of a compiler.
53+
54+
.. code:: cpp
55+
56+
_CCCL_CUDA_COMPILER(NVCC, <, 12, 3)
57+
_CCCL_CUDA_COMPILER(CLANG, >=, 14)
58+
59+
**CUDA identification/version macros**:
60+
61+
+----------------------------------+-----------------------------+
62+
| ``_CCCL_HAS_CUDA_COMPILER`` | CUDA compiler is available |
63+
+----------------------------------+-----------------------------+
64+
| ``_CCCL_CUDACC_BELOW(12, 7)`` | CUDA version below 12.7 |
65+
+----------------------------------+-----------------------------+
66+
| ``_CCCL_CUDACC_AT_LEAST(12, 7)`` | CUDA version at least 12.7 |
67+
+----------------------------------+-----------------------------+
68+
69+
**PTX macros**:
70+
71+
+-------------------------+-------------------------------------------------------------------------------------------------------------------+
72+
| ``_CCCL_PTX_ARCH`` | Alias of ``__CUDA_ARCH__`` with value equal to 0 if cuda compiler is not available |
73+
+-------------------------+-------------------------------------------------------------------------------------------------------------------+
74+
| ``__cccl_ptx_isa`` | PTX ISA version available with the current CUDA compiler, e.g. PTX ISA 8.4 (``840``) is available from CUDA 12.4 |
75+
+-------------------------+-------------------------------------------------------------------------------------------------------------------+
76+
77+
----
78+
79+
Architecture Macros
80+
-------------------
81+
82+
The following macros are used to check the target architecture. They comply with the compiler supported by the CUDA toolkit. Compilers outside the CUDA toolkit may define such macros in a different way.
83+
84+
+-------------------------+-------------------------------------+
85+
| ``_CCCL_ARCH(ARM64)`` | ARM 64-bit |
86+
+-------------------------+-------------------------------------+
87+
| ``_CCCL_ARCH(X86_64)`` | X86 64-bit |
88+
+-------------------------+-------------------------------------+
89+
90+
----
91+
92+
OS Macros
93+
---------
94+
95+
+-----------------------+---------+
96+
| ``_CCCL_OS(WINDOWS)`` | Windows |
97+
+-----------------------+---------+
98+
| ``_CCCL_OS(LINUX)`` | Linux |
99+
+-----------------------+---------+
100+
| ``_CCCL_OS(ANDROID)`` | Android |
101+
+-----------------------+---------+
102+
| ``_CCCL_OS(QNX)`` | QNX |
103+
+-----------------------+---------+
104+
105+
----
106+
107+
CUDA Extension Macros
108+
---------------------
109+
110+
**Execution space**:
111+
112+
+-----------------------+-----------------------+
113+
| ``_CCCL_HOST`` | Host function |
114+
+-----------------------+-----------------------+
115+
| ``_CCCL_DEVICE`` | Device function |
116+
+-----------------------+-----------------------+
117+
| ``_CCCL_HOST_DEVICE`` | Host/Device function |
118+
+-----------------------+-----------------------+
119+
120+
**Other CUDA attributes**:
121+
122+
+------------------------------+----------------------------------------------------------+
123+
| ``_CCCL_GRID_CONSTANT`` | Grid constant kernel parameter |
124+
+------------------------------+----------------------------------------------------------+
125+
| ``_CCCL_GLOBAL_CONSTANT`` | Host/device global scope constant (``inline constexpr``) |
126+
+------------------------------+----------------------------------------------------------+
127+
| ``_CCCL_EXEC_CHECK_DISABLE`` | Disable execution space check for the NVHPC compiler |
128+
+------------------------------+----------------------------------------------------------+
129+
130+
**Extended floating-point types**:
131+
132+
+------------------------------+-----------------------------------------------------------------------------------------------------------------+
133+
| ``_CCCL_HAS_NVFP16`` | `__half/__half2` data types are supported and enabled. Prefer over ``__CUDA_FP16_TYPES_EXIST__`` |
134+
+------------------------------+-----------------------------------------------------------------------------------------------------------------+
135+
| ``_CCCL_HAS_NVBF16`` | `__nv_bfloat16/__nv_bfloat162` data types are supported and enabled. Prefer over ``__CUDA_BF16_TYPES_EXIST__`` |
136+
+------------------------------+-----------------------------------------------------------------------------------------------------------------+
137+
138+
+------------------------------+----------------------------------------------------------------+
139+
| ``_LIBCUDACXX_HAS_NVFP16`` | `__half/__half2` host/device support (CUDA 12.2) |
140+
+------------------------------+----------------------------------------------------------------+
141+
| ``_LIBCUDACXX_HAS_NVBF16`` | `__nv_bfloat16/__nv_bfloat162` host/device support (CUDA 12.2) |
142+
+------------------------------+----------------------------------------------------------------+
143+
144+
145+
----
146+
147+
C++ Language Macros
148+
-------------------
149+
150+
The following macros are required only if the target C++ version does not support the corresponding attribute
151+
152+
+-----------------------------+----------------------------------------------------------+
153+
| ``_CCCL_STD_VER`` | C++ standard version, e.g. ``#if _CCCL_STD_VER >= 2017`` |
154+
+-----------------------------+----------------------------------------------------------+
155+
| ``_CCCL_IF_CONSTEXPR`` | Portable ``if constexpr`` (before C++17) |
156+
+-----------------------------+----------------------------------------------------------+
157+
| ``_CCCL_CONSTEXPR_CXX14`` | Enable ``constexpr`` for C++14 or newer |
158+
+-----------------------------+----------------------------------------------------------+
159+
| ``_CCCL_CONSTEXPR_CXX17`` | Enable ``constexpr`` for C++17 or newer |
160+
+-----------------------------+----------------------------------------------------------+
161+
| ``_CCCL_CONSTEXPR_CXX20`` | Enable ``constexpr`` for C++20 or newer |
162+
+-----------------------------+----------------------------------------------------------+
163+
| ``_CCCL_CONSTEXPR_CXX23`` | Enable ``constexpr`` for C++23 or newer |
164+
+-----------------------------+----------------------------------------------------------+
165+
| ``_CCCL_INLINE_VAR`` | Portable ``inline constexpr`` variable (before C++17) |
166+
+-----------------------------+----------------------------------------------------------+
167+
168+
**Concept-like Macros**:
169+
170+
+------------------------+--------------------------------------------------------------------------------------------+
171+
| ``_CCCL_TEMPLATE(X)`` | ``template`` clause |
172+
+------------------------+--------------------------------------------------------------------------------------------+
173+
| ``_CCCL_REQUIRES(X)`` | ``requires`` clause |
174+
+------------------------+--------------------------------------------------------------------------------------------+
175+
| ``_CCCL_TRAIT(X)`` | Selects variable template ``is_meow_v<T>`` instead of ``is_meow<T>::value`` when available |
176+
+------------------------+--------------------------------------------------------------------------------------------+
177+
| ``_CCCL_AND`` | Traits conjunction only used with ``_CCCL_REQUIRES`` |
178+
+------------------------+--------------------------------------------------------------------------------------------+
179+
180+
Usage example:
181+
182+
.. code-block:: c++
183+
184+
_CCCL_TEMPLATE(typename T)
185+
_CCCL_REQUIRES(_CCCL_TRAIT(is_integral, T) _CCCL_AND(sizeof(T) > 1))
186+
187+
.. code-block:: c++
188+
189+
_CCCL_TEMPLATE(typename T)
190+
_CCCL_REQUIRES(_CCCL_TRAIT(is_arithmetic, T) _CCCL_AND (!_CCCL_TRAIT(is_integral, T)))
191+
192+
193+
**Portable feature testing**:
194+
195+
+--------------------------+--------------------------------------------------+
196+
| ``_CCCL_HAS_BUILTIN(X)`` | Portable ``__has_builtin(X)`` |
197+
+--------------------------+--------------------------------------------------+
198+
| ``_CCCL_HAS_FEATURE(X)`` | Portable ``__has_feature(X)`` |
199+
+--------------------------+--------------------------------------------------+
200+
| ``_CCCL_HAS_INCLUDE(X)`` | Portable ``__has_include(X)`` (before C++17) |
201+
+--------------------------+--------------------------------------------------+
202+
203+
**Portable attributes**:
204+
205+
+----------------------------------+------------------------------------------------------------------------------+
206+
| ``_CCCL_FALLTHROUGH()`` | Portable ``[[fallthrough]]`` attribute (before C++17) |
207+
+----------------------------------+------------------------------------------------------------------------------+
208+
| ``_CCCL_NO_UNIQUE_ADDRESS`` | Portable ``[[no_unique_address]]`` attribute |
209+
+----------------------------------+------------------------------------------------------------------------------+
210+
| ``_CCCL_NODISCARD`` | Portable ``[[nodiscard]]`` attribute (before C++17) |
211+
+----------------------------------+------------------------------------------------------------------------------+
212+
| ``_CCCL_NODISCARD_FRIEND`` | Portable ``[[nodiscard]]`` attribute for ``friend`` functions (before C++17) |
213+
+----------------------------------+------------------------------------------------------------------------------+
214+
| ``_CCCL_NORETURN`` | Portable ``[[noreturn]]`` attribute (before C++11) |
215+
+----------------------------------+------------------------------------------------------------------------------+
216+
| ``CCCL_DEPRECATED`` | Portable ``[[deprecated]]`` attribute (before C++14) |
217+
+----------------------------------+------------------------------------------------------------------------------+
218+
| ``CCCL_DEPRECATED_BECAUSE(MSG)`` | Portable ``[[deprecated]]`` attribute with custom message (before C++14) |
219+
+----------------------------------+------------------------------------------------------------------------------+
220+
| ``_CCCL_FORCEINLINE`` | Portable "always inline" attribute |
221+
+----------------------------------+------------------------------------------------------------------------------+
222+
223+
**Portable Builtin Macros**:
224+
225+
+-----------------------------+--------------------------------------------+
226+
| ``_CCCL_UNREACHABLE()`` | Portable ``__builtin_unreachable()`` |
227+
+-----------------------------+--------------------------------------------+
228+
| ``_CCCL_BUILTIN_ASSUME(X)`` | Portable ``__builtin_assume(X)`` |
229+
+-----------------------------+--------------------------------------------+
230+
| ``_CCCL_BUILTIN_EXPECT(X)`` | Portable ``__builtin_expected(X)`` |
231+
+-----------------------------+--------------------------------------------+
232+
233+
**Portable Keyword Macros**
234+
235+
+-----------------------------+--------------------------------------------+
236+
| ``_CCCL_RESTRICT`` | Portable ``restrict`` keyword |
237+
+-----------------------------+--------------------------------------------+
238+
| ``_CCCL_ALIGNAS(X)`` | Portable ``alignas(X)`` keyword (variable) |
239+
+-----------------------------+--------------------------------------------+
240+
| ``_CCCL_ALIGNAS_TYPE(X)`` | Portable ``alignas(X)`` keyword (type) |
241+
+-----------------------------+--------------------------------------------+
242+
| ``_CCCL_PRAGMA(X)`` | Portable ``_Pragma(X)`` keyword |
243+
+-----------------------------+--------------------------------------------+
244+
245+
----
246+
247+
Visibility Macros
248+
-----------------
249+
250+
+-------------------------------+-----------------------------------------------------------------------------------------------------+
251+
| ``_CCCL_VISIBILITY_HIDDEN`` | Hidden visibility attribute (e.g. ``__attribute__((visibility("hidden")))``) |
252+
+-------------------------------+-----------------------------------------------------------------------------------------------------+
253+
| ``_CCCL_HIDE_FROM_ABI`` | Hidden visibility (i.e. ``inline``, not exported, not instantiated) |
254+
+-------------------------------+-----------------------------------------------------------------------------------------------------+
255+
| ``_LIBCUDACXX_HIDE_FROM_ABI`` | Host/device function with hidden visibility. Most libcu++ functions are hidden with this attribute |
256+
+-------------------------------+-----------------------------------------------------------------------------------------------------+
257+
258+
----
259+
260+
Other Common Macros
261+
-------------------
262+
263+
+-----------------------------+--------------------------------------------+
264+
| ``_CUDA_VSTD`` | ``cuda::std`` namespace. To use in libcu++ |
265+
+-----------------------------+--------------------------------------------+
266+
| ``_CCCL_TO_STRING(X)`` | ``X`` to literal string |
267+
+-----------------------------+--------------------------------------------+
268+
| ``_CCCL_DOXYGEN_INVOKED`` | Defined during Doxygen parsing |
269+
+-----------------------------+--------------------------------------------+
270+
271+
----
272+
273+
Debugging Macros
274+
----------------
275+
276+
+-----------------------------------+-------------------------------------------------------------------------------------------------------------+
277+
| ``_CCCL_ASSERT(COND, MSG)`` | Portable CCCL assert macro. Requires (``CCCL_ENABLE_HOST_ASSERTIONS`` or ``CCCL_ENABLE_DEVICE_ASSERTIONS``) |
278+
+-----------------------------------+-------------------------------------------------------------------------------------------------------------+
279+
| ``_CCCL_VERIFY(COND, MSG)`` | Portable ``alignas(X)`` keyword (variable) |
280+
+-----------------------------------+-------------------------------------------------------------------------------------------------------------+
281+
| ``_CCCL_ENABLE_ASSERTIONS`` | Enable assertions |
282+
+-----------------------------------+-------------------------------------------------------------------------------------------------------------+
283+
| ``CCCL_ENABLE_HOST_ASSERTIONS`` | Enable host-side assertions |
284+
+-----------------------------------+-------------------------------------------------------------------------------------------------------------+
285+
| ``CCCL_ENABLE_DEVICE_ASSERTIONS`` | Enable device-side assertions |
286+
+-----------------------------------+-------------------------------------------------------------------------------------------------------------+
287+
| ``_CCCL_ENABLE_DEBUG_MODE`` | Enable debug mode (and assertions) |
288+
+-----------------------------------+-------------------------------------------------------------------------------------------------------------+
289+
290+
----
291+
292+
Warning Suppression Macros
293+
--------------------------
294+
295+
+-----------------------------+--------------------------------------------+
296+
| ``_CCCL_DIAG_PUSH`` | Portable ``#pragma push`` |
297+
+-----------------------------+--------------------------------------------+
298+
| ``_CCCL_DIAG_POP`` | Portable ``#pragma pop`` |
299+
+-----------------------------+--------------------------------------------+
300+
| ``_CCCL_PUSH_MACROS`` | Push common msvc warning suppressions |
301+
+-----------------------------+--------------------------------------------+
302+
| ``_CCCL_POP_MACROS`` | Pop common msvc warning suppressions |
303+
+-----------------------------+--------------------------------------------+
304+
305+
**Compiler-specific Suppression Macros**:
306+
307+
+-----------------------------------+-------------------------------------------------------------+
308+
| ``_CCCL_DIAG_SUPPRESS_CLANG(X)`` | Suppress clang warning, e.g. ``"-Wattributes"`` |
309+
+-----------------------------------+-------------------------------------------------------------+
310+
| ``_CCCL_DIAG_SUPPRESS_GCC(X)`` | Suppress gcc warning, e.g. ``"-Wattributes"`` |
311+
+-----------------------------------+-------------------------------------------------------------+
312+
| ``_CCCL_DIAG_SUPPRESS_NVHPC(X)`` | Suppress nvhpc warning, e.g. ``expr_has_no_effect`` |
313+
+-----------------------------------+-------------------------------------------------------------+
314+
| ``_CCCL_DIAG_SUPPRESS_MSVC(X)`` | Suppress msvc warning, e.g. ``4127`` |
315+
+-----------------------------------+-------------------------------------------------------------+
316+
| ``_CCCL_NV_DIAG_SUPPRESS(X)`` | Suppress nvcc warning, e.g. ``177`` |
317+
+-----------------------------------+-------------------------------------------------------------+
318+
319+
Usage example:
320+
321+
.. code-block:: c++
322+
323+
_CCCL_DIAG_PUSH
324+
_CCCL_DIAG_SUPPRESS_GCC("-Wattributes")
325+
// code ..
326+
_CCCL_DIAG_POP

‎docs/cpp.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ CUDA C++ Core Libraries
1111
CUB <https://nvidia.github.io/cccl/cub/>
1212
Thrust <https://nvidia.github.io/cccl/thrust/>
1313
Cuda Experimental <https://nvidia.github.io/cccl/cudax/>
14+
CCCL development <cccl_development/index>
1415

1516
Welcome to the CUDA Core Compute Libraries (CCCL) libraries for C++.
1617

0 commit comments

Comments
 (0)