nvToolsExt.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: Copyright (c) 2009-2022 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 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
 
#if defined(_MSC_VER)
#define NVTX_API __stdcall
#define NVTX_INLINE_STATIC __inline static
#else /*defined(__GNUC__)*/
#define NVTX_API
#if defined(__cplusplus) || (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L)
#define NVTX_INLINE_STATIC inline static
#else
#define NVTX_INLINE_STATIC __inline__ static
#endif
#endif /* Platform */
 
#if defined(NVTX_NO_IMPL)
/* When omitting implementation, avoid declaring functions inline */
/* without definitions, since this causes compiler warnings. */
#define NVTX_DECLSPEC
#elif defined(NVTX_EXPORT_API)
/* Allow overriding definition of NVTX_DECLSPEC when exporting API. */
/* Default is empty, meaning non-inline with external linkage. */
#if !defined(NVTX_DECLSPEC)
#define NVTX_DECLSPEC
#endif
#else
/* Normal NVTX usage defines the NVTX API inline with static */
/* (internal) linkage. */
#define NVTX_DECLSPEC NVTX_INLINE_STATIC
#endif
 
#include "nvtxDetail/nvtxLinkOnce.h"
 
#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) */