Helper macros for defining NVTX binary payload schemas. More...

Include dependency graph for nvToolsExtPayloadHelper.h:

Macros
#define	NVTX_PAYLOAD_ENTRIES

#define	NVTX_PAYLOAD_NESTED(schemaId) _NVTX_PAYLOAD_NESTED(schemaId)

#define	NVTX_DEFINE_SCHEMA_FOR_STRUCT(struct_id, ...) _NVTX_DEFINE_SCHEMA_FOR_STRUCT(struct_id, __VA_ARGS__)
	Define a payload schema for an existing C `struct` definition.

#define	NVTX_DEFINE_STRUCT_WITH_SCHEMA(struct_id, ...) _NVTX_DEFINE_STRUCT_WITH_SCHEMA(struct_id, __VA_ARGS__)
	Define a C struct together with a matching schema.

#define	NVTX_DEFINE_STRUCT_WITH_SCHEMA_AND_REGISTER(domain, struct_id, ...)
	Initialize and register the NVTX binary payload schema.

#define	NVTX_DEFINE_SCHEMA_FOR_STRUCT_AND_REGISTER(domain, struct_id, ...)
	Define payload schema for an existing `struct` and register the schema.

#define	NVTX_DEFINE_STRUCT(struct_id, ...) _NVTX_PAYLOAD_TYPEDEF_STRUCT(struct_id, __VA_ARGS__)
	Create a type definition for the given struct ID and members.

#define	NVTX_PAYLOAD_SCHEMA_REGISTER(domain, struct_id) nvtxPayloadSchemaRegister(domain, &struct_id##Attr)
	Register an NVTX binary payload schema.

Detailed Description

Helper macros for defining NVTX binary payload schemas.

MSVC Preprocessor Requirement

Several macros in this header rely on variadic macro argument counting and dispatch, which requires a standards-conforming preprocessor. On Microsoft Visual C++, the traditional preprocessor does not expand __VA_ARGS__ correctly for these patterns. To use the affected macros (listed below) with MSVC, enable the modern conforming preprocessor:

Visual Studio 2019 and newer: /Zc:preprocessor
Visual Studio 2017 (v15.5+): /experimental:preprocessor

Visual Studio versions older than 2017 do not support the conforming preprocessor and cannot use these macros.

Affected macros:

GCC, Clang, and other compilers with conforming preprocessors work without any additional flags.

Definition in file nvToolsExtPayloadHelper.h.

Macro Definition Documentation

◆ NVTX_DEFINE_SCHEMA_FOR_STRUCT

#define NVTX_DEFINE_SCHEMA_FOR_STRUCT	(	struct_id,
		...
	)	_NVTX_DEFINE_SCHEMA_FOR_STRUCT(struct_id, __VA_ARGS__)

Define a payload schema for an existing C struct definition.

This macro does 1) create schema description (array of schema entries). 2) set the schema attributes for a static data layout.

It can be used in static code or within a function context.

Example: NVTX_DEFINE_SCHEMA_FOR_STRUCT(your_struct, "SchemaName", NVTX_PAYLOAD_ENTRIES( (index, TYPE_INT, "integer value"), (dpfloat, TYPE_DOUBLE, "fp64 value"), (text, TYPE_CSTRING, "text", NULL, 24) ) )

It is required to at least provide the struct name and the payload entries. The first two fields (member name and NVTX entry type) of each payload entry are required.

The optional parameters are only allowed to be passed in the predefined order. Hence, payload_flags requires payload_schema to be given and prefix requires payload_flags and payload_schema to be given. The payload entries are always the last parameter. A maximum of 16 schema entries is supported.

It is recommended to use NVTX_PAYLOAD_SCHEMA_REGISTER to register the schema.

Parameters

struct_id	The name of the struct.
schema_name	(Optional 1) name of the payload schema. Default is `NULL`.
prefix	(Optional 2) prefix before the schema and attributes variables, e.g. `static const`. Leave this empty, if no prefix is desired.
schema_flags	(Optional 2) flags to augment the payload schema. Default is `NVTX_PAYLOAD_SCHEMA_FLAG_NONE`.
schema_id	(Optional 4) User-defined payload schema ID.
entries	(Mandatory) Payload schema entries. This is always the last parameter to the macro.

Note: On MSVC, this macro requires the conforming preprocessor: /Zc:preprocessor (VS 2019+) or /experimental:preprocessor (VS 2017 v15.5+). Not supported on older MSVC versions.

Definition at line 116 of file nvToolsExtPayloadHelper.h.

◆ NVTX_DEFINE_SCHEMA_FOR_STRUCT_AND_REGISTER

#define NVTX_DEFINE_SCHEMA_FOR_STRUCT_AND_REGISTER	(	domain,
		struct_id,
		...
	)

Value:

_NVTX_DEFINE_SCHEMA_FOR_STRUCT(struct_id, __VA_ARGS__) \

const uint64_t struct_id##_schemaId = nvtxPayloadSchemaRegister(domain, &struct_id##Attr);

Define payload schema for an existing struct and register the schema.

This does essentially the same as NVTX_PAYLOAD_STATIC_SCHEMA_DEFINE, but in addition, the schema is registered and uint64_t struct_id##_schemaId set.

Parameters

domain The NVTX domain handle. All other parameters are similar to NVTX_PAYLOAD_STATIC_SCHEMA_DEFINE.

Note: On MSVC, this macro requires the conforming preprocessor: /Zc:preprocessor (VS 2019+) or /experimental:preprocessor (VS 2017 v15.5+). Not supported on older MSVC versions.

Definition at line 198 of file nvToolsExtPayloadHelper.h.

◆ NVTX_DEFINE_STRUCT

#define NVTX_DEFINE_STRUCT	(	struct_id,
		...
	)	_NVTX_PAYLOAD_TYPEDEF_STRUCT(struct_id, __VA_ARGS__)

Create a type definition for the given struct ID and members.

This is a convenience macro. A normal typedef can be used instead.

Example usage: NVTX_DEFINE_STRUCT(your_struct, (double, fp64), (uint8_t, u8), (float, fp32[3]) )

Parameters

struct_id	The name of the struct.
members	The members of the struct.

Note: On MSVC, this macro requires the conforming preprocessor: /Zc:preprocessor (VS 2019+) or /experimental:preprocessor (VS 2017 v15.5+). Not supported on older MSVC versions.

Definition at line 221 of file nvToolsExtPayloadHelper.h.

◆ NVTX_DEFINE_STRUCT_WITH_SCHEMA

#define NVTX_DEFINE_STRUCT_WITH_SCHEMA	(	struct_id,
		...
	)	_NVTX_DEFINE_STRUCT_WITH_SCHEMA(struct_id, __VA_ARGS__)

Define a C struct together with a matching schema.

This macro does 1) define the payload type (typedef struct). 2) create schema description (array of schema entries). 3) set the schema attributes for a static data layout.

The macro can be used in static code or within a function context.

It defines the schema attributes in struct_id##Attr. Thus, it is recommended to use NVTX_PAYLOAD_SCHEMA_REGISTER(domain, struct_id) to register the schema.

Example: NVTX_DEFINE_STRUCT_WITH_SCHEMA(your_struct_name, "Your schema name", NVTX_PAYLOAD_ENTRIES( (int, index, TYPE_INT, "integer value"), (double, dpfloat, TYPE_DOUBLE, "fp64 value"), (const char, (text, 24), TYPE_CSTRING, "text", NULL, 24) ) )

The first three fields (C type, member, entry type) of each entry are required. A fixed-size array or string requires a special notation with the member name and the size separated by comma and put into brackets (see last entry in the example).

The optional parameters are positional (only allowed to be passed in the predefined order). A maximum of 16 schema entries is supported.

Parameters

struct_id	The name of the struct.
schema_name	(Optional 1) name of the payload schema. Default is `NULL`.
prefix	(Optional 2) prefix before the schema and attributes variables, e.g. `static const`. Leave this empty, if no prefix is desired.
schema_flags	(Optional 3) flags to augment the payload schema. Default is `NVTX_PAYLOAD_SCHEMA_FLAG_NONE`.
schema_id	(Optional 4) User-defined payload schema ID.
entries	(Mandatory) The schema entries. This is always the last parameter to the macro.

Note: On MSVC, this macro requires the conforming preprocessor: /Zc:preprocessor (VS 2019+) or /experimental:preprocessor (VS 2017 v15.5+). Not supported on older MSVC versions.

Definition at line 164 of file nvToolsExtPayloadHelper.h.

◆ NVTX_DEFINE_STRUCT_WITH_SCHEMA_AND_REGISTER

#define NVTX_DEFINE_STRUCT_WITH_SCHEMA_AND_REGISTER	(	domain,
		struct_id,
		...
	)

Value:

_NVTX_DEFINE_STRUCT_WITH_SCHEMA(struct_id, __VA_ARGS__) \

const uint64_t struct_id##_schemaId = nvtxPayloadSchemaRegister(domain, &struct_id##Attr);

Initialize and register the NVTX binary payload schema.

This does essentially the same as NVTX_DEFINE_STRUCT_WITH_SCHEMA, but in addition the schema is registered. The schema ID will be defined as follows: const uint64_t struct_id##_schemaId.

Parameters

domain The NVTX domain handle. All other parameters are similar to NVTX_DEFINE_STRUCT_WITH_SCHEMA.

Note: On MSVC, this macro requires the conforming preprocessor: /Zc:preprocessor (VS 2019+) or /experimental:preprocessor (VS 2017 v15.5+). Not supported on older MSVC versions.

Definition at line 181 of file nvToolsExtPayloadHelper.h.

◆ NVTX_PAYLOAD_ENTRIES

#define NVTX_PAYLOAD_ENTRIES

Definition at line 62 of file nvToolsExtPayloadHelper.h.

◆ NVTX_PAYLOAD_NESTED

#define NVTX_PAYLOAD_NESTED ( schemaId ) _NVTX_PAYLOAD_NESTED(schemaId)

Use this macro for payload entries that are defined by a schema (nested payload schema).

Definition at line 69 of file nvToolsExtPayloadHelper.h.

◆ NVTX_PAYLOAD_SCHEMA_REGISTER

#define NVTX_PAYLOAD_SCHEMA_REGISTER	(	domain,
		struct_id
	)	nvtxPayloadSchemaRegister(domain, &struct_id##Attr)

Register an NVTX binary payload schema.

This is a convenience macro, which takes the same struct_id that has been used in other helper macros. Instead, nvtxPayloadSchemaRegister can also be used, but &struct_id##Attr has to be passed.

Parameters

domain	The NVTX domain handle.
struct_id	The name of the struct.

Returns: NVTX schema ID

Definition at line 236 of file nvToolsExtPayloadHelper.h.

Macros

Detailed Description

Macro Definition Documentation

◆ NVTX_DEFINE_SCHEMA_FOR_STRUCT

◆ NVTX_DEFINE_SCHEMA_FOR_STRUCT_AND_REGISTER

◆ NVTX_DEFINE_STRUCT

◆ NVTX_DEFINE_STRUCT_WITH_SCHEMA

◆ NVTX_DEFINE_STRUCT_WITH_SCHEMA_AND_REGISTER

◆ NVTX_PAYLOAD_ENTRIES

◆ NVTX_PAYLOAD_NESTED

◆ NVTX_PAYLOAD_SCHEMA_REGISTER