nvtx3/nvtxDetail/nvtxTypes.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 /* This header defines types which are used by the internal implementation
0022 *  of NVTX and callback subscribers.  API clients do not use these types,
0023 *  so they are defined here instead of in nvToolsExt.h to clarify they are
0024 *  not part of the NVTX client API. */
0025
0026 #ifndef NVTX_IMPL_GUARD
0027 #error Never include this file directly -- it is automatically included by nvToolsExt.h.
0028 #endif
0029
0030 #if defined(NVTX_AS_SYSTEM_HEADER)
0031 #if defined(__clang__)
0032 #pragma clang system_header
0033 #elif defined(__GNUC__) || defined(__NVCOMPILER)
0034 #pragma GCC system_header
0035 #elif defined(_MSC_VER)
0036 #pragma system_header
0037 #endif
0038 #endif
0039
0040 /* ------ Dependency-free types binary-compatible with real types ------- */
0041
0042 /* In order to avoid having the NVTX core API headers depend on non-NVTX
0043 *  headers like cuda.h, NVTX defines binary-compatible types to use for
0044 *  safely making the initialization versions of all NVTX functions without
0045 *  needing to have definitions for the real types. */
0046
0047 typedef int   nvtx_CUdevice;
0048 typedef void* nvtx_CUcontext;
0049 typedef void* nvtx_CUstream;
0050 typedef void* nvtx_CUevent;
0051
0052 typedef void* nvtx_cudaStream_t;
0053 typedef void* nvtx_cudaEvent_t;
0054
0055 typedef void* nvtx_cl_platform_id;
0056 typedef void* nvtx_cl_device_id;
0057 typedef void* nvtx_cl_context;
0058 typedef void* nvtx_cl_command_queue;
0059 typedef void* nvtx_cl_mem;
0060 typedef void* nvtx_cl_program;
0061 typedef void* nvtx_cl_kernel;
0062 typedef void* nvtx_cl_event;
0063 typedef void* nvtx_cl_sampler;
0064
0065 typedef void* nvtx_nvtxSyncUser_t;
0066 typedef void nvtx_nvtxSyncUserAttributes_t;
0067
0068 /* --------- Types for function pointers (with fake API types) ---------- */
0069
0070 typedef void (NVTX_API * nvtxMarkEx_impl_fntype)(const nvtxEventAttributes_t* eventAttrib);
0071 typedef void (NVTX_API * nvtxMarkA_impl_fntype)(const char* message);
0072 typedef void (NVTX_API * nvtxMarkW_impl_fntype)(const wchar_t* message);
0073 typedef nvtxRangeId_t (NVTX_API * nvtxRangeStartEx_impl_fntype)(const nvtxEventAttributes_t* eventAttrib);
0074 typedef nvtxRangeId_t (NVTX_API * nvtxRangeStartA_impl_fntype)(const char* message);
0075 typedef nvtxRangeId_t (NVTX_API * nvtxRangeStartW_impl_fntype)(const wchar_t* message);
0076 typedef void (NVTX_API * nvtxRangeEnd_impl_fntype)(nvtxRangeId_t id);
0077 typedef int (NVTX_API * nvtxRangePushEx_impl_fntype)(const nvtxEventAttributes_t* eventAttrib);
0078 typedef int (NVTX_API * nvtxRangePushA_impl_fntype)(const char* message);
0079 typedef int (NVTX_API * nvtxRangePushW_impl_fntype)(const wchar_t* message);
0080 typedef int (NVTX_API * nvtxRangePop_impl_fntype)(void);
0081 typedef void (NVTX_API * nvtxNameCategoryA_impl_fntype)(uint32_t category, const char* name);
0082 typedef void (NVTX_API * nvtxNameCategoryW_impl_fntype)(uint32_t category, const wchar_t* name);
0083 typedef void (NVTX_API * nvtxNameOsThreadA_impl_fntype)(uint32_t threadId, const char* name);
0084 typedef void (NVTX_API * nvtxNameOsThreadW_impl_fntype)(uint32_t threadId, const wchar_t* name);
0085
0086 /* Real impl types are defined in nvtxImplCuda_v3.h, where CUDA headers are included */
0087 typedef void (NVTX_API * nvtxNameCuDeviceA_fakeimpl_fntype)(nvtx_CUdevice device, const char* name);
0088 typedef void (NVTX_API * nvtxNameCuDeviceW_fakeimpl_fntype)(nvtx_CUdevice device, const wchar_t* name);
0089 typedef void (NVTX_API * nvtxNameCuContextA_fakeimpl_fntype)(nvtx_CUcontext context, const char* name);
0090 typedef void (NVTX_API * nvtxNameCuContextW_fakeimpl_fntype)(nvtx_CUcontext context, const wchar_t* name);
0091 typedef void (NVTX_API * nvtxNameCuStreamA_fakeimpl_fntype)(nvtx_CUstream stream, const char* name);
0092 typedef void (NVTX_API * nvtxNameCuStreamW_fakeimpl_fntype)(nvtx_CUstream stream, const wchar_t* name);
0093 typedef void (NVTX_API * nvtxNameCuEventA_fakeimpl_fntype)(nvtx_CUevent event, const char* name);
0094 typedef void (NVTX_API * nvtxNameCuEventW_fakeimpl_fntype)(nvtx_CUevent event, const wchar_t* name);
0095
0096 /* Real impl types are defined in nvtxImplOpenCL_v3.h, where OPENCL headers are included */
0097 typedef void (NVTX_API * nvtxNameClDeviceA_fakeimpl_fntype)(nvtx_cl_device_id device, const char* name);
0098 typedef void (NVTX_API * nvtxNameClDeviceW_fakeimpl_fntype)(nvtx_cl_device_id device, const wchar_t* name);
0099 typedef void (NVTX_API * nvtxNameClContextA_fakeimpl_fntype)(nvtx_cl_context context, const char* name);
0100 typedef void (NVTX_API * nvtxNameClContextW_fakeimpl_fntype)(nvtx_cl_context context, const wchar_t* name);
0101 typedef void (NVTX_API * nvtxNameClCommandQueueA_fakeimpl_fntype)(nvtx_cl_command_queue command_queue, const char* name);
0102 typedef void (NVTX_API * nvtxNameClCommandQueueW_fakeimpl_fntype)(nvtx_cl_command_queue command_queue, const wchar_t* name);
0103 typedef void (NVTX_API * nvtxNameClMemObjectA_fakeimpl_fntype)(nvtx_cl_mem memobj, const char* name);
0104 typedef void (NVTX_API * nvtxNameClMemObjectW_fakeimpl_fntype)(nvtx_cl_mem memobj, const wchar_t* name);
0105 typedef void (NVTX_API * nvtxNameClSamplerA_fakeimpl_fntype)(nvtx_cl_sampler sampler, const char* name);
0106 typedef void (NVTX_API * nvtxNameClSamplerW_fakeimpl_fntype)(nvtx_cl_sampler sampler, const wchar_t* name);
0107 typedef void (NVTX_API * nvtxNameClProgramA_fakeimpl_fntype)(nvtx_cl_program program, const char* name);
0108 typedef void (NVTX_API * nvtxNameClProgramW_fakeimpl_fntype)(nvtx_cl_program program, const wchar_t* name);
0109 typedef void (NVTX_API * nvtxNameClEventA_fakeimpl_fntype)(nvtx_cl_event evnt, const char* name);
0110 typedef void (NVTX_API * nvtxNameClEventW_fakeimpl_fntype)(nvtx_cl_event evnt, const wchar_t* name);
0111
0112 /* Real impl types are defined in nvtxImplCudaRt_v3.h, where CUDART headers are included */
0113 typedef void (NVTX_API * nvtxNameCudaDeviceA_fakeimpl_fntype)(int device, const char* name);
0114 typedef void (NVTX_API * nvtxNameCudaDeviceW_fakeimpl_fntype)(int device, const wchar_t* name);
0115 typedef void (NVTX_API * nvtxNameCudaStreamA_fakeimpl_fntype)(nvtx_cudaStream_t stream, const char* name);
0116 typedef void (NVTX_API * nvtxNameCudaStreamW_fakeimpl_fntype)(nvtx_cudaStream_t stream, const wchar_t* name);
0117 typedef void (NVTX_API * nvtxNameCudaEventA_fakeimpl_fntype)(nvtx_cudaEvent_t event, const char* name);
0118 typedef void (NVTX_API * nvtxNameCudaEventW_fakeimpl_fntype)(nvtx_cudaEvent_t event, const wchar_t* name);
0119
0120 typedef void (NVTX_API * nvtxDomainMarkEx_impl_fntype)(nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib);
0121 typedef nvtxRangeId_t (NVTX_API * nvtxDomainRangeStartEx_impl_fntype)(nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib);
0122 typedef void (NVTX_API * nvtxDomainRangeEnd_impl_fntype)(nvtxDomainHandle_t domain, nvtxRangeId_t id);
0123 typedef int (NVTX_API * nvtxDomainRangePushEx_impl_fntype)(nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib);
0124 typedef int (NVTX_API * nvtxDomainRangePop_impl_fntype)(nvtxDomainHandle_t domain);
0125 typedef nvtxResourceHandle_t (NVTX_API * nvtxDomainResourceCreate_impl_fntype)(nvtxDomainHandle_t domain, nvtxResourceAttributes_t* attribs);
0126 typedef void (NVTX_API * nvtxDomainResourceDestroy_impl_fntype)(nvtxResourceHandle_t resource);
0127 typedef void (NVTX_API * nvtxDomainNameCategoryA_impl_fntype)(nvtxDomainHandle_t domain, uint32_t category, const char* name);
0128 typedef void (NVTX_API * nvtxDomainNameCategoryW_impl_fntype)(nvtxDomainHandle_t domain, uint32_t category, const wchar_t* name);
0129 typedef nvtxStringHandle_t (NVTX_API * nvtxDomainRegisterStringA_impl_fntype)(nvtxDomainHandle_t domain, const char* string);
0130 typedef nvtxStringHandle_t (NVTX_API * nvtxDomainRegisterStringW_impl_fntype)(nvtxDomainHandle_t domain, const wchar_t* string);
0131 typedef nvtxDomainHandle_t (NVTX_API * nvtxDomainCreateA_impl_fntype)(const char* message);
0132 typedef nvtxDomainHandle_t (NVTX_API * nvtxDomainCreateW_impl_fntype)(const wchar_t* message);
0133 typedef void (NVTX_API * nvtxDomainDestroy_impl_fntype)(nvtxDomainHandle_t domain);
0134 typedef void (NVTX_API * nvtxInitialize_impl_fntype)(const void* reserved);
0135
0136 typedef nvtx_nvtxSyncUser_t (NVTX_API * nvtxDomainSyncUserCreate_fakeimpl_fntype)(nvtxDomainHandle_t domain, const nvtx_nvtxSyncUserAttributes_t* attribs);
0137 typedef void (NVTX_API * nvtxDomainSyncUserDestroy_fakeimpl_fntype)(nvtx_nvtxSyncUser_t handle);
0138 typedef void (NVTX_API * nvtxDomainSyncUserAcquireStart_fakeimpl_fntype)(nvtx_nvtxSyncUser_t handle);
0139 typedef void (NVTX_API * nvtxDomainSyncUserAcquireFailed_fakeimpl_fntype)(nvtx_nvtxSyncUser_t handle);
0140 typedef void (NVTX_API * nvtxDomainSyncUserAcquireSuccess_fakeimpl_fntype)(nvtx_nvtxSyncUser_t handle);
0141 typedef void (NVTX_API * nvtxDomainSyncUserReleasing_fakeimpl_fntype)(nvtx_nvtxSyncUser_t handle);
0142
0143 /* ---------------- Types for callback subscription --------------------- */
0144
0145 typedef const void *(NVTX_API * NvtxGetExportTableFunc_t)(uint32_t exportTableId);
0146 typedef int (NVTX_API * NvtxInitializeInjectionNvtxFunc_t)(NvtxGetExportTableFunc_t exportTable);
0147
0148 typedef enum NvtxCallbackModule
0149 {
0150     NVTX_CB_MODULE_INVALID                 = 0,
0151     NVTX_CB_MODULE_CORE                    = 1,
0152     NVTX_CB_MODULE_CUDA                    = 2,
0153     NVTX_CB_MODULE_OPENCL                  = 3,
0154     NVTX_CB_MODULE_CUDART                  = 4,
0155     NVTX_CB_MODULE_CORE2                   = 5,
0156     NVTX_CB_MODULE_SYNC                    = 6,
0157     /* --- New constants must only be added directly above this line --- */
0158     NVTX_CB_MODULE_SIZE,
0159     NVTX_CB_MODULE_FORCE_INT               = 0x7fffffff
0160 } NvtxCallbackModule;
0161
0162 typedef enum NvtxCallbackIdCore
0163 {
0164     NVTX_CBID_CORE_INVALID                 =  0,
0165     NVTX_CBID_CORE_MarkEx                  =  1,
0166     NVTX_CBID_CORE_MarkA                   =  2,
0167     NVTX_CBID_CORE_MarkW                   =  3,
0168     NVTX_CBID_CORE_RangeStartEx            =  4,
0169     NVTX_CBID_CORE_RangeStartA             =  5,
0170     NVTX_CBID_CORE_RangeStartW             =  6,
0171     NVTX_CBID_CORE_RangeEnd                =  7,
0172     NVTX_CBID_CORE_RangePushEx             =  8,
0173     NVTX_CBID_CORE_RangePushA              =  9,
0174     NVTX_CBID_CORE_RangePushW              = 10,
0175     NVTX_CBID_CORE_RangePop                = 11,
0176     NVTX_CBID_CORE_NameCategoryA           = 12,
0177     NVTX_CBID_CORE_NameCategoryW           = 13,
0178     NVTX_CBID_CORE_NameOsThreadA           = 14,
0179     NVTX_CBID_CORE_NameOsThreadW           = 15,
0180     /* --- New constants must only be added directly above this line --- */
0181     NVTX_CBID_CORE_SIZE,
0182     NVTX_CBID_CORE_FORCE_INT = 0x7fffffff
0183 } NvtxCallbackIdCore;
0184
0185 typedef enum NvtxCallbackIdCore2
0186 {
0187     NVTX_CBID_CORE2_INVALID                 = 0,
0188     NVTX_CBID_CORE2_DomainMarkEx            = 1,
0189     NVTX_CBID_CORE2_DomainRangeStartEx      = 2,
0190     NVTX_CBID_CORE2_DomainRangeEnd          = 3,
0191     NVTX_CBID_CORE2_DomainRangePushEx       = 4,
0192     NVTX_CBID_CORE2_DomainRangePop          = 5,
0193     NVTX_CBID_CORE2_DomainResourceCreate    = 6,
0194     NVTX_CBID_CORE2_DomainResourceDestroy   = 7,
0195     NVTX_CBID_CORE2_DomainNameCategoryA     = 8,
0196     NVTX_CBID_CORE2_DomainNameCategoryW     = 9,
0197     NVTX_CBID_CORE2_DomainRegisterStringA   = 10,
0198     NVTX_CBID_CORE2_DomainRegisterStringW   = 11,
0199     NVTX_CBID_CORE2_DomainCreateA           = 12,
0200     NVTX_CBID_CORE2_DomainCreateW           = 13,
0201     NVTX_CBID_CORE2_DomainDestroy           = 14,
0202     NVTX_CBID_CORE2_Initialize              = 15,
0203     /* --- New constants must only be added directly above this line --- */
0204     NVTX_CBID_CORE2_SIZE,
0205     NVTX_CBID_CORE2_FORCE_INT               = 0x7fffffff
0206 } NvtxCallbackIdCore2;
0207
0208 typedef enum NvtxCallbackIdCuda
0209 {
0210     NVTX_CBID_CUDA_INVALID                 =  0,
0211     NVTX_CBID_CUDA_NameCuDeviceA           =  1,
0212     NVTX_CBID_CUDA_NameCuDeviceW           =  2,
0213     NVTX_CBID_CUDA_NameCuContextA          =  3,
0214     NVTX_CBID_CUDA_NameCuContextW          =  4,
0215     NVTX_CBID_CUDA_NameCuStreamA           =  5,
0216     NVTX_CBID_CUDA_NameCuStreamW           =  6,
0217     NVTX_CBID_CUDA_NameCuEventA            =  7,
0218     NVTX_CBID_CUDA_NameCuEventW            =  8,
0219     /* --- New constants must only be added directly above this line --- */
0220     NVTX_CBID_CUDA_SIZE,
0221     NVTX_CBID_CUDA_FORCE_INT               = 0x7fffffff
0222 } NvtxCallbackIdCuda;
0223
0224 typedef enum NvtxCallbackIdCudaRt
0225 {
0226     NVTX_CBID_CUDART_INVALID               =  0,
0227     NVTX_CBID_CUDART_NameCudaDeviceA       =  1,
0228     NVTX_CBID_CUDART_NameCudaDeviceW       =  2,
0229     NVTX_CBID_CUDART_NameCudaStreamA       =  3,
0230     NVTX_CBID_CUDART_NameCudaStreamW       =  4,
0231     NVTX_CBID_CUDART_NameCudaEventA        =  5,
0232     NVTX_CBID_CUDART_NameCudaEventW        =  6,
0233     /* --- New constants must only be added directly above this line --- */
0234     NVTX_CBID_CUDART_SIZE,
0235     NVTX_CBID_CUDART_FORCE_INT             = 0x7fffffff
0236 } NvtxCallbackIdCudaRt;
0237
0238 typedef enum NvtxCallbackIdOpenCL
0239 {
0240     NVTX_CBID_OPENCL_INVALID               =  0,
0241     NVTX_CBID_OPENCL_NameClDeviceA         =  1,
0242     NVTX_CBID_OPENCL_NameClDeviceW         =  2,
0243     NVTX_CBID_OPENCL_NameClContextA        =  3,
0244     NVTX_CBID_OPENCL_NameClContextW        =  4,
0245     NVTX_CBID_OPENCL_NameClCommandQueueA   =  5,
0246     NVTX_CBID_OPENCL_NameClCommandQueueW   =  6,
0247     NVTX_CBID_OPENCL_NameClMemObjectA      =  7,
0248     NVTX_CBID_OPENCL_NameClMemObjectW      =  8,
0249     NVTX_CBID_OPENCL_NameClSamplerA        =  9,
0250     NVTX_CBID_OPENCL_NameClSamplerW        = 10,
0251     NVTX_CBID_OPENCL_NameClProgramA        = 11,
0252     NVTX_CBID_OPENCL_NameClProgramW        = 12,
0253     NVTX_CBID_OPENCL_NameClEventA          = 13,
0254     NVTX_CBID_OPENCL_NameClEventW          = 14,
0255     /* --- New constants must only be added directly above this line --- */
0256     NVTX_CBID_OPENCL_SIZE,
0257     NVTX_CBID_OPENCL_FORCE_INT             = 0x7fffffff
0258 } NvtxCallbackIdOpenCL;
0259
0260 typedef enum NvtxCallbackIdSync
0261 {
0262     NVTX_CBID_SYNC_INVALID                      = 0,
0263     NVTX_CBID_SYNC_DomainSyncUserCreate         = 1,
0264     NVTX_CBID_SYNC_DomainSyncUserDestroy        = 2,
0265     NVTX_CBID_SYNC_DomainSyncUserAcquireStart   = 3,
0266     NVTX_CBID_SYNC_DomainSyncUserAcquireFailed  = 4,
0267     NVTX_CBID_SYNC_DomainSyncUserAcquireSuccess = 5,
0268     NVTX_CBID_SYNC_DomainSyncUserReleasing      = 6,
0269     /* --- New constants must only be added directly above this line --- */
0270     NVTX_CBID_SYNC_SIZE,
0271     NVTX_CBID_SYNC_FORCE_INT                    = 0x7fffffff
0272 } NvtxCallbackIdSync;
0273
0274 /* IDs for NVTX Export Tables */
0275 typedef enum NvtxExportTableID
0276 {
0277     NVTX_ETID_INVALID                      = 0,
0278     NVTX_ETID_CALLBACKS                    = 1,
0279     NVTX_ETID_RESERVED0                    = 2,
0280     NVTX_ETID_VERSIONINFO                  = 3,
0281     /* --- New constants must only be added directly above this line --- */
0282     NVTX_ETID_SIZE,
0283     NVTX_ETID_FORCE_INT                    = 0x7fffffff
0284 } NvtxExportTableID;
0285
0286 typedef void (* NvtxFunctionPointer)(void); /* generic uncallable function pointer, must be cast to appropriate function type */
0287 typedef NvtxFunctionPointer** NvtxFunctionTable; /* double pointer because array(1) of pointers(2) to function pointers */
0288
0289 typedef struct NvtxExportTableCallbacks
0290 {
0291     size_t struct_size;
0292
0293     /* returns an array of pointer to function pointers*/
0294     int (NVTX_API *GetModuleFunctionTable)(
0295         NvtxCallbackModule callback_module,
0296         NvtxFunctionTable* out_table,
0297         unsigned int* out_size);
0298 } NvtxExportTableCallbacks;
0299
0300 typedef struct NvtxExportTableVersionInfo
0301 {
0302     /* sizeof(NvtxExportTableVersionInfo) */
0303     size_t struct_size;
0304
0305     /* The API version comes from the NVTX library linked to the app.  The
0306     * injection library is can use this info to make some assumptions */
0307     uint32_t version;
0308
0309     /* Reserved for alignment, do not use */
0310     uint32_t reserved0;
0311
0312     /* This must be set by tools when attaching to provide applications
0313     *  the ability to, in emergency situations, detect problematic tools
0314     *  versions and modify the NVTX source to prevent attaching anything
0315     *  that causes trouble in the app.  Currently, this value is ignored. */
0316     void (NVTX_API *SetInjectionNvtxVersion)(
0317         uint32_t version);
0318 } NvtxExportTableVersionInfo;