NVTX  v3
NVIDIA Tools Extension Library
nvToolsExt.h
Go to the documentation of this file.
1 /*
2 * Copyright 2009-2020 NVIDIA Corporation. All rights reserved.
3 *
4 * Licensed under the Apache License v2.0 with LLVM Exceptions.
5 * See https://llvm.org/LICENSE.txt for license information.
6 * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 */
8 
12 /* ========================================================================= */
149 #if defined(NVTX_VERSION) && NVTX_VERSION < 3
150 #error "Trying to #include NVTX version 3 in a source file where an older NVTX version has already been included. If you are not directly using NVTX (the NVIDIA Tools Extension library), you are getting this error because libraries you are using have included different versions of NVTX. Suggested solutions are: (1) reorder #includes so the newest NVTX version is included first, (2) avoid using the conflicting libraries in the same .c/.cpp file, or (3) update the library using the older NVTX version to use the newer version instead."
151 #endif
152 
153 /* Header guard */
154 #if !defined(NVTX_VERSION)
155 #define NVTX_VERSION 3
156 
157 #if defined(_MSC_VER)
158 #define NVTX_API __stdcall
159 #define NVTX_INLINE_STATIC __inline static
160 #else /*defined(__GNUC__)*/
161 #define NVTX_API
162 #define NVTX_INLINE_STATIC inline static
163 #endif /* Platform */
164 
165 #if defined(NVTX_NO_IMPL)
166 /* When omitting implementation, avoid declaring functions inline */
167 /* without definitions, since this causes compiler warnings. */
168 #define NVTX_DECLSPEC
169 #elif defined(NVTX_EXPORT_API)
170 /* Allow overriding definition of NVTX_DECLSPEC when exporting API. */
171 /* Default is empty, meaning non-inline with external linkage. */
172 #if !defined(NVTX_DECLSPEC)
173 #define NVTX_DECLSPEC
174 #endif
175 #else
176 /* Normal NVTX usage defines the NVTX API inline with static */
177 /* (internal) linkage. */
178 #define NVTX_DECLSPEC NVTX_INLINE_STATIC
179 #endif
180 
181 #include "nvtxDetail/nvtxLinkOnce.h"
182 
183 #define NVTX_VERSIONED_IDENTIFIER_L3(NAME, VERSION) NAME##_v##VERSION
184 #define NVTX_VERSIONED_IDENTIFIER_L2(NAME, VERSION) NVTX_VERSIONED_IDENTIFIER_L3(NAME, VERSION)
185 #define NVTX_VERSIONED_IDENTIFIER(NAME) NVTX_VERSIONED_IDENTIFIER_L2(NAME, NVTX_VERSION)
186 
205 #ifndef NVTX_STDINT_TYPES_ALREADY_DEFINED
206 #include <stdint.h>
207 #endif
208 
209 #include <stddef.h>
210 
211 #ifdef __cplusplus
212 extern "C" {
213 #endif /* __cplusplus */
214 
219 #define NVTX_SUCCESS 0
220 #define NVTX_FAIL 1
221 #define NVTX_ERR_INIT_LOAD_PROPERTY 2
222 #define NVTX_ERR_INIT_ACCESS_LIBRARY 3
223 #define NVTX_ERR_INIT_LOAD_LIBRARY 4
224 #define NVTX_ERR_INIT_MISSING_LIBRARY_ENTRY_POINT 5
225 #define NVTX_ERR_INIT_FAILED_LIBRARY_ENTRY_POINT 6
226 #define NVTX_ERR_NO_INJECTION_LIBRARY_AVAILABLE 7
227 
231 #define NVTX_EVENT_ATTRIB_STRUCT_SIZE ( (uint16_t)( sizeof(nvtxEventAttributes_t) ) )
232 
233 #define NVTX_NO_PUSH_POP_TRACKING ((int)-2)
234 
235 typedef uint64_t nvtxRangeId_t;
236 
237 /* Forward declaration of opaque domain registration structure */
238 struct nvtxDomainRegistration_st;
239 typedef struct nvtxDomainRegistration_st nvtxDomainRegistration;
240 
241 /* \brief Domain Handle Structure.
242 * \anchor DOMAIN_HANDLE_STRUCTURE
243 *
244 * This structure is opaque to the user and is used as a handle to reference
245 * a domain. This type is returned from tools when using the NVTX API to
246 * create a domain.
247 *
248 */
249 typedef nvtxDomainRegistration* nvtxDomainHandle_t;
250 
251 /* Forward declaration of opaque string registration structure */
252 struct nvtxStringRegistration_st;
253 typedef struct nvtxStringRegistration_st nvtxStringRegistration;
254 
255 /* \brief Registered String Handle Structure.
256 * \anchor REGISTERED_STRING_HANDLE_STRUCTURE
257 *
258 * This structure is opaque to the user and is used as a handle to reference
259 * a registered string. This type is returned from tools when using the NVTX
260 * API to create a registered string.
261 *
262 */
263 typedef nvtxStringRegistration* nvtxStringHandle_t;
264 
265 /* ========================================================================= */
273 typedef enum nvtxColorType_t
274 {
278 
282 typedef enum nvtxMessageType_t
283 {
287  /* NVTX_VERSION_2 */
292 
293 typedef union nvtxMessageValue_t
294 {
295  const char* ascii;
296  const wchar_t* unicode;
297  /* NVTX_VERSION_2 */
298  nvtxStringHandle_t registered;
300 
301  /*END defgroup*/
303 /* ------------------------------------------------------------------------- */
325 NVTX_DECLSPEC void NVTX_API nvtxInitialize(const void* reserved); /*END defgroup*/
330 
331 /* ========================================================================= */
339 typedef enum nvtxPayloadType_t
340 {
345  /* NVTX_VERSION_2 */
350 
429 {
437  uint16_t version;
438 
445  uint16_t size;
446 
458  uint32_t category;
459 
467  int32_t colorType; /* nvtxColorType_t */
468 
473  uint32_t color;
474 
483  int32_t payloadType; /* nvtxPayloadType_t */
484 
485  int32_t reserved0;
486 
493  union payload_t
494  {
495  uint64_t ullValue;
496  int64_t llValue;
497  double dValue;
498  /* NVTX_VERSION_2 */
499  uint32_t uiValue;
500  int32_t iValue;
501  float fValue;
502  } payload;
503 
511  int32_t messageType; /* nvtxMessageType_t */
512 
518 
520 
521 typedef struct nvtxEventAttributes_v2 nvtxEventAttributes_t;
522  /*END defgroup*/
524 /* ========================================================================= */
534 /* ------------------------------------------------------------------------- */
554 NVTX_DECLSPEC void NVTX_API nvtxDomainMarkEx(nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib);
557 /* ------------------------------------------------------------------------- */
590 NVTX_DECLSPEC void NVTX_API nvtxMarkEx(const nvtxEventAttributes_t* eventAttrib);
593 /* ------------------------------------------------------------------------- */
613 NVTX_DECLSPEC void NVTX_API nvtxMarkA(const char* message);
614 NVTX_DECLSPEC void NVTX_API nvtxMarkW(const wchar_t* message);
620 /* ------------------------------------------------------------------------- */
649 NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxDomainRangeStartEx(nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib);
652 /* ------------------------------------------------------------------------- */
683 NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartEx(const nvtxEventAttributes_t* eventAttrib);
686 /* ------------------------------------------------------------------------- */
710 NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartA(const char* message);
711 NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartW(const wchar_t* message);
714 /* ------------------------------------------------------------------------- */
741 NVTX_DECLSPEC void NVTX_API nvtxDomainRangeEnd(nvtxDomainHandle_t domain, nvtxRangeId_t id);
744 /* ------------------------------------------------------------------------- */
757 NVTX_DECLSPEC void NVTX_API nvtxRangeEnd(nvtxRangeId_t id);
762 /* ------------------------------------------------------------------------- */
798 NVTX_DECLSPEC int NVTX_API nvtxDomainRangePushEx(nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib);
801 /* ------------------------------------------------------------------------- */
836 NVTX_DECLSPEC int NVTX_API nvtxRangePushEx(const nvtxEventAttributes_t* eventAttrib);
839 /* ------------------------------------------------------------------------- */
861 NVTX_DECLSPEC int NVTX_API nvtxRangePushA(const char* message);
862 NVTX_DECLSPEC int NVTX_API nvtxRangePushW(const wchar_t* message);
866 /* ------------------------------------------------------------------------- */
888 NVTX_DECLSPEC int NVTX_API nvtxDomainRangePop(nvtxDomainHandle_t domain);
891 /* ------------------------------------------------------------------------- */
912 NVTX_DECLSPEC int NVTX_API nvtxRangePop(void); /*END defgroup*/
917 /* ========================================================================= */
926 /* ------------------------------------------------------------------------- */
928 /* ------------------------------------------------------------------------- */
929 
930 /* ------------------------------------------------------------------------- */
937 #define NVTX_RESOURCE_MAKE_TYPE(CLASS, INDEX) ((((uint32_t)(NVTX_RESOURCE_CLASS_ ## CLASS))<<16)|((uint32_t)(INDEX)))
938 #define NVTX_RESOURCE_CLASS_GENERIC 1
939 
941 /* ------------------------------------------------------------------------- */
950 {
951  NVTX_RESOURCE_TYPE_UNKNOWN = 0,
952  NVTX_RESOURCE_TYPE_GENERIC_POINTER = NVTX_RESOURCE_MAKE_TYPE(GENERIC, 1),
953  NVTX_RESOURCE_TYPE_GENERIC_HANDLE = NVTX_RESOURCE_MAKE_TYPE(GENERIC, 2),
954  NVTX_RESOURCE_TYPE_GENERIC_THREAD_NATIVE = NVTX_RESOURCE_MAKE_TYPE(GENERIC, 3),
955  NVTX_RESOURCE_TYPE_GENERIC_THREAD_POSIX = NVTX_RESOURCE_MAKE_TYPE(GENERIC, 4)
957 
958 
959 
1036 {
1044  uint16_t version;
1045 
1052  uint16_t size;
1053 
1062  int32_t identifierType; /* values from enums following the pattern nvtxResource[name]Type_t */
1063 
1072  {
1073  const void* pValue;
1074  uint64_t ullValue;
1075  } identifier;
1076 
1084  int32_t messageType; /* nvtxMessageType_t */
1085 
1091 
1093 
1094 typedef struct nvtxResourceAttributes_v0 nvtxResourceAttributes_t;
1095 
1096 /* \cond SHOW_HIDDEN
1097 * \version \NVTX_VERSION_2
1098 */
1099 #define NVTX_RESOURCE_ATTRIB_STRUCT_SIZE ( (uint16_t)( sizeof(nvtxResourceAttributes_v0) ) )
1100 typedef struct nvtxResourceHandle* nvtxResourceHandle_t;
1105 /* ------------------------------------------------------------------------- */
1135 NVTX_DECLSPEC nvtxResourceHandle_t NVTX_API nvtxDomainResourceCreate(nvtxDomainHandle_t domain, nvtxResourceAttributes_t* attribs);
1138 /* ------------------------------------------------------------------------- */
1164 NVTX_DECLSPEC void NVTX_API nvtxDomainResourceDestroy(nvtxResourceHandle_t resource);
1170 /* ------------------------------------------------------------------------- */
1198 NVTX_DECLSPEC void NVTX_API nvtxDomainNameCategoryA(nvtxDomainHandle_t domain, uint32_t category, const char* name);
1199 NVTX_DECLSPEC void NVTX_API nvtxDomainNameCategoryW(nvtxDomainHandle_t domain, uint32_t category, const wchar_t* name);
1223 NVTX_DECLSPEC void NVTX_API nvtxNameCategoryA(uint32_t category, const char* name);
1224 NVTX_DECLSPEC void NVTX_API nvtxNameCategoryW(uint32_t category, const wchar_t* name);
1229 /* ------------------------------------------------------------------------- */
1290 NVTX_DECLSPEC void NVTX_API nvtxNameOsThreadA(uint32_t threadId, const char* name);
1291 NVTX_DECLSPEC void NVTX_API nvtxNameOsThreadW(uint32_t threadId, const wchar_t* name); /*END defgroup*/
1296 /* ========================================================================= */
1308 /* ------------------------------------------------------------------------- */
1339 NVTX_DECLSPEC nvtxStringHandle_t NVTX_API nvtxDomainRegisterStringA(nvtxDomainHandle_t domain, const char* string);
1340 NVTX_DECLSPEC nvtxStringHandle_t NVTX_API nvtxDomainRegisterStringW(nvtxDomainHandle_t domain, const wchar_t* string); /*END defgroup*/
1344 /* ========================================================================= */
1363 /* ------------------------------------------------------------------------- */
1401 NVTX_DECLSPEC nvtxDomainHandle_t NVTX_API nvtxDomainCreateA(const char* name);
1402 NVTX_DECLSPEC nvtxDomainHandle_t NVTX_API nvtxDomainCreateW(const wchar_t* name);
1405 /* ------------------------------------------------------------------------- */
1424 NVTX_DECLSPEC void NVTX_API nvtxDomainDestroy(nvtxDomainHandle_t domain); /*END defgroup*/
1429 /* ========================================================================= */
1432 #ifdef UNICODE
1433  #define nvtxMark nvtxMarkW
1434  #define nvtxRangeStart nvtxRangeStartW
1435  #define nvtxRangePush nvtxRangePushW
1436  #define nvtxNameCategory nvtxNameCategoryW
1437  #define nvtxNameOsThread nvtxNameOsThreadW
1438  /* NVTX_VERSION_2 */
1439  #define nvtxDomainCreate nvtxDomainCreateW
1440  #define nvtxDomainRegisterString nvtxDomainRegisterStringW
1441  #define nvtxDomainNameCategory nvtxDomainNameCategoryW
1442 #else
1443  #define nvtxMark nvtxMarkA
1444  #define nvtxRangeStart nvtxRangeStartA
1445  #define nvtxRangePush nvtxRangePushA
1446  #define nvtxNameCategory nvtxNameCategoryA
1447  #define nvtxNameOsThread nvtxNameOsThreadA
1448  /* NVTX_VERSION_2 */
1449  #define nvtxDomainCreate nvtxDomainCreateA
1450  #define nvtxDomainRegisterString nvtxDomainRegisterStringA
1451  #define nvtxDomainNameCategory nvtxDomainNameCategoryA
1452 #endif
1453 
1456 #ifdef __cplusplus
1457 } /* extern "C" */
1458 #endif /* __cplusplus */
1459 
1460 #define NVTX_IMPL_GUARD /* Ensure other headers cannot included directly */
1461 
1462 #include "nvtxDetail/nvtxTypes.h"
1463 
1464 #ifndef NVTX_NO_IMPL
1465 #include "nvtxDetail/nvtxImpl.h"
1466 #endif /*NVTX_NO_IMPL*/
1467 
1468 #undef NVTX_IMPL_GUARD
1469 
1470 #endif /* !defined(NVTX_VERSION) */
uint32_t category
ID of the category the event is assigned to.
Definition: nvToolsExt.h:458
uint16_t size
Size of the structure.
Definition: nvToolsExt.h:1052
int32_t identifierType
Identifier type specifies how to interpret the identifier field.
Definition: nvToolsExt.h:1062
NVTX_DECLSPEC void NVTX_API nvtxDomainMarkEx(nvtxDomainHandle_t domain, const nvtxEventAttributes_t *eventAttrib)
Marks an instantaneous event in the application.
int32_t messageType
Message type specified in this attribute structure.
Definition: nvToolsExt.h:1084
NVTX_DECLSPEC void NVTX_API nvtxMarkEx(const nvtxEventAttributes_t *eventAttrib)
Marks an instantaneous event in the application.
NVTX_DECLSPEC int NVTX_API nvtxDomainRangePop(nvtxDomainHandle_t domain)
Ends a nested thread range.
NVTX_DECLSPEC nvtxResourceHandle_t NVTX_API nvtxDomainResourceCreate(nvtxDomainHandle_t domain, nvtxResourceAttributes_t *attribs)
Create a resource object to track and associate data with OS and middleware objects.
uint16_t size
Size of the structure.
Definition: nvToolsExt.h:445
NVTX_DECLSPEC void NVTX_API nvtxDomainRangeEnd(nvtxDomainHandle_t domain, nvtxRangeId_t id)
Ends a process range.
NVTX_DECLSPEC nvtxStringHandle_t NVTX_API nvtxDomainRegisterStringA(nvtxDomainHandle_t domain, const char *string)
Register a string.
NVTX_DECLSPEC void NVTX_API nvtxDomainResourceDestroy(nvtxResourceHandle_t resource)
Destroy a resource object to track and associate data with OS and middleware objects.
NVTX_DECLSPEC int NVTX_API nvtxRangePop(void)
Ends a nested thread range.
nvtxResourceGenericType_t
Generic resource type for when a resource class is not available.
Definition: nvToolsExt.h:949
NVTX_DECLSPEC int NVTX_API nvtxDomainRangePushEx(nvtxDomainHandle_t domain, const nvtxEventAttributes_t *eventAttrib)
Starts a nested thread range.
NVTX_DECLSPEC nvtxDomainHandle_t NVTX_API nvtxDomainCreateA(const char *name)
Register a NVTX domain.
NVTX_DECLSPEC void NVTX_API nvtxInitialize(const void *reserved)
Force initialization (optional)
int32_t messageType
Message type specified in this attribute structure.
Definition: nvToolsExt.h:511
nvtxMessageType_t
Definition: nvToolsExt.h:282
NVTX_DECLSPEC void NVTX_API nvtxMarkA(const char *message)
Marks an instantaneous event in the application.
Payload assigned to this event.
Definition: nvToolsExt.h:493
uint16_t version
Version flag of the structure.
Definition: nvToolsExt.h:1044
uint32_t color
Color assigned to this event.
Definition: nvToolsExt.h:473
Identifier for the resource.
Definition: nvToolsExt.h:1071
int32_t payloadType
Payload type specified in this attribute structure.
Definition: nvToolsExt.h:483
uint16_t version
Version flag of the structure.
Definition: nvToolsExt.h:437
NVTX_DECLSPEC void NVTX_API nvtxDomainNameCategoryA(nvtxDomainHandle_t domain, uint32_t category, const char *name)
Annotate an NVTX category used within a domain.
NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartA(const char *message)
Starts a process range.
Resource Attribute Structure.
Definition: nvToolsExt.h:1035
NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartEx(const nvtxEventAttributes_t *eventAttrib)
Starts a process range.
NVTX_DECLSPEC int NVTX_API nvtxRangePushEx(const nvtxEventAttributes_t *eventAttrib)
Starts a nested thread range.
int32_t colorType
Color type specified in this attribute structure.
Definition: nvToolsExt.h:467
NVTX_DECLSPEC void NVTX_API nvtxNameCategoryA(uint32_t category, const char *name)
Annotate an NVTX category.
NVTX_DECLSPEC void NVTX_API nvtxRangeEnd(nvtxRangeId_t id)
Ends a process range.
nvtxColorType_t
Definition: nvToolsExt.h:273
nvtxPayloadType_t
Definition: nvToolsExt.h:339
Event Attribute Structure.
Definition: nvToolsExt.h:428
nvtxMessageValue_t message
Message assigned to this attribute structure.
Definition: nvToolsExt.h:1090
NVTX_DECLSPEC void NVTX_API nvtxNameOsThreadA(uint32_t threadId, const char *name)
Annotate an OS thread.
NVTX_DECLSPEC int NVTX_API nvtxRangePushA(const char *message)
Starts a nested thread range.
NVTX_DECLSPEC void NVTX_API nvtxDomainDestroy(nvtxDomainHandle_t domain)
Unregister a NVTX domain.
nvtxMessageValue_t message
Message assigned to this attribute structure.
Definition: nvToolsExt.h:517
NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxDomainRangeStartEx(nvtxDomainHandle_t domain, const nvtxEventAttributes_t *eventAttrib)
Starts a process range in a domain.