Entry in a schema. More...

#include <nvToolsExtPayload.h>

Data Fields
uint64_t	flags
	Flags to augment the basic type.

uint64_t	type
	Predefined payload schema entry type, registered enum ID, or registered schema ID.

const char *	name
	Name or label of the payload entry. (Optional)

const char *	description
	Description of the payload entry. (Optional)

uint64_t	arrayOrUnionDetail
	String length, array length or member selector for union types.

uint64_t	offset
	Offset in the binary payload data (in bytes).

const nvtxSemanticsHeader_t *	semantics
	Additional semantics of the payload entry.

const void *	reserved
	Reserved for future use.

Detailed Description

Entry in a schema.

Payload schemas are arrays of entries registered with nvtxPayloadSchemaRegister. For simple values, set flags to 0; type is the only required field. Zero-initialized optional fields mean no name and implicit offset calculation.

Example schema: nvtxPayloadSchemaEntry_t schema[] = { {0, NVTX_PAYLOAD_ENTRY_TYPE_UINT8, "one byte"}, {0, NVTX_PAYLOAD_ENTRY_TYPE_INT32, "four bytes"} };

Definition at line 871 of file nvToolsExtPayload.h.

Field Documentation

◆ arrayOrUnionDetail

uint64_t nvtxPayloadSchemaEntry_t::arrayOrUnionDetail

String length, array length or member selector for union types.

If type is a C string type and the entry represents an embedded fixed-size string, this field specifies the string length in string code units (not bytes), and must be at least 1. The byte footprint is this value multiplied by the code-unit width of the string type (see NVTX_PAYLOAD_ENTRY_TYPE_CSTRING). The value 0 does not denote a zero-length embedded string; it selects the pointer/null-terminated form instead. An empty embedded string uses a length of at least 1 with a leading null code unit.

If flags specify that the entry is an array, this field specifies the array length or length-source index depending on the array flag. See NVTX_PAYLOAD_ENTRY_FLAG_ARRAY_* for more details.

If type is a union with schema type NVTX_PAYLOAD_SCHEMA_TYPE_UNION (external selection of the union member), this field contains the index (starting with 0) to an entry of integral type in the same schema. The associated field value specifies the selected union member.

Note: An array of schema type NVTX_PAYLOAD_SCHEMA_TYPE_UNION is not supported. NVTX_PAYLOAD_SCHEMA_TYPE_UNION_WITH_INTERNAL_SELECTOR can be used instead.

Definition at line 935 of file nvToolsExtPayload.h.

◆ description

const char* nvtxPayloadSchemaEntry_t::description

Description of the payload entry. (Optional)

A more detailed description of the data stored with this entry.

Definition at line 908 of file nvToolsExtPayload.h.

◆ flags

uint64_t nvtxPayloadSchemaEntry_t::flags

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_*.

Definition at line 879 of file nvToolsExtPayload.h.

◆ name

const char* nvtxPayloadSchemaEntry_t::name

Name or label of the payload entry. (Optional)

A meaningful name or label helps tools organize and interpret the data.

Definition at line 901 of file nvToolsExtPayload.h.

◆ offset

uint64_t nvtxPayloadSchemaEntry_t::offset

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 start address of the data of this entry.

It is recommended (but not required) to provide the offset. Otherwise, the NVTX handler will determine the offset from natural alignment rules (capped by nvtxPayloadSchemaAttr_t::packAlign when set).

Implicit offset convention: For the first entry (index 0), a value of 0 is always treated as an explicit offset. For all subsequent entries (index > 0), a value of 0 signals the tool to compute the offset implicitly. Therefore, to place a later entry explicitly at byte offset 0, use the first entry slot instead. In dynamic schemas, implicit offsets are computed by advancing a running cursor that is aligned per the entry's type alignment.

Setting the offset can also be used to skip reserved regions in the payload during parsing.

Definition at line 958 of file nvToolsExtPayload.h.

◆ reserved

const void* nvtxPayloadSchemaEntry_t::reserved

Reserved for future use.

Definition at line 971 of file nvToolsExtPayload.h.

◆ semantics

const nvtxSemanticsHeader_t* nvtxPayloadSchemaEntry_t::semantics

Additional semantics of the payload entry.

The field points to the first element in a linked list, which enables multiple semantic extensions.

Definition at line 966 of file nvToolsExtPayload.h.

◆ type

uint64_t nvtxPayloadSchemaEntry_t::type

Predefined payload schema entry type, registered enum ID, or registered schema ID.

The value can be:

A predefined type (NVTX_PAYLOAD_ENTRY_TYPE_*).
A registered schema ID (>= NVTX_PAYLOAD_SCHEMA_ID_STATIC_START), nesting the referenced schema inline. Size and alignment are taken from the referenced schema.
A registered enum ID (>= NVTX_PAYLOAD_SCHEMA_ID_STATIC_START). Byte width is given by nvtxPayloadEnumAttr_t::sizeOfEnum. A tool resolves the integer value to the enum entry name.

Definition at line 894 of file nvToolsExtPayload.h.

The documentation for this struct was generated from the following file:

nvToolsExtPayload.h

Data Fields