util/X86LINUX64/cuda-6.5/include/nvToolsExt.h

   1 /*
   2 * Copyright 2009-2012  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 /** \mainpage
  39  * \section Introduction
  40  * The NVIDIA Tools Extension library is a set of functions that a
  41  * developer can use to provide additional information to tools.
  42  * The additional information is used by the tool to improve
  43  * analysis and visualization of data.
  44  *
  45  * The library introduces close to zero overhead if no tool is
  46  * attached to the application.  The overhead when a tool is
  47  * attached is specific to the tool.
  48  */
  49
  50 #ifndef NVTOOLSEXT_H_
  51 #define NVTOOLSEXT_H_
  52
  53 #if defined(_MSC_VER) /* Microsoft Visual C++ Compiler */
  54     #ifdef NVTX_EXPORTS
  55         #define NVTX_DECLSPEC
  56     #else
  57         #define NVTX_DECLSPEC __declspec(dllimport)
  58     #endif /* NVTX_EXPORTS */
  59     #define NVTX_API __stdcall
  60 #else /* GCC and most other compilers */
  61     #define NVTX_DECLSPEC
  62     #define NVTX_API
  63 #endif /* Platform */
  64
  65 /**
  66  * The nvToolsExt library depends on stdint.h.  If the build tool chain in use
  67  * does not include stdint.h then define NVTX_STDINT_TYPES_ALREADY_DEFINED
  68  * and define the following types:
  69  * <ul>
  70  *   <li>uint8_t
  71  *   <li>int8_t
  72  *   <li>uint16_t
  73  *   <li>int16_t
  74  *   <li>uint32_t
  75  *   <li>int32_t
  76  *   <li>uint64_t
  77  *   <li>int64_t
  78  *   <li>uintptr_t
  79  *   <li>intptr_t
  80  * </ul>
  81  #define NVTX_STDINT_TYPES_ALREADY_DEFINED if you are using your own header file.
  82  */
  83 #ifndef NVTX_STDINT_TYPES_ALREADY_DEFINED
  84 #include <stdint.h>
  85 #endif
  86
  87 #ifdef __cplusplus
  88 extern "C" {
  89 #endif /* __cplusplus */
  90
  91 /**
  92  * Tools Extension API version
  93  */
  94 #define NVTX_VERSION 1
  95
  96 /**
  97  * Size of the nvtxEventAttributes_t structure.
  98  */
  99 #define NVTX_EVENT_ATTRIB_STRUCT_SIZE ( (uint16_t)( sizeof(nvtxEventAttributes_v1) ) )
 100
 101 #define NVTX_NO_PUSH_POP_TRACKING ((int)-2)
 102
 103 typedef uint64_t nvtxRangeId_t;
 104
 105 /** \page EVENT_ATTRIBUTES Event Attributes
 106  *
 107  * \ref MARKER_AND_RANGES can be annotated with various attributes to provide
 108  * additional information for an event or to guide the tool's visualization of
 109  * the data. Each of the attributes is optional and if left unused the
 110  * attributes fall back to a default value.
 111  *
 112  * To specify any attribute other than the text message, the \ref
 113  * EVENT_ATTRIBUTE_STRUCTURE "Event Attribute Structure" must be used.
 114  */
 115
 116 /** ---------------------------------------------------------------------------
 117  * Color Types
 118  * ------------------------------------------------------------------------- */
 119 typedef enum nvtxColorType_t
 120 {
 121     NVTX_COLOR_UNKNOWN  = 0,                 /**< Color attribute is unused. */
 122     NVTX_COLOR_ARGB     = 1                  /**< An ARGB color is provided. */
 123 } nvtxColorType_t;
 124
 125 /** ---------------------------------------------------------------------------
 126  * Payload Types
 127  * ------------------------------------------------------------------------- */
 128 typedef enum nvtxPayloadType_t
 129 {
 130     NVTX_PAYLOAD_UNKNOWN                = 0,   /**< Color payload is unused. */
 131     NVTX_PAYLOAD_TYPE_UNSIGNED_INT64    = 1,   /**< A unsigned integer value is used as payload. */
 132     NVTX_PAYLOAD_TYPE_INT64             = 2,   /**< A signed integer value is used as payload. */
 133     NVTX_PAYLOAD_TYPE_DOUBLE            = 3    /**< A floating point value is used as payload. */
 134 } nvtxPayloadType_t;
 135
 136 /** ---------------------------------------------------------------------------
 137  * Message Types
 138  * ------------------------------------------------------------------------- */
 139 typedef enum nvtxMessageType_t
 140 {
 141     NVTX_MESSAGE_UNKNOWN        = 0,         /**< Message payload is unused. */
 142     NVTX_MESSAGE_TYPE_ASCII     = 1,         /**< A character sequence is used as payload. */
 143     NVTX_MESSAGE_TYPE_UNICODE   = 2          /**< A wide character sequence is used as payload. */
 144 } nvtxMessageType_t;
 145
 146 /** \brief Event Attribute Structure.
 147  * \anchor EVENT_ATTRIBUTE_STRUCTURE
 148  *
 149  * This structure is used to describe the attributes of an event. The layout of
 150  * the structure is defined by a specific version of the tools extension
 151  * library and can change between different versions of the Tools Extension
 152  * library.
 153  *
 154  * \par Initializing the Attributes
 155  *
 156  * The caller should always perform the following three tasks when using
 157  * attributes:
 158  * <ul>
 159  *    <li>Zero the structure
 160  *    <li>Set the version field
 161  *    <li>Set the size field
 162  * </ul>
 163  *
 164  * Zeroing the structure sets all the event attributes types and values
 165  * to the default value.
 166  *
 167  * The version and size field are used by the Tools Extension
 168  * implementation to handle multiple versions of the attributes structure.
 169  *
 170  * It is recommended that the caller use one of the following to methods
 171  * to initialize the event attributes structure:
 172  *
 173  * \par Method 1: Initializing nvtxEventAttributes for future compatibility
 174  * \code
 175  * nvtxEventAttributes_t eventAttrib = {0};
 176  * eventAttrib.version = NVTX_VERSION;
 177  * eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
 178  * \endcode
 179  *
 180  * \par Method 2: Initializing nvtxEventAttributes for a specific version
 181  * \code
 182  * nvtxEventAttributes_t eventAttrib = {0};
 183  * eventAttrib.version = 1;
 184  * eventAttrib.size = (uint16_t)(sizeof(nvtxEventAttributes_v1));
 185  * \endcode
 186  *
 187  * If the caller uses Method 1 it is critical that the entire binary
 188  * layout of the structure be configured to 0 so that all fields
 189  * are initialized to the default value.
 190  *
 191  * The caller should either use both NVTX_VERSION and
 192  * NVTX_EVENT_ATTRIB_STRUCT_SIZE (Method 1) or use explicit values
 193  * and a versioned type (Method 2).  Using a mix of the two methods
 194  * will likely cause either source level incompatibility or binary
 195  * incompatibility in the future.
 196  *
 197  * \par Settings Attribute Types and Values
 198  *
 199  *
 200  * \par Example:
 201  * \code
 202  * // Initialize
 203  * nvtxEventAttributes_t eventAttrib = {0};
 204  * eventAttrib.version = NVTX_VERSION;
 205  * eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
 206  *
 207  * // Configure the Attributes
 208  * eventAttrib.colorType = NVTX_COLOR_ARGB;
 209  * eventAttrib.color = 0xFF880000;
 210  * eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
 211  * eventAttrib.message.ascii = "Example";
 212  * \endcode
 213  *
 214  * In the example the caller does not have to set the value of
 215  * \ref ::nvtxEventAttributes_v1::category or
 216  * \ref ::nvtxEventAttributes_v1::payload as these fields were set to
 217  * the default value by {0}.
 218  * \sa
 219  * ::nvtxMarkEx
 220  * ::nvtxRangeStartEx
 221  * ::nvtxRangePushEx
 222  */
 223 typedef struct nvtxEventAttributes_v1
 224 {
 225     /**
 226     * \brief Version flag of the structure.
 227     *
 228     * Needs to be set to NVTX_VERSION to indicate the version of NVTX APIs
 229     * supported in this header file. This can optionally be overridden to
 230     * another version of the tools extension library.
 231     */
 232     uint16_t version;
 233
 234     /**
 235     * \brief Size of the structure.
 236     *
 237     * Needs to be set to the size in bytes of the event attribute
 238     * structure used to specify the event.
 239     */
 240     uint16_t size;
 241
 242     /**
 243      * \brief ID of the category the event is assigned to.
 244      *
 245      * A category is a user-controlled ID that can be used to group
 246      * events.  The tool may use category IDs to improve filtering or
 247      * enable grouping of events in the same category. The functions
 248      * \ref ::nvtxNameCategoryA or \ref ::nvtxNameCategoryW can be used
 249      * to name a category.
 250      *
 251      * Default Value is 0
 252      */
 253     uint32_t category;
 254
 255     /** \brief Color type specified in this attribute structure.
 256      *
 257      * Defines the color format of the attribute structure's \ref COLOR_FIELD
 258      * "color" field.
 259      *
 260      * Default Value is NVTX_COLOR_UNKNOWN
 261      */
 262     int32_t colorType;              /* nvtxColorType_t */
 263
 264     /** \brief Color assigned to this event. \anchor COLOR_FIELD
 265      *
 266      * The color that the tool should use to visualize the event.
 267      */
 268     uint32_t color;
 269
 270     /**
 271      * \brief Payload type specified in this attribute structure.
 272      *
 273      * Defines the payload format of the attribute structure's \ref PAYLOAD_FIELD
 274      * "payload" field.
 275      *
 276      * Default Value is NVTX_PAYLOAD_UNKNOWN
 277      */
 278     int32_t payloadType;            /* nvtxPayloadType_t */
 279
 280     int32_t reserved0;
 281
 282     /**
 283      * \brief Payload assigned to this event. \anchor PAYLOAD_FIELD
 284      *
 285      * A numerical value that can be used to annotate an event. The tool could
 286      * use the payload data to reconstruct graphs and diagrams.
 287      */
 288     union payload_t
 289     {
 290         uint64_t ullValue;
 291         int64_t llValue;
 292         double dValue;
 293     } payload;
 294
 295     /** \brief Message type specified in this attribute structure.
 296      *
 297      * Defines the message format of the attribute structure's \ref MESSAGE_FIELD
 298      * "message" field.
 299      *
 300      * Default Value is NVTX_MESSAGE_UNKNOWN
 301      */
 302     int32_t messageType;            /* nvtxMessageType_t */
 303
 304     /** \brief Message assigned to this attribute structure. \anchor MESSAGE_FIELD
 305      *
 306      * The text message that is attached to an event.
 307      */
 308     union message_t
 309     {
 310         const char* ascii;
 311         const wchar_t* unicode;
 312     } message;
 313
 314 } nvtxEventAttributes_v1;
 315
 316 typedef struct nvtxEventAttributes_v1 nvtxEventAttributes_t;
 317
 318 /* ========================================================================= */
 319 /** \defgroup MARKER_AND_RANGES Marker and Ranges
 320  *
 321  * Markers and ranges are used to describe events at a specific time (markers)
 322  * or over a time span (ranges) during the execution of the application
 323  * respectively. The additional information is presented alongside all other
 324  * captured data and facilitates understanding of the collected information.
 325  */
 326
 327 /* ========================================================================= */
 328 /** \name Markers
 329  */
 330 /** \name Markers
 331  */
 332 /** \addtogroup MARKER_AND_RANGES
 333  * \section MARKER Marker
 334  *
 335  * A marker describes a single point in time.  A marker event has no side effect
 336  * on other events.
 337  *
 338  * @{
 339  */
 340
 341 /* ------------------------------------------------------------------------- */
 342 /** \brief Marks an instantaneous event in the application.
 343  *
 344  * A marker can contain a text message or specify additional information
 345  * using the event attributes structure.  These attributes include a text
 346  * message, color, category, and a payload. Each of the attributes is optional
 347  * and can only be sent out using the \ref nvtxMarkEx function.
 348  * If \ref nvtxMarkA or \ref nvtxMarkW are used to specify the the marker
 349  * or if an attribute is unspecified then a default value will be used.
 350  *
 351  * \param eventAttrib - The event attribute structure defining the marker's
 352  * attribute types and attribute values.
 353  *
 354  * \par Example:
 355  * \code
 356  * // zero the structure
 357  * nvtxEventAttributes_t eventAttrib = {0};
 358  * // set the version and the size information
 359  * eventAttrib.version = NVTX_VERSION;
 360  * eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
 361  * // configure the attributes.  0 is the default for all attributes.
 362  * eventAttrib.colorType = NVTX_COLOR_ARGB;
 363  * eventAttrib.color = 0xFF880000;
 364  * eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
 365  * eventAttrib.message.ascii = "Example nvtxMarkEx";
 366  * nvtxMarkEx(&eventAttrib);
 367  * \endcode
 368  *
 369  * \version \NVTX_VERSION_1
 370  * @{ */
 371 NVTX_DECLSPEC void NVTX_API nvtxMarkEx(const nvtxEventAttributes_t* eventAttrib);
 372 /** @} */
 373
 374 /* ------------------------------------------------------------------------- */
 375 /** \brief Marks an instantaneous event in the application.
 376  *
 377  * A marker created using \ref nvtxMarkA or \ref nvtxMarkW contains only a
 378  * text message.
 379  *
 380  * \param message     - The message associated to this marker event.
 381  *
 382  * \par Example:
 383  * \code
 384  * nvtxMarkA("Example nvtxMarkA");
 385  * nvtxMarkW(L"Example nvtxMarkW");
 386  * \endcode
 387  *
 388  * \version \NVTX_VERSION_0
 389  * @{ */
 390 NVTX_DECLSPEC void NVTX_API nvtxMarkA(const char* message);
 391 NVTX_DECLSPEC void NVTX_API nvtxMarkW(const wchar_t* message);
 392 /** @} */
 393
 394 /** @} */ /* END MARKER_AND_RANGES */
 395
 396 /* ========================================================================= */
 397 /** \name Start/Stop Ranges
 398  */
 399 /** \addtogroup MARKER_AND_RANGES
 400  * \section INDEPENDENT_RANGES Start/Stop Ranges
 401  *
 402  * Start/Stop ranges denote a time span that can expose arbitrary concurrency -
 403  * opposed to Push/Pop ranges that only support nesting. In addition the start
 404  * of a range can happen on a different thread than the end. For the
 405  * correlation of a start/end pair an unique correlation ID is used that is
 406  * returned from the start API call and needs to be passed into the end API
 407  * call.
 408  *
 409  * @{
 410  */
 411
 412 /* ------------------------------------------------------------------------- */
 413 /** \brief Marks the start of a range.
 414  *
 415  * \param eventAttrib - The event attribute structure defining the range's
 416  * attribute types and attribute values.
 417  *
 418  * \return The unique ID used to correlate a pair of Start and End events.
 419  *
 420  * \remarks Ranges defined by Start/End can overlap.
 421  *
 422  * \par Example:
 423  * \code
 424  * nvtxEventAttributes_t eventAttrib = {0};
 425  * eventAttrib.version = NVTX_VERSION;
 426  * eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
 427  * eventAttrib.category = 3;
 428  * eventAttrib.colorType = NVTX_COLOR_ARGB;
 429  * eventAttrib.color = 0xFF0088FF;
 430  * eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
 431  * eventAttrib.message.ascii = "Example RangeStartEnd";
 432  * nvtxRangeId_t rangeId = nvtxRangeStartEx(&eventAttrib);
 433  * // ...
 434  * nvtxRangeEnd(rangeId);
 435  * \endcode
 436  *
 437  * \sa
 438  * ::nvtxRangeEnd
 439  *
 440  * \version \NVTX_VERSION_1
 441  * @{ */
 442 NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartEx(const nvtxEventAttributes_t* eventAttrib);
 443 /** @} */
 444
 445 /* ------------------------------------------------------------------------- */
 446 /** \brief Marks the start of a range.
 447  *
 448  * \param message     - The event message associated to this range event.
 449  *
 450  * \return The unique ID used to correlate a pair of Start and End events.
 451  *
 452  * \remarks Ranges defined by Start/End can overlap.
 453  *
 454  * \par Example:
 455  * \code
 456  * nvtxRangeId_t r1 = nvtxRangeStartA("Range 1");
 457  * nvtxRangeId_t r2 = nvtxRangeStartW(L"Range 2");
 458  * nvtxRangeEnd(r1);
 459  * nvtxRangeEnd(r2);
 460  * \endcode
 461  * \sa
 462  * ::nvtxRangeEnd
 463  *
 464  * \version \NVTX_VERSION_0
 465  * @{ */
 466 NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartA(const char* message);
 467 NVTX_DECLSPEC nvtxRangeId_t NVTX_API nvtxRangeStartW(const wchar_t* message);
 468 /** @} */
 469
 470 /* ------------------------------------------------------------------------- */
 471 /** \brief Marks the end of a range.
 472  *
 473  * \param id - The correlation ID returned from a nvtxRangeStart call.
 474  *
 475  * \sa
 476  * ::nvtxRangeStartEx
 477  * ::nvtxRangeStartA
 478  * ::nvtxRangeStartW
 479  *
 480  * \version \NVTX_VERSION_0
 481  * @{ */
 482 NVTX_DECLSPEC void NVTX_API nvtxRangeEnd(nvtxRangeId_t id);
 483 /** @} */
 484
 485 /** @} */
 486
 487
 488 /* ========================================================================= */
 489 /** \name Push/Pop Ranges
 490  */
 491 /** \addtogroup MARKER_AND_RANGES
 492  * \section PUSH_POP_RANGES Push/Pop Ranges
 493  *
 494  * Push/Pop ranges denote nested time ranges. Nesting is maintained per thread
 495  * and does not require any additional correlation mechanism. The duration of a
 496  * push/pop range is defined by the corresponding pair of Push/Pop API calls.
 497  *
 498  * @{
 499  */
 500
 501 /* ------------------------------------------------------------------------- */
 502 /** \brief Marks the start of a nested range
 503  *
 504  * \param eventAttrib - The event attribute structure defining the range's
 505  * attribute types and attribute values.
 506  *
 507  * \return The 0 based level of range being started.  If an error occurs a
 508  * negative value is returned.
 509  *
 510  * \par Example:
 511  * \code
 512  * nvtxEventAttributes_t eventAttrib = {0};
 513  * eventAttrib.version = NVTX_VERSION;
 514  * eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
 515  * eventAttrib.colorType = NVTX_COLOR_ARGB;
 516  * eventAttrib.color = 0xFFFF0000;
 517  * eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
 518  * eventAttrib.message.ascii = "Level 0";
 519  * nvtxRangePushEx(&eventAttrib);
 520  *
 521  * // Re-use eventAttrib
 522  * eventAttrib.messageType = NVTX_MESSAGE_TYPE_UNICODE;
 523  * eventAttrib.message.unicode = L"Level 1";
 524  * nvtxRangePushEx(&eventAttrib);
 525  *
 526  * nvtxRangePop();
 527  * nvtxRangePop();
 528  * \endcode
 529  *
 530  * \sa
 531  * ::nvtxRangePop
 532  *
 533  * \version \NVTX_VERSION_1
 534  * @{ */
 535 NVTX_DECLSPEC int NVTX_API nvtxRangePushEx(const nvtxEventAttributes_t* eventAttrib);
 536 /** @} */
 537
 538 /* ------------------------------------------------------------------------- */
 539 /** \brief Marks the start of a nested range
 540  *
 541  * \param message     - The event message associated to this range event.
 542  *
 543  * \return The 0 based level of range being started.  If an error occurs a
 544  * negative value is returned.
 545  *
 546  * \par Example:
 547  * \code
 548  * nvtxRangePushA("Level 0");
 549  * nvtxRangePushW(L"Level 1");
 550  * nvtxRangePop();
 551  * nvtxRangePop();
 552  * \endcode
 553  *
 554  * \sa
 555  * ::nvtxRangePop
 556  *
 557  * \version \NVTX_VERSION_0
 558  * @{ */
 559 NVTX_DECLSPEC int NVTX_API nvtxRangePushA(const char* message);
 560 NVTX_DECLSPEC int NVTX_API nvtxRangePushW(const wchar_t* message);
 561 /** @} */
 562
 563 /* ------------------------------------------------------------------------- */
 564 /** \brief Marks the end of a nested range
 565  *
 566  * \return The level of the range being ended. If an error occurs a negative
 567  * value is returned on the current thread.
 568  *
 569  * \sa
 570  * ::nvtxRangePushEx
 571  * ::nvtxRangePushA
 572  * ::nvtxRangePushW
 573  *
 574  * \version \NVTX_VERSION_0
 575  * @{ */
 576 NVTX_DECLSPEC int NVTX_API nvtxRangePop(void);
 577 /** @} */
 578
 579 /** @} */
 580
 581 /* ========================================================================= */
 582 /** \defgroup RESOURCE_NAMING Resource Naming
 583  *
 584  * This section covers calls that allow to annotate objects with user-provided
 585  * names in order to allow for a better analysis of complex trace data. All of
 586  * the functions take the handle or the ID of the object to name and the name.
 587  * The functions can be called multiple times during the execution of an
 588  * application, however, in that case it is implementation dependent which
 589  * name will be reported by the tool.
 590  *
 591  * \section RESOURCE_NAMING_NVTX NVTX Resource Naming
 592  * The NVIDIA Tools Extension library allows to attribute events with additional
 593  * information such as category IDs. These category IDs can be annotated with
 594  * user-provided names using the respective resource naming functions.
 595  *
 596  * \section RESOURCE_NAMING_OS OS Resource Naming
 597  * In order to enable a tool to report system threads not just by their thread
 598  * identifier, the NVIDIA Tools Extension library allows to provide user-given
 599  * names to these OS resources.
 600  * @{
 601  */
 602
 603 /* ------------------------------------------------------------------------- */
 604 /** \name Functions for NVTX Resource Naming
 605  */
 606 /** @{
 607  * \brief Annotate an NVTX category.
 608  *
 609  * Categories are used to group sets of events. Each category is identified
 610  * through a unique ID and that ID is passed into any of the marker/range
 611  * events to assign that event to a specific category. The nvtxNameCategory
 612  * function calls allow the user to assign a name to a category ID.
 613  *
 614  * \param category - The category ID to name.
 615  * \param name     - The name of the category.
 616  *
 617  * \remarks The category names are tracked per process.
 618  *
 619  * \par Example:
 620  * \code
 621  * nvtxNameCategory(1, "Memory Allocation");
 622  * nvtxNameCategory(2, "Memory Transfer");
 623  * nvtxNameCategory(3, "Memory Object Lifetime");
 624  * \endcode
 625  *
 626  * \version \NVTX_VERSION_1
 627  */
 628 NVTX_DECLSPEC void NVTX_API nvtxNameCategoryA(uint32_t category, const char* name);
 629 NVTX_DECLSPEC void NVTX_API nvtxNameCategoryW(uint32_t category, const wchar_t* name);
 630 /** @} */
 631
 632 /* ------------------------------------------------------------------------- */
 633 /** \name Functions for OS Resource Naming
 634  */
 635 /** @{
 636  * \brief Annotate an OS thread.
 637  *
 638  * Allows the user to name an active thread of the current process. If an
 639  * invalid thread ID is provided or a thread ID from a different process is
 640  * used the behavior of the tool is implementation dependent.
 641  *
 642  * \param threadId - The ID of the thread to name.
 643  * \param name     - The name of the thread.
 644  *
 645  * \par Example:
 646  * \code
 647  * nvtxNameOsThread(GetCurrentThreadId(), "MAIN_THREAD");
 648  * \endcode
 649  *
 650  * \version \NVTX_VERSION_1
 651  */
 652 NVTX_DECLSPEC void NVTX_API nvtxNameOsThreadA(uint32_t threadId, const char* name);
 653 NVTX_DECLSPEC void NVTX_API nvtxNameOsThreadW(uint32_t threadId, const wchar_t* name);
 654 /** @} */
 655
 656 /** @} */ /* END RESOURCE_NAMING */
 657
 658 /* ========================================================================= */
 659
 660 #ifdef UNICODE
 661     #define nvtxMark            nvtxMarkW
 662     #define nvtxRangeStart      nvtxRangeStartW
 663     #define nvtxRangePush       nvtxRangePushW
 664     #define nvtxNameCategory    nvtxNameCategoryW
 665     #define nvtxNameOsThread    nvtxNameOsThreadW
 666 #else
 667     #define nvtxMark            nvtxMarkA
 668     #define nvtxRangeStart      nvtxRangeStartA
 669     #define nvtxRangePush       nvtxRangePushA
 670     #define nvtxNameCategory    nvtxNameCategoryA
 671     #define nvtxNameOsThread    nvtxNameOsThreadA
 672 #endif
 673
 674 #ifdef __cplusplus
 675 }
 676 #endif /* __cplusplus */
 677
 678 #endif /* NVTOOLSEXT_H_ */