Data Structures
struct	nvtxResourceAttributes_t
	Resource Attribute Structure. . More...

Functions for Generic Resource Naming
enum	nvtxResourceGenericType_t { NVTX_RESOURCE_TYPE_UNKNOWN = 0 , NVTX_RESOURCE_TYPE_GENERIC_POINTER = NVTX_RESOURCE_MAKE_TYPE(GENERIC, 1) , NVTX_RESOURCE_TYPE_GENERIC_HANDLE = NVTX_RESOURCE_MAKE_TYPE(GENERIC, 2) , NVTX_RESOURCE_TYPE_GENERIC_THREAD_NATIVE = NVTX_RESOURCE_MAKE_TYPE(GENERIC, 3) , NVTX_RESOURCE_TYPE_GENERIC_THREAD_POSIX = NVTX_RESOURCE_MAKE_TYPE(GENERIC, 4) }
	Generic resource type for when a resource class is not available. More...

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.

Functions for CUDA Resource Naming
enum	nvtxResourceCUDAType_t { 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) }
	Resource types for CUDA. More...

NVTX_DECLSPEC void NVTX_API	nvtxNameCuDeviceA (CUdevice device, const char *name)
	Annotates a CUDA device.

NVTX_DECLSPEC void NVTX_API	nvtxNameCuDeviceW (CUdevice device, const wchar_t *name)

Functions for CUDA Resource Naming
enum	nvtxResourceCUDARTType_t { 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) }
	Resource types for CUDART. More...

NVTX_DECLSPEC void NVTX_API	nvtxNameCudaDeviceA (int device, const char *name)
	Annotates a CUDA device.

NVTX_DECLSPEC void NVTX_API	nvtxNameCudaDeviceW (int device, const wchar_t *name)

Functions for OpenCL Resource Naming
enum	nvtxResourceOpenCLType_t { 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) }
	Resource types for OpenCL. More...

NVTX_DECLSPEC void NVTX_API	nvtxNameClDeviceA (cl_device_id device, const char *name)
	Annotates an OpenCL device.

NVTX_DECLSPEC void NVTX_API	nvtxNameClDeviceW (cl_device_id device, const wchar_t *name)

NVTX_DECLSPEC void NVTX_API	nvtxDomainResourceDestroy (nvtxResourceHandle_t resource)
	Destroy a resource object to track and associate data with OS and middleware objects.

Functions for NVTX Category Naming
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 void NVTX_API	nvtxDomainNameCategoryW (nvtxDomainHandle_t domain, uint32_t category, const wchar_t *name)

NVTX_DECLSPEC void NVTX_API	nvtxNameCategoryA (uint32_t category, const char *name)
	Annotate an NVTX category.

NVTX_DECLSPEC void NVTX_API	nvtxNameCategoryW (uint32_t category, const wchar_t *name)

Functions for OS Threads Naming
NVTX_DECLSPEC void NVTX_API	nvtxNameOsThreadA (uint32_t threadId, const char *name)
	Annotate an OS thread.

NVTX_DECLSPEC void NVTX_API	nvtxNameOsThreadW (uint32_t threadId, const wchar_t *name)

NVTX_DECLSPEC void NVTX_API	nvtxNameCuContextA (CUcontext context, const char *name)
	Annotates a CUDA context.

NVTX_DECLSPEC void NVTX_API	nvtxNameCuContextW (CUcontext context, const wchar_t *name)

NVTX_DECLSPEC void NVTX_API	nvtxNameCuStreamA (CUstream stream, const char *name)
	Annotates a CUDA stream.

NVTX_DECLSPEC void NVTX_API	nvtxNameCuStreamW (CUstream stream, const wchar_t *name)

NVTX_DECLSPEC void NVTX_API	nvtxNameCuEventA (CUevent event, const char *name)
	Annotates a CUDA event.

NVTX_DECLSPEC void NVTX_API	nvtxNameCuEventW (CUevent event, const wchar_t *name)

NVTX_DECLSPEC void NVTX_API	nvtxNameCudaStreamA (cudaStream_t stream, const char *name)
	Annotates a CUDA stream.

NVTX_DECLSPEC void NVTX_API	nvtxNameCudaStreamW (cudaStream_t stream, const wchar_t *name)

NVTX_DECLSPEC void NVTX_API	nvtxNameCudaEventA (cudaEvent_t event, const char *name)
	Annotates a CUDA event.

NVTX_DECLSPEC void NVTX_API	nvtxNameCudaEventW (cudaEvent_t event, const wchar_t *name)

NVTX_DECLSPEC void NVTX_API	nvtxNameClContextA (cl_context context, const char *name)
	Annotates an OpenCL context.

NVTX_DECLSPEC void NVTX_API	nvtxNameClContextW (cl_context context, const wchar_t *name)

NVTX_DECLSPEC void NVTX_API	nvtxNameClCommandQueueA (cl_command_queue command_queue, const char *name)
	Annotates an OpenCL command queue.

NVTX_DECLSPEC void NVTX_API	nvtxNameClCommandQueueW (cl_command_queue command_queue, const wchar_t *name)

NVTX_DECLSPEC void NVTX_API	nvtxNameClMemObjectA (cl_mem memobj, const char *name)
	Annotates an OpenCL memory object.

NVTX_DECLSPEC void NVTX_API	nvtxNameClMemObjectW (cl_mem memobj, const wchar_t *name)

NVTX_DECLSPEC void NVTX_API	nvtxNameClSamplerA (cl_sampler sampler, const char *name)
	Annotates an OpenCL sampler.

NVTX_DECLSPEC void NVTX_API	nvtxNameClSamplerW (cl_sampler sampler, const wchar_t *name)

NVTX_DECLSPEC void NVTX_API	nvtxNameClProgramA (cl_program program, const char *name)
	Annotates an OpenCL program.

NVTX_DECLSPEC void NVTX_API	nvtxNameClProgramW (cl_program program, const wchar_t *name)

NVTX_DECLSPEC void NVTX_API	nvtxNameClEventA (cl_event evnt, const char *name)
	Annotates an OpenCL event.

NVTX_DECLSPEC void NVTX_API	nvtxNameClEventW (cl_event evnt, const wchar_t *name)

Detailed Description

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.

Enumeration Type Documentation

◆ nvtxResourceCUDARTType_t

enum nvtxResourceCUDARTType_t

Resource types for CUDART.

Definition at line 66 of file nvToolsExtCudaRt.h.

◆ nvtxResourceCUDAType_t

enum nvtxResourceCUDAType_t

Resource types for CUDA.

Definition at line 65 of file nvToolsExtCuda.h.

◆ nvtxResourceGenericType_t

enum nvtxResourceGenericType_t

Generic resource type for when a resource class is not available.

See also: nvtxDomainResourceCreate

Version: NVTX_VERSION_2

Enumerator
NVTX_RESOURCE_TYPE_GENERIC_POINTER	Generic pointer assumed to have no collisions with other pointers.
NVTX_RESOURCE_TYPE_GENERIC_HANDLE	Generic handle assumed to have no collisions with other handles.
NVTX_RESOURCE_TYPE_GENERIC_THREAD_NATIVE	OS native thread identifier.
NVTX_RESOURCE_TYPE_GENERIC_THREAD_POSIX	POSIX pthread identifier.

Definition at line 1136 of file nvToolsExt.h.

◆ nvtxResourceOpenCLType_t

enum nvtxResourceOpenCLType_t

Resource types for OpenCL.

Definition at line 65 of file nvToolsExtOpenCL.h.

Function Documentation

◆ nvtxDomainNameCategoryA()

NVTX_DECLSPEC void NVTX_API nvtxDomainNameCategoryA	(	nvtxDomainHandle_t	domain,
		uint32_t	category,
		const char *	name
	)

Annotate an NVTX category used within a domain.

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).

Parameters

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

Remarks: The category names are tracked per domain.

Example: Assign names to categories in a domain:
nvtxDomainHandle_t domain = nvtxDomainCreateA("example");

nvtxDomainNameCategoryA(domain, 1, "Memory Allocation");

nvtxDomainNameCategoryW(domain, 2, L"Memory Transfer");

nvtxDomainCreateA
NVTX_DECLSPEC nvtxDomainHandle_t NVTX_API nvtxDomainCreateA(const char *name)
Register a NVTX domain.

nvtxDomainNameCategoryA
NVTX_DECLSPEC void NVTX_API nvtxDomainNameCategoryA(nvtxDomainHandle_t domain, uint32_t category, const char *name)
Annotate an NVTX category used within a domain.

Version: NVTX_VERSION_2

◆ nvtxDomainResourceCreate()

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.

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

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.

Example: Register a resource:
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);

NVTX_MESSAGE_TYPE_ASCII
@ NVTX_MESSAGE_TYPE_ASCII
Definition nvToolsExt.h:450

nvtxDomainResourceCreate
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.

NVTX_RESOURCE_TYPE_GENERIC_POINTER
@ NVTX_RESOURCE_TYPE_GENERIC_POINTER
Definition nvToolsExt.h:1139

NVTX_VERSION
#define NVTX_VERSION
Definition nvToolsExt.h:177

See also: ::nvtxResourceAttributes_t nvtxDomainResourceDestroy

Version: NVTX_VERSION_2

◆ nvtxDomainResourceDestroy()

NVTX_DECLSPEC void NVTX_API nvtxDomainResourceDestroy ( nvtxResourceHandle_t resource )

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

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

Parameters

resource - Handle to the resource in which to operate.

Example: Unregister a resource:
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);

nvtxDomainResourceDestroy
NVTX_DECLSPEC void NVTX_API nvtxDomainResourceDestroy(nvtxResourceHandle_t resource)
Destroy a resource object to track and associate data with OS and middleware objects.

See also: nvtxDomainResourceCreate

Version: NVTX_VERSION_2

◆ nvtxNameCategoryA()

NVTX_DECLSPEC void NVTX_API nvtxNameCategoryA	(	uint32_t	category,
		const char *	name
	)

Annotate an NVTX category.

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.

Parameters

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

Remarks: The category names are tracked per process.

Example: Assign names to categories:
nvtxNameCategory(1, "Memory Allocation");

nvtxNameCategory(2, "Memory Transfer");

nvtxNameCategory(3, "Memory Object Lifetime");

Version: NVTX_VERSION_1

◆ nvtxNameClCommandQueueA()

NVTX_DECLSPEC void NVTX_API nvtxNameClCommandQueueA	(	cl_command_queue	command_queue,
		const char *	name
	)

Annotates an OpenCL command queue.

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

Parameters

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

Version: NVTX_VERSION_1

◆ nvtxNameClContextA()

NVTX_DECLSPEC void NVTX_API nvtxNameClContextA	(	cl_context	context,
		const char *	name
	)

Annotates an OpenCL context.

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

Parameters

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

Version: NVTX_VERSION_1

◆ nvtxNameClDeviceA()

NVTX_DECLSPEC void NVTX_API nvtxNameClDeviceA	(	cl_device_id	device,
		const char *	name
	)

Annotates an OpenCL device.

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

Parameters

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

Version: NVTX_VERSION_1

◆ nvtxNameClEventA()

NVTX_DECLSPEC void NVTX_API nvtxNameClEventA	(	cl_event	evnt,
		const char *	name
	)

Annotates an OpenCL event.

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

Parameters

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

Version: NVTX_VERSION_1

◆ nvtxNameClMemObjectA()

NVTX_DECLSPEC void NVTX_API nvtxNameClMemObjectA	(	cl_mem	memobj,
		const char *	name
	)

Annotates an OpenCL memory object.

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

Parameters

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

Version: NVTX_VERSION_1

◆ nvtxNameClProgramA()

NVTX_DECLSPEC void NVTX_API nvtxNameClProgramA	(	cl_program	program,
		const char *	name
	)

Annotates an OpenCL program.

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

Parameters

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

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

Version: NVTX_VERSION_1

◆ nvtxNameClSamplerA()

NVTX_DECLSPEC void NVTX_API nvtxNameClSamplerA	(	cl_sampler	sampler,
		const char *	name
	)

Annotates an OpenCL sampler.

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

Parameters

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

Version: NVTX_VERSION_1

◆ nvtxNameCuContextA()

NVTX_DECLSPEC void NVTX_API nvtxNameCuContextA	(	CUcontext	context,
		const char *	name
	)

Annotates a CUDA context.

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

Parameters

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

Example: Name a CUDA context:
CUresult status = cuCtxCreate( &cuContext, 0, cuDevice );

if ( CUDA_SUCCESS != status )

goto Error;

nvtxNameCuContext(cuContext, "CTX_NAME");

Version: NVTX_VERSION_1

◆ nvtxNameCudaDeviceA()

NVTX_DECLSPEC void NVTX_API nvtxNameCudaDeviceA	(	int	device,
		const char *	name
	)

Annotates a CUDA device.

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

Parameters

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

Version: NVTX_VERSION_1

◆ nvtxNameCudaEventA()

NVTX_DECLSPEC void NVTX_API nvtxNameCudaEventA	(	cudaEvent_t	event,
		const char *	name
	)

Annotates a CUDA event.

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

Parameters

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

Version: NVTX_VERSION_1

◆ nvtxNameCudaStreamA()

NVTX_DECLSPEC void NVTX_API nvtxNameCudaStreamA	(	cudaStream_t	stream,
		const char *	name
	)

Annotates a CUDA stream.

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

Parameters

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

Version: NVTX_VERSION_1

◆ nvtxNameCuDeviceA()

NVTX_DECLSPEC void NVTX_API nvtxNameCuDeviceA	(	CUdevice	device,
		const char *	name
	)

Annotates a CUDA device.

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

Parameters

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

Version: NVTX_VERSION_1

◆ nvtxNameCuEventA()

NVTX_DECLSPEC void NVTX_API nvtxNameCuEventA	(	CUevent	event,
		const char *	name
	)

Annotates a CUDA event.

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

Parameters

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

Version: NVTX_VERSION_1

◆ nvtxNameCuStreamA()

NVTX_DECLSPEC void NVTX_API nvtxNameCuStreamA	(	CUstream	stream,
		const char *	name
	)

Annotates a CUDA stream.

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

Parameters

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

Version: NVTX_VERSION_1

◆ nvtxNameOsThreadA()

NVTX_DECLSPEC void NVTX_API nvtxNameOsThreadA	(	uint32_t	threadId,
		const char *	name
	)

Annotate an OS thread.

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.

Parameters

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

Examples: Name a thread based on the given operating system:

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");

macOS:

#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");

Version: NVTX_VERSION_1

Data Structures

Functions for Generic Resource Naming

Functions for CUDA Resource Naming

Functions for CUDA Resource Naming

Functions for OpenCL Resource Naming

Functions for NVTX Category Naming

Functions for OS Threads Naming

Detailed Description

CUDA Resource Naming

CUDA Runtime Resource Naming

OpenCL Resource Naming

Enumeration Type Documentation

◆ nvtxResourceCUDARTType_t

◆ nvtxResourceCUDAType_t

◆ nvtxResourceGenericType_t

◆ nvtxResourceOpenCLType_t

Function Documentation

◆ nvtxDomainNameCategoryA()

◆ nvtxDomainResourceCreate()

◆ nvtxDomainResourceDestroy()

◆ nvtxNameCategoryA()

◆ nvtxNameClCommandQueueA()

◆ nvtxNameClContextA()

◆ nvtxNameClDeviceA()

◆ nvtxNameClEventA()

◆ nvtxNameClMemObjectA()

◆ nvtxNameClProgramA()

◆ nvtxNameClSamplerA()

◆ nvtxNameCuContextA()

◆ nvtxNameCudaDeviceA()

◆ nvtxNameCudaEventA()

◆ nvtxNameCudaStreamA()

◆ nvtxNameCuDeviceA()

◆ nvtxNameCuEventA()

◆ nvtxNameCuStreamA()

◆ nvtxNameOsThreadA()