include/nvtx3/nvToolsExtPayloadHelper.h

0001 /*
0002  * SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
0003  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0004  *
0005  * Licensed under the Apache License, Version 2.0 (the "License");
0006  * you may not use this file except in compliance with the License.
0007  * You may obtain a copy of the License at
0008  *
0009  *     http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  *
0017  * Licensed under the Apache License v2.0 with LLVM Exceptions.
0018  * See https://nvidia.github.io/NVTX/LICENSE.txt for license information.
0019  */
0020
0021 #if defined(NVTX_AS_SYSTEM_HEADER)
0022 #if defined(__clang__)
0023 #pragma clang system_header
0024 #elif defined(__GNUC__) || defined(__NVCOMPILER)
0025 #pragma GCC system_header
0026 #elif defined(_MSC_VER)
0027 #pragma system_header
0028 #endif
0029 #endif
0030
0031 #include "nvtxDetail/nvtxExtPayloadHelperInternal.h"
0032
0033
0034 /* This is just an empty marker (for readability), which can be omitted. */
0035 /* TODO: Fix issue with trailing comma at end of entry list. */
0036 #define NVTX_PAYLOAD_ENTRIES
0037
0038
0039 /**
0040  * Use this macro for payload entries that are defined by a schema (nested
0041  * payload schema).
0042  */
0043 #define NVTX_PAYLOAD_NESTED(schemaId) _NVTX_PAYLOAD_NESTED(schemaId)
0044
0045
0046 /**
0047  * \brief Define a payload schema for an existing C `struct` definition.
0048  *
0049  *  This macro does
0050  *   1) create schema description (array of schema entries).
0051  *   2) set the schema attributes for a static data layout.
0052  *
0053  * It can be used in static code or within a function context.
0054  *
0055  * Example:
0056  *  NVTX_DEFINE_SCHEMA_FOR_STRUCT(your_struct, "SchemaName",
0057  *      NVTX_PAYLOAD_ENTRIES(
0058  *          (index, TYPE_INT, "integer value"),
0059  *          (dpfloat, TYPE_DOUBLE, "fp64 value"),
0060  *          (text, TYPE_CSTRING, "text", NULL, 24)
0061  *      )
0062  *  )
0063  *
0064  * It is required to at least provide the struct name and the payload entries.
0065  * The first two fields (member name and NVTX entry type) of each payload entry
0066  * are required.
0067  *
0068  * The optional parameters are only allowed to be passed in the predefined order.
0069  * Hence, `payload_flags` requires `payload_schema` to be given and
0070  * `prefix` requires `payload_flags` and `payload_schema` to be given.
0071  * The payload entries are always the last parameter. A maximum of 16 schema
0072  * entries is supported.
0073  *
0074  * It is recommended to use `NVTX_PAYLOAD_SCHEMA_REGISTER` to register the schema.
0075  *
0076  * @param struct_id The name of the struct.
0077  * @param schema_name (Optional 1) name of the payload schema. Default is `NULL`.
0078  * @param prefix (Optional 2) prefix before the schema and attributes variables,
0079  *               e.g. `static const`. Leave this empty, if no prefix is desired.
0080  * @param schema_flags (Optional 2) flags to augment the payload schema.
0081  *                     Default is `NVTX_PAYLOAD_SCHEMA_FLAG_NONE`.
0082  * @param schema_id (Optional 4) User-defined payload schema ID.
0083  * @param entries (Mandatory) Payload schema entries. This is always the last
0084  *                parameter to the macro.
0085  */
0086 #define NVTX_DEFINE_SCHEMA_FOR_STRUCT(struct_id, ...) \
0087     _NVTX_DEFINE_SCHEMA_FOR_STRUCT(struct_id, __VA_ARGS__)
0088
0089
0090 /**
0091  * \brief Define a C struct together with a matching schema.
0092  *
0093  * This macro does
0094  *   1) define the payload type (typedef struct).
0095  *   2) create schema description (array of schema entries).
0096  *   3) set the schema attributes for a static data layout.
0097  *
0098  * The macro can be used in static code or within a function context.
0099  *
0100  * It defines the schema attributes in `struct_id##Attr`. Thus, it is recommended
0101  * to use `NVTX_PAYLOAD_SCHEMA_REGISTER(domain, struct_id)` to register the schema.
0102  *
0103  * Example:
0104  *  NVTX_DEFINE_STRUCT_WITH_SCHEMA(your_struct_name, "Your schema name",
0105  *      NVTX_PAYLOAD_ENTRIES(
0106  *          (int, index, TYPE_INT, "integer value"),
0107  *          (double, dpfloat, TYPE_DOUBLE, "fp64 value"),
0108  *          (const char, (text, 24), TYPE_CSTRING, "text", NULL, 24)
0109  *      )
0110  *  )
0111  *
0112  * The first three fields (C type, member, entry type) of each entry are required.
0113  * A fixed-size array or string requires a special notation with the member
0114  * name and the size separated by comma and put into brackets (see last entry
0115  * in the example).
0116  *
0117  * The optional parameters are positional (only allowed to be passed in the
0118  * predefined order). A maximum of 16 schema entries is supported.
0119  *
0120  * @param struct_id The name of the struct.
0121  * @param schema_name (Optional 1) name of the payload schema. Default is `NULL`.
0122  * @param prefix (Optional 2) prefix before the schema and attributes variables,
0123  *               e.g. `static const`. Leave this empty, if no prefix is desired.
0124  * @param schema_flags (Optional 3) flags to augment the payload schema.
0125  *                     Default is `NVTX_PAYLOAD_SCHEMA_FLAG_NONE`.
0126  * @param schema_id (Optional 4) User-defined payload schema ID.
0127  * @param entries (Mandatory) The schema entries. This is always the last
0128  *                parameter to the macro.
0129  */
0130 #define NVTX_DEFINE_STRUCT_WITH_SCHEMA(struct_id, ...) \
0131     _NVTX_DEFINE_STRUCT_WITH_SCHEMA(struct_id, __VA_ARGS__)
0132
0133 /**
0134  * \brief Initialize and register the NVTX binary payload schema.
0135  *
0136  * This does essentially the same as `NVTX_DEFINE_STRUCT_WITH_SCHEMA`, but in
0137  * addition the schema is registered. The schema ID will be defined as follows:
0138  * `const uint64_t struct_id##_schemaId`.
0139  *
0140  * @param domain The NVTX domain handle.
0141  * All other parameters are similar to `NVTX_DEFINE_STRUCT_WITH_SCHEMA`.
0142  */
0143 #define NVTX_DEFINE_STRUCT_WITH_SCHEMA_AND_REGISTER(domain, struct_id, ...) \
0144     _NVTX_DEFINE_STRUCT_WITH_SCHEMA(struct_id, __VA_ARGS__) \
0145     const uint64_t struct_id##_schemaId = nvtxPayloadSchemaRegister(domain, &struct_id##Attr);
0146
0147 /**
0148  * \brief Define payload schema for an existing `struct` and register the schema.
0149  *
0150  * This does essentially the same as `NVTX_PAYLOAD_STATIC_SCHEMA_DEFINE`, but in
0151  * addition, the schema is registered and `uint64_t struct_id##_schemaId` set.
0152  *
0153  * @param domain The NVTX domain handle.
0154  * All other parameters are similar to `NVTX_PAYLOAD_STATIC_SCHEMA_DEFINE`.
0155  */
0156 #define NVTX_DEFINE_SCHEMA_FOR_STRUCT_AND_REGISTER(domain, struct_id, ...) \
0157     _NVTX_DEFINE_SCHEMA_FOR_STRUCT(struct_id, __VA_ARGS__) \
0158     const uint64_t struct_id##_schemaId = nvtxPayloadSchemaRegister(domain, &struct_id##Attr);
0159
0160 /**
0161  * \brief Create a type definition for the given struct ID and members.
0162  *
0163  * This is a convenience macro. A normal `typedef` can be used instead.
0164  *
0165  * Example usage:
0166  *   NVTX_DEFINE_STRUCT(your_struct,
0167  *           (double, fp64),
0168  *           (uint8_t, u8),
0169  *           (float, fp32[3])
0170  *   )
0171  *
0172  * @param struct_id The name of the struct.
0173  * @param members The members of the struct.
0174  */
0175 #define NVTX_DEFINE_STRUCT(struct_id, ...) \
0176     _NVTX_PAYLOAD_TYPEDEF_STRUCT(struct_id, __VA_ARGS__)
0177
0178 /**
0179  * \brief Register an NVTX binary payload schema.
0180  *
0181  * This is a convenience macro, which takes the same `struct_id` that has been
0182  * used in other helper macros. Instead, `nvtxPayloadSchemaRegister` can also be
0183  * used, but `&struct_id##Attr` has to be passed.
0184  *
0185  * @param domain The NVTX domain handle.
0186  * @param struct_id The name of the struct.
0187  *
0188  * @return NVTX schema ID
0189  */
0190 #define NVTX_PAYLOAD_SCHEMA_REGISTER(domain, struct_id) \
0191     nvtxPayloadSchemaRegister(domain, &struct_id##Attr);
0192