include/nvtx3/nvToolsExtSync.h

0001 /*
0002  * SPDX-FileCopyrightText: Copyright (c) 2009-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 "nvToolsExt.h"
0032
0033 #ifndef NVTOOLSEXT_SYNC_V3
0034 #define NVTOOLSEXT_SYNC_V3
0035
0036 #ifdef __cplusplus
0037 extern "C" {
0038 #endif /* __cplusplus */
0039
0040 /* \cond SHOW_HIDDEN
0041 * \version NVTX_VERSION_2
0042 */
0043 #define NVTX_SYNCUSER_ATTRIB_STRUCT_SIZE (NVTX_STATIC_CAST(uint16_t, sizeof(nvtxSyncUserAttributes_v0)))
0044 /** \endcond */
0045
0046
0047 /**
0048 * \page PAGE_SYNCHRONIZATION Synchronization
0049 *
0050 * This section covers a subset of the API that allow users to track additional
0051 * synchronization details of their application.   Naming OS synchronization primitives
0052 * may allow users to better understand the data collected by traced synchronization
0053 * APIs.  Additionally, a user defined synchronization object can allow the users to
0054 * to tell the tools when the user is building their own synchronization system
0055 * that do not rely on the OS to provide behaviors and instead use techniques like
0056 * atomic operations and spinlocks.
0057 *
0058 * See module \ref SYNCHRONIZATION for details.
0059 *
0060 * \par Example
0061 * Instrument a mutex class:
0062 * \code
0063 * class MyMutex
0064 * {
0065 *     volatile long bLocked;
0066 *     nvtxSyncUser_t hSync;
0067 * public:
0068 *     MyMutex(const char* name, nvtxDomainHandle_t d) {
0069 *          bLocked = 0;
0070 *
0071 *          nvtxSyncUserAttributes_t attribs = { 0 };
0072 *          attribs.version = NVTX_VERSION;
0073 *          attribs.size = NVTX_SYNCUSER_ATTRIB_STRUCT_SIZE;
0074 *          attribs.messageType = NVTX_MESSAGE_TYPE_ASCII;
0075 *          attribs.message.ascii = name;
0076 *          hSync = nvtxDomainSyncUserCreate(d, &attribs);
0077 *     }
0078 *
0079 *     ~MyMutex() {
0080 *          nvtxDomainSyncUserDestroy(hSync);
0081 *     }
0082 *
0083 *     bool Lock() {
0084 *          nvtxDomainSyncUserAcquireStart(hSync);
0085 *          bool acquired = __sync_bool_compare_and_swap(&bLocked, 0, 1); // atomic compiler intrinsic
0086 *
0087 *          if (acquired) {
0088 *              nvtxDomainSyncUserAcquireSuccess(hSync);
0089 *          }
0090 *          else {
0091 *              nvtxDomainSyncUserAcquireFailed(hSync);
0092 *          }
0093 *          return acquired;
0094 *     }
0095 *
0096 *     void Unlock() {
0097 *          nvtxDomainSyncUserReleasing(hSync);
0098 *          bLocked = false;
0099 *     }
0100 * };
0101 * \endcode
0102 *
0103 * \version NVTX_VERSION_2
0104 */
0105
0106 /*  ------------------------------------------------------------------------- */
0107 /* \cond SHOW_HIDDEN
0108 * \brief Used to build a non-colliding value for resource types separated class
0109 * \version NVTX_VERSION_2
0110 */
0111 #define NVTX_RESOURCE_CLASS_SYNC_OS 2 /**< Synchronization objects that are OS specific. */
0112 #define NVTX_RESOURCE_CLASS_SYNC_PTHREAD 3 /**< Synchronization objects that are from the POSIX Threads API (pthread)*/
0113 /** \endcond */
0114
0115
0116 /*  ------------------------------------------------------------------------- */
0117 /** \defgroup SYNCHRONIZATION Synchronization
0118 * See page \ref PAGE_SYNCHRONIZATION.
0119 * @{
0120 */
0121
0122 /** \brief Resource type values for OSs with POSIX Thread API support
0123  */
0124 typedef enum nvtxResourceSyncPosixThreadType_t
0125 {
0126     NVTX_RESOURCE_TYPE_SYNC_PTHREAD_MUTEX = NVTX_RESOURCE_MAKE_TYPE(SYNC_PTHREAD, 1), /* pthread_mutex_t  */
0127     NVTX_RESOURCE_TYPE_SYNC_PTHREAD_CONDITION = NVTX_RESOURCE_MAKE_TYPE(SYNC_PTHREAD, 2), /* pthread_cond_t  */
0128     NVTX_RESOURCE_TYPE_SYNC_PTHREAD_RWLOCK = NVTX_RESOURCE_MAKE_TYPE(SYNC_PTHREAD, 3), /* pthread_rwlock_t  */
0129     NVTX_RESOURCE_TYPE_SYNC_PTHREAD_BARRIER = NVTX_RESOURCE_MAKE_TYPE(SYNC_PTHREAD, 4), /* pthread_barrier_t  */
0130     NVTX_RESOURCE_TYPE_SYNC_PTHREAD_SPINLOCK = NVTX_RESOURCE_MAKE_TYPE(SYNC_PTHREAD, 5), /* pthread_spinlock_t  */
0131     NVTX_RESOURCE_TYPE_SYNC_PTHREAD_ONCE = NVTX_RESOURCE_MAKE_TYPE(SYNC_PTHREAD, 6) /* pthread_once_t  */
0132 } nvtxResourceSyncPosixThreadType_t;
0133
0134 /** \brief Resource type values for Windows OSs
0135 */
0136 typedef enum nvtxResourceSyncWindowsType_t
0137 {
0138     NVTX_RESOURCE_TYPE_SYNC_WINDOWS_MUTEX = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS, 1),
0139     NVTX_RESOURCE_TYPE_SYNC_WINDOWS_SEMAPHORE = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS, 2),
0140     NVTX_RESOURCE_TYPE_SYNC_WINDOWS_EVENT = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS, 3),
0141     NVTX_RESOURCE_TYPE_SYNC_WINDOWS_CRITICAL_SECTION = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS, 4),
0142     NVTX_RESOURCE_TYPE_SYNC_WINDOWS_SRWLOCK = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS, 5)
0143 } nvtxResourceSyncWindowsType_t;
0144
0145 /** \brief Resource type values for Linux and Linux derived OSs such as Android
0146 * \sa
0147 * ::nvtxResourceSyncPosixThreadType_t
0148 */
0149 typedef enum nvtxResourceSyncLinuxType_t
0150 {
0151     NVTX_RESOURCE_TYPE_SYNC_LINUX_MUTEX = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS, 1),
0152     NVTX_RESOURCE_TYPE_SYNC_LINUX_FUTEX = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS, 2),
0153     NVTX_RESOURCE_TYPE_SYNC_LINUX_SEMAPHORE = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS, 3),
0154     NVTX_RESOURCE_TYPE_SYNC_LINUX_COMPLETION = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS, 4),
0155     NVTX_RESOURCE_TYPE_SYNC_LINUX_SPINLOCK = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS, 5),
0156     NVTX_RESOURCE_TYPE_SYNC_LINUX_SEQLOCK = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS, 6),
0157     NVTX_RESOURCE_TYPE_SYNC_LINUX_RCU = NVTX_RESOURCE_MAKE_TYPE(SYNC_OS, 7)
0158 } nvtxResourceSyncLinuxType_t;
0159
0160 /** \brief Resource type values for Android come from Linux.
0161 * \sa
0162 * ::nvtxResourceSyncLinuxType_t
0163 * ::nvtxResourceSyncPosixThreadType_t
0164 */
0165 typedef enum nvtxResourceSyncLinuxType_t nvtxResourceSyncAndroidType_t;
0166
0167 /** \brief User Defined Synchronization Object Handle .
0168 * \anchor SYNCUSER_HANDLE_STRUCTURE
0169 *
0170 * This structure is opaque to the user and is used as a handle to reference
0171 * a user defined synchronization object.  The tools will return a pointer through the API for the application
0172 * to hold on its behalf to reference the string in the future.
0173 *
0174 */
0175 typedef struct nvtxSyncUser* nvtxSyncUser_t;
0176
0177 /** \brief User Defined Synchronization Object Attributes Structure.
0178 * \anchor USERDEF_SYNC_ATTRIBUTES_STRUCTURE
0179 *
0180 * This structure is used to describe the attributes of a user defined synchronization
0181 * object.  The layout of the structure is defined by a specific version of the tools
0182 * extension library and can change between different versions of the Tools Extension
0183 * library.
0184 *
0185 * \par Guidelines
0186 * The caller should always perform the following three tasks when using
0187 * attributes:
0188 * <ul>
0189 *    <li>Zero the structure
0190 *    <li>Set the version field
0191 *    <li>Set the size field
0192 * </ul>
0193 *
0194 * Zeroing the structure sets all the event attributes types and values
0195 * to the default value.
0196 *
0197 * The version and size field are used by the Tools Extension
0198 * implementation to handle multiple versions of the attributes structure.
0199 *
0200 * It is recommended that the caller use one of the following to methods
0201 * to initialize the event attributes structure:
0202 *
0203 * \par Method 1
0204 * Initializing nvtxEventAttributes for future compatibility:
0205 * \code
0206 * nvtxSyncUserAttributes_t attribs = {0};
0207 * attribs.version = NVTX_VERSION;
0208 * attribs.size = NVTX_SYNCUSER_ATTRIB_STRUCT_SIZE;
0209 * \endcode
0210 *
0211 * \par Method 2
0212 * Initializing nvtxSyncUserAttributes_t for a specific version:
0213 * \code
0214 * nvtxSyncUserAttributes_t attribs = {0};
0215 * attribs.version = 1;
0216 * attribs.size = (uint16_t)(sizeof(nvtxSyncUserAttributes_t));
0217 * \endcode
0218 *
0219 * If the caller uses Method 1 it is critical that the entire binary
0220 * layout of the structure be configured to 0 so that all fields
0221 * are initialized to the default value.
0222 *
0223 * The caller should either use both NVTX_VERSION and
0224 * NVTX_SYNCUSER_ATTRIB_STRUCT_SIZE (Method 1) or use explicit values
0225 * and a versioned type (Method 2).  Using a mix of the two methods
0226 * will likely cause either source level incompatibility or binary
0227 * incompatibility in the future.
0228 *
0229 * \par Example
0230 * Populate a sync attributes structure:
0231 * \code
0232 * // Initialize
0233 * nvtxSyncUserAttributes_t attribs = {0};
0234 * attribs.version = NVTX_VERSION;
0235 * attribs.size = NVTX_SYNCUSER_ATTRIB_STRUCT_SIZE;
0236 *
0237 * // Configure the Attributes
0238 * attribs.messageType = NVTX_MESSAGE_TYPE_ASCII;
0239 * attribs.message.ascii = "Example";
0240 * \endcode
0241 *
0242 * \sa
0243 * ::nvtxDomainSyncUserCreate
0244 */
0245 typedef struct nvtxSyncUserAttributes_v0
0246 {
0247     /**
0248     * \brief Version flag of the structure.
0249     *
0250     * Needs to be set to NVTX_VERSION to indicate the version of NVTX APIs
0251     * supported in this header file. This can optionally be overridden to
0252     * another version of the tools extension library.
0253     */
0254     uint16_t version;
0255
0256     /**
0257     * \brief Size of the structure.
0258     *
0259     * Needs to be set to the size in bytes of the event attribute
0260     * structure used to specify the event.
0261     */
0262     uint16_t size;
0263
0264     /** \brief Message type specified in this attribute structure.
0265     *
0266     * Defines the message format of the attribute structure's \ref nvtxSyncUserAttributes_v0::message
0267     * "message" field.
0268     *
0269     * Default Value is NVTX_MESSAGE_UNKNOWN
0270     */
0271     int32_t messageType;            /* nvtxMessageType_t */
0272
0273     /** \brief Message assigned to this attribute structure.
0274     *
0275     * The text message that is attached to an event.
0276     */
0277     nvtxMessageValue_t message;
0278
0279 } nvtxSyncUserAttributes_v0;
0280
0281 typedef struct nvtxSyncUserAttributes_v0 nvtxSyncUserAttributes_t;
0282
0283 /* ------------------------------------------------------------------------- */
0284 /** \brief Create a user defined synchronization object
0285 * This is used to track non-OS synchronization working with spinlocks and atomics
0286 *
0287 * \param domain - Domain to own the resource
0288 * \param attribs - A structure to assign multiple attributes to the object.
0289 *
0290 * \return A handle that represents the newly created user defined synchronization object.
0291 *
0292 * \sa
0293 * ::nvtxDomainSyncUserCreate
0294 * ::nvtxDomainSyncUserDestroy
0295 * ::nvtxDomainSyncUserAcquireStart
0296 * ::nvtxDomainSyncUserAcquireFailed
0297 * ::nvtxDomainSyncUserAcquireSuccess
0298 * ::nvtxDomainSyncUserReleasing
0299 *
0300 * \version NVTX_VERSION_2
0301 */
0302 NVTX_DECLSPEC nvtxSyncUser_t NVTX_API nvtxDomainSyncUserCreate(nvtxDomainHandle_t domain, const nvtxSyncUserAttributes_t* attribs);
0303
0304 /* ------------------------------------------------------------------------- */
0305 /** \brief Destroy a user defined synchronization object
0306 * This is used to track non-OS synchronization working with spinlocks and atomics
0307 *
0308 * \param handle - A handle to the object to operate on.
0309 *
0310 * \sa
0311 * ::nvtxDomainSyncUserCreate
0312 * ::nvtxDomainSyncUserDestroy
0313 * ::nvtxDomainSyncUserAcquireStart
0314 * ::nvtxDomainSyncUserAcquireFailed
0315 * ::nvtxDomainSyncUserAcquireSuccess
0316 * ::nvtxDomainSyncUserReleasing
0317 *
0318 * \version NVTX_VERSION_2
0319 */
0320 NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserDestroy(nvtxSyncUser_t handle);
0321
0322 /* ------------------------------------------------------------------------- */
0323 /** \brief Signal to tools that an attempt to acquire a user defined synchronization object
0324 *
0325 * \param handle - A handle to the object to operate on.
0326 *
0327 * \sa
0328 * ::nvtxDomainSyncUserCreate
0329 * ::nvtxDomainSyncUserDestroy
0330 * ::nvtxDomainSyncUserAcquireStart
0331 * ::nvtxDomainSyncUserAcquireFailed
0332 * ::nvtxDomainSyncUserAcquireSuccess
0333 * ::nvtxDomainSyncUserReleasing
0334 *
0335 * \version NVTX_VERSION_2
0336 */
0337 NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserAcquireStart(nvtxSyncUser_t handle);
0338
0339 /* ------------------------------------------------------------------------- */
0340 /** \brief Signal to tools of failure in acquiring a user defined synchronization object
0341 * This should be called after \ref nvtxDomainSyncUserAcquireStart
0342 *
0343 * \param handle - A handle to the object to operate on.
0344 *
0345 * \sa
0346 * ::nvtxDomainSyncUserCreate
0347 * ::nvtxDomainSyncUserDestroy
0348 * ::nvtxDomainSyncUserAcquireStart
0349 * ::nvtxDomainSyncUserAcquireFailed
0350 * ::nvtxDomainSyncUserAcquireSuccess
0351 * ::nvtxDomainSyncUserReleasing
0352 *
0353 * \version NVTX_VERSION_2
0354 */
0355 NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserAcquireFailed(nvtxSyncUser_t handle);
0356
0357 /* ------------------------------------------------------------------------- */
0358 /** \brief Signal to tools of success in acquiring a user defined synchronization object
0359 * This should be called after \ref nvtxDomainSyncUserAcquireStart.
0360 *
0361 * \param handle - A handle to the object to operate on.
0362 *
0363 * \sa
0364 * ::nvtxDomainSyncUserCreate
0365 * ::nvtxDomainSyncUserDestroy
0366 * ::nvtxDomainSyncUserAcquireStart
0367 * ::nvtxDomainSyncUserAcquireFailed
0368 * ::nvtxDomainSyncUserAcquireSuccess
0369 * ::nvtxDomainSyncUserReleasing
0370 *
0371 * \version NVTX_VERSION_2
0372 */
0373 NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserAcquireSuccess(nvtxSyncUser_t handle);
0374
0375 /* ------------------------------------------------------------------------- */
0376 /** \brief Signal to tools of releasing a reservation on user defined synchronization object
0377 * This should be called after \ref nvtxDomainSyncUserAcquireSuccess.
0378 *
0379 * \param handle - A handle to the object to operate on.
0380 *
0381 * \sa
0382 * ::nvtxDomainSyncUserCreate
0383 * ::nvtxDomainSyncUserDestroy
0384 * ::nvtxDomainSyncUserAcquireStart
0385 * ::nvtxDomainSyncUserAcquireFailed
0386 * ::nvtxDomainSyncUserAcquireSuccess
0387 * ::nvtxDomainSyncUserReleasing
0388 *
0389 * \version NVTX_VERSION_2
0390 */
0391 NVTX_DECLSPEC void NVTX_API nvtxDomainSyncUserReleasing(nvtxSyncUser_t handle);
0392
0393
0394 /** @} */ /*END defgroup*/
0395
0396 #ifdef __cplusplus
0397 }
0398 #endif /* __cplusplus */
0399
0400 #ifndef NVTX_NO_IMPL
0401 #define NVTX_IMPL_GUARD_SYNC /* Ensure other headers cannot be included directly */
0402 #include "nvtxDetail/nvtxImplSync_v3.h"
0403 #undef NVTX_IMPL_GUARD_SYNC
0404 #endif /*NVTX_NO_IMPL*/
0405
0406 #endif /* NVTOOLSEXT_SYNC_V3 */