include/nvtx3/nvToolsExtCuda.h

0001 /*
0002  * SPDX-FileCopyrightText: Copyright (c) 2009-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
0003  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0004  *
0005  * Licensed under the Apache License, Version 2.0 (the "License");
0006  * you may not use this file except in compliance with the License.
0007  * You may obtain a copy of the License at
0008  *
0009  *     http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  *
0017  * Licensed under the Apache License v2.0 with LLVM Exceptions.
0018  * See https://nvidia.github.io/NVTX/LICENSE.txt for license information.
0019  */
0020
0021 #if defined(NVTX_AS_SYSTEM_HEADER)
0022 #if defined(__clang__)
0023 #pragma clang system_header
0024 #elif defined(__GNUC__) || defined(__NVCOMPILER)
0025 #pragma GCC system_header
0026 #elif defined(_MSC_VER)
0027 #pragma system_header
0028 #endif
0029 #endif
0030
0031 #include "nvToolsExt.h"
0032
0033 #include "cuda.h"
0034
0035 #ifndef NVTOOLSEXT_CUDA_V3
0036 #define NVTOOLSEXT_CUDA_V3
0037
0038 #ifdef __cplusplus
0039 extern "C" {
0040 #endif /* __cplusplus */
0041
0042 /* ========================================================================= */
0043 /** \name Functions for CUDA Resource Naming
0044 */
0045 /** \addtogroup RESOURCE_NAMING
0046  * \section RESOURCE_NAMING_CUDA CUDA Resource Naming
0047  *
0048  * This section covers the API functions that allow to annotate CUDA resources
0049  * with user-provided names.
0050  *
0051  * @{
0052  */
0053
0054 /*  ------------------------------------------------------------------------- */
0055 /* \cond SHOW_HIDDEN
0056 * \brief Used to build a non-colliding value for resource types separated class
0057 * \version NVTX_VERSION_2
0058 */
0059 #define NVTX_RESOURCE_CLASS_CUDA  4
0060 /** \endcond */
0061
0062 /*  ------------------------------------------------------------------------- */
0063 /** \brief Resource types for CUDA
0064 */
0065 typedef enum nvtxResourceCUDAType_t
0066 {
0067     NVTX_RESOURCE_TYPE_CUDA_DEVICE = NVTX_RESOURCE_MAKE_TYPE(CUDA, 1), /* CUdevice */
0068     NVTX_RESOURCE_TYPE_CUDA_CONTEXT = NVTX_RESOURCE_MAKE_TYPE(CUDA, 2), /* CUcontext */
0069     NVTX_RESOURCE_TYPE_CUDA_STREAM = NVTX_RESOURCE_MAKE_TYPE(CUDA, 3), /* CUstream */
0070     NVTX_RESOURCE_TYPE_CUDA_EVENT = NVTX_RESOURCE_MAKE_TYPE(CUDA, 4) /* CUevent */
0071 } nvtxResourceCUDAType_t;
0072
0073
0074 /* ------------------------------------------------------------------------- */
0075 /** \brief Annotates a CUDA device.
0076  *
0077  * Allows the user to associate a CUDA device with a user-provided name.
0078  *
0079  * \param device - The handle of the CUDA device to name.
0080  * \param name   - The name of the CUDA device.
0081  *
0082  * \version NVTX_VERSION_1
0083  * @{ */
0084 NVTX_DECLSPEC void NVTX_API nvtxNameCuDeviceA(CUdevice device, const char* name);
0085 NVTX_DECLSPEC void NVTX_API nvtxNameCuDeviceW(CUdevice device, const wchar_t* name);
0086 /** @} */
0087
0088 /* ------------------------------------------------------------------------- */
0089 /** \brief Annotates a CUDA context.
0090  *
0091  * Allows the user to associate a CUDA context with a user-provided name.
0092  *
0093  * \param context - The handle of the CUDA context to name.
0094  * \param name    - The name of the CUDA context.
0095  *
0096  * \par Example
0097  * Name a CUDA context:
0098  * \code
0099  * CUresult status = cuCtxCreate( &cuContext, 0, cuDevice );
0100  * if ( CUDA_SUCCESS != status )
0101  *     goto Error;
0102  * nvtxNameCuContext(cuContext, "CTX_NAME");
0103  * \endcode
0104  *
0105  * \version NVTX_VERSION_1
0106  * @{ */
0107 NVTX_DECLSPEC void NVTX_API nvtxNameCuContextA(CUcontext context, const char* name);
0108 NVTX_DECLSPEC void NVTX_API nvtxNameCuContextW(CUcontext context, const wchar_t* name);
0109 /** @} */
0110
0111 /* ------------------------------------------------------------------------- */
0112 /** \brief Annotates a CUDA stream.
0113  *
0114  * Allows the user to associate a CUDA stream with a user-provided name.
0115  *
0116  * \param stream - The handle of the CUDA stream to name.
0117  * \param name   - The name of the CUDA stream.
0118  *
0119  * \version NVTX_VERSION_1
0120  * @{ */
0121 NVTX_DECLSPEC void NVTX_API nvtxNameCuStreamA(CUstream stream, const char* name);
0122 NVTX_DECLSPEC void NVTX_API nvtxNameCuStreamW(CUstream stream, const wchar_t* name);
0123 /** @} */
0124
0125 /* ------------------------------------------------------------------------- */
0126 /** \brief Annotates a CUDA event.
0127  *
0128  * Allows the user to associate a CUDA event with a user-provided name.
0129  *
0130  * \param event - The handle of the CUDA event to name.
0131  * \param name  - The name of the CUDA event.
0132  *
0133  * \version NVTX_VERSION_1
0134  * @{ */
0135 NVTX_DECLSPEC void NVTX_API nvtxNameCuEventA(CUevent event, const char* name);
0136 NVTX_DECLSPEC void NVTX_API nvtxNameCuEventW(CUevent event, const wchar_t* name);
0137 /** @} */
0138
0139 /** @} */ /* END RESOURCE_NAMING */
0140
0141 /* ========================================================================= */
0142 #ifdef UNICODE
0143   #define nvtxNameCuDevice   nvtxNameCuDeviceW
0144   #define nvtxNameCuContext  nvtxNameCuContextW
0145   #define nvtxNameCuStream   nvtxNameCuStreamW
0146   #define nvtxNameCuEvent    nvtxNameCuEventW
0147 #else
0148   #define nvtxNameCuDevice   nvtxNameCuDeviceA
0149   #define nvtxNameCuContext  nvtxNameCuContextA
0150   #define nvtxNameCuStream   nvtxNameCuStreamA
0151   #define nvtxNameCuEvent    nvtxNameCuEventA
0152 #endif
0153
0154 #ifdef __cplusplus
0155 }
0156 #endif /* __cplusplus */
0157
0158 #ifndef NVTX_NO_IMPL
0159 #define NVTX_IMPL_GUARD_CUDA /* Ensure other headers cannot be included directly */
0160 #include "nvtxDetail/nvtxImplCuda_v3.h"
0161 #undef NVTX_IMPL_GUARD_CUDA
0162 #endif /*NVTX_NO_IMPL*/
0163
0164 #endif /* NVTOOLSEXT_CUDA_V3 */