nvToolsExt.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: Copyright (c) 2009-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * Licensed under the Apache License v2.0 with LLVM Exceptions.
 * See https://nvidia.github.io/NVTX/LICENSE.txt for license information.
 */
 
/* ========================================================================= */
#if defined(NVTX_VERSION) && NVTX_VERSION < 3
#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."
#endif
 
/* Header guard */
#if !defined(NVTX_VERSION)
#define NVTX_VERSION 3
 
/* Platform-dependent defines:
 *
 * - NVTX_API - Calling conventions (only used on Windows, and only effects
 *   32-bit x86 builds, i.e. callee pops stack instead of caller)
 *
 * - NVTX_DYNAMIC_EXPORT - Make function an exported entry point from a
 *   dynamic library or shared object.
 *
 * - NVTX_EXPORT_UNMANGLED_FUNCTION_NAME - When used inside the body of a
 *   function declared with NVTX_DYNAMIC_EXPORT, ensures the symbol exported
 *   for the function is the exact string of the function's name as written
 *   in the code.  Name-mangling or name-decoration is disabled.  Note that
 *   on many platforms this is not necessary, since either the function name
 *   is already exported verbatim, or the dynamic loader also checks for
 *   functions with the mangling applied.  Forcing the exports to avoid any
 *   mangling simplifies usage across platforms and from other languages.
 */
#if defined(_WIN32)
 
#define NVTX_API __stdcall
 
#if defined(_MSC_VER)
#define NVTX_DYNAMIC_EXPORT __declspec(dllexport)
#else
#define NVTX_DYNAMIC_EXPORT __attribute__((visibility("default"))) __declspec(dllexport)
#endif
 
#if defined(_M_IX86) || defined(_M_ARM64EC)
#define NVTX_EXPORT_UNMANGLED_FUNCTION_NAME _Pragma("comment(linker, \"/EXPORT:\" __FUNCTION__ \"=\" __FUNCDNAME__)")
#else
#define NVTX_EXPORT_UNMANGLED_FUNCTION_NAME
#endif
 
#else /* POSIX-like platform */
 
#define NVTX_API
 
#define NVTX_DYNAMIC_EXPORT __attribute__((visibility("default")))
 
#define NVTX_EXPORT_UNMANGLED_FUNCTION_NAME
 
#endif /* Platform-dependent defines */
 
/* Compiler-dependent defines:
 *
 * - NVTX_INLINE_STATIC - Ensure function has internal linkage, and suggest
 *   avoiding code-gen of the function.  Without this, function has external
 *   linkage with a strong symbol, so linker expects only one definition.
 */
#if defined(_MSC_VER)
 
#define NVTX_INLINE_STATIC __inline static
 
#else /* GCC-like compiler */
 
#if defined(__cplusplus) || (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L)
#define NVTX_INLINE_STATIC inline static
#else
#define NVTX_INLINE_STATIC __inline__ static
#endif
 
#endif /* Compiler-dependent defines */
 
 
/* API linkage/export options:
 *
 * - By default, the NVTX API functions are declared as "inline", with the
 *   implementations provided in the headers.  This allows multiple .c/.cpp
 *   files in the same project to include NVTX headers without duplicate-
 *   definition linker errors.  An optimizing compiler should inline these
 *   implementations, ensuring that the overhead of making an NVTX call is as
 *   low as possible, even without enabling link-time optimizations.
 *
 * - NVTX_NO_IMPL - Use when writing NVTX tools.  If this macro is defined,
 *   the NVTX headers will provide all the typedefs, macros, and declarations
 *   of API functions (not marked inline), but no function implementations.
 *
 * - NVTX_EXPORT_API - NVTX is normally used in C/C++ applications by simply
 *   including the headers.  There is no need to link with a static library,
 *   or to ship a dynamic library with the application (this was changed in
 *   NVTX v3).  For other languages, it's not convenient to use a header-only
 *   C library.  The best way to provide an idiomatic NVTX API for another
 *   language is a .c file that includes the NVTX headers and implements
 *   functions for that language using its native calling conventions and
 *   datatypes -- this method can allow static linking to avoid depending on
 *   a separate dynamic library.  Alternatively, other languages may support
 *   using C calling conventions to directly call C functions exported from a
 *   dynamic library.  To build such a library, write a .c file that defines
 *   NVTX_EXPORT_API and includes any/all of the NVTX headers.  Compile this
 *   file as a dynamic library, and the NVTX API functions from the included
 *   headers will be exported with no name-mangling or decoration.  Defining
 *   ABI-compatible NVTX struct and enum types in the other language is the
 *   responsibility of the user of this dynamic library.
 *
 * Whichever of the above modes is chosen, the following macros are defined
 * appropriately below to implement that mode.  These macros are only defined
 * if not already defined by the user, so they may be overridden by users to
 * handle advanced cases.
 *
 * - NVTX_DECLSPEC - Specify linkage for NVTX API functions.
 *
 * - NVTX_SET_NAME_MANGLING_OPTIONS - If necessary for the platform, will use
 *   platform-dependent syntax for ensuring function name is exported with no
 *   name-mangling or decoration.  Certain compiler and calling-convention
 *   combinations will add name-mangling or decorations when exporting NVTX
 *   function name symbols, which makes it much harder for other languages
 *   to access these functions.  This macro must be used inside a function's
 *   body because it uses built-in macros to get the current function's name.
 */
#if defined(NVTX_NO_IMPL)
 
/* When omitting implementation, avoid declaring functions inline
 * without definitions, since this causes compiler warnings. */
#if !defined(NVTX_DECLSPEC)
#define NVTX_DECLSPEC
#endif
#if !defined(NVTX_SET_NAME_MANGLING_OPTIONS)
#define NVTX_SET_NAME_MANGLING_OPTIONS
#endif
 
#elif defined(NVTX_EXPORT_API)
 
/* Add platform-dependent declaration syntax to ensure NVTX API functions are
 * exported when compiling as a dynamic library/shared object, and ensure the
 * exported names are not mangled/decorated. */
#if !defined(NVTX_DECLSPEC)
#define NVTX_DECLSPEC NVTX_DYNAMIC_EXPORT
#endif
#if !defined(NVTX_SET_NAME_MANGLING_OPTIONS)
#define NVTX_SET_NAME_MANGLING_OPTIONS NVTX_EXPORT_UNMANGLED_FUNCTION_NAME
#endif
 
#else /* Normal NVTX usage */
 
/* Functions definitions are provided, and functions are declared inline to
 * avoid duplicate-definition linker errors when using multiple source files. */
#if !defined(NVTX_DECLSPEC)
#define NVTX_DECLSPEC NVTX_INLINE_STATIC
#endif
#if !defined(NVTX_SET_NAME_MANGLING_OPTIONS)
#define NVTX_SET_NAME_MANGLING_OPTIONS
#endif
 
#endif
 
/* Platform-dependent helpers for defining global variables in header files.
 * Ensures the linker uses only one instance when multiple source files include
 * the headers, avoiding duplicate-definition linker errors. */
#include "nvtxDetail/nvtxLinkOnce.h"
 
/* Macros for applying major-version-specific suffix to NVTX global symbols, so
 * usage of different versions in different source files is supported without
 * violating the one-definition rule. */
#define NVTX_VERSIONED_IDENTIFIER_L3(NAME, VERSION) NAME##_v##VERSION
#define NVTX_VERSIONED_IDENTIFIER_L2(NAME, VERSION) NVTX_VERSIONED_IDENTIFIER_L3(NAME, VERSION)
#define NVTX_VERSIONED_IDENTIFIER(NAME) NVTX_VERSIONED_IDENTIFIER_L2(NAME, NVTX_VERSION)
 
#ifndef NVTX_STDINT_TYPES_ALREADY_DEFINED
#include <stdint.h>
#endif
 
#include <stddef.h>
 
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
 
#define NVTX_SUCCESS 0
#define NVTX_FAIL 1
#define NVTX_ERR_INIT_LOAD_PROPERTY 2
#define NVTX_ERR_INIT_ACCESS_LIBRARY 3
#define NVTX_ERR_INIT_LOAD_LIBRARY 4
#define NVTX_ERR_INIT_MISSING_LIBRARY_ENTRY_POINT 5
#define NVTX_ERR_INIT_FAILED_LIBRARY_ENTRY_POINT 6
#define NVTX_ERR_NO_INJECTION_LIBRARY_AVAILABLE 7
 
#define NVTX_EVENT_ATTRIB_STRUCT_SIZE ( (uint16_t)( sizeof(nvtxEventAttributes_t) ) )
 
#define NVTX_NO_PUSH_POP_TRACKING ((int)-2)
 
typedef uint64_t nvtxRangeId_t;
 
/* Forward declaration of opaque domain registration structure */
struct nvtxDomainRegistration_st;
typedef struct nvtxDomainRegistration_st nvtxDomainRegistration;
 
/* \brief Domain Handle Structure.
* \anchor DOMAIN_HANDLE_STRUCTURE
*
* This structure is opaque to the user and is used as a handle to reference
* a domain.  This type is returned from tools when using the NVTX API to
* create a domain.
*
*/
typedef nvtxDomainRegistration* nvtxDomainHandle_t;
 
/* Forward declaration of opaque string registration structure */
struct nvtxStringRegistration_st;
typedef struct nvtxStringRegistration_st nvtxStringRegistration;
 
/* \brief Registered String Handle Structure.
* \anchor REGISTERED_STRING_HANDLE_STRUCTURE
*
* This structure is opaque to the user and is used as a handle to reference
* a registered string.  This type is returned from tools when using the NVTX
* API to create a registered string.
*
*/
typedef nvtxStringRegistration* nvtxStringHandle_t;
 
/* ========================================================================= */
typedef enum nvtxColorType_t
{
    NVTX_COLOR_UNKNOWN  = 0,                 
    NVTX_COLOR_ARGB     = 1                  
} nvtxColorType_t;
 
typedef enum nvtxMessageType_t
{
    NVTX_MESSAGE_UNKNOWN          = 0,    
    NVTX_MESSAGE_TYPE_ASCII       = 1,    
    NVTX_MESSAGE_TYPE_UNICODE     = 2,     
    /* NVTX_VERSION_2 */
    NVTX_MESSAGE_TYPE_REGISTERED  = 3,    
} nvtxMessageType_t;
 
typedef union nvtxMessageValue_t
{
    const char* ascii;
    const wchar_t* unicode;
    /* NVTX_VERSION_2 */
    nvtxStringHandle_t registered;
} nvtxMessageValue_t;
 
 
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC void NVTX_API nvtxInitialize(const void* reserved);
 
/* ========================================================================= */
typedef enum nvtxPayloadType_t
{
    NVTX_PAYLOAD_UNKNOWN = 0,   
    NVTX_PAYLOAD_TYPE_UNSIGNED_INT64 = 1,   
    NVTX_PAYLOAD_TYPE_INT64 = 2,   
    NVTX_PAYLOAD_TYPE_DOUBLE = 3,   
    /* NVTX_VERSION_2 */
    NVTX_PAYLOAD_TYPE_UNSIGNED_INT32 = 4,   
    NVTX_PAYLOAD_TYPE_INT32 = 5,   
    NVTX_PAYLOAD_TYPE_FLOAT = 6    
} nvtxPayloadType_t;
 
typedef struct nvtxEventAttributes_v2
{
    uint16_t version;
 
    uint16_t size;
 
    uint32_t category;
 
    int32_t colorType;              /* nvtxColorType_t */
 
    uint32_t color;
 
    int32_t payloadType;            /* nvtxPayloadType_t */
 
    int32_t reserved0;
 
    union payload_t
    {
        uint64_t ullValue;
        int64_t llValue;
        double dValue;
        /* NVTX_VERSION_2 */
        uint32_t uiValue;
        int32_t iValue;
        float fValue;
    } payload;
 
    int32_t messageType;            /* nvtxMessageType_t */
 
    nvtxMessageValue_t message;
 
} nvtxEventAttributes_v2;
 
typedef struct nvtxEventAttributes_v2 nvtxEventAttributes_t;
 
/* ========================================================================= */
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC void NVTX_API nvtxDomainMarkEx(nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC void NVTX_API nvtxMarkEx(const nvtxEventAttributes_t* eventAttrib);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC void NVTX_API nvtxMarkA(const char* message);
NVTX_DECLSPEC void NVTX_API nvtxMarkW(const wchar_t* message);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxDomainRangeStartEx(nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartEx(const nvtxEventAttributes_t* eventAttrib);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartA(const char* message);
NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartW(const wchar_t* message);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC void NVTX_API nvtxDomainRangeEnd(nvtxDomainHandle_t domain, nvtxRangeId_t id);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC void NVTX_API nvtxRangeEnd(nvtxRangeId_t id);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC int NVTX_API nvtxDomainRangePushEx(nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC int NVTX_API nvtxRangePushEx(const nvtxEventAttributes_t* eventAttrib);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC int NVTX_API nvtxRangePushA(const char* message);
NVTX_DECLSPEC int NVTX_API nvtxRangePushW(const wchar_t* message);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC int NVTX_API nvtxDomainRangePop(nvtxDomainHandle_t domain);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC int NVTX_API nvtxRangePop(void);
/* ========================================================================= */
/*  ------------------------------------------------------------------------- */
/*  ------------------------------------------------------------------------- */
 
/*  ------------------------------------------------------------------------- */
#define NVTX_RESOURCE_MAKE_TYPE(CLASS, INDEX) ((((uint32_t)(NVTX_RESOURCE_CLASS_ ## CLASS))<<16)|((uint32_t)(INDEX)))
#define NVTX_RESOURCE_CLASS_GENERIC 1
/* ------------------------------------------------------------------------- */
typedef 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) 
} nvtxResourceGenericType_t;
 
 
 
typedef struct nvtxResourceAttributes_v0
{
    uint16_t version;
 
    uint16_t size;
 
    int32_t identifierType;            /* values from enums following the pattern nvtxResource[name]Type_t */
 
    union identifier_t
    {
        const void* pValue;
        uint64_t ullValue;
    } identifier;
 
    int32_t messageType;            /* nvtxMessageType_t */
 
    nvtxMessageValue_t message;
 
} nvtxResourceAttributes_v0;
 
typedef struct nvtxResourceAttributes_v0 nvtxResourceAttributes_t;
 
/* \cond SHOW_HIDDEN
* \version \NVTX_VERSION_2
*/
#define NVTX_RESOURCE_ATTRIB_STRUCT_SIZE ( (uint16_t)( sizeof(nvtxResourceAttributes_v0) ) )
typedef struct nvtxResourceHandle* nvtxResourceHandle_t;
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC nvtxResourceHandle_t NVTX_API nvtxDomainResourceCreate(nvtxDomainHandle_t domain, nvtxResourceAttributes_t* attribs);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC void NVTX_API nvtxDomainResourceDestroy(nvtxResourceHandle_t resource);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC void NVTX_API nvtxDomainNameCategoryA(nvtxDomainHandle_t domain, uint32_t category, const char* name);
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);
NVTX_DECLSPEC void NVTX_API nvtxNameCategoryW(uint32_t category, const wchar_t* name);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC void NVTX_API nvtxNameOsThreadA(uint32_t threadId, const char* name);
NVTX_DECLSPEC void NVTX_API nvtxNameOsThreadW(uint32_t threadId, const wchar_t* name);
/* ========================================================================= */
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC nvtxStringHandle_t NVTX_API nvtxDomainRegisterStringA(nvtxDomainHandle_t domain, const char* string);
NVTX_DECLSPEC nvtxStringHandle_t NVTX_API nvtxDomainRegisterStringW(nvtxDomainHandle_t domain, const wchar_t* string);
/* ========================================================================= */
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC nvtxDomainHandle_t NVTX_API nvtxDomainCreateA(const char* name);
NVTX_DECLSPEC nvtxDomainHandle_t NVTX_API nvtxDomainCreateW(const wchar_t* name);
/* ------------------------------------------------------------------------- */
NVTX_DECLSPEC void NVTX_API nvtxDomainDestroy(nvtxDomainHandle_t domain);
/* ========================================================================= */
#ifdef UNICODE
    #define nvtxMark            nvtxMarkW
    #define nvtxRangeStart      nvtxRangeStartW
    #define nvtxRangePush       nvtxRangePushW
    #define nvtxNameCategory    nvtxNameCategoryW
    #define nvtxNameOsThread    nvtxNameOsThreadW
    /* NVTX_VERSION_2 */
    #define nvtxDomainCreate         nvtxDomainCreateW
    #define nvtxDomainRegisterString nvtxDomainRegisterStringW
    #define nvtxDomainNameCategory   nvtxDomainNameCategoryW
#else
    #define nvtxMark            nvtxMarkA
    #define nvtxRangeStart      nvtxRangeStartA
    #define nvtxRangePush       nvtxRangePushA
    #define nvtxNameCategory    nvtxNameCategoryA
    #define nvtxNameOsThread    nvtxNameOsThreadA
    /* NVTX_VERSION_2 */
    #define nvtxDomainCreate         nvtxDomainCreateA
    #define nvtxDomainRegisterString nvtxDomainRegisterStringA
    #define nvtxDomainNameCategory   nvtxDomainNameCategoryA
#endif
 
#ifdef __cplusplus
} /* extern "C" */
#endif /* __cplusplus */
 
#define NVTX_IMPL_GUARD /* Ensure other headers cannot be included directly */
 
#include "nvtxDetail/nvtxTypes.h"
 
#ifndef NVTX_NO_IMPL
#include "nvtxDetail/nvtxImpl.h"
#endif /*NVTX_NO_IMPL*/
 
#undef NVTX_IMPL_GUARD
 
#endif /* !defined(NVTX_VERSION) */