nvToolsExtMem.h

/*
 * 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_AS_SYSTEM_HEADER)
#if defined(__clang__)
#pragma clang system_header
#elif defined(__GNUC__) || defined(__NVCOMPILER)
#pragma GCC system_header
#elif defined(_MSC_VER)
#pragma system_header
#endif
#endif
 
#include "nvToolsExt.h"
 
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
 
#ifndef NVTX_EXT_MODULEID_MEM
#define NVTX_EXT_MODULEID_MEM 1
#endif
 
/* \cond SHOW_HIDDEN
 * \brief A compatibility ID value used in structures and initialization to
 * identify version differences.
 */
#ifndef NVTX_EXT_COMPATID_MEM
#define NVTX_EXT_COMPATID_MEM 0x0102
#endif
/* \endcond
 */
 
#ifndef NVTX_MEM_CONTENTS_V1
#define NVTX_MEM_CONTENTS_V1
 
/* \cond SHOW_HIDDEN
 * \brief This value is returned by functions that return `nvtxMemHeapHandle_t`,
 * if a tool is not attached.
 */
#define NVTX_MEM_HEAP_HANDLE_NO_TOOL (NVTX_STATIC_CAST(nvtxMemHeapHandle_t, NVTX_STATIC_CAST(intptr_t, -1)))
/* \endcond
 */
 
/* \cond SHOW_HIDDEN
 * \brief This value is returned by functions that return `nvtxMemRegionHandle_t`
 * if a tool is not attached.
 */
#define NVTX_MEM_REGION_HANDLE_NO_TOOL (NVTX_STATIC_CAST(nvtxMemRegionHandle_t, NVTX_STATIC_CAST(intptr_t, -1)))
/* \endcond
 */
 
/* \cond SHOW_HIDDEN
 * \brief This value is returned by functions that return `nvtxMemPermissionsHandle_t`
 * if a tool is not attached.
 */
#define NVTX_MEM_PERMISSIONS_HANDLE_NO_TOOL (NVTX_STATIC_CAST(nvtxMemPermissionsHandle_t, -1))
/* \endcond
 */
 
 
/* \cond SHOW_HIDDEN
 * \brief This should not be used and is considered an error but defined to
 * detect an accidental use of zero or NULL.
 */
#define NVTX_MEM_HEAP_USAGE_UNKNOWN 0x0
/* \endcond
 */
 
 
/* \cond SHOW_HIDDEN
 * \brief This should not be used and is considered an error but defined to
 * detect an accidental use of zero or NULL.
 */
#define NVTX_MEM_TYPE_UNKNOWN 0x0
/* \endcond
 */
 
 
/*  ------------------------------------------------------------------------- */
#define NVTX_MEM_HEAP_HANDLE_PROCESS_WIDE (NVTX_STATIC_CAST(nvtxMemHeapHandle_t, 0))
 
#define NVTX_MEM_HEAP_USAGE_TYPE_SUB_ALLOCATOR 0x1
 
#define NVTX_MEM_HEAP_USAGE_TYPE_LAYOUT 0x2
 
 
#define NVTX_MEM_TYPE_VIRTUAL_ADDRESS 0x1
 
 
#define NVTX_MEM_PERMISSIONS_HANDLE_PROCESS_WIDE (NVTX_STATIC_CAST(nvtxMemPermissionsHandle_t, 0))
 
#define NVTX_MEM_PERMISSIONS_CREATE_FLAGS_NONE 0x0
#define NVTX_MEM_PERMISSIONS_CREATE_FLAGS_EXCLUDE_GLOBAL_READ 0x1
#define NVTX_MEM_PERMISSIONS_CREATE_FLAGS_EXCLUDE_GLOBAL_WRITE 0x2
#define NVTX_MEM_PERMISSIONS_CREATE_FLAGS_EXCLUDE_GLOBAL_ATOMIC 0x4
 
 
/* \cond SHOW_HIDDEN
 * \brief Forward declaration of opaque memory heap structure.
 */
struct nvtxMemHeap_v1;
typedef struct nvtxMemHeap_v1 nvtxMemHeap_t;
/* \endcond
 */
 
typedef nvtxMemHeap_t* nvtxMemHeapHandle_t;
 
/* \cond SHOW_HIDDEN
 * \brief Forward declaration of opaque memory heap structure.
 */
struct nvtxMemRegion_v1;
typedef struct nvtxMemRegion_v1 nvtxMemRegion_t;
/* \endcond
 */
 
typedef nvtxMemRegion_t* nvtxMemRegionHandle_t;
 
typedef union nvtxMemRegionRef_t
{
    void const* pointer;
    nvtxMemRegionHandle_t handle;
} nvtxMemRegionRef_t;
 
/* \cond SHOW_HIDDEN
 * \brief Forward declaration of opaque memory permissions structure
 */
struct nvtxMemPermissions_v1;
typedef struct nvtxMemPermissions_v1 nvtxMemPermissions_t;
/* \endcond
 */
 
typedef nvtxMemPermissions_t* nvtxMemPermissionsHandle_t;
 
 
typedef struct nvtxMemVirtualRangeDesc_v1
{
    size_t  size;
    void const*  ptr;
} nvtxMemVirtualRangeDesc_v1 ;
typedef nvtxMemVirtualRangeDesc_v1 nvtxMemVirtualRangeDesc_t;
 
 
typedef struct nvtxMemHeapDesc_v1
{
    uint16_t extCompatID; /* Set to NVTX_EXT_COMPATID_MEM */
    uint16_t structSize; /* Size of the structure. */
    uint32_t reserved0;
 
    uint32_t usage;
 
    uint32_t type;
 
    size_t typeSpecificDescSize;
 
    void const* typeSpecificDesc;
 
    uint32_t category;
 
    uint32_t messageType;            /* nvtxMessageType_t */
 
    nvtxMessageValue_t message;
 
} nvtxMemHeapDesc_v1 ;
typedef nvtxMemHeapDesc_v1 nvtxMemHeapDesc_t;
 
NVTX_DECLSPEC nvtxMemHeapHandle_t NVTX_API nvtxMemHeapRegister(
    nvtxDomainHandle_t domain,
    nvtxMemHeapDesc_t const* desc);
 
NVTX_DECLSPEC void NVTX_API nvtxMemHeapUnregister(
    nvtxDomainHandle_t domain,
    nvtxMemHeapHandle_t heap);/* NVTX_MEM_HEAP_HANDLE_PROCESS_WIDE is not supported */
 
NVTX_DECLSPEC void NVTX_API nvtxMemHeapReset(
    nvtxDomainHandle_t domain,
    nvtxMemHeapHandle_t heap); /* NVTX_MEM_HEAP_HANDLE_PROCESS_WIDE is supported */
 
typedef struct nvtxMemRegionsRegisterBatch_v1
{
    uint16_t extCompatID; /* Set to NVTX_EXT_COMPATID_MEM */
    uint16_t structSize; /* Size of the structure. */
 
    uint32_t regionType; /* NVTX_MEM_TYPE_* */
 
    nvtxMemHeapHandle_t heap;
 
    size_t regionCount;
    size_t regionDescElementSize;
    void const* regionDescElements; /* This will also become the handle for this region. */
    nvtxMemRegionHandle_t* regionHandleElementsOut; /* This will also become the handle for this region. */
 
} nvtxMemRegionsRegisterBatch_v1;
typedef nvtxMemRegionsRegisterBatch_v1 nvtxMemRegionsRegisterBatch_t;
 
NVTX_DECLSPEC void NVTX_API nvtxMemRegionsRegister(
    nvtxDomainHandle_t domain,
    nvtxMemRegionsRegisterBatch_t const* desc);
 
 
 
typedef struct nvtxMemRegionsResizeBatch_v1
{
    uint16_t extCompatID; /* Set to NVTX_EXT_COMPATID_MEM */
    uint16_t structSize; /* Size of the structure. */
 
    uint32_t regionType; /* NVTX_MEM_TYPE_* */
 
    size_t regionDescCount;
    size_t regionDescElementSize;
    void const* regionDescElements; /* This will also become the handle for this region. */
 
} nvtxMemRegionsResizeBatch_v1;
typedef nvtxMemRegionsResizeBatch_v1 nvtxMemRegionsResizeBatch_t;
 
NVTX_DECLSPEC void NVTX_API nvtxMemRegionsResize(
    nvtxDomainHandle_t domain,
    nvtxMemRegionsResizeBatch_t const* desc);
 
 
#define NVTX_MEM_REGION_REF_TYPE_UNKNOWN 0x0
#define NVTX_MEM_REGION_REF_TYPE_POINTER 0x1
#define NVTX_MEM_REGION_REF_TYPE_HANDLE 0x2
 
typedef struct nvtxMemRegionsUnregisterBatch_v1
{
    uint16_t extCompatID; /* Set to NVTX_EXT_COMPATID_MEM */
    uint16_t structSize; /* Size of the structure. */
 
    uint32_t refType; /* NVTX_MEM_REGION_REF_TYPE_* */
 
    size_t refCount; /* count of elements in refArray */
    size_t refElementSize;
    nvtxMemRegionRef_t const* refElements; /* This will also become the handle for this region. */
 
} nvtxMemRegionsUnregisterBatch_v1;
typedef nvtxMemRegionsUnregisterBatch_v1 nvtxMemRegionsUnregisterBatch_t;
 
NVTX_DECLSPEC void NVTX_API nvtxMemRegionsUnregister(
    nvtxDomainHandle_t domain,
    nvtxMemRegionsUnregisterBatch_t const* desc);
 
typedef struct nvtxMemRegionNameDesc_v1
{
    uint32_t regionRefType; /* NVTX_MEM_REGION_REF_TYPE_* */
    uint32_t nameType; /* nvtxMessageType_t */
 
    nvtxMemRegionRef_t region;
    nvtxMessageValue_t name;
 
    uint32_t category;
    uint32_t reserved0;
} nvtxMemRegionNameDesc_v1;
typedef nvtxMemRegionNameDesc_v1 nvtxMemRegionNameDesc_t;
 
 
typedef struct nvtxMemRegionsNameBatch_v1
{
    uint16_t extCompatID; /* Set to NVTX_EXT_COMPATID_MEM */
    uint16_t structSize; /* Size of the structure. */
 
    uint32_t reserved0;
 
    size_t regionCount;
    size_t regionElementSize;
    nvtxMemRegionNameDesc_t const* regionElements;
    size_t reserved1;
} nvtxMemRegionsNameBatch_v1 ;
typedef nvtxMemRegionsNameBatch_v1 nvtxMemRegionsNameBatch_t;
 
 
NVTX_DECLSPEC void NVTX_API nvtxMemRegionsName(
    nvtxDomainHandle_t domain,
    nvtxMemRegionsNameBatch_t const* desc);
 
#define NVTX_MEM_PERMISSIONS_REGION_FLAGS_NONE 0x0
 
#define NVTX_MEM_PERMISSIONS_REGION_FLAGS_READ 0x1
 
#define NVTX_MEM_PERMISSIONS_REGION_FLAGS_WRITE 0x2
 
#define NVTX_MEM_PERMISSIONS_REGION_FLAGS_ATOMIC 0x4
 
#define NVTX_MEM_PERMISSIONS_REGION_FLAGS_RESET 0x8
 
 
typedef struct nvtxMemPermissionsAssignRegionDesc_v1
{
    uint32_t flags; /* NVTX_MEM_PERMISSIONS_REGION_FLAGS_* */
    uint32_t regionRefType; /* NVTX_MEM_REGION_REF_TYPE_* */
    nvtxMemRegionRef_t region;
 
} nvtxMemPermissionsAssignRegionDesc_v1 ;
typedef nvtxMemPermissionsAssignRegionDesc_v1 nvtxMemPermissionsAssignRegionDesc_t;
 
 
typedef struct nvtxMemPermissionsAssignBatch_v1
{
    uint16_t extCompatID; /* Set to NVTX_EXT_COMPATID_MEM */
    uint16_t structSize; /* Size of the structure. */
 
    uint32_t reserved0;
 
    nvtxMemPermissionsHandle_t permissions;
 
    size_t regionCount;
    size_t regionElementSize;
    nvtxMemPermissionsAssignRegionDesc_t const* regionElements;
 
    size_t reserved1;
} nvtxMemPermissionsAssignBatch_v1 ;
typedef nvtxMemPermissionsAssignBatch_v1 nvtxMemPermissionsAssignBatch_t;
 
 
NVTX_DECLSPEC void NVTX_API nvtxMemPermissionsAssign(
    nvtxDomainHandle_t domain,
    nvtxMemPermissionsAssignBatch_t const* desc);
 
 
NVTX_DECLSPEC nvtxMemPermissionsHandle_t NVTX_API nvtxMemPermissionsCreate(
    nvtxDomainHandle_t domain,
    int32_t creationflags); /* NVTX_MEM_PERMISSIONS_CREATE_FLAGS_* */
 
NVTX_DECLSPEC void NVTX_API nvtxMemPermissionsDestroy(
    nvtxDomainHandle_t domain,
    nvtxMemPermissionsHandle_t permissionsHandle); /* only supported on objects from nvtxMemPermissionsCreate */
 
NVTX_DECLSPEC void NVTX_API nvtxMemPermissionsReset(
    nvtxDomainHandle_t domain,
    nvtxMemPermissionsHandle_t permissionsHandle);
/* NVTX_MEM_PERMISSIONS_HANDLE_PROCESS_WIDE and other special handles are supported */
 
 
#define NVTX_MEM_PERMISSIONS_BIND_FLAGS_NONE 0x0
 
#define NVTX_MEM_PERMISSIONS_BIND_FLAGS_STRICT_WRITE 0x2
 
#define NVTX_MEM_PERMISSIONS_BIND_FLAGS_STRICT_READ 0x1
 
#define NVTX_MEM_PERMISSIONS_BIND_FLAGS_STRICT_ATOMIC 0x4
 
 
#define NVTX_MEM_PERMISSIONS_BIND_SCOPE_UNKNOWN 0x0
 
#define NVTX_MEM_PERMISSIONS_BIND_SCOPE_CPU_THREAD 0x1
 
#define NVTX_MEM_PERMISSIONS_BIND_SCOPE_CUDA_STREAM 0x2
 
 
NVTX_DECLSPEC void NVTX_API nvtxMemPermissionsBind(
    nvtxDomainHandle_t domain,
    nvtxMemPermissionsHandle_t permissions, /* special object like NVTX_MEM_PERMISSIONS_HANDLE_PROCESS_WIDE are not supported */
    uint32_t bindScope, /* NVTX_MEM_PERMISSIONS_BIND_SCOPE_* */
    uint32_t bindFlags); /* NVTX_MEM_PERMISSIONS_BIND_FLAGS_* */
 
NVTX_DECLSPEC void NVTX_API nvtxMemPermissionsUnbind(
    nvtxDomainHandle_t domain,
    uint32_t bindScope);
 
#endif /* NVTX_MEM_CONTENTS_V1 */
 
#ifndef NVTX_MEM_CALLBACK_ID_V1
#define NVTX_MEM_CALLBACK_ID_V1
 
#define NVTX3EXT_CBID_nvtxMemHeapRegister                  0
#define NVTX3EXT_CBID_nvtxMemHeapUnregister                1
#define NVTX3EXT_CBID_nvtxMemHeapReset                     2
#define NVTX3EXT_CBID_nvtxMemRegionsRegister               3
#define NVTX3EXT_CBID_nvtxMemRegionsResize                 4
#define NVTX3EXT_CBID_nvtxMemRegionsUnregister             5
#define NVTX3EXT_CBID_nvtxMemRegionsName                   6
#define NVTX3EXT_CBID_nvtxMemPermissionsAssign             7
#define NVTX3EXT_CBID_nvtxMemPermissionsCreate             8
#define NVTX3EXT_CBID_nvtxMemPermissionsDestroy            9
#define NVTX3EXT_CBID_nvtxMemPermissionsReset              10
#define NVTX3EXT_CBID_nvtxMemPermissionsBind               11
#define NVTX3EXT_CBID_nvtxMemPermissionsUnbind             12
 
/* 13-16 in nvtxExtImplMemCudaRt_v1.h */
#define NVTX3EXT_CBID_nvtxMemCudaGetProcessWidePermissions 13
#define NVTX3EXT_CBID_nvtxMemCudaGetDeviceWidePermissions  14
#define NVTX3EXT_CBID_nvtxMemCudaSetPeerAccess             15
#define NVTX3EXT_CBID_nvtxMemCudaMarkInitialized           16
 
#endif /* NVTX_MEM_CALLBACK_ID_V1 */
 
/* Macros to create versioned symbols. */
#ifndef NVTX_EXT_MEM_VERSIONED_IDENTIFIERS_V1
#define NVTX_EXT_MEM_VERSIONED_IDENTIFIERS_V1
#define NVTX_EXT_MEM_VERSIONED_IDENTIFIER_L3(NAME, VERSION, COMPATID) \
    NAME##_v##VERSION##_mem##COMPATID
#define NVTX_EXT_MEM_VERSIONED_IDENTIFIER_L2(NAME, VERSION, COMPATID) \
    NVTX_EXT_MEM_VERSIONED_IDENTIFIER_L3(NAME, VERSION, COMPATID)
#define NVTX_EXT_MEM_VERSIONED_ID(NAME) \
    NVTX_EXT_MEM_VERSIONED_IDENTIFIER_L2(NAME, NVTX_VERSION, NVTX_EXT_COMPATID_MEM)
#endif /* NVTX_EXT_MEM_VERSIONED_IDENTIFIERS_V1 */
 
#ifdef __GNUC__
#pragma GCC visibility push(internal)
#endif
 
/* Extension types are required for the implementation and the NVTX handler. */
#define NVTX_EXT_TYPES_GUARD /* Ensure other headers cannot be included directly */
#include "nvtxDetail/nvtxExtTypes.h"
#undef NVTX_EXT_TYPES_GUARD
 
#ifndef NVTX_NO_IMPL
/* Ensure other headers cannot be included directly */
#define NVTX_EXT_IMPL_MEM_GUARD
#include "nvtxDetail/nvtxExtImplMem_v1.h"
#undef NVTX_EXT_IMPL_MEM_GUARD
#endif /*NVTX_NO_IMPL*/
 
#ifdef __GNUC__
#pragma GCC visibility pop
#endif
 
#ifdef __cplusplus
}
#endif /* __cplusplus */