codekingpro/portable-devtools
114k
1/*
2* Copyright 2009-2016 NVIDIA Corporation. All rights reserved.
3*
4* NOTICE TO USER:
5*
6* This source code is subject to NVIDIA ownership rights under U.S. and
7* international Copyright laws.
8*
9* This software and the information contained herein is PROPRIETARY and
10* CONFIDENTIAL to NVIDIA and is being provided under the terms and conditions
11* of a form of NVIDIA software license agreement.
12*
13* NVIDIA MAKES NO REPRESENTATION ABOUT THE SUITABILITY OF THIS SOURCE
14* CODE FOR ANY PURPOSE. IT IS PROVIDED "AS IS" WITHOUT EXPRESS OR
15* IMPLIED WARRANTY OF ANY KIND. NVIDIA DISCLAIMS ALL WARRANTIES WITH
16* REGARD TO THIS SOURCE CODE, INCLUDING ALL IMPLIED WARRANTIES OF
17* MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.
18* IN NO EVENT SHALL NVIDIA BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL,
19* OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
20* OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
21* OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE
22* OR PERFORMANCE OF THIS SOURCE CODE.
23*
24* U.S. Government End Users. This source code is a "commercial item" as
25* that term is defined at 48 C.F.R. 2.101 (OCT 1995), consisting of
26* "commercial computer software" and "commercial computer software
27* documentation" as such terms are used in 48 C.F.R. 12.212 (SEPT 1995)
28* and is provided to the U.S. Government only as a commercial end item.
29* Consistent with 48 C.F.R.12.212 and 48 C.F.R. 227.7202-1 through
30* 227.7202-4 (JUNE 1995), all U.S. Government End Users acquire the
31* source code with only those rights set forth herein.
32*
33* Any use of this source code in individual and commercial software must
34* include, in the user documentation and internal comments to the code,
35* the above Disclaimer and U.S. Government End Users Notice.
36*/
37
38/** \file nvToolsExt.h
39 */
40
41/* ========================================================================= */
42/** \mainpage
43 * \tableofcontents
44 * \section INTRODUCTION Introduction
45 *
46 * The NVIDIA Tools Extension library is a set of functions that a
47 * developer can use to provide additional information to tools.
48 * The additional information is used by the tool to improve
49 * analysis and visualization of data.
50 *
51 * The library introduces close to zero overhead if no tool is
52 * attached to the application. The overhead when a tool is
53 * attached is specific to the tool.
54 *
55 * \section INITIALIZATION_SECTION Initialization
56 *
57 * Typically the tool's library that plugs into NVTX is indirectly
58 * loaded via enviromental properties that are platform specific.
59 * For some platform or special cases, the user may be required
60 * to instead explicity initialize instead though. This can also
61 * be helpful to control when the API loads a tool's library instead
62 * of what would typically be the first function call to emit info.
63 * For these rare case, see \ref INITIALIZATION for additional information.
64 *
65 * \section MARKERS_AND_RANGES Markers and Ranges
66 *
67 * Markers and ranges are used to describe events at a specific time (markers)
68 * or over a time span (ranges) during the execution of the application
69 * respectively.
70 *
71 * \subsection MARKERS Markers
72 *
73 * Markers denote specific moments in time.
74 *
75 *
76 * See \ref DOMAINS and \ref EVENT_ATTRIBUTES for additional information on
77 * how to specify the domain.
78 *
79 * \subsection THREAD_RANGES Thread Ranges
80 *
81 * Thread ranges denote nested time ranges. Nesting is maintained per thread
82 * per domain and does not require any additional correlation mechanism. The
83 * duration of a thread range is defined by the corresponding pair of
84 * nvtxRangePush* to nvtxRangePop API calls.
85 *
86 * See \ref DOMAINS and \ref EVENT_ATTRIBUTES for additional information on
87 * how to specify the domain.
88 *
89 * \subsection PROCESS_RANGES Process Ranges
90 *
91 * Process ranges denote a time span that can expose arbitrary concurrency, as
92 * opposed to thread ranges that only support nesting. In addition the range
93 * start event can happen on a different thread than the end marker. For the
94 * correlation of a start/end pair an unique correlation ID is used that is
95 * returned from the start API call and needs to be passed into the end API
96 * call.
97 *
98 * \subsection EVENT_ATTRIBUTES Event Attributes
99 *
100 * \ref MARKERS_AND_RANGES can be annotated with various attributes to provide
101 * additional information for an event or to guide the tool's visualization of
102 * the data. Each of the attributes is optional and if left unused the
103 * attributes fall back to a default value. The attributes include:
104 * - color
105 * - category
106 *
107 * To specify any attribute other than the text message, the \ref
108 * EVENT_ATTRIBUTE_STRUCTURE "Event Attribute Structure" must be used.
109 *
110 * \section DOMAINS Domains
111 *
112 * Domains enable developers to scope annotations. By default all events and
113 * annotations are in the default domain. Additional domains can be registered.
114 * This allows developers to scope markers, ranges, and resources names to
115 * avoid conflicts.
116 *
117 * The function ::nvtxDomainCreateA or ::nvtxDomainCreateW is used to create
118 * a named domain.
119 *
120 * Each domain maintains its own
121 * - categories
122 * - thread range stacks
123 * - registered strings
124 *
125 * The function ::nvtxDomainDestroy marks the end of the domain. Destroying
126 * a domain unregisters and destroys all objects associated with it such as
127 * registered strings, resource objects, named categories, and started ranges.
128 *
129 * \section RESOURCE_NAMING Resource Naming
130 *
131 * This section covers calls that allow to annotate objects with user-provided
132 * names in order to allow for a better analysis of complex trace data. All of
133 * the functions take the handle or the ID of the object to name and the name.
134 * The functions can be called multiple times during the execution of an
135 * application, however, in that case it is implementation dependent which
136 * name will be reported by the tool.
137 *
138 * \subsection CATEGORY_NAMING Category Naming
139 *
140 * Some function in this library support associating an integer category
141 * to enable filtering and sorting. The category naming functions allow
142 * the application to associate a user friendly name with the integer
143 * category. Support for domains have been added in NVTX_VERSION_2 to
144 * avoid collisions when domains are developed independantly.
145 *
146 * \subsection RESOURCE_OBJECTS Resource Objects
147 *
148 * Resource objects are a generic mechanism for attaching data to an application
149 * resource. The identifier field makes the association to a pointer or handle,
150 * while the type field helps provide deeper understanding of the identifier as
151 * well as enabling differentiation in cases where handles generated by different
152 * APIs may collide. The resource object may also have an associated message to
153 * associate with the application resource, enabling further annotation of this
154 * object and how it is used.
155 *
156 * The resource object was introduced in NVTX_VERSION_2 to supersede existing naming
157 * functions and allow the application resource identified by those functions to be
158 * associated to a domain. The other naming functions are still supported for backward
159 * compatibility but will be associated only to the default domain.
160 *
161 * \subsection RESOURCE_NAMING_OS Resource Naming
162 *
163 * Some operating system resources creation APIs do not support providing a user friendly
164 * name, such as some OS thread creation APIs. This API support resource naming though
165 * both through resource objects and functions following the pattern
166 * nvtxName[RESOURCE_TYPE][A|W](identifier, name). Resource objects introduced in NVTX_VERSION 2
167 * supersede the other functions with a a more general method of assigning names to OS resources,
168 * along with associating them to domains too. The older nvtxName* functions are only associated
169 * with the default domain.
170 * \section EXTENSIONS Optional Extensions
171 * Optional extensions will either appear within the existing sections the extend or appear
172 * in the "Related Pages" when they introduce new concepts.
173 */
174
175 /**
176 * Tools Extension API version
177 */
178#if defined(NVTX_VERSION) && NVTX_VERSION < 3
179#error "Trying to #include NVTX version 3 in a source file where an older NVTX version has already been included. If you are not directly using NVTX (the NVIDIA Tools Extension library), you are getting this error because libraries you are using have included different versions of NVTX. Suggested solutions are: (1) reorder #includes so the newest NVTX version is included first, (2) avoid using the conflicting libraries in the same .c/.cpp file, or (3) update the library using the older NVTX version to use the newer version instead."
180#endif
181
182/* Header guard */
183#if !defined(NVTX_VERSION)
184#define NVTX_VERSION 3
185
186#if defined(_MSC_VER)
187#define NVTX_API __stdcall
188#define NVTX_INLINE_STATIC __inline static
189#else /*defined(__GNUC__)*/
190#define NVTX_API
191#define NVTX_INLINE_STATIC inline static
192#endif /* Platform */
193
194#if defined(NVTX_NO_IMPL)
195/* When omitting implementation, avoid declaring functions inline */
196/* without definitions, since this causes compiler warnings. */
197#define NVTX_DECLSPEC
198#elif defined(NVTX_EXPORT_API)
199/* Allow overriding definition of NVTX_DECLSPEC when exporting API. */
200/* Default is empty, meaning non-inline with external linkage. */
201#if !defined(NVTX_DECLSPEC)
202#define NVTX_DECLSPEC
203#endif
204#else
205/* Normal NVTX usage defines the NVTX API inline with static */
206/* (internal) linkage. */
207#define NVTX_DECLSPEC NVTX_INLINE_STATIC
208#endif
209
210#include "nvtxDetail/nvtxLinkOnce.h"
211
212#define NVTX_VERSIONED_IDENTIFIER_L3(NAME, VERSION) NAME##_v##VERSION
213#define NVTX_VERSIONED_IDENTIFIER_L2(NAME, VERSION) NVTX_VERSIONED_IDENTIFIER_L3(NAME, VERSION)
214#define NVTX_VERSIONED_IDENTIFIER(NAME) NVTX_VERSIONED_IDENTIFIER_L2(NAME, NVTX_VERSION)
215
216/**
217 * The nvToolsExt library depends on stdint.h. If the build tool chain in use
218 * does not include stdint.h then define NVTX_STDINT_TYPES_ALREADY_DEFINED
219 * and define the following types:
220 * <ul>
221 * <li>uint8_t
222 * <li>int8_t
223 * <li>uint16_t
224 * <li>int16_t
225 * <li>uint32_t
226 * <li>int32_t
227 * <li>uint64_t
228 * <li>int64_t
229 * <li>uintptr_t
230 * <li>intptr_t
231 * </ul>
232 * #define NVTX_STDINT_TYPES_ALREADY_DEFINED if you are using your own header file.
233 */
234#ifndef NVTX_STDINT_TYPES_ALREADY_DEFINED
235#include <stdint.h>
236#endif
237
238#include <stddef.h>
239
240#ifdef __cplusplus
241extern "C" {
242#endif /* __cplusplus */
243
244/**
245* Result Codes
246*/
247
248#define NVTX_SUCCESS 0
249#define NVTX_FAIL 1
250#define NVTX_ERR_INIT_LOAD_PROPERTY 2
251#define NVTX_ERR_INIT_ACCESS_LIBRARY 3
252#define NVTX_ERR_INIT_LOAD_LIBRARY 4
253#define NVTX_ERR_INIT_MISSING_LIBRARY_ENTRY_POINT 5
254#define NVTX_ERR_INIT_FAILED_LIBRARY_ENTRY_POINT 6
255#define NVTX_ERR_NO_INJECTION_LIBRARY_AVAILABLE 7
256
257/**
258 * Size of the nvtxEventAttributes_t structure.
259 */
260#define NVTX_EVENT_ATTRIB_STRUCT_SIZE ( (uint16_t)( sizeof(nvtxEventAttributes_t) ) )
261
262#define NVTX_NO_PUSH_POP_TRACKING ((int)-2)
263
264typedef uint64_t nvtxRangeId_t;
265
266/* Forward declaration of opaque domain registration structure */
267struct nvtxDomainRegistration_st;
268typedef struct nvtxDomainRegistration_st nvtxDomainRegistration;
269
270/* \brief Domain Handle Structure.
271* \anchor DOMAIN_HANDLE_STRUCTURE
272*
273* This structure is opaque to the user and is used as a handle to reference
274* a domain. This type is returned from tools when using the NVTX API to
275* create a domain.
276*
277*/
278typedef nvtxDomainRegistration* nvtxDomainHandle_t;
279
280/* Forward declaration of opaque string registration structure */
281struct nvtxStringRegistration_st;
282typedef struct nvtxStringRegistration_st nvtxStringRegistration;
283
284/* \brief Registered String Handle Structure.
285* \anchor REGISTERED_STRING_HANDLE_STRUCTURE
286*
287* This structure is opaque to the user and is used as a handle to reference
288* a registered string. This type is returned from tools when using the NVTX
289* API to create a registered string.
290*
291*/
292typedef nvtxStringRegistration* nvtxStringHandle_t;
293
294/* ========================================================================= */
295/** \defgroup GENERAL General
296 * @{
297 */
298
299/** ---------------------------------------------------------------------------
300 * Color Types
301 * ------------------------------------------------------------------------- */
302typedef enum nvtxColorType_t
303{
304 NVTX_COLOR_UNKNOWN = 0, /**< Color attribute is unused. */
305 NVTX_COLOR_ARGB = 1 /**< An ARGB color is provided. */
306} nvtxColorType_t;
307
308/** ---------------------------------------------------------------------------
309 * Message Types
310 * ------------------------------------------------------------------------- */
311typedef enum nvtxMessageType_t
312{
313 NVTX_MESSAGE_UNKNOWN = 0, /**< Message payload is unused. */
314 NVTX_MESSAGE_TYPE_ASCII = 1, /**< A character sequence is used as payload. */
315 NVTX_MESSAGE_TYPE_UNICODE = 2, /**< A wide character sequence is used as payload. */
316 /* NVTX_VERSION_2 */
317 NVTX_MESSAGE_TYPE_REGISTERED = 3, /**< A unique string handle that was registered
318 with \ref nvtxDomainRegisterStringA() or
319 \ref nvtxDomainRegisterStringW(). */
320} nvtxMessageType_t;
321
322typedef union nvtxMessageValue_t
323{
324 const char* ascii;
325 const wchar_t* unicode;
326 /* NVTX_VERSION_2 */
327 nvtxStringHandle_t registered;
328} nvtxMessageValue_t;
329
330
331/** @} */ /*END defgroup*/
332/* ------------------------------------------------------------------------- */
333/** \brief Force initialization (optional)
334*
335* Force NVTX library to initialize. The first call to any NVTX API function
336* will automatically initialize the entire API. This can make the first call
337* much slower than subsequent calls. In applications where the first call to
338* NVTX may be in a performance-critical section, calling nvtxInitialize before
339* any performance-critical sections will ensure NVTX initialization occurs at
340* an acceptable time. Since nvtxInitialize takes no parameters and has no
341* expected behavior besides initialization, it is convenient to add a call to
342* nvtxInitialize in NVTX-instrumented applications that need to force earlier
343* initialization without changing any other code. For example, if an app's
344* first NVTX call is nvtxDomainCreate, and it is difficult to move that call
345* earlier because the domain handle must be stored in an object only created
346* at that point, adding a call to nvtxInitialize at the top of main() will
347* ensure the later call to nvtxDomainCreate is as fast as possible.
348*
349* \version \NVTX_VERSION_3
350*
351* \param reserved - must be zero or NULL.
352*
353* @{ */
354NVTX_DECLSPEC void NVTX_API nvtxInitialize(const void* reserved);
355/** @} */
356
357
358/** @} */ /*END defgroup*/
359
360/* ========================================================================= */
361/** \defgroup EVENT_ATTRIBUTES Event Attributes
362* @{
363*/
364
365/** ---------------------------------------------------------------------------
366* Payload Types
367* ------------------------------------------------------------------------- */
368typedef enum nvtxPayloadType_t
369{
370 NVTX_PAYLOAD_UNKNOWN = 0, /**< Color payload is unused. */
371 NVTX_PAYLOAD_TYPE_UNSIGNED_INT64 = 1, /**< A 64 bit unsigned integer value is used as payload. */
372 NVTX_PAYLOAD_TYPE_INT64 = 2, /**< A 64 bit signed integer value is used as payload. */
373 NVTX_PAYLOAD_TYPE_DOUBLE = 3, /**< A 64 bit floating point value is used as payload. */
374 /* NVTX_VERSION_2 */
375 NVTX_PAYLOAD_TYPE_UNSIGNED_INT32 = 4, /**< A 32 bit floating point value is used as payload. */
376 NVTX_PAYLOAD_TYPE_INT32 = 5, /**< A 32 bit floating point value is used as payload. */
377 NVTX_PAYLOAD_TYPE_FLOAT = 6 /**< A 32 bit floating point value is used as payload. */
378} nvtxPayloadType_t;
379
380/** \brief Event Attribute Structure.
381 * \anchor EVENT_ATTRIBUTE_STRUCTURE
382 *
383 * This structure is used to describe the attributes of an event. The layout of
384 * the structure is defined by a specific version of the tools extension
385 * library and can change between different versions of the Tools Extension
386 * library.
387 *
388 * \par Initializing the Attributes
389 *
390 * The caller should always perform the following three tasks when using
391 * attributes:
392 * <ul>
393 * <li>Zero the structure
394 * <li>Set the version field
395 * <li>Set the size field
396 * </ul>
397 *
398 * Zeroing the structure sets all the event attributes types and values
399 * to the default value.
400 *
401 * The version and size field are used by the Tools Extension
402 * implementation to handle multiple versions of the attributes structure.
403 *
404 * It is recommended that the caller use one of the following to methods
405 * to initialize the event attributes structure:
406 *
407 * \par Method 1: Initializing nvtxEventAttributes for future compatibility
408 * \code
409 * nvtxEventAttributes_t eventAttrib = {0};
410 * eventAttrib.version = NVTX_VERSION;
411 * eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
412 * \endcode
413 *
414 * \par Method 2: Initializing nvtxEventAttributes for a specific version
415 * \code
416 * nvtxEventAttributes_t eventAttrib = {0};
417 * eventAttrib.version = 1;
418 * eventAttrib.size = (uint16_t)(sizeof(nvtxEventAttributes_v1));
419 * \endcode
420 *
421 * If the caller uses Method 1 it is critical that the entire binary
422 * layout of the structure be configured to 0 so that all fields
423 * are initialized to the default value.
424 *
425 * The caller should either use both NVTX_VERSION and
426 * NVTX_EVENT_ATTRIB_STRUCT_SIZE (Method 1) or use explicit values
427 * and a versioned type (Method 2). Using a mix of the two methods
428 * will likely cause either source level incompatibility or binary
429 * incompatibility in the future.
430 *
431 * \par Settings Attribute Types and Values
432 *
433 *
434 * \par Example:
435 * \code
436 * // Initialize
437 * nvtxEventAttributes_t eventAttrib = {0};
438 * eventAttrib.version = NVTX_VERSION;
439 * eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
440 *
441 * // Configure the Attributes
442 * eventAttrib.colorType = NVTX_COLOR_ARGB;
443 * eventAttrib.color = 0xFF880000;
444 * eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
445 * eventAttrib.message.ascii = "Example";
446 * \endcode
447 *
448 * In the example the caller does not have to set the value of
449 * \ref ::nvtxEventAttributes_v2::category or
450 * \ref ::nvtxEventAttributes_v2::payload as these fields were set to
451 * the default value by {0}.
452 * \sa
453 * ::nvtxDomainMarkEx
454 * ::nvtxDomainRangeStartEx
455 * ::nvtxDomainRangePushEx
456 */
457typedef struct nvtxEventAttributes_v2
458{
459 /**
460 * \brief Version flag of the structure.
461 *
462 * Needs to be set to NVTX_VERSION to indicate the version of NVTX APIs
463 * supported in this header file. This can optionally be overridden to
464 * another version of the tools extension library.
465 */
466 uint16_t version;
467
468 /**
469 * \brief Size of the structure.
470 *
471 * Needs to be set to the size in bytes of the event attribute
472 * structure used to specify the event.
473 */
474 uint16_t size;
475
476 /**
477 * \brief ID of the category the event is assigned to.
478 *
479 * A category is a user-controlled ID that can be used to group
480 * events. The tool may use category IDs to improve filtering or
481 * enable grouping of events in the same category. The functions
482 * \ref ::nvtxNameCategoryA or \ref ::nvtxNameCategoryW can be used
483 * to name a category.
484 *
485 * Default Value is 0
486 */
487 uint32_t category;
488
489 /** \brief Color type specified in this attribute structure.
490 *
491 * Defines the color format of the attribute structure's \ref COLOR_FIELD
492 * "color" field.
493 *
494 * Default Value is NVTX_COLOR_UNKNOWN
495 */
496 int32_t colorType; /* nvtxColorType_t */
497
498 /** \brief Color assigned to this event. \anchor COLOR_FIELD
499 *
500 * The color that the tool should use to visualize the event.
501 */
502 uint32_t color;
503
504 /**
505 * \brief Payload type specified in this attribute structure.
506 *
507 * Defines the payload format of the attribute structure's \ref PAYLOAD_FIELD
508 * "payload" field.
509 *
510 * Default Value is NVTX_PAYLOAD_UNKNOWN
511 */
512 int32_t payloadType; /* nvtxPayloadType_t */
513
514 int32_t reserved0;
515
516 /**
517 * \brief Payload assigned to this event. \anchor PAYLOAD_FIELD
518 *
519 * A numerical value that can be used to annotate an event. The tool could
520 * use the payload data to reconstruct graphs and diagrams.
521 */
522 union payload_t
523 {
524 uint64_t ullValue;
525 int64_t llValue;
526 double dValue;
527 /* NVTX_VERSION_2 */
528 uint32_t uiValue;
529 int32_t iValue;
530 float fValue;
531 } payload;
532
533 /** \brief Message type specified in this attribute structure.
534 *
535 * Defines the message format of the attribute structure's \ref MESSAGE_FIELD
536 * "message" field.
537 *
538 * Default Value is NVTX_MESSAGE_UNKNOWN
539 */
540 int32_t messageType; /* nvtxMessageType_t */
541
542 /** \brief Message assigned to this attribute structure. \anchor MESSAGE_FIELD
543 *
544 * The text message that is attached to an event.
545 */
546 nvtxMessageValue_t message;
547
548} nvtxEventAttributes_v2;
549
550typedef struct nvtxEventAttributes_v2 nvtxEventAttributes_t;
551
552/** @} */ /*END defgroup*/
553/* ========================================================================= */
554/** \defgroup MARKERS_AND_RANGES Markers and Ranges
555 *
556 * See \ref MARKERS_AND_RANGES for more details
557 *
558 * @{
559 */
560
561/** \name Marker */
562
563/* ------------------------------------------------------------------------- */
564/** \brief Marks an instantaneous event in the application.
565*
566* A marker can contain a text message or specify additional information
567* using the event attributes structure. These attributes include a text
568* message, color, category, and a payload. Each of the attributes is optional
569* and can only be sent out using the \ref nvtxDomainMarkEx function.
570*
571* nvtxDomainMarkEx(NULL, event) is equivalent to calling
572* nvtxMarkEx(event).
573*
574* \param domain - The domain of scoping the category.
575* \param eventAttrib - The event attribute structure defining the marker's
576* attribute types and attribute values.
577*
578* \sa
579* ::nvtxMarkEx
580*
581* \version \NVTX_VERSION_2
582* @{ */
583NVTX_DECLSPEC void NVTX_API nvtxDomainMarkEx(nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib);
584/** @} */
585
586/* ------------------------------------------------------------------------- */
587/** \brief Marks an instantaneous event in the application.
588 *
589 * A marker can contain a text message or specify additional information
590 * using the event attributes structure. These attributes include a text
591 * message, color, category, and a payload. Each of the attributes is optional
592 * and can only be sent out using the \ref nvtxMarkEx function.
593 * If \ref nvtxMarkA or \ref nvtxMarkW are used to specify the marker
594 * or if an attribute is unspecified then a default value will be used.
595 *
596 * \param eventAttrib - The event attribute structure defining the marker's
597 * attribute types and attribute values.
598 *
599 * \par Example:
600 * \code
601 * // zero the structure
602 * nvtxEventAttributes_t eventAttrib = {0};
603 * // set the version and the size information
604 * eventAttrib.version = NVTX_VERSION;
605 * eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
606 * // configure the attributes. 0 is the default for all attributes.
607 * eventAttrib.colorType = NVTX_COLOR_ARGB;
608 * eventAttrib.color = 0xFF880000;
609 * eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
610 * eventAttrib.message.ascii = "Example nvtxMarkEx";
611 * nvtxMarkEx(&eventAttrib);
612 * \endcode
613 *
614 * \sa
615 * ::nvtxDomainMarkEx
616 *
617 * \version \NVTX_VERSION_1
618 * @{ */
619NVTX_DECLSPEC void NVTX_API nvtxMarkEx(const nvtxEventAttributes_t* eventAttrib);
620/** @} */
621
622/* ------------------------------------------------------------------------- */
623/** \brief Marks an instantaneous event in the application.
624 *
625 * A marker created using \ref nvtxMarkA or \ref nvtxMarkW contains only a
626 * text message.
627 *
628 * \param message - The message associated to this marker event.
629 *
630 * \par Example:
631 * \code
632 * nvtxMarkA("Example nvtxMarkA");
633 * nvtxMarkW(L"Example nvtxMarkW");
634 * \endcode
635 *
636 * \sa
637 * ::nvtxDomainMarkEx
638 * ::nvtxMarkEx
639 *
640 * \version \NVTX_VERSION_0
641 * @{ */
642NVTX_DECLSPEC void NVTX_API nvtxMarkA(const char* message);
643NVTX_DECLSPEC void NVTX_API nvtxMarkW(const wchar_t* message);
644/** @} */
645
646
647/** \name Process Ranges */
648
649/* ------------------------------------------------------------------------- */
650/** \brief Starts a process range in a domain.
651*
652* \param domain - The domain of scoping the category.
653* \param eventAttrib - The event attribute structure defining the range's
654* attribute types and attribute values.
655*
656* \return The unique ID used to correlate a pair of Start and End events.
657*
658* \remarks Ranges defined by Start/End can overlap.
659*
660* \par Example:
661* \code
662* nvtxDomainHandle_t domain = nvtxDomainCreateA("my domain");
663* nvtxEventAttributes_t eventAttrib = {0};
664* eventAttrib.version = NVTX_VERSION;
665* eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
666* eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
667* eventAttrib.message.ascii = "my range";
668* nvtxRangeId_t rangeId = nvtxDomainRangeStartEx(&eventAttrib);
669* // ...
670* nvtxDomainRangeEnd(rangeId);
671* \endcode
672*
673* \sa
674* ::nvtxDomainRangeEnd
675*
676* \version \NVTX_VERSION_2
677* @{ */
678NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxDomainRangeStartEx(nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib);
679/** @} */
680
681/* ------------------------------------------------------------------------- */
682/** \brief Starts a process range.
683 *
684 * \param eventAttrib - The event attribute structure defining the range's
685 * attribute types and attribute values.
686 *
687 * \return The unique ID used to correlate a pair of Start and End events.
688 *
689 * \remarks Ranges defined by Start/End can overlap.
690 *
691 * \par Example:
692 * \code
693 * nvtxEventAttributes_t eventAttrib = {0};
694 * eventAttrib.version = NVTX_VERSION;
695 * eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
696 * eventAttrib.category = 3;
697 * eventAttrib.colorType = NVTX_COLOR_ARGB;
698 * eventAttrib.color = 0xFF0088FF;
699 * eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
700 * eventAttrib.message.ascii = "Example Range";
701 * nvtxRangeId_t rangeId = nvtxRangeStartEx(&eventAttrib);
702 * // ...
703 * nvtxRangeEnd(rangeId);
704 * \endcode
705 *
706 * \sa
707 * ::nvtxRangeEnd
708 * ::nvtxDomainRangeStartEx
709 *
710 * \version \NVTX_VERSION_1
711 * @{ */
712NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartEx(const nvtxEventAttributes_t* eventAttrib);
713/** @} */
714
715/* ------------------------------------------------------------------------- */
716/** \brief Starts a process range.
717 *
718 * \param message - The event message associated to this range event.
719 *
720 * \return The unique ID used to correlate a pair of Start and End events.
721 *
722 * \remarks Ranges defined by Start/End can overlap.
723 *
724 * \par Example:
725 * \code
726 * nvtxRangeId_t r1 = nvtxRangeStartA("Range 1");
727 * nvtxRangeId_t r2 = nvtxRangeStartW(L"Range 2");
728 * nvtxRangeEnd(r1);
729 * nvtxRangeEnd(r2);
730 * \endcode
731 *
732 * \sa
733 * ::nvtxRangeEnd
734 * ::nvtxRangeStartEx
735 * ::nvtxDomainRangeStartEx
736 *
737 * \version \NVTX_VERSION_0
738 * @{ */
739NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartA(const char* message);
740NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartW(const wchar_t* message);
741/** @} */
742
743/* ------------------------------------------------------------------------- */
744/** \brief Ends a process range.
745*
746* \param domain - The domain
747* \param id - The correlation ID returned from a nvtxRangeStart call.
748*
749* \remarks This function is offered completeness but is an alias for ::nvtxRangeEnd.
750* It does not need a domain param since that is associated iwth the range ID at ::nvtxDomainRangeStartEx
751*
752* \par Example:
753* \code
754* nvtxDomainHandle_t domain = nvtxDomainCreateA("my domain");
755* nvtxEventAttributes_t eventAttrib = {0};
756* eventAttrib.version = NVTX_VERSION;
757* eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
758* eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
759* eventAttrib.message.ascii = "my range";
760* nvtxRangeId_t rangeId = nvtxDomainRangeStartEx(&eventAttrib);
761* // ...
762* nvtxDomainRangeEnd(rangeId);
763* \endcode
764*
765* \sa
766* ::nvtxDomainRangeStartEx
767*
768* \version \NVTX_VERSION_2
769* @{ */
770NVTX_DECLSPEC void NVTX_API nvtxDomainRangeEnd(nvtxDomainHandle_t domain, nvtxRangeId_t id);
771/** @} */
772
773/* ------------------------------------------------------------------------- */
774/** \brief Ends a process range.
775 *
776 * \param id - The correlation ID returned from an nvtxRangeStart call.
777 *
778 * \sa
779 * ::nvtxDomainRangeStartEx
780 * ::nvtxRangeStartEx
781 * ::nvtxRangeStartA
782 * ::nvtxRangeStartW
783 *
784 * \version \NVTX_VERSION_0
785 * @{ */
786NVTX_DECLSPEC void NVTX_API nvtxRangeEnd(nvtxRangeId_t id);
787/** @} */
788
789/** \name Thread Ranges */
790
791/* ------------------------------------------------------------------------- */
792/** \brief Starts a nested thread range.
793*
794* \param domain - The domain of scoping.
795* \param eventAttrib - The event attribute structure defining the range's
796* attribute types and attribute values.
797*
798* \return The 0 based level of range being started. This value is scoped to the domain.
799* If an error occurs, a negative value is returned.
800*
801* \par Example:
802* \code
803* nvtxDomainHandle_t domain = nvtxDomainCreateA("example domain");
804* nvtxEventAttributes_t eventAttrib = {0};
805* eventAttrib.version = NVTX_VERSION;
806* eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
807* eventAttrib.colorType = NVTX_COLOR_ARGB;
808* eventAttrib.color = 0xFFFF0000;
809* eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
810* eventAttrib.message.ascii = "Level 0";
811* nvtxDomainRangePushEx(domain, &eventAttrib);
812*
813* // Re-use eventAttrib
814* eventAttrib.messageType = NVTX_MESSAGE_TYPE_UNICODE;
815* eventAttrib.message.unicode = L"Level 1";
816* nvtxDomainRangePushEx(domain, &eventAttrib);
817*
818* nvtxDomainRangePop(domain); //level 1
819* nvtxDomainRangePop(domain); //level 0
820* \endcode
821*
822* \sa
823* ::nvtxDomainRangePop
824*
825* \version \NVTX_VERSION_2
826* @{ */
827NVTX_DECLSPEC int NVTX_API nvtxDomainRangePushEx(nvtxDomainHandle_t domain, const nvtxEventAttributes_t* eventAttrib);
828/** @} */
829
830/* ------------------------------------------------------------------------- */
831/** \brief Starts a nested thread range.
832 *
833 * \param eventAttrib - The event attribute structure defining the range's
834 * attribute types and attribute values.
835 *
836 * \return The 0 based level of range being started. This level is per domain.
837 * If an error occurs a negative value is returned.
838 *
839 * \par Example:
840 * \code
841 * nvtxEventAttributes_t eventAttrib = {0};
842 * eventAttrib.version = NVTX_VERSION;
843 * eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
844 * eventAttrib.colorType = NVTX_COLOR_ARGB;
845 * eventAttrib.color = 0xFFFF0000;
846 * eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
847 * eventAttrib.message.ascii = "Level 0";
848 * nvtxRangePushEx(&eventAttrib);
849 *
850 * // Re-use eventAttrib
851 * eventAttrib.messageType = NVTX_MESSAGE_TYPE_UNICODE;
852 * eventAttrib.message.unicode = L"Level 1";
853 * nvtxRangePushEx(&eventAttrib);
854 *
855 * nvtxRangePop();
856 * nvtxRangePop();
857 * \endcode
858 *
859 * \sa
860 * ::nvtxDomainRangePushEx
861 * ::nvtxRangePop
862 *
863 * \version \NVTX_VERSION_1
864 * @{ */
865NVTX_DECLSPEC int NVTX_API nvtxRangePushEx(const nvtxEventAttributes_t* eventAttrib);
866/** @} */
867
868/* ------------------------------------------------------------------------- */
869/** \brief Starts a nested thread range.
870 *
871 * \param message - The event message associated to this range event.
872 *
873 * \return The 0 based level of range being started. If an error occurs a
874 * negative value is returned.
875 *
876 * \par Example:
877 * \code
878 * nvtxRangePushA("Level 0");
879 * nvtxRangePushW(L"Level 1");
880 * nvtxRangePop();
881 * nvtxRangePop();
882 * \endcode
883 *
884 * \sa
885 * ::nvtxDomainRangePushEx
886 * ::nvtxRangePop
887 *
888 * \version \NVTX_VERSION_0
889 * @{ */
890NVTX_DECLSPEC int NVTX_API nvtxRangePushA(const char* message);
891NVTX_DECLSPEC int NVTX_API nvtxRangePushW(const wchar_t* message);
892/** @} */
893
894
895/* ------------------------------------------------------------------------- */
896/** \brief Ends a nested thread range.
897*
898* \return The level of the range being ended. If an error occurs a negative
899* value is returned on the current thread.
900*
901* \par Example:
902* \code
903* nvtxDomainHandle_t domain = nvtxDomainCreate("example library");
904* nvtxDomainRangePushA(domain, "Level 0");
905* nvtxDomainRangePushW(domain, L"Level 1");
906* nvtxDomainRangePop(domain);
907* nvtxDomainRangePop(domain);
908* \endcode
909*
910* \sa
911* ::nvtxRangePushEx
912* ::nvtxRangePushA
913* ::nvtxRangePushW
914*
915* \version \NVTX_VERSION_2
916* @{ */
917NVTX_DECLSPEC int NVTX_API nvtxDomainRangePop(nvtxDomainHandle_t domain);
918/** @} */
919
920/* ------------------------------------------------------------------------- */
921/** \brief Ends a nested thread range.
922 *
923 * \return The level of the range being ended. If an error occurs a negative
924 * value is returned on the current thread.
925 *
926 * \par Example:
927 * \code
928 * nvtxRangePushA("Level 0");
929 * nvtxRangePushW(L"Level 1");
930 * nvtxRangePop();
931 * nvtxRangePop();
932 * \endcode
933 *
934 * \sa
935 * ::nvtxRangePushEx
936 * ::nvtxRangePushA
937 * ::nvtxRangePushW
938 *
939 * \version \NVTX_VERSION_0
940 * @{ */
941NVTX_DECLSPEC int NVTX_API nvtxRangePop(void);
942/** @} */
943
944
945/** @} */ /*END defgroup*/
946/* ========================================================================= */
947/** \defgroup RESOURCE_NAMING Resource Naming
948 *
949 * See \ref RESOURCE_NAMING for more details
950 *
951 * @{
952 */
953
954
955/* ------------------------------------------------------------------------- */
956/** \name Functions for Generic Resource Naming*/
957/* ------------------------------------------------------------------------- */
958
959/* ------------------------------------------------------------------------- */
960/** \cond SHOW_HIDDEN
961* \brief Resource typing helpers.
962*
963* Classes are used to make it easy to create a series of resource types
964* per API without collisions
965*/
966#define NVTX_RESOURCE_MAKE_TYPE(CLASS, INDEX) ((((uint32_t)(NVTX_RESOURCE_CLASS_ ## CLASS))<<16)|((uint32_t)(INDEX)))
967#define NVTX_RESOURCE_CLASS_GENERIC 1
968/** \endcond */
969
970/* ------------------------------------------------------------------------- */
971/** \brief Generic resource type for when a resource class is not available.
972*
973* \sa
974* ::nvtxDomainResourceCreate
975*
976* \version \NVTX_VERSION_2
977*/
978typedef enum nvtxResourceGenericType_t
979{
980 NVTX_RESOURCE_TYPE_UNKNOWN = 0,
981 NVTX_RESOURCE_TYPE_GENERIC_POINTER = NVTX_RESOURCE_MAKE_TYPE(GENERIC, 1), /**< Generic pointer assumed to have no collisions with other pointers. */
982 NVTX_RESOURCE_TYPE_GENERIC_HANDLE = NVTX_RESOURCE_MAKE_TYPE(GENERIC, 2), /**< Generic handle assumed to have no collisions with other handles. */
983 NVTX_RESOURCE_TYPE_GENERIC_THREAD_NATIVE = NVTX_RESOURCE_MAKE_TYPE(GENERIC, 3), /**< OS native thread identifier. */
984 NVTX_RESOURCE_TYPE_GENERIC_THREAD_POSIX = NVTX_RESOURCE_MAKE_TYPE(GENERIC, 4) /**< POSIX pthread identifier. */
985} nvtxResourceGenericType_t;
986
987
988
989/** \brief Resource Attribute Structure.
990* \anchor RESOURCE_ATTRIBUTE_STRUCTURE
991*
992* This structure is used to describe the attributes of a resource. The layout of
993* the structure is defined by a specific version of the tools extension
994* library and can change between different versions of the Tools Extension
995* library.
996*
997* \par Initializing the Attributes
998*
999* The caller should always perform the following three tasks when using
1000* attributes:
1001* <ul>
1002* <li>Zero the structure
1003* <li>Set the version field
1004* <li>Set the size field
1005* </ul>
1006*
1007* Zeroing the structure sets all the resource attributes types and values
1008* to the default value.
1009*
1010* The version and size field are used by the Tools Extension
1011* implementation to handle multiple versions of the attributes structure.
1012*
1013* It is recommended that the caller use one of the following to methods
1014* to initialize the event attributes structure:
1015*
1016* \par Method 1: Initializing nvtxEventAttributes for future compatibility
1017* \code
1018* nvtxResourceAttributes_t attribs = {0};
1019* attribs.version = NVTX_VERSION;
1020* attribs.size = NVTX_RESOURCE_ATTRIB_STRUCT_SIZE;
1021* \endcode
1022*
1023* \par Method 2: Initializing nvtxEventAttributes for a specific version
1024* \code
1025* nvtxResourceAttributes_v0 attribs = {0};
1026* attribs.version = 2;
1027* attribs.size = (uint16_t)(sizeof(nvtxResourceAttributes_v0));
1028* \endcode
1029*
1030* If the caller uses Method 1 it is critical that the entire binary
1031* layout of the structure be configured to 0 so that all fields
1032* are initialized to the default value.
1033*
1034* The caller should either use both NVTX_VERSION and
1035* NVTX_RESOURCE_ATTRIB_STRUCT_SIZE (Method 1) or use explicit values
1036* and a versioned type (Method 2). Using a mix of the two methods
1037* will likely cause either source level incompatibility or binary
1038* incompatibility in the future.
1039*
1040* \par Settings Attribute Types and Values
1041*
1042*
1043* \par Example:
1044* \code
1045* nvtxDomainHandle_t domain = nvtxDomainCreateA("example domain");
1046*
1047* // Initialize
1048* nvtxResourceAttributes_t attribs = {0};
1049* attribs.version = NVTX_VERSION;
1050* attribs.size = NVTX_RESOURCE_ATTRIB_STRUCT_SIZE;
1051*
1052* // Configure the Attributes
1053* attribs.identifierType = NVTX_RESOURCE_TYPE_GENERIC_POINTER;
1054* attribs.identifier.pValue = (const void*)pMutex;
1055* attribs.messageType = NVTX_MESSAGE_TYPE_ASCII;
1056* attribs.message.ascii = "Single thread access to database.";
1057*
1058* nvtxResourceHandle_t handle = nvtxDomainResourceCreate(domain, attribs);
1059* \endcode
1060*
1061* \sa
1062* ::nvtxDomainResourceCreate
1063*/
1064typedef struct nvtxResourceAttributes_v0
1065{
1066 /**
1067 * \brief Version flag of the structure.
1068 *
1069 * Needs to be set to NVTX_VERSION to indicate the version of NVTX APIs
1070 * supported in this header file. This can optionally be overridden to
1071 * another version of the tools extension library.
1072 */
1073 uint16_t version;
1074
1075 /**
1076 * \brief Size of the structure.
1077 *
1078 * Needs to be set to the size in bytes of this attribute
1079 * structure.
1080 */
1081 uint16_t size;
1082
1083 /**
1084 * \brief Identifier type specifies how to interpret the identifier field
1085 *
1086 * Defines the identifier format of the attribute structure's \ref RESOURCE_IDENTIFIER_FIELD
1087 * "identifier" field.
1088 *
1089 * Default Value is NVTX_RESOURCE_TYPE_UNKNOWN
1090 */
1091 int32_t identifierType; /* values from enums following the pattern nvtxResource[name]Type_t */
1092
1093 /**
1094 * \brief Identifier for the resource.
1095 * \anchor RESOURCE_IDENTIFIER_FIELD
1096 *
1097 * An identifier may be a pointer or a handle to an OS or middleware API object.
1098 * The resource type will assist in avoiding collisions where handles values may collide.
1099 */
1100 union identifier_t
1101 {
1102 const void* pValue;
1103 uint64_t ullValue;
1104 } identifier;
1105
1106 /** \brief Message type specified in this attribute structure.
1107 *
1108 * Defines the message format of the attribute structure's \ref RESOURCE_MESSAGE_FIELD
1109 * "message" field.
1110 *
1111 * Default Value is NVTX_MESSAGE_UNKNOWN
1112 */
1113 int32_t messageType; /* nvtxMessageType_t */
1114
1115 /** \brief Message assigned to this attribute structure. \anchor RESOURCE_MESSAGE_FIELD
1116 *
1117 * The text message that is attached to a resource.
1118 */
1119 nvtxMessageValue_t message;
1120
1121} nvtxResourceAttributes_v0;
1122
1123typedef struct nvtxResourceAttributes_v0 nvtxResourceAttributes_t;
1124
1125/* \cond SHOW_HIDDEN
1126* \version \NVTX_VERSION_2
1127*/
1128#define NVTX_RESOURCE_ATTRIB_STRUCT_SIZE ( (uint16_t)( sizeof(nvtxResourceAttributes_v0) ) )
1129typedef struct nvtxResourceHandle* nvtxResourceHandle_t;
1130/** \endcond */
1131
1132
1133
1134/* ------------------------------------------------------------------------- */
1135/** \brief Create a resource object to track and associate data with OS and middleware objects
1136*
1137* Allows users to associate an API handle or pointer with a user-provided name.
1138*
1139*
1140* \param domain - Domain to own the resource object
1141* \param attribs - Attributes to be associated with the resource
1142*
1143* \return A handle that represents the newly created resource object.
1144*
1145* \par Example:
1146* \code
1147* nvtxDomainHandle_t domain = nvtxDomainCreateA("example domain");
1148* nvtxResourceAttributes_t attribs = {0};
1149* attribs.version = NVTX_VERSION;
1150* attribs.size = NVTX_RESOURCE_ATTRIB_STRUCT_SIZE;
1151* attribs.identifierType = NVTX_RESOURCE_TYPE_GENERIC_POINTER;
1152* attribs.identifier.pValue = (const void*)pMutex;
1153* attribs.messageType = NVTX_MESSAGE_TYPE_ASCII;
1154* attribs.message.ascii = "Single thread access to database.";
1155* nvtxResourceHandle_t handle = nvtxDomainResourceCreate(domain, attribs);
1156* \endcode
1157*
1158* \sa
1159* ::nvtxResourceAttributes_t
1160* ::nvtxDomainResourceDestroy
1161*
1162* \version \NVTX_VERSION_2
1163* @{ */
1164NVTX_DECLSPEC nvtxResourceHandle_t NVTX_API nvtxDomainResourceCreate(nvtxDomainHandle_t domain, nvtxResourceAttributes_t* attribs);
1165/** @} */
1166
1167/* ------------------------------------------------------------------------- */
1168/** \brief Destroy a resource object to track and associate data with OS and middleware objects
1169*
1170* Allows users to associate an API handle or pointer with a user-provided name.
1171*
1172* \param resource - Handle to the resource in which to operate.
1173*
1174* \par Example:
1175* \code
1176* nvtxDomainHandle_t domain = nvtxDomainCreateA("example domain");
1177* nvtxResourceAttributes_t attribs = {0};
1178* attribs.version = NVTX_VERSION;
1179* attribs.size = NVTX_RESOURCE_ATTRIB_STRUCT_SIZE;
1180* attribs.identifierType = NVTX_RESOURCE_TYPE_GENERIC_POINTER;
1181* attribs.identifier.pValue = (const void*)pMutex;
1182* attribs.messageType = NVTX_MESSAGE_TYPE_ASCII;
1183* attribs.message.ascii = "Single thread access to database.";
1184* nvtxResourceHandle_t handle = nvtxDomainResourceCreate(domain, attribs);
1185* nvtxDomainResourceDestroy(handle);
1186* \endcode
1187*
1188* \sa
1189* ::nvtxDomainResourceCreate
1190*
1191* \version \NVTX_VERSION_2
1192* @{ */
1193NVTX_DECLSPEC void NVTX_API nvtxDomainResourceDestroy(nvtxResourceHandle_t resource);
1194/** @} */
1195
1196
1197/** \name Functions for NVTX Category Naming*/
1198
1199/* ------------------------------------------------------------------------- */
1200/**