API Reference :: NVIDIA Tools Extension (NVTX) Documentation

2. Modules

Here is a list of all modules:

2.1. General

Enumerations

enum nvtxColorType_t
enum nvtxMessageType_t

Enumerations

enum nvtxColorType_t

--------------------------------------------------------------------------- Color Types -------------------------------------------------------------------------

Values

NVTX_COLOR_UNKNOWN = 0: Color attribute is unused.
NVTX_COLOR_ARGB = 1: An ARGB color is provided.

enum nvtxMessageType_t

--------------------------------------------------------------------------- Message Types -------------------------------------------------------------------------

Values

NVTX_MESSAGE_UNKNOWN = 0: Message payload is unused.
NVTX_MESSAGE_TYPE_ASCII = 1: A character sequence is used as payload.
NVTX_MESSAGE_TYPE_UNICODE = 2: A wide character sequence is used as payload.
NVTX_MESSAGE_TYPE_REGISTERED = 3: A unique string handle that was registered with nvtxDomainRegisterStringA() or nvtxDomainRegisterStringW().

2.2. Event Attributes

Classes

struct nvtxEventAttributes_v2

Enumerations

enum nvtxPayloadType_t

Enumerations

enum nvtxPayloadType_t

--------------------------------------------------------------------------- Payload Types -------------------------------------------------------------------------

Values

NVTX_PAYLOAD_UNKNOWN = 0: Color payload is unused.
NVTX_PAYLOAD_TYPE_UNSIGNED_INT64 = 1: A 64 bit unsigned integer value is used as payload.
NVTX_PAYLOAD_TYPE_INT64 = 2: A 64 bit signed integer value is used as payload.
NVTX_PAYLOAD_TYPE_DOUBLE = 3: A 64 bit floating point value is used as payload.
NVTX_PAYLOAD_TYPE_UNSIGNED_INT32 = 4: A 32 bit floating point value is used as payload.
NVTX_PAYLOAD_TYPE_INT32 = 5: A 32 bit floating point value is used as payload.
NVTX_PAYLOAD_TYPE_FLOAT = 6: A 32 bit floating point value is used as payload.

2.3. Markers and Ranges

See Markers and Ranges for more details

Member Functions

NVTX_DECLSPEC void NVTX_API MARKERS_AND_RANGES::nvtxDomainMarkEx ( nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib ) [inherited]

Marks an instantaneous event in the application.

Parameters

domain: - The domain of scoping the category.
eventAttrib: - The event attribute structure defining the marker's attribute types and attribute values.

Description

nvtxDomainMarkEx(NULL, event) is equivalent to calling nvtxMarkEx(event).

See also:

nvtxMarkEx

NVTX_DECLSPEC void NVTX_API MARKERS_AND_RANGES::nvtxDomainRangeEnd ( nvtxDomainHandle_t domain, nvtxRangeId_t id ) [inherited]

Ends a process range.

Parameters

domain: - The domain
id: - The correlation ID returned from a nvtxRangeStart call.

Description

Example:

‎ nvtxDomainHandle_t domain = nvtxDomainCreateA("my domain");
       nvtxEventAttributes_t eventAttrib = {0};
       eventAttrib.version = NVTX_VERSION;
       eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
       eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
       eventAttrib.message.ascii = "my range";
       nvtxRangeId_t rangeId = nvtxDomainRangeStartEx(&eventAttrib);
       // ...
       nvtxDomainRangeEnd(rangeId);

See also:

nvtxDomainRangeStartEx

NVTX_DECLSPEC int NVTX_API MARKERS_AND_RANGES::nvtxDomainRangePop ( nvtxDomainHandle_t domain ) [inherited]

Ends a nested thread range.

Returns

The level of the range being ended. If an error occurs a negative value is returned on the current thread.

Description

Example:

‎ nvtxDomainHandle_t domain = nvtxDomainCreate("example library");
       nvtxDomainRangePushA(domain, "Level 0");
       nvtxDomainRangePushW(domain, L"Level 1");
       nvtxDomainRangePop(domain);
       nvtxDomainRangePop(domain);

See also:

nvtxRangePushEx nvtxRangePushA nvtxRangePushW

NVTX_DECLSPEC int NVTX_API MARKERS_AND_RANGES::nvtxDomainRangePushEx ( nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib ) [inherited]

Starts a nested thread range.

Parameters

domain: - The domain of scoping.
eventAttrib: - The event attribute structure defining the range's attribute types and attribute values.

Returns

The 0 based level of range being started. This value is scoped to the domain. If an error occurs, a negative value is returned.

Description

Example:

‎ nvtxDomainHandle_t domain = nvtxDomainCreateA("example domain");
       nvtxEventAttributes_t eventAttrib = {0};
       eventAttrib.version = NVTX_VERSION;
       eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
       eventAttrib.colorType = NVTX_COLOR_ARGB;
       eventAttrib.color = 0xFFFF0000;
       eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
       eventAttrib.message.ascii = "Level 0";
       nvtxDomainRangePushEx(domain, &eventAttrib);
      
       // Re-use eventAttrib
       eventAttrib.messageType = NVTX_MESSAGE_TYPE_UNICODE;
       eventAttrib.message.unicode = L"Level 1";
       nvtxDomainRangePushEx(domain, &eventAttrib);
      
       nvtxDomainRangePop(domain); //level 1
       nvtxDomainRangePop(domain); //level 0

See also:

nvtxDomainRangePop

NVTX_DECLSPEC nvtxRangeId_t NVTX_API MARKERS_AND_RANGES::nvtxDomainRangeStartEx ( nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib ) [inherited]

Starts a process range in a domain.

Parameters

domain: - The domain of scoping the category.
eventAttrib: - The event attribute structure defining the range's attribute types and attribute values.

Returns

The unique ID used to correlate a pair of Start and End events.

Description

Example:

‎ nvtxDomainHandle_t domain = nvtxDomainCreateA("my domain");
       nvtxEventAttributes_t eventAttrib = {0};
       eventAttrib.version = NVTX_VERSION;
       eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
       eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
       eventAttrib.message.ascii = "my range";
       nvtxRangeId_t rangeId = nvtxDomainRangeStartEx(&eventAttrib);
       // ...
       nvtxDomainRangeEnd(rangeId);

See also:

nvtxDomainRangeEnd

NVTX_DECLSPEC void NVTX_API MARKERS_AND_RANGES::nvtxMarkA ( const char* message ) [inherited]

Marks an instantaneous event in the application.

Parameters

message: - The message associated to this marker event.

Description

A marker created using nvtxMarkA or nvtxMarkW contains only a text message.

Example:

‎ nvtxMarkA("Example nvtxMarkA");
       nvtxMarkW(L"Example nvtxMarkW");

See also:

nvtxDomainMarkEx nvtxMarkEx

NVTX_DECLSPEC void NVTX_API MARKERS_AND_RANGES::nvtxMarkEx ( const nvtxEventAttributes_t* eventAttrib ) [inherited]

Marks an instantaneous event in the application.

Parameters

eventAttrib: - The event attribute structure defining the marker's attribute types and attribute values.

Description

A marker can contain a text message or specify additional information using the event attributes structure. These attributes include a text message, color, category, and a payload. Each of the attributes is optional and can only be sent out using the nvtxMarkEx function. If nvtxMarkA or nvtxMarkW are used to specify the marker or if an attribute is unspecified then a default value will be used.

Example:

‎ // zero the structure
       nvtxEventAttributes_t eventAttrib = {0};
       // set the version and the size information
       eventAttrib.version = NVTX_VERSION;
       eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
       // configure the attributes.  0 is the default for all attributes.
       eventAttrib.colorType = NVTX_COLOR_ARGB;
       eventAttrib.color = 0xFF880000;
       eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
       eventAttrib.message.ascii = "Example nvtxMarkEx";
       nvtxMarkEx(&eventAttrib);

See also:

nvtxDomainMarkEx

NVTX_DECLSPEC void NVTX_API MARKERS_AND_RANGES::nvtxRangeEnd ( nvtxRangeId_t id ) [inherited]

Ends a process range.

Parameters

id: - The correlation ID returned from an nvtxRangeStart call.

Description

NVTX_DECLSPEC int NVTX_API MARKERS_AND_RANGES::nvtxRangePop ( void ) [inherited]

Ends a nested thread range.

Returns

The level of the range being ended. If an error occurs a negative value is returned on the current thread.

Description

Example:

‎ nvtxRangePushA("Level 0");
       nvtxRangePushW(L"Level 1");
       nvtxRangePop();
       nvtxRangePop();

See also:

nvtxRangePushEx nvtxRangePushA nvtxRangePushW

NVTX_DECLSPEC int NVTX_API MARKERS_AND_RANGES::nvtxRangePushA ( const char* message ) [inherited]

Starts a nested thread range.

Parameters

message: - The event message associated to this range event.

Returns

The 0 based level of range being started. If an error occurs a negative value is returned.

Description

Example:

‎ nvtxRangePushA("Level 0");
       nvtxRangePushW(L"Level 1");
       nvtxRangePop();
       nvtxRangePop();

See also:

nvtxDomainRangePushEx nvtxRangePop

NVTX_DECLSPEC int NVTX_API MARKERS_AND_RANGES::nvtxRangePushEx ( const nvtxEventAttributes_t* eventAttrib ) [inherited]

Starts a nested thread range.

Parameters

eventAttrib: - The event attribute structure defining the range's attribute types and attribute values.

Returns

The 0 based level of range being started. This level is per domain. If an error occurs a negative value is returned.

Description

Example:

‎ nvtxEventAttributes_t eventAttrib = {0};
       eventAttrib.version = NVTX_VERSION;
       eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
       eventAttrib.colorType = NVTX_COLOR_ARGB;
       eventAttrib.color = 0xFFFF0000;
       eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
       eventAttrib.message.ascii = "Level 0";
       nvtxRangePushEx(&eventAttrib);
      
       // Re-use eventAttrib
       eventAttrib.messageType = NVTX_MESSAGE_TYPE_UNICODE;
       eventAttrib.message.unicode = L"Level 1";
       nvtxRangePushEx(&eventAttrib);
      
       nvtxRangePop();
       nvtxRangePop();

See also:

nvtxDomainRangePushEx nvtxRangePop

NVTX_DECLSPEC nvtxRangeId_t NVTX_API MARKERS_AND_RANGES::nvtxRangeStartA ( const char* message ) [inherited]

Starts a process range.

Parameters

message: - The event message associated to this range event.

Returns

The unique ID used to correlate a pair of Start and End events.

Description

Example:

‎ nvtxRangeId_t r1 = nvtxRangeStartA("Range 1");
       nvtxRangeId_t r2 = nvtxRangeStartW(L"Range 2");
       nvtxRangeEnd(r1);
       nvtxRangeEnd(r2);

NVTX_DECLSPEC nvtxRangeId_t NVTX_API MARKERS_AND_RANGES::nvtxRangeStartEx ( const nvtxEventAttributes_t* eventAttrib ) [inherited]

Starts a process range.

Parameters

eventAttrib: - The event attribute structure defining the range's attribute types and attribute values.

Returns

The unique ID used to correlate a pair of Start and End events.

Description

Example:

‎ nvtxEventAttributes_t eventAttrib = {0};
       eventAttrib.version = NVTX_VERSION;
       eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
       eventAttrib.category = 3;
       eventAttrib.colorType = NVTX_COLOR_ARGB;
       eventAttrib.color = 0xFF0088FF;
       eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
       eventAttrib.message.ascii = "Example Range";
       nvtxRangeId_t rangeId = nvtxRangeStartEx(&eventAttrib);
       // ...
       nvtxRangeEnd(rangeId);

See also:

nvtxRangeEnd nvtxDomainRangeStartEx

2.4. Resource Naming

See Resource Naming for more details

CUDA Resource Naming

This section covers the API functions that allow to annotate CUDA resources with user-provided names.

CUDA Runtime Resource Naming

This section covers the API functions that allow to annotate CUDA resources with user-provided names.

OpenCL Resource Naming

This section covers the API functions that allow to annotate OpenCL resources with user-provided names.

Classes

struct nvtxResourceAttributes_v0

Enumerations

enum RESOURCE_NAMING::nvtxResourceCUDARTType_t [inherited]

Values

NVTX_RESOURCE_TYPE_CUDART_DEVICE = NVTX_RESOURCE_MAKE_TYPE(CUDART,0)
NVTX_RESOURCE_TYPE_CUDART_STREAM = NVTX_RESOURCE_MAKE_TYPE(CUDART,1)
NVTX_RESOURCE_TYPE_CUDART_EVENT = NVTX_RESOURCE_MAKE_TYPE(CUDART,2)

enum RESOURCE_NAMING::nvtxResourceCUDAType_t [inherited]

Values

NVTX_RESOURCE_TYPE_CUDA_DEVICE = NVTX_RESOURCE_MAKE_TYPE(CUDA,1)
NVTX_RESOURCE_TYPE_CUDA_CONTEXT = NVTX_RESOURCE_MAKE_TYPE(CUDA,2)
NVTX_RESOURCE_TYPE_CUDA_STREAM = NVTX_RESOURCE_MAKE_TYPE(CUDA,3)
NVTX_RESOURCE_TYPE_CUDA_EVENT = NVTX_RESOURCE_MAKE_TYPE(CUDA,4)

enum RESOURCE_NAMING::nvtxResourceGenericType_t [inherited]

See also:

nvtxDomainResourceCreate

Values

NVTX_RESOURCE_TYPE_UNKNOWN = 0
NVTX_RESOURCE_TYPE_GENERIC_POINTER = NVTX_RESOURCE_MAKE_TYPE(GENERIC,1): Generic pointer assumed to have no collisions with other pointers.
NVTX_RESOURCE_TYPE_GENERIC_HANDLE = NVTX_RESOURCE_MAKE_TYPE(GENERIC,2): Generic handle assumed to have no collisions with other handles.
NVTX_RESOURCE_TYPE_GENERIC_THREAD_NATIVE = NVTX_RESOURCE_MAKE_TYPE(GENERIC,3): OS native thread identifier.
NVTX_RESOURCE_TYPE_GENERIC_THREAD_POSIX = NVTX_RESOURCE_MAKE_TYPE(GENERIC,4): POSIX pthread identifier.

enum RESOURCE_NAMING::nvtxResourceOpenCLType_t [inherited]

Values

NVTX_RESOURCE_TYPE_OPENCL_DEVICE = NVTX_RESOURCE_MAKE_TYPE(OPENCL,1)
NVTX_RESOURCE_TYPE_OPENCL_CONTEXT = NVTX_RESOURCE_MAKE_TYPE(OPENCL,2)
NVTX_RESOURCE_TYPE_OPENCL_COMMANDQUEUE = NVTX_RESOURCE_MAKE_TYPE(OPENCL,3)
NVTX_RESOURCE_TYPE_OPENCL_MEMOBJECT = NVTX_RESOURCE_MAKE_TYPE(OPENCL,4)
NVTX_RESOURCE_TYPE_OPENCL_SAMPLER = NVTX_RESOURCE_MAKE_TYPE(OPENCL,5)
NVTX_RESOURCE_TYPE_OPENCL_PROGRAM = NVTX_RESOURCE_MAKE_TYPE(OPENCL,6)
NVTX_RESOURCE_TYPE_OPENCL_EVENT = NVTX_RESOURCE_MAKE_TYPE(OPENCL,7)

Member Functions

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxDomainNameCategoryA ( nvtxDomainHandle_t domain, uint32_t category, const char* name ) [inherited]

Annotate an NVTX category used within a domain.

Parameters

domain: - The domain of scoping the category.
category: - The category ID to name.
name: - The name of the category.

Description

Categories are used to group sets of events. Each category is identified through a unique ID and that ID is passed into any of the marker/range events to assign that event to a specific category. The nvtxDomainNameCategory function calls allow the user to assign a name to a category ID that is specific to the domain.

nvtxDomainNameCategory(NULL, category, name) is equivalent to calling nvtxNameCategory(category, name).

Example:

‎ nvtxDomainHandle_t domain = nvtxDomainCreateA("example");
       nvtxDomainNameCategoryA(domain, 1, "Memory Allocation");
       nvtxDomainNameCategoryW(domain, 2, L"Memory Transfer");

NVTX_DECLSPEC nvtxResourceHandle_t NVTX_API RESOURCE_NAMING::nvtxDomainResourceCreate ( nvtxDomainHandle_t domain, nvtxResourceAttributes_t* attribs ) [inherited]

Create a resource object to track and associate data with OS and middleware objects.

Parameters

domain: - Domain to own the resource object
attribs: - Attributes to be associated with the resource

Returns

A handle that represents the newly created resource object.

Description

Allows users to associate an API handle or pointer with a user-provided name.

Example:

‎ nvtxDomainHandle_t domain = nvtxDomainCreateA("example domain");
       nvtxResourceAttributes_t attribs = {0};
       attribs.version = NVTX_VERSION;
       attribs.size = NVTX_RESOURCE_ATTRIB_STRUCT_SIZE;
       attribs.identifierType = NVTX_RESOURCE_TYPE_GENERIC_POINTER;
       attribs.identifier.pValue = (const void*)pMutex;
       attribs.messageType = NVTX_MESSAGE_TYPE_ASCII;
       attribs.message.ascii = "Single thread access to database.";
       nvtxResourceHandle_t handle = nvtxDomainResourceCreate(domain, attribs);

See also:

nvtxResourceAttributes_t nvtxDomainResourceDestroy

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxDomainResourceDestroy ( nvtxResourceHandle_t resource ) [inherited]

Destroy a resource object to track and associate data with OS and middleware objects.

Parameters

resource: - Handle to the resource in which to operate.

Description

Allows users to associate an API handle or pointer with a user-provided name.

Example:

‎ nvtxDomainHandle_t domain = nvtxDomainCreateA("example domain");
       nvtxResourceAttributes_t attribs = {0};
       attribs.version = NVTX_VERSION;
       attribs.size = NVTX_RESOURCE_ATTRIB_STRUCT_SIZE;
       attribs.identifierType = NVTX_RESOURCE_TYPE_GENERIC_POINTER;
       attribs.identifier.pValue = (const void*)pMutex;
       attribs.messageType = NVTX_MESSAGE_TYPE_ASCII;
       attribs.message.ascii = "Single thread access to database.";
       nvtxResourceHandle_t handle = nvtxDomainResourceCreate(domain, attribs);
       nvtxDomainResourceDestroy(handle);

See also:

nvtxDomainResourceCreate

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameCategoryA ( uint32_t category, const char* name ) [inherited]

Annotate an NVTX category.

Parameters

category: - The category ID to name.
name: - The name of the category.

Description

Categories are used to group sets of events. Each category is identified through a unique ID and that ID is passed into any of the marker/range events to assign that event to a specific category. The nvtxNameCategory function calls allow the user to assign a name to a category ID.

Example:

‎ nvtxNameCategory(1, "Memory Allocation");
       nvtxNameCategory(2, "Memory Transfer");
       nvtxNameCategory(3, "Memory Object Lifetime");

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameClCommandQueueA ( cl_command_queue command_queue, const char* name ) [inherited]

Annotates an OpenCL command queue.

Parameters

command_queue: - The handle of the OpenCL command queue to name.
name: - The name of the OpenCL command queue.

Description

Allows to associate an OpenCL command queue with a user-provided name.

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameClContextA ( cl_context context, const char* name ) [inherited]

Annotates an OpenCL context.

Parameters

context: - The handle of the OpenCL context to name.
name: - The name of the OpenCL context.

Description

Allows to associate an OpenCL context with a user-provided name.

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameClDeviceA ( cl_device_id device, const char* name ) [inherited]

Annotates an OpenCL device.

Parameters

device: - The handle of the OpenCL device to name.
name: - The name of the OpenCL device.

Description

Allows to associate an OpenCL device with a user-provided name.

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameClEventA ( cl_event evnt, const char* name ) [inherited]

Annotates an OpenCL event.

Parameters

evnt: - The handle of the OpenCL event to name.
name: - The name of the OpenCL event.

Description

Allows to associate an OpenCL event with a user-provided name.

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameClMemObjectA ( cl_mem memobj, const char* name ) [inherited]

Annotates an OpenCL memory object.

Parameters

memobj: - The handle of the OpenCL memory object to name.
name: - The name of the OpenCL memory object.

Description

Allows to associate an OpenCL memory object with a user-provided name.

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameClProgramA ( cl_program program, const char* name ) [inherited]

Annotates an OpenCL program.

Parameters

program: - The handle of the OpenCL program to name.
name: - The name of the OpenCL program.

Description

Allows to associate an OpenCL program with a user-provided name.

‎ cpProgram = clCreateProgramWithSource(cxGPUContext, 1,
           (const char **) &cSourceCL, &program_length, &ciErrNum);
       shrCheckErrorEX(ciErrNum, CL_SUCCESS, pCleanup);
       nvtxNameClProgram(cpProgram, L"PROGRAM_NAME");

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameClSamplerA ( cl_sampler sampler, const char* name ) [inherited]

Annotates an OpenCL sampler.

Parameters

sampler: - The handle of the OpenCL sampler to name.
name: - The name of the OpenCL sampler.

Description

Allows to associate an OpenCL sampler with a user-provided name.

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameCuContextA ( CUcontext context, const char* name ) [inherited]

Annotates a CUDA context.

Parameters

context: - The handle of the CUDA context to name.
name: - The name of the CUDA context.

Description

Allows the user to associate a CUDA context with a user-provided name.

Example:

‎ CUresult status = cuCtxCreate( &cuContext, 0, cuDevice );
       if ( CUDA_SUCCESS != status )
           goto Error;
       nvtxNameCuContext(cuContext, "CTX_NAME");

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameCuDeviceA ( CUdevice device, const char* name ) [inherited]

Annotates a CUDA device.

Parameters

device: - The handle of the CUDA device to name.
name: - The name of the CUDA device.

Description

Allows the user to associate a CUDA device with a user-provided name.

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameCuEventA ( CUevent event, const char* name ) [inherited]

Annotates a CUDA event.

Parameters

event: - The handle of the CUDA event to name.
name: - The name of the CUDA event.

Description

Allows the user to associate a CUDA event with a user-provided name.

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameCuStreamA ( CUstream stream, const char* name ) [inherited]

Annotates a CUDA stream.

Parameters

stream: - The handle of the CUDA stream to name.
name: - The name of the CUDA stream.

Description

Allows the user to associate a CUDA stream with a user-provided name.

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameCudaDeviceA ( int device, const char* name ) [inherited]

Annotates a CUDA device.

Parameters

device: - The id of the CUDA device to name.
name: - The name of the CUDA device.

Description

Allows the user to associate a CUDA device with a user-provided name.

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameCudaEventA ( cudaEvent_t event, const char* name ) [inherited]

Annotates a CUDA event.

Parameters

event: - The handle of the CUDA event to name.
name: - The name of the CUDA event.

Description

Allows the user to associate a CUDA event with a user-provided name.

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameCudaStreamA ( cudaStream_t stream, const char* name ) [inherited]

Annotates a CUDA stream.

Parameters

stream: - The handle of the CUDA stream to name.
name: - The name of the CUDA stream.

Description

Allows the user to associate a CUDA stream with a user-provided name.

NVTX_DECLSPEC void NVTX_API RESOURCE_NAMING::nvtxNameOsThreadA ( uint32_t threadId, const char* name ) [inherited]

Annotate an OS thread.

Parameters

threadId: - The ID of the thread to name.
name: - The name of the thread.

Description

Allows the user to name an active thread of the current process. If an invalid thread ID is provided or a thread ID from a different process is used the behavior of the tool is implementation dependent.

Tools expect thread ID to be a number that uniquely identifies the thread at the time of the call. Note that a thread's ID can be reused after it is destroyed. Tools may choose how to handle aliasing of thread IDs.

POSIX pthread_t type returned by pthread_self() may not comply with these expectations. Please use OS-specific thread ID instead of pthread_t.

The thread name is associated to the default domain. To support domains use resource objects via nvtxDomainResourceCreate.

Examples:

MS Windows:

‎ #include <windows.h>
       nvtxNameOsThread(GetCurrentThreadId(), "Current thread");
       nvtxNameOsThread(GetThreadId(SomeThreadHandle), "Other thread");

Android:

‎ #include <unistd.h>
       nvtxNameOsThreadA(gettid(), "Current thread");
       nvtxNameOsThreadA(getpid(), "Main thread");

Linux:

‎ #include <sys/syscall.h>
       nvtxNameOsThreadA(syscall(SYS_gettid), "Current thread");

‎ #include <unistd.h>
       nvtxNameOsThreadA(getpid(), "Main thread");

OS X:

‎ #include <sys/syscall.h>
       nvtxNameOsThreadA(syscall(SYS_thread_selfid), "Current thread");

‎ #include <pthread.h>
       __uint64_t id;
       pthread_threadid_np(pthread_self(), &id);
       nvtxNameOsThreadA(id, "Current thread");
       pthread_threadid_np(somePThreadId, &id);
       nvtxNameOsThreadA(id, "Other thread");

2.5. String Registration

Registered strings are intended to increase performance by lowering instrumentation overhead. String may be registered once and the handle may be passed in place of a string where an the APIs may allow.

See String Registration for more details

Member Functions

NVTX_DECLSPEC nvtxStringHandle_t NVTX_API STRING_REGISTRATION::nvtxDomainRegisterStringA ( nvtxDomainHandle_t domain, const char* string ) [inherited]

Parameters

domain: - Domain handle. If NULL then the global domain is used.
string: - A unique pointer to a sequence of characters.

Returns

A handle representing the registered string.

Description

Registers an immutable string with NVTX. Once registered the pointer used to register the domain name can be used in nvtxEventAttributes_t MESSAGE_FIELD. This allows NVTX implementation to skip copying the contents of the message on each event invocation.

String registration is an optimization. It is recommended to use string registration if the string will be passed to an event many times.

String are not unregistered, except that by unregistering the entire domain

Example:

‎ nvtxDomainCreateA("com.nvidia.nvtx.example");
       nvtxStringHandle_t message = nvtxDomainRegisterStringA(domain, "registered string");
       nvtxEventAttributes_t eventAttrib = {0};
       eventAttrib.version = NVTX_VERSION;
       eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
       eventAttrib.messageType = NVTX_MESSAGE_TYPE_REGISTERED;
       eventAttrib.message.registered = message;

2.6. Domains

Domains are used to group events to a developer defined scope. Middleware vendors may also scope their own events to avoid collisions with the the application developer's events, so that the application developer may inspect both parts and easily differentiate or filter them. By default all events are scoped to a global domain where NULL is provided or when using APIs provided b versions of NVTX below v2

Domains are intended to be typically long lived objects with the intention of logically separating events of large modules from each other such as middleware libraries from each other and the main application.

See Domains for more details

Member Functions

NVTX_DECLSPEC nvtxDomainHandle_t NVTX_API DOMAINS::nvtxDomainCreateA ( const char* name ) [inherited]

Parameters

name: - A unique string representing the domain.

Returns

A handle representing the domain.

Description

Domains are used to scope annotations. All NVTX_VERSION_0 and NVTX_VERSION_1 annotations are scoped to the global domain. The function nvtxDomainCreate creates a new named domain.

Each domain maintains its own nvtxRangePush and nvtxRangePop stack.

Example:

‎ nvtxDomainHandle_t domain = nvtxDomainCreateA("com.nvidia.nvtx.example");
      
       nvtxMarkA("nvtxMarkA to global domain");
      
       nvtxEventAttributes_t eventAttrib1 = {0};
       eventAttrib1.version = NVTX_VERSION;
       eventAttrib1.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
       eventAttrib1.message.ascii = "nvtxDomainMarkEx to global domain";
       nvtxDomainMarkEx(NULL, &eventAttrib1);
      
       nvtxEventAttributes_t eventAttrib2 = {0};
       eventAttrib2.version = NVTX_VERSION;
       eventAttrib2.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
       eventAttrib2.message.ascii = "nvtxDomainMarkEx to com.nvidia.nvtx.example";
       nvtxDomainMarkEx(domain, &eventAttrib2);
       nvtxDomainDestroy(domain);

See also:

nvtxDomainDestroy

NVTX_DECLSPEC void NVTX_API DOMAINS::nvtxDomainDestroy ( nvtxDomainHandle_t domain ) [inherited]

Unregister a NVTX domain.

Parameters

domain: - the domain handle

Description

Unregisters the domain handle and frees all domain specific resources.

Example:

‎ nvtxDomainHandle_t domain = nvtxDomainCreateA("com.nvidia.nvtx.example");
       nvtxDomainDestroy(domain);

See also:

nvtxDomainCreateA nvtxDomainCreateW

2.7. Synchronization

See page Synchronization.

Classes

struct nvtxSyncUserAttributes_v0: User Defined Synchronization Object Attributes Structure.

Typedefs

typedef enumnvtxResourceSyncLinuxType_t nvtxResourceSyncAndroidType_t: Resource type values for Android come from Linux.
typedef nvtxSyncUser * nvtxSyncUser_t: User Defined Synchronization Object Handle .

Enumerations

enum nvtxResourceSyncLinuxType_t: Resource type values for Linux and Linux derived OSs such as Android.
enum nvtxResourceSyncPosixThreadType_t: Resource type values for OSs with POSIX Thread API support.
enum nvtxResourceSyncWindowsType_t: Resource type values for Windows OSs.

Functions

NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserAcquireFailed ( nvtxSyncUser_t handle ): Signal to tools of failure in acquiring a user defined synchronization object This should be called after nvtxDomainSyncUserAcquireStart.
NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserAcquireStart ( nvtxSyncUser_t handle ): Signal to tools that an attempt to acquire a user defined synchronization object.
NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserAcquireSuccess ( nvtxSyncUser_t handle ): Signal to tools of success in acquiring a user defined synchronization object This should be called after nvtxDomainSyncUserAcquireStart.
nvtxSyncUser_t nvtxDomainSyncUserCreate ( nvtxDomainHandle_t domain, const nvtxSyncUserAttributes_t* attribs ): Create a user defined synchronization object This is used to track non-OS synchronization working with spinlocks and atomics.
NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserDestroy ( nvtxSyncUser_t handle ): Destroy a user defined synchronization object This is used to track non-OS synchronization working with spinlocks and atomics.
NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserReleasing ( nvtxSyncUser_t handle ): Signal to tools of releasing a reservation on user defined synchronization object This should be called after nvtxDomainSyncUserAcquireSuccess.

Typedefs

typedef enumnvtxResourceSyncLinuxType_t nvtxResourceSyncAndroidType_t: Resource type values for Android come from Linux.

See also:

nvtxResourceSyncLinuxType_t nvtxResourceSyncPosixThreadType_t
typedef nvtxSyncUser * nvtxSyncUser_t: User Defined Synchronization Object Handle .

This structure is opaque to the user and is used as a handle to reference a user defined syncrhonization object. The tools will return a pointer through the API for the application to hold on it's behalf to reference the string in the future.

Enumerations

enum nvtxResourceSyncLinuxType_t

See also:

nvtxResourceSyncPosixThreadType_t

Values

NVTX_RESOURCE_TYPE_SYNC_LINUX_MUTEX = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS,1)
NVTX_RESOURCE_TYPE_SYNC_LINUX_FUTEX = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS,2)
NVTX_RESOURCE_TYPE_SYNC_LINUX_SEMAPHORE = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS,3)
NVTX_RESOURCE_TYPE_SYNC_LINUX_COMPLETION = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS,4)
NVTX_RESOURCE_TYPE_SYNC_LINUX_SPINLOCK = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS,5)
NVTX_RESOURCE_TYPE_SYNC_LINUX_SEQLOCK = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS,6)
NVTX_RESOURCE_TYPE_SYNC_LINUX_RCU = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS,7)

enum nvtxResourceSyncPosixThreadType_t

Values

NVTX_RESOURCE_TYPE_SYNC_PTHREAD_MUTEX = NVTX_RESOURCE_MAKE_TYPE(SYNC_PTHREAD,1)
NVTX_RESOURCE_TYPE_SYNC_PTHREAD_CONDITION = NVTX_RESOURCE_MAKE_TYPE(SYNC_PTHREAD,2)
NVTX_RESOURCE_TYPE_SYNC_PTHREAD_RWLOCK = NVTX_RESOURCE_MAKE_TYPE(SYNC_PTHREAD,3)
NVTX_RESOURCE_TYPE_SYNC_PTHREAD_BARRIER = NVTX_RESOURCE_MAKE_TYPE(SYNC_PTHREAD,4)
NVTX_RESOURCE_TYPE_SYNC_PTHREAD_SPINLOCK = NVTX_RESOURCE_MAKE_TYPE(SYNC_PTHREAD,5)
NVTX_RESOURCE_TYPE_SYNC_PTHREAD_ONCE = NVTX_RESOURCE_MAKE_TYPE(SYNC_PTHREAD,6)

enum nvtxResourceSyncWindowsType_t

Values

NVTX_RESOURCE_TYPE_SYNC_WINDOWS_MUTEX = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS,1)
NVTX_RESOURCE_TYPE_SYNC_WINDOWS_SEMAPHORE = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS,2)
NVTX_RESOURCE_TYPE_SYNC_WINDOWS_EVENT = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS,3)
NVTX_RESOURCE_TYPE_SYNC_WINDOWS_CRITICAL_SECTION = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS,4)
NVTX_RESOURCE_TYPE_SYNC_WINDOWS_SRWLOCK = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS,5)

Functions

NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserAcquireFailed ( nvtxSyncUser_t handle )

Signal to tools of failure in acquiring a user defined synchronization object This should be called after nvtxDomainSyncUserAcquireStart.

Parameters

handle: - A handle to the object to operate on.

Description

NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserAcquireStart ( nvtxSyncUser_t handle )

Signal to tools that an attempt to acquire a user defined synchronization object.

Parameters

handle: - A handle to the object to operate on.

Description

NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserAcquireSuccess ( nvtxSyncUser_t handle )

Signal to tools of success in acquiring a user defined synchronization object This should be called after nvtxDomainSyncUserAcquireStart.

Parameters

handle: - A handle to the object to operate on.

Description

nvtxSyncUser_t nvtxDomainSyncUserCreate ( nvtxDomainHandle_t domain, const nvtxSyncUserAttributes_t* attribs )

Create a user defined synchronization object This is used to track non-OS synchronization working with spinlocks and atomics.

Parameters

domain: - Domain to own the resource
attribs: - A structure to assign multiple attributes to the object.

Returns

A handle that represents the newly created user defined synchronization object.

Description

NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserDestroy ( nvtxSyncUser_t handle )

Destroy a user defined synchronization object This is used to track non-OS synchronization working with spinlocks and atomics.

Parameters

handle: - A handle to the object to operate on.

Description

NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserReleasing ( nvtxSyncUser_t handle )

Signal to tools of releasing a reservation on user defined synchronization object This should be called after nvtxDomainSyncUserAcquireSuccess.

Parameters

handle: - A handle to the object to operate on.