include/nvtx3/nvToolsExtSemanticsCounters.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 /** Identifier of the semantic extension for counters. */
0034 #ifndef NVTX_SEMANTIC_ID_COUNTERS_V1
0035 #define NVTX_SEMANTIC_ID_COUNTERS_V1 5
0036
0037 /* Use with the version field of `nvtxSemanticsHeader_t`. */
0038 #define NVTX_COUNTER_SEMANTIC_VERSION 2
0039
0040 /***  Flags to augment the counter value. ***/
0041 #define NVTX_COUNTER_FLAGS_NONE  0
0042
0043 /**
0044  * Convert the fixed point value to a normalized floating point.
0045  * Use the sign/unsign from the underlying type this flag is applied to.
0046  * Unsigned [0f : 1f] or signed [-1f : 1f]
0047  */
0048 #define NVTX_COUNTER_FLAG_NORMALIZE  (1 << 1)
0049
0050 /**
0051  * Tools should apply scale and limits when graphing, ideally in a "soft" way to
0052  * to see when limits are exceeded.
0053  */
0054 #define NVTX_COUNTER_FLAG_LIMIT_MIN  (1 << 2)
0055 #define NVTX_COUNTER_FLAG_LIMIT_MAX  (1 << 3)
0056 #define NVTX_COUNTER_FLAG_LIMITS \
0057     (NVTX_COUNTER_FLAG_LIMIT_MIN | NVTX_COUNTER_FLAG_LIMIT_MAX)
0058
0059 /**
0060  * Counter value types
0061  */
0062 #define NVTX_COUNTER_FLAG_VALUETYPE_ABSOLUTE          (1 << 4)
0063 /* Delta to previous sample, tool-defined if no previous sample is available. */
0064 #define NVTX_COUNTER_FLAG_VALUETYPE_DELTA             (2 << 4)
0065 #define NVTX_COUNTER_FLAG_VALUETYPE_DELTA_SINCE_START (3 << 4)
0066
0067 /**
0068  * Counter interpolation / effective range of counters.
0069  */
0070 /* No interpolation between samples. */
0071 #define NVTX_COUNTER_FLAG_INTERPOLATION_POINT         (1 << 8)
0072 /* Piecewise constant interpolation between the current and the last sample. */
0073 #define NVTX_COUNTER_FLAG_INTERPOLATION_SINCE_LAST    (2 << 8)
0074 /* Piecewise constant interpolation between the current and the next sample. */
0075 #define NVTX_COUNTER_FLAG_INTERPOLATION_UNTIL_NEXT    (3 << 8)
0076 /* Piecewise linear interpolation between samples. */
0077 #define NVTX_COUNTER_FLAG_INTERPOLATION_LINEAR        (4 << 8)
0078
0079 /**
0080  * Datatype for limits union (value of `limitType`).
0081  */
0082 #define NVTX_COUNTER_LIMIT_UNDEFINED 0
0083 #define NVTX_COUNTER_LIMIT_I64       1
0084 #define NVTX_COUNTER_LIMIT_U64       2
0085 #define NVTX_COUNTER_LIMIT_F64       3
0086
0087
0088 /**
0089  * Union of datatypes that can be used as counter value limits.
0090  */
0091 typedef union
0092 {
0093     int64_t i64;
0094     uint64_t u64;
0095     double f64;
0096 } nvtxCounterLimit_t;
0097
0098 /**
0099  * \brief Specify additional properties of a counter or counter group.
0100  */
0101 typedef struct nvtxSemanticsCounter_v1
0102 {
0103     /** Header of the semantic extension (with identifier, version, etc.). */
0104     struct nvtxSemanticsHeader_v1 header;
0105
0106     /**
0107      * Flag if normalization, scale limits, etc. should be applied to counter
0108      * values.
0109      */
0110     uint64_t flags;
0111
0112     /** Unit of the counter value (case insensitive) */
0113     const char* unit;
0114
0115     /** Should be 1 if not used. */
0116     uint64_t unitScaleNumerator;
0117
0118     /** Should be 1 if not used. */
0119     uint64_t unitScaleDenominator;
0120
0121     /**
0122      * Specifies the used union member for `min` and `max`.
0123      * Use the defines `NVTX_COUNTER_LIMIT_*`.
0124      */
0125     int64_t limitType;
0126
0127     /** Value limits. */
0128     nvtxCounterLimit_t min;
0129     nvtxCounterLimit_t max;
0130 } nvtxSemanticsCounter_t;
0131
0132 #endif /* NVTX_SEMANTIC_ID_COUNTERS_V1 */