Sylvain Jeaugey
5d3ab08b69
Add new NVLS algorithm for allreduce using NVLink SHARP (intra-node only). Add new config options: cgaClusterSize, minCTAs, maxCTAs, netName. Enable LL128 when we use PXN to close rings. NVTX3 includes update. Fix crash when one CollNet (SHARP) rail fails to initialize.
777 lines
26 KiB
C
777 lines
26 KiB
C
/*
|
||
* Copyright 2021-2022 NVIDIA Corporation. All rights reserved.
|
||
*
|
||
* Licensed under the Apache License v2.0 with LLVM Exceptions.
|
||
* See https://llvm.org/LICENSE.txt for license information.
|
||
* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
||
*/
|
||
|
||
#include "nvToolsExt.h"
|
||
|
||
#ifndef NVTOOLSEXT_PAYLOAD_H
|
||
#define NVTOOLSEXT_PAYLOAD_H
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif /* __cplusplus */
|
||
|
||
/**
|
||
* \brief A compatibility ID value used in initialization to identify version
|
||
* differences.
|
||
*/
|
||
#define NVTX_EXT_COMPATID_PAYLOAD 0x0103
|
||
|
||
/**
|
||
* \brief This module ID identifies the payload extension. It has to be unique
|
||
* among the extension modules.
|
||
*/
|
||
#define NVTX_EXT_MODULEID_PAYLOAD 2
|
||
|
||
/**
|
||
* \brief Additional values for the enum @ref nvtxPayloadType_t
|
||
*/
|
||
#define NVTX_PAYLOAD_TYPE_BINARY ((int32_t)0xDFBD0009)
|
||
|
||
|
||
/** ---------------------------------------------------------------------------
|
||
* Payload schema entry flags.
|
||
* ------------------------------------------------------------------------- */
|
||
#define NVTX_PAYLOAD_ENTRY_FLAG_UNUSED 0
|
||
|
||
/**
|
||
* Absolute pointer into a payload (entry) of the same event.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_FLAG_POINTER (1 << 1)
|
||
|
||
/**
|
||
* Offset from base address of the payload.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_FLAG_OFFSET_FROM_BASE (1 << 2)
|
||
|
||
/**
|
||
* Offset from the end of this payload entry.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_FLAG_OFFSET_FROM_HERE (1 << 3)
|
||
|
||
/**
|
||
* The value is an array with fixed length, set with the field `arrayLength`.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_FLAG_ARRAY_FIXED_SIZE (1 << 4)
|
||
|
||
/**
|
||
* The value is a zero-/null-terminated array.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_FLAG_ARRAY_ZERO_TERMINATED (2 << 4)
|
||
|
||
/**
|
||
* \brief A single or multi-dimensional array of variable length.
|
||
*
|
||
* The field `arrayLength` contains the index of the schema entry that holds the
|
||
* length(s). If the other field points to a scalar entry then this will be the
|
||
* 1D array. If the other field points to a FIXED_SIZE array, then the number of
|
||
* dimensions is defined with the registration of the scheme. If the other field
|
||
* is ZERO_TERMINATED, the array the dimensions can be determined at runtime.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_FLAG_ARRAY_LENGTH_INDEX (3 << 4)
|
||
|
||
/**
|
||
* A tool may not support deep copy and just ignore this flag.
|
||
* See @ref NVTX_PAYLOAD_SCHEMA_FLAG_DEEP_COPY for more details.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_FLAG_DEEP_COPY (1 << 9)
|
||
|
||
/**
|
||
* The entry specifies the message in a deferred event. The entry type can be
|
||
* any string type. The flag is ignored for schemas that are not flagged with
|
||
* `NVTX_PAYLOAD_SCHEMA_FLAG_RANGE*` or `NVTX_PAYLOAD_SCHEMA_FLAG_MARK`.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_FLAG_EVENT_MESSAGE (1 << 10)
|
||
|
||
/**
|
||
* @note The ‘array’ flags assume that the array is embedded. Otherwise,
|
||
* @ref NVTX_PAYLOAD_ENTRY_FLAG_POINTER has to be additionally specified. Some
|
||
* combinations may be invalid based on the `NVTX_PAYLOAD_SCHEMA_TYPE_*` this
|
||
* entry is enclosed. For instance, variable length embedded arrays are valid
|
||
* within @ref NVTX_PAYLOAD_SCHEMA_TYPE_DYNAMIC but invalid with
|
||
* @ref NVTX_PAYLOAD_SCHEMA_TYPE_STATIC. See `NVTX_PAYLOAD_SCHEMA_TYPE_*` for
|
||
* additional details.
|
||
*/
|
||
|
||
/* Helper macro to check if an entry represents an array. */
|
||
#define NVTX_PAYLOAD_ENTRY_FLAG_IS_ARRAY (\
|
||
NVTX_PAYLOAD_ENTRY_FLAG_ARRAY_FIXED_SIZE | \
|
||
NVTX_PAYLOAD_ENTRY_FLAG_ARRAY_ZERO_TERMINATED | \
|
||
NVTX_PAYLOAD_ENTRY_FLAG_ARRAY_LENGTH_INDEX)
|
||
|
||
/** ---------------------------------------------------------------------------
|
||
* Types of entries in a payload schema.
|
||
* ------------------------------------------------------------------------- */
|
||
|
||
/**
|
||
* @note Several of the predefined types contain the size (in bits) in their
|
||
* names. For some data types the size (in bytes) is not fixed and may differ
|
||
* for different platforms/operating systems/compilers. To provide portability,
|
||
* an array of sizes (in bytes) for type 1 to 28 ( @ref
|
||
* NVTX_PAYLOAD_ENTRY_TYPE_CHAR to @ref NVTX_PAYLOAD_ENTRY_TYPE_INFO_ARRAY_SIZE)
|
||
* is passed to the NVTX extension initialization function
|
||
* @ref InitializeInjectionNvtxExtension via the `extInfo` field of
|
||
* @ref nvtxExtModuleInfo_t.
|
||
*/
|
||
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_INVALID 0
|
||
|
||
/**
|
||
* Basic integer types.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_CHAR 1
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_UCHAR 2
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_SHORT 3
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_USHORT 4
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_INT 5
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_UINT 6
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_LONG 7
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_ULONG 8
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_LONGLONG 9
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_ULONGLONG 10
|
||
|
||
/**
|
||
* Integer types with explicit size.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_INT8 11
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_UINT8 12
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_INT16 13
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_UINT16 14
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_INT32 15
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_UINT32 16
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_INT64 17
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_UINT64 18
|
||
|
||
/**
|
||
* C floating point types
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_FLOAT 19
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_DOUBLE 20
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_LONGDOUBLE 21
|
||
|
||
/**
|
||
* Size type (`size_t`)
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_SIZE 22
|
||
|
||
/**
|
||
* Any address, e.g. `void*`. If the pointer type matters, use the flag @ref
|
||
* NVTX_PAYLOAD_ENTRY_FLAG_POINTER and the respective type instead.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_ADDRESS 23
|
||
|
||
/**
|
||
* Special character types.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_WCHAR 24 /* wide character (since C90) */
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_CHAR8 25 /* since C2x and C++20 */
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_CHAR16 26
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_CHAR32 27
|
||
|
||
/**
|
||
* There is type size and alignment information for all previous types.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_INFO_ARRAY_SIZE (NVTX_PAYLOAD_ENTRY_TYPE_CHAR32 + 1)
|
||
|
||
/**
|
||
* Store raw 8-bit binary data. As with `char`, 1-byte alignment is assumed.
|
||
* Typically a tool will display this as hex or binary.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_BYTE 32
|
||
|
||
/**
|
||
* These types do not have standardized equivalents. It is assumed that the
|
||
* number at the end corresponds to the bits used to store the value and that
|
||
* the alignment corresponds to standardized types of the same size.
|
||
* A tool may not support these types.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_INT128 33
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_UINT128 34
|
||
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_FLOAT16 42
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_FLOAT32 43
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_FLOAT64 44
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_FLOAT128 45
|
||
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_BF16 50
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TF32 52
|
||
|
||
/**
|
||
* These types are normalized numbers stored in integers. UNORMs represent 0.0
|
||
* to 1.0 and SNORMs represent -1.0 to 1.0. The number after represents the
|
||
* number of integer bits. Alignment is take from equivalent types INT# matching
|
||
* to SNORM# and UINT# matching to UNORM#.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_SNORM8 61
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_UNORM8 62
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_SNORM16 63
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_UNORM16 64
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_SNORM32 65
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_UNORM32 66
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_SNORM64 67
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_UNORM64 68
|
||
|
||
/**
|
||
* String types.
|
||
*
|
||
* If `arrayOrUnionDetail` is greater than `0`, the entry is a fixed-size string
|
||
* with the provided length.
|
||
*
|
||
* `NVTX_PAYLOAD_ENTRY_FLAG_ARRAY_FIXED_SIZE` is ignored for string types. It
|
||
* just specifies once more that the entry is a fixed-size string.
|
||
*
|
||
* Setting the flag `NVTX_PAYLOAD_ENTRY_FLAG_ARRAY_ZERO_TERMINATED` indicates a
|
||
* zero-terminated string. If `arrayOrUnionDetail` is greater than `0`, a zero-
|
||
* terminated array of fixed-size strings is assumed.
|
||
*
|
||
* Setting the flag `NVTX_PAYLOAD_ENTRY_FLAG_ARRAY_LENGTH_INDEX` specifies the
|
||
* entry index of the entry which contains the string length. It is not possible
|
||
* to describe a variable length array of strings.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_CSTRING 75 /* `char*`, system LOCALE */
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_CSTRING_UTF8 76
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_CSTRING_UTF16 77
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_CSTRING_UTF32 78
|
||
|
||
/**
|
||
* @ref nvtxStringHandle_t returned by @ref nvtxDomainRegisterString
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_NVTX_REGISTERED_STRING_HANDLE 80
|
||
|
||
/**
|
||
* Entry types to be used in deferred events. Data types are as defined by
|
||
* NVTXv3 core: category -> uint32_t, color -> uint32_t, color type -> int32_t.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_NVTX_CATEGORY 90
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_NVTX_COLORTYPE 91
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_NVTX_COLOR 92
|
||
|
||
/**
|
||
* This type marks the union selector member (entry index) in schemas used by
|
||
* a union with internal internal selector.
|
||
* See @ref NVTX_PAYLOAD_SCHEMA_TYPE_UNION_WITH_INTERNAL_SELECTOR.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_UNION_SELECTOR 100
|
||
|
||
/**
|
||
* Timestamp types occupy the range from 128 to 255
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP64 128 /* data type is uint64_t */
|
||
|
||
/**
|
||
* CPU timestamp sources.
|
||
* \todo All 64 bits?
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPU_TSC 129
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPU_TSC_NONVIRTUALIZED 130
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPU_CLOCK_GETTIME_REALTIME 131
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPU_CLOCK_GETTIME_REALTIME_COARSE 132
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPU_CLOCK_GETTIME_MONOTONIC 133
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPU_CLOCK_GETTIME_MONOTONIC_RAW 134
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPU_CLOCK_GETTIME_MONOTONIC_COARSE 135
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPU_CLOCK_GETTIME_BOOTTIME 136
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPU_CLOCK_GETTIME_PROCESS_CPUTIME_ID 137
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPU_CLOCK_GETTIME_THREAD_CPUTIME_ID 138
|
||
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_WIN_QPC 160
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_WIN_GSTAFT 161
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_WIN_GSTAFTP 162
|
||
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_C_TIME 163
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_C_CLOCK 164
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_C_TIMESPEC_GET 165
|
||
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPP_STEADY_CLOCK 166
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPP_HIGH_RESOLUTION_CLOCK 167
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPP_SYSTEM_CLOCK 168
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPP_UTC_CLOCK 169
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPP_TAI_CLOCK 170
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPP_GPS_CLOCK 171
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_CPP_FILE_CLOCK 172
|
||
|
||
/**
|
||
* \brief GPU timestamp sources.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_GPU_GLOBALTIMER 192
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_GPU_SM_CLOCK 193
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_GPU_SM_CLOCK64 194
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_GPU_CUPTI 195
|
||
|
||
/**
|
||
* The timestamp was provided by the NVTX handler’s timestamp routine.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_TIMESTAMP_TOOL_PROVIDED 224
|
||
|
||
/**
|
||
* This predefined schema ID can be used in `nvtxPayloadData_t` to indicate that
|
||
* the payload is a blob of memory which other payload entries may point into.
|
||
* A tool will not expose this payload directly.
|
||
*/
|
||
#define NVTX_TYPE_PAYLOAD_SCHEMA_REFERENCED 1022
|
||
|
||
/**
|
||
* This predefined schema ID can be used in `nvtxPayloadData_t` to indicate that
|
||
* the payload is a blob which can be shown with an arbitrary data viewer.
|
||
*/
|
||
#define NVTX_TYPE_PAYLOAD_SCHEMA_RAW 1023
|
||
|
||
/* Custom (static) schema IDs. */
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_SCHEMA_ID_STATIC_START (1 << 24)
|
||
|
||
/* Dynamic schema IDs (generated by the tool) start here. */
|
||
#define NVTX_PAYLOAD_ENTRY_TYPE_SCHEMA_ID_DYNAMIC_START 4294967296 // 1 << 32
|
||
|
||
|
||
/**
|
||
* \brief Size and alignment information for predefined payload entry types.
|
||
*
|
||
* The struct contains the size and the alignment size in bytes. A respective
|
||
* array for the predefined types is passed via nvtxExtModuleInfo_t to the NVTX
|
||
* client/handler. The type (ID) is used as index into this array.
|
||
*/
|
||
typedef struct nvtxPayloadEntryTypeInfo_t
|
||
{
|
||
uint16_t size;
|
||
uint16_t align;
|
||
} nvtxPayloadEntryTypeInfo_t;
|
||
|
||
/**
|
||
* \brief Entry in a schema.
|
||
*
|
||
* A payload schema consists of an array of payload schema entries. It is
|
||
* registered with @ref nvtxPayloadSchemaRegister. `flag` can be set to `0` for
|
||
* simple values, 'type' is the only "required" field. If not set explicitly,
|
||
* all other fields are zero-initialized, which means that the entry has no name
|
||
* and the offset is determined based on self-alignment rules.
|
||
*
|
||
* Example schema:
|
||
* nvtxPayloadSchemaEntry_t desc[] = {
|
||
* {0, NVTX_EXT_PAYLOAD_TYPE_UINT8, "one byte"},
|
||
* {0, NVTX_EXT_PAYLOAD_TYPE_INT32, "four bytes"}
|
||
* };
|
||
*/
|
||
typedef struct nvtxPayloadSchemaEntry_t
|
||
{
|
||
/**
|
||
* \brief Flags to augment the basic type.
|
||
*
|
||
* This field allows additional properties of the payload entry to be
|
||
* specified. Valid values are `NVTX_PAYLOAD_ENTRY_FLAG_*`.
|
||
*/
|
||
uint64_t flags;
|
||
|
||
/**
|
||
* \brief Predefined payload schema entry type or ID of a registered payload
|
||
* schema.
|
||
*/
|
||
uint64_t type;
|
||
|
||
/**
|
||
* \brief Name of the payload entry. (Optional)
|
||
*
|
||
* Providing a name is useful to give a meaning to the associated value.
|
||
*/
|
||
const char* name;
|
||
|
||
/**
|
||
* \brief Description of the payload entry. (Optional)
|
||
*/
|
||
const char* description;
|
||
|
||
/**
|
||
* \brief String or array length or union selector for union types.
|
||
*
|
||
* If @ref type is a C string type, this defines the length of the string.
|
||
*
|
||
* If @ref flags specify that the entry is an array, this field defines the
|
||
* length of the array. See `NVTX_PAYLOAD_ENTRY_FLAG_ARRAY_*` for more
|
||
* details.
|
||
*
|
||
* If @ref type implies that the entry is a union with schema type
|
||
* @ref NVTX_PAYLOAD_SCHEMA_TYPE_UNION (external selection of the union
|
||
* member), this field contains the index (starting with 0) to an entry of
|
||
* integer type in the same schema. The associated field contains the
|
||
* selected union member.
|
||
*
|
||
* @note An array of schema type @ref NVTX_PAYLOAD_SCHEMA_TYPE_UNION is not
|
||
* supported. @ref NVTX_PAYLOAD_SCHEMA_TYPE_UNION_WITH_INTERNAL_SELECTOR can
|
||
* be used instead.
|
||
*/
|
||
uint64_t arrayOrUnionDetail;
|
||
|
||
/**
|
||
* \brief Offset in the binary payload data (in bytes).
|
||
*
|
||
* This field specifies the byte offset from the base address of the actual
|
||
* binary data (blob) to the data of this entry.
|
||
*
|
||
* This is an optional field, but it is recommended to specify this field to
|
||
* avoid issues in the automatic detection of the offset by a tool/handler.
|
||
*/
|
||
uint64_t offset;
|
||
|
||
/**
|
||
* Semantics are not yet defined.
|
||
*/
|
||
void* semantics;
|
||
|
||
/**
|
||
* Reserved for future use. Do not use it!
|
||
*/
|
||
void* reserved;
|
||
} nvtxPayloadSchemaEntry_t;
|
||
|
||
/**
|
||
* \brief Binary payload data, size and decoding information.
|
||
*
|
||
* An array of nvtxPayloadData_t is passed to the NVTX event attribute payload
|
||
* member. To attach a single payload the macro @ref NVTX_EXT_PAYLOAD_SET_ATTR
|
||
* can be used.
|
||
*/
|
||
typedef struct nvtxPayloadData_t
|
||
{
|
||
/**
|
||
* The schema ID, which defines the layout of the binary data.
|
||
*/
|
||
uint64_t schemaId;
|
||
|
||
/**
|
||
* Size of the binary payload (blob) in bytes.
|
||
*/
|
||
size_t size;
|
||
|
||
/**
|
||
* Pointer to the binary payload data.
|
||
*/
|
||
const void* payload;
|
||
} nvtxPayloadData_t;
|
||
|
||
/* Helper macros for safe double-cast of pointer to uint64_t value */
|
||
#ifndef NVTX_POINTER_AS_PAYLOAD_ULLVALUE
|
||
# ifdef __cplusplus
|
||
# define NVTX_POINTER_AS_PAYLOAD_ULLVALUE(p) \
|
||
static_cast<uint64_t>(reinterpret_cast<uintptr_t>(p))
|
||
# else
|
||
#define NVTX_POINTER_AS_PAYLOAD_ULLVALUE(p) ((uint64_t)(uintptr_t)p)
|
||
# endif
|
||
#endif
|
||
|
||
|
||
#define NVTX_PAYLOAD_CONCAT2(a,b) a##b
|
||
#define NVTX_PAYLOAD_CONCAT(a,b) NVTX_PAYLOAD_CONCAT2(a,b)
|
||
#define NVTX_DATA_VAR NVTX_PAYLOAD_CONCAT(nvtxDFDB,__LINE__)
|
||
|
||
/**
|
||
* \brief Helper macro to attach a single payload to an NVTX event attribute.
|
||
*
|
||
* @note The NVTX push, start or mark operation must not be in the same or a
|
||
* nested scope.
|
||
*/
|
||
#define NVTX_PAYLOAD_EVTATTR_SET(EVTATTR, SCHEMA_ID, PAYLOAD_ADDR, SIZE) \
|
||
nvtxPayloadData_t NVTX_DATA_VAR[] = {{SCHEMA_ID, SIZE, PAYLOAD_ADDR}}; \
|
||
(EVTATTR).payload.ullValue = \
|
||
NVTX_POINTER_AS_PAYLOAD_ULLVALUE(NVTX_DATA_VAR); \
|
||
(EVTATTR).payloadType = NVTX_PAYLOAD_TYPE_BINARY; \
|
||
(EVTATTR).reserved0 = 1;
|
||
|
||
/**
|
||
* \brief Helper macro to attach multiple payloads to an NVTX event attribute.
|
||
*
|
||
* The payload data array (`nvtxPayloadData_t`) is passed as first argument to
|
||
* this macro.
|
||
*/
|
||
#define NVTX_PAYLOAD_EVTATTR_SET_MULTIPLE(EVTATTR, PAYLOADS) \
|
||
(EVTATTR).payloadType = NVTX_PAYLOAD_TYPE_BINARY; \
|
||
(EVTATTR).reserved0 = sizeof(PAYLOADS)/sizeof(nvtxPayloadData_t); \
|
||
(EVTATTR).payload.ullValue = NVTX_POINTER_AS_PAYLOAD_ULLVALUE(PAYLOADS);
|
||
|
||
|
||
/**
|
||
* \brief The payload schema type.
|
||
*
|
||
* A schema can be either of these types.
|
||
*/
|
||
enum nvtxPayloadSchemaType
|
||
{
|
||
NVTX_PAYLOAD_SCHEMA_TYPE_INVALID = 0,
|
||
|
||
NVTX_PAYLOAD_SCHEMA_TYPE_STATIC = 1,
|
||
NVTX_PAYLOAD_SCHEMA_TYPE_DYNAMIC = 2,
|
||
|
||
NVTX_PAYLOAD_SCHEMA_TYPE_UNION = 3,
|
||
NVTX_PAYLOAD_SCHEMA_TYPE_UNION_WITH_INTERNAL_SELECTOR = 4
|
||
};
|
||
|
||
/**
|
||
* \brief Flags for static and dynamic schemas.
|
||
*/
|
||
enum nvtxPayloadSchemaFlags
|
||
{
|
||
NVTX_PAYLOAD_SCHEMA_FLAG_NONE = 0,
|
||
|
||
/**
|
||
* This flag indicates that a schema and the corresponding payloads can
|
||
* contain fields which require a deep copy.
|
||
*/
|
||
NVTX_PAYLOAD_SCHEMA_FLAG_DEEP_COPY = (1 << 1),
|
||
|
||
/**
|
||
* This flag indicates that a schema and the corresponding payloads can
|
||
* be referenced by another payload of the same event.
|
||
*/
|
||
NVTX_PAYLOAD_SCHEMA_FLAG_REFERENCED = (1 << 2),
|
||
|
||
/**
|
||
* The schema describes a deferred event/marker. Such a schema requires one
|
||
* timestamp entry and one string entry with the flag
|
||
* `NVTX_PAYLOAD_ENTRY_FLAG_EVENT_MESSAGE`. Category and color can be
|
||
* optionally specified with the respective entry types. The deferred event
|
||
* can contain a binary payload itself by using a custom schema ID as type
|
||
* its schema description. Multiple occurrences of the same event can be
|
||
* described by specifying an array timestamps.
|
||
*/
|
||
NVTX_PAYLOAD_SCHEMA_FLAG_DEFERRED_EVENT = (1 << 3),
|
||
/**
|
||
* The schema describes a deferred event/marker. Such a schema requires
|
||
* one start timestamp, one end timestamp and one string entry with the flag
|
||
* `NVTX_PAYLOAD_ENTRY_FLAG_EVENT_MESSAGE`. Category and color can be
|
||
* optionally specified with the respective entry types. The deferred range
|
||
* can contain a binary payload itself by using a custom schema ID as type
|
||
* its schema description.
|
||
*
|
||
* Timestamps can be provided in different ways:
|
||
* - A single range has two timestamp entries with the first (smaller entry
|
||
* index) being used as the start/push timestamp.
|
||
* - If the range schema contains one array of timestamps, the tool assumes
|
||
* that the array contains alternating start and end timestamps.
|
||
* - If two timestamp arrays are specified the first entry (with the
|
||
* smaller entry index) is assumed to contain the start timestamps. Both
|
||
* arrays have to be of the same size.
|
||
*/
|
||
NVTX_PAYLOAD_SCHEMA_FLAG_DEFERRED_RANGE = (2 << 3)
|
||
};
|
||
|
||
/**
|
||
* The values allow the valid fields in @ref nvtxPayloadSchemaAttr_t to be
|
||
* specified via setting the field `fieldMask`.
|
||
*/
|
||
#define NVTX_PAYLOAD_SCHEMA_ATTR_NAME (1 << 1)
|
||
#define NVTX_PAYLOAD_SCHEMA_ATTR_TYPE (1 << 2)
|
||
#define NVTX_PAYLOAD_SCHEMA_ATTR_FLAGS (1 << 3)
|
||
#define NVTX_PAYLOAD_SCHEMA_ATTR_ENTRIES (1 << 4)
|
||
#define NVTX_PAYLOAD_SCHEMA_ATTR_NUM_ENTRIES (1 << 5)
|
||
#define NVTX_PAYLOAD_SCHEMA_ATTR_STATIC_SIZE (1 << 6)
|
||
#define NVTX_PAYLOAD_SCHEMA_ATTR_ALIGNMENT (1 << 7)
|
||
#define NVTX_PAYLOAD_SCHEMA_ATTR_SCHEMA_ID (1 << 8)
|
||
|
||
/**
|
||
* NVTX payload schema attributes.
|
||
*/
|
||
typedef struct nvtxPayloadSchemaAttr_t
|
||
{
|
||
/**
|
||
* \brief Mask of valid fields in this structure.
|
||
*
|
||
* The values from `enum nvtxPayloadSchemaAttributes` have to be used.
|
||
*/
|
||
uint64_t fieldMask;
|
||
|
||
/**
|
||
* \brief Name of the payload schema. (Optional)
|
||
*/
|
||
const char* name;
|
||
|
||
/**
|
||
* \brief Payload schema type. (Mandatory) \anchor PAYLOAD_TYPE_FIELD
|
||
*
|
||
* A value from `enum nvtxPayloadSchemaType` has to be used.
|
||
*/
|
||
uint64_t type;
|
||
|
||
/**
|
||
* \brief Payload schema flags. (Optional)
|
||
*
|
||
* Flags defined in `enum nvtxPayloadSchemaFlags` can be used to set
|
||
* additional properties of the schema.
|
||
*/
|
||
uint64_t flags;
|
||
|
||
/**
|
||
* \brief Entries of a payload schema. (Mandatory) \anchor ENTRIES_FIELD
|
||
*
|
||
* This field is a pointer to an array of schema entries, each describing a
|
||
* field in a data structure, e.g. in a C struct or union.
|
||
*/
|
||
const nvtxPayloadSchemaEntry_t* entries;
|
||
|
||
/**
|
||
* \brief Number of entries in the payload schema. (Mandatory)
|
||
*
|
||
* Number of entries in the array of payload entries \ref ENTRIES_FIELD.
|
||
*/
|
||
size_t numEntries;
|
||
|
||
/**
|
||
* \brief The binary payload size in bytes for static payload schemas.
|
||
*
|
||
* If \ref PAYLOAD_TYPE_FIELD is @ref NVTX_PAYLOAD_SCHEMA_TYPE_DYNAMIC this
|
||
* value is ignored. If this field is not specified for a schema of type
|
||
* @ref NVTX_PAYLOAD_SCHEMA_TYPE_STATIC, the size can be automatically
|
||
* determined by a tool.
|
||
*/
|
||
size_t payloadStaticSize;
|
||
|
||
/**
|
||
* \brief The byte alignment for packed structures.
|
||
*
|
||
* If not specified, this field defaults to `0`, which means that the fields
|
||
* in the data structure are not packed and natural alignment rules can be
|
||
* applied.
|
||
*/
|
||
size_t packAlign;
|
||
|
||
/* Static/custom schema ID must be
|
||
>= NVTX_PAYLOAD_ENTRY_TYPE_SCHEMA_ID_STATIC_START and
|
||
< NVTX_PAYLOAD_ENTRY_TYPE_SCHEMA_ID_DYNAMIC_START */
|
||
uint64_t schemaId;
|
||
} nvtxPayloadSchemaAttr_t;
|
||
|
||
/**
|
||
* \brief Register a payload schema.
|
||
*
|
||
* @param domain NVTX domain handle.
|
||
* @param attr NVTX payload schema attributes.
|
||
*/
|
||
NVTX_DECLSPEC uint64_t NVTX_API nvtxPayloadSchemaRegister(
|
||
nvtxDomainHandle_t domain, const nvtxPayloadSchemaAttr_t* attr);
|
||
|
||
/**
|
||
* \brief Enumeration entry.
|
||
*
|
||
* Since the value of an enum entry might not be meaningful for the analysis,
|
||
* a tool can show the name of enum entry instead.
|
||
*
|
||
* @note EXPERIMENTAL
|
||
*/
|
||
typedef struct nvtxPayloadEnum_t
|
||
{
|
||
/**
|
||
* Name of the enum value.
|
||
*/
|
||
const char* name;
|
||
|
||
/**
|
||
* Value of the enum entry.
|
||
*/
|
||
uint64_t value;
|
||
|
||
/**
|
||
* Indicates that this entry sets a specific set of bits, which can be used
|
||
* to easily define bitsets.
|
||
*/
|
||
int8_t isFlag;
|
||
} nvtxPayloadEnum_t;
|
||
|
||
/**
|
||
* The values are used to set the field `fieldMask` and specify which fields in
|
||
* `nvtxPayloadEnumAttr_t` are set.
|
||
*/
|
||
#define NVTX_PAYLOAD_ENUM_ATTR_NAME (1 << 1)
|
||
#define NVTX_PAYLOAD_ENUM_ATTR_ENTRIES (1 << 2)
|
||
#define NVTX_PAYLOAD_ENUM_ATTR_NUM_ENTRIES (1 << 3)
|
||
#define NVTX_PAYLOAD_ENUM_ATTR_SIZE (1 << 4)
|
||
#define NVTX_PAYLOAD_ENUM_ATTR_SCHEMA_ID (1 << 5)
|
||
|
||
/**
|
||
* NVTX payload enumeration type attributes.
|
||
*/
|
||
typedef struct nvtxPayloadEnumAttr_t {
|
||
/**
|
||
* Mask of valid fields in this struct.
|
||
* The values from `enum nvtxPayloadSchemaAttributes` have to be used.
|
||
*/
|
||
uint64_t fieldMask;
|
||
|
||
/**
|
||
* Name of the enum. (Optional)
|
||
*/
|
||
const char* name;
|
||
|
||
/**
|
||
* Entries of the enum. (Mandatory)
|
||
*/
|
||
const nvtxPayloadEnum_t* entries;
|
||
|
||
/**
|
||
* Number of entries in the enum. (Mandatory)
|
||
*/
|
||
size_t numEntries;
|
||
|
||
/**
|
||
* Size of enumeration type in bytes
|
||
*/
|
||
size_t sizeOfEnum;
|
||
|
||
/**
|
||
* Static/custom schema ID must be
|
||
* >= NVTX_PAYLOAD_ENTRY_TYPE_SCHEMA_ID_STATIC_START and
|
||
* < NVTX_PAYLOAD_ENTRY_TYPE_SCHEMA_ID_DYNAMIC_START
|
||
*/
|
||
uint64_t schemaId;
|
||
} nvtxPayloadEnumAttr_t;
|
||
|
||
/**
|
||
* \brief Register an enumeration type with the payload extension.
|
||
*
|
||
* @param domain NVTX domain handle
|
||
* @param attr NVTX payload enumeration type attributes.
|
||
*/
|
||
NVTX_DECLSPEC uint64_t nvtxPayloadEnumRegister(nvtxDomainHandle_t domain,
|
||
const nvtxPayloadEnumAttr_t* attr);
|
||
|
||
/**
|
||
* \brief Callback Ids of API functions in the payload extension.
|
||
*
|
||
* The NVTX handler can use these values to register a handler function. When
|
||
* InitializeInjectionNvtxExtension(nvtxExtModuleInfo_t* moduleInfo) is
|
||
* executed, a handler routine 'handlenvtxPayloadRegisterSchema' can be
|
||
* registered as follows:
|
||
* moduleInfo->segments->slots[NVTX3EXT_CBID_nvtxPayloadSchemaRegister] =
|
||
* (intptr_t)handlenvtxPayloadRegisterSchema;
|
||
*/
|
||
typedef enum NvtxExtPayloadCallbackId
|
||
{
|
||
NVTX3EXT_CBID_nvtxPayloadSchemaRegister = 0,
|
||
NVTX3EXT_CBID_nvtxPayloadEnumRegister = 1,
|
||
NVTX3EXT_CBID_PAYLOAD_FN_NUM = 2
|
||
} NvtxExtPayloadCallbackId;
|
||
|
||
#ifdef __GNUC__
|
||
#pragma GCC visibility push(internal)
|
||
#endif
|
||
|
||
#define NVTX_EXT_TYPES_GUARD /* Ensure other headers cannot include directly */
|
||
#include "nvtxExtDetail/nvtxExtTypes.h"
|
||
#undef NVTX_EXT_TYPES_GUARD
|
||
|
||
#ifndef NVTX_NO_IMPL
|
||
#define NVTX_EXT_IMPL_PAYLOAD_GUARD /* Ensure other headers cannot included directly */
|
||
#include "nvtxExtDetail/nvtxExtPayloadTypeInfo.h"
|
||
#include "nvtxExtDetail/nvtxExtImplPayload_v1.h"
|
||
#undef NVTX_EXT_IMPL_PAYLOAD_GUARD
|
||
#endif /*NVTX_NO_IMPL*/
|
||
|
||
#ifdef __GNUC__
|
||
#pragma GCC visibility pop
|
||
#endif
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif /* __cplusplus */
|
||
|
||
#endif /* NVTOOLSEXT_PAYLOAD_H */
|