include/nvtx3/nvToolsExtCounters.h

0001 /*
0002  * SPDX-FileCopyrightText: Copyright (c) 2024-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 "nvToolsExtPayload.h"
0032
0033 /**
0034  * \brief The compatibility ID is used for versioning of this extension.
0035  */
0036 #ifndef NVTX_EXT_COUNTERS_COMPATID
0037 #define NVTX_EXT_COUNTERS_COMPATID 0x0102
0038 #endif
0039
0040 /**
0041  * \brief The module ID identifies the payload extension. It has to be unique
0042  * among the extension modules.
0043  */
0044 #ifndef NVTX_EXT_COUNTERS_MODULEID
0045 #define NVTX_EXT_COUNTERS_MODULEID 4
0046 #endif
0047
0048 #ifndef NVTX_COUNTER_IDS_V1
0049 #define NVTX_COUNTER_IDS_V1
0050
0051 /** The counter ID is not specified. */
0052 #define NVTX_COUNTER_ID_NONE          0
0053
0054 /** Static (user-provided, feed-forward) counter (group) IDs. */
0055 #define NVTX_COUNTER_ID_STATIC_START  (1 << 24)
0056
0057 /** Dynamically (tool) generated counter (group) IDs */
0058 #define NVTX_COUNTER_ID_DYNAMIC_START (NVTX_STATIC_CAST(uint64_t, 1) << 32)
0059
0060 #endif /* NVTX_COUNTER_IDS_V1 */
0061
0062 /** Reasons for the missing sample value. */
0063 #ifndef NVTX_COUNTER_SAMPLES_V1
0064 #define NVTX_COUNTER_SAMPLES_V1
0065
0066 #define NVTX_COUNTER_SAMPLE_ZERO        0
0067 #define NVTX_COUNTER_SAMPLE_UNCHANGED   1
0068 #define NVTX_COUNTER_SAMPLE_UNAVAILABLE 2 /* Failed to get a counter sample. */
0069
0070 #endif /* NVTX_COUNTER_SAMPLES_V1 */
0071
0072 /**
0073  * Counter batch timestamp array flags.
0074  * Values must not overlap with `NVTX_BATCH_FLAG_*`.
0075  * By default, one timestamp per sample is assumed.
0076  */
0077 #ifndef NVTX_COUNTER_BATCH_FLAGS_V1
0078 #define NVTX_COUNTER_BATCH_FLAGS_V1
0079
0080 #define NVTX_COUNTER_BATCH_FLAG_BEGINTIME_INTERVAL_PAIR (1 << 32)
0081 #define NVTX_COUNTER_BATCH_FLAG_ENDTIME_INTERVAL_PAIR   (2 << 32)
0082
0083 #endif /* NVTX_COUNTER_BATCH_FLAGS_V1 */
0084
0085 #ifdef __cplusplus
0086 extern "C" {
0087 #endif /* __cplusplus */
0088
0089 #ifndef NVTX_COUNTER_TYPEDEFS_V1
0090 #define NVTX_COUNTER_TYPEDEFS_V1
0091
0092 /**
0093  * \brief Attributes of a counter or counter group.
0094  */
0095 typedef struct nvtxCounterAttr_v1
0096 {
0097     size_t structSize;
0098
0099     /**
0100      * A schema ID referring to the data layout of the counter group or a
0101      * predefined NVTX payloads number type.
0102      */
0103     uint64_t schemaId;
0104
0105     /** Name of the counter (group). */
0106     const char* name;
0107
0108     /**
0109      * Optional detailed description of the counter (group). A description for
0110      * individual counters can be set in the schema registration.
0111      */
0112     const char* description;
0113
0114     /**
0115      * Identifier of the counters' scope. A valid scope ID is either a
0116      * predefined scope or the value returned by `nvtxScopeRegister` called for
0117      * the same NVTX domain as `nvtxCounterRegister`. An invalid scope ID will
0118      * be handled like `NVTX_SCOPE_NONE`.
0119      */
0120     uint64_t scopeId;
0121
0122     /**
0123      * Optional semantics for a counter (group). The specified semantics apply
0124      * to all counters in a group. If the semantics should only refer to a
0125      * single counter in a group, the semantics field of the payload entry has
0126      * to be used. Accepted semantics are `nvtxSemanticsCounter_t` and
0127      * `nvtxSemanticsTime_t`.
0128      */
0129     const nvtxSemanticsHeader_t* semantics;
0130
0131     /**
0132      * A static counter ID must be unique within the domain,
0133      * >= NVTX_COUNTER_ID_STATIC_START, and < NVTX_COUNTER_ID_DYNAMIC_START.
0134      * Use NVTX_COUNTER_ID_NONE to let the tool create a (dynamic) counter ID.
0135      */
0136     uint64_t counterId;
0137 } nvtxCounterAttr_t;
0138
0139 /**
0140  * \brief Helper struct to submit a batch of counters.
0141  *
0142  * The size of one sample is specified via the `payloadStaticSize` field of the
0143  * counter's data layout schema or the size of the predefined payload entry type
0144  * and must include padding. There should be no remainder when dividing
0145  * `countersSize` by `nvtxPayloadSchemaAttr_t::payloadStaticSize`.
0146  */
0147 typedef struct nvtxCounterBatch_v1
0148 {
0149     /**
0150      * Identifier of a counter group (data layout, scope, etc.). All counter
0151      * samples in the batch have the same layout and size.
0152      */
0153     uint64_t counterId;
0154
0155     /** Batch of counter (group) samples. */
0156     const void* counters;
0157
0158     /** Size of the counter batch (in bytes). */
0159     size_t countersSize;
0160
0161     /**
0162      * Timestamp ordering, timestamp style, etc.
0163      * See `NVTX_BATCH_FLAG_*` and `NVTX_COUNTER_BATCH_FLAG_*`.
0164      */
0165     uint64_t flags;
0166
0167     /**
0168      * Array of timestamps or a timestamp/interval pair. This field can be
0169      * `NULL`, if timestamps are included in the counter samples as part of the
0170      * counter group layout. By default, one timestamp per sample is assumed.
0171      * The timestamp source is specified via time semantics passed during the
0172      * counter group registration.
0173      * This overrides the timestamps embedded in counter samples.
0174      */
0175     const int64_t* timestamps;
0176
0177     /** Size of the timestamps array or timestamp/interval pair (in bytes). */
0178     size_t timestampsSize;
0179 } nvtxCounterBatch_t;
0180
0181 #endif /* NVTX_COUNTER_TYPEDEFS_V1 */
0182
0183 #ifndef NVTX_COUNTER_API_FUNCTIONS_V1
0184 #define NVTX_COUNTER_API_FUNCTIONS_V1
0185
0186 /**
0187  * \brief Register a counter (group).
0188  *
0189  * @param hDomain NVTX domain handle.
0190  * @param attr Pointer to the attributes of the counter (group).
0191  *
0192  * @return Identifier of a counter (group). The counter ID is unique within
0193  *         the NVTX domain.
0194  */
0195 NVTX_DECLSPEC uint64_t NVTX_API nvtxCounterRegister(
0196     nvtxDomainHandle_t hDomain,
0197     const nvtxCounterAttr_t* attr);
0198
0199 /**
0200  * Sample one integer counter by value immediately
0201  * (the NVTX tool determines the timestamp).
0202  *
0203  * @param hDomain handle of the NVTX domain.
0204  * @param counterId identifier of the NVTX counter (group).
0205  * @param value 64-bit integer counter value.
0206  */
0207 NVTX_DECLSPEC void NVTX_API nvtxCounterSampleInt64(
0208     nvtxDomainHandle_t hDomain,
0209     uint64_t counterId,
0210     int64_t value);
0211
0212 /**
0213  * Sample one floating point counter by value immediately
0214  * (the NVTX tool determines the timestamp).
0215  *
0216  * @param hDomain handle of the NVTX domain.
0217  * @param counterId identifier of the NVTX counter (group).
0218  * @param value 64-bit floating-point counter value.
0219  */
0220 NVTX_DECLSPEC void NVTX_API nvtxCounterSampleFloat64(
0221     nvtxDomainHandle_t hDomain,
0222     uint64_t counterId,
0223     double value);
0224
0225 /**
0226  * Sample a counter (group) by reference immediately
0227  * (the NVTX tool determines the timestamp).
0228  *
0229  * @param hDomain handle of the NVTX domain.
0230  * @param counterId identifier of the NVTX counter (group).
0231  * @param value pointer to one or more counter values.
0232  * @param size size of the counter value(s) in bytes.
0233  */
0234 NVTX_DECLSPEC void NVTX_API nvtxCounterSample(
0235     nvtxDomainHandle_t hDomain,
0236     uint64_t counterId,
0237     const void* value,
0238     size_t size);
0239
0240 /**
0241  * \brief Sample without value.
0242  *
0243  * @param hDomain handle of the NVTX domain.
0244  * @param counterId identifier of the NVTX counter (group).
0245  * @param reason reason for the missing sample value.
0246  */
0247 NVTX_DECLSPEC void NVTX_API nvtxCounterSampleNoValue(
0248     nvtxDomainHandle_t hDomain,
0249     uint64_t counterId,
0250     uint8_t reason);
0251
0252 /**
0253  * \brief Submit a batch of counters in the given domain.
0254  *
0255  * The size of a data sampling point is defined by the `payloadStaticSize` field
0256  * of the payload schema. An NVTX tool can assume that the counter samples are
0257  * stored as an array with each entry being `payloadStaticSize` bytes.
0258  *
0259  * @param hDomain handle of the NVTX domain
0260  * @param counterData Pointer to the counter data to be submitted.
0261  */
0262 NVTX_DECLSPEC void NVTX_API nvtxCounterBatchSubmit(
0263     nvtxDomainHandle_t hDomain,
0264     const nvtxCounterBatch_t* counterData);
0265
0266 #endif /* NVTX_COUNTER_API_FUNCTIONS_V1 */
0267
0268 #ifndef NVTX_COUNTER_CALLBACK_ID_V1
0269 #define NVTX_COUNTER_CALLBACK_ID_V1
0270
0271 #define NVTX3EXT_CBID_nvtxCounterRegister           0
0272 #define NVTX3EXT_CBID_nvtxCounterSampleInt64        1
0273 #define NVTX3EXT_CBID_nvtxCounterSampleFloat64      2
0274 #define NVTX3EXT_CBID_nvtxCounterSample             3
0275 #define NVTX3EXT_CBID_nvtxCounterSampleNoValue      4
0276 #define NVTX3EXT_CBID_nvtxCounterBatchSubmit        5
0277
0278 #endif /* NVTX_COUNTER_CALLBACK_ID_V1 */
0279
0280 /* Macros to create versioned symbols. */
0281 #ifndef NVTX_EXT_COUNTERS_VERSIONED_IDENTIFIERS_V1
0282 #define NVTX_EXT_COUNTERS_VERSIONED_IDENTIFIERS_V1
0283 #define NVTX_EXT_COUNTERS_VERSIONED_IDENTIFIER_L3(NAME, VERSION, COMPATID) \
0284     NAME##_v##VERSION##_cnt##COMPATID
0285 #define NVTX_EXT_COUNTERS_VERSIONED_IDENTIFIER_L2(NAME, VERSION, COMPATID) \
0286     NVTX_EXT_COUNTERS_VERSIONED_IDENTIFIER_L3(NAME, VERSION, COMPATID)
0287 #define NVTX_EXT_COUNTERS_VERSIONED_ID(NAME) \
0288     NVTX_EXT_COUNTERS_VERSIONED_IDENTIFIER_L2(NAME, NVTX_VERSION, NVTX_EXT_COUNTERS_COMPATID)
0289 #endif /* NVTX_EXT_COUNTERS_VERSIONED_IDENTIFIERS_V1 */
0290
0291 #ifdef __GNUC__
0292 #pragma GCC visibility push(internal)
0293 #endif
0294
0295 #define NVTX_EXT_TYPES_GUARD /* Ensure other headers cannot be included directly. */
0296 #include "nvtxDetail/nvtxExtTypes.h"
0297 #undef NVTX_EXT_TYPES_GUARD
0298
0299 #ifndef NVTX_NO_IMPL
0300 #define NVTX_EXT_IMPL_COUNTERS_GUARD /* Ensure other headers cannot be included directly. */
0301 #include "nvtxDetail/nvtxExtImplCounters_v1.h"
0302 #undef NVTX_EXT_IMPL_COUNTERS_GUARD
0303 #endif /*NVTX_NO_IMPL*/
0304
0305 #ifdef __GNUC__
0306 #pragma GCC visibility pop
0307 #endif
0308
0309 #ifdef __cplusplus
0310 }
0311 #endif /* __cplusplus */