1. Introduction
The NVIDIA Tools Extension (NVTX) library is a set of functions that a developer can use to provide additional information to tools. The additional information is used by the tool to improve analysis and visualization of data.
The library introduces close to zero overhead if no tool is attached to the application. The overhead when a tool is attached is specific to the tool.
2. Initialization
Typically the tool's library that plugs into NVTX is indirectly loaded via environmental properties that are platform specific. For some platform or special cases, the user may be required to instead explicitly initialize instead though. This can also be helpful to control when the API loads a tool's library instead of what would typically be the first function call to emit info. For these rare case, see INITIALIZATION for additional information.
3. Markers and Ranges
Markers and ranges are used to describe events at a specific time (markers) or over a time span (ranges) during the execution of the application respectively.
3.1. Markers
Markers denote specific moments in time.
See Domains and Event Attributes for additional information on how to specify the domain.
3.2. Thread Ranges
Thread ranges denote nested time ranges. Nesting is maintained per thread per domain and does not require any additional correlation mechanism. The duration of a thread range is defined by the corresponding pair of nvtxRangePush* to nvtxRangePop API calls.
See Domains and Event Attributes for additional information on how to specify the domain.
3.3. Process Ranges
Process ranges denote a time span that can expose arbitrary concurrency, as opposed to thread ranges that only support nesting. In addition the range start event can happen on a different thread than the end marker. For the correlation of a start/end pair an unique correlation ID is used that is returned from the start API call and needs to be passed into the end API call.
3.4. Event Attributes
Markers and Ranges can be annotated with various attributes to provide additional information for an event or to guide the tool's visualization of the data. Each of the attributes is optional and if left unused the attributes fall back to a default value. The attributes include:
- color
- category
To specify any attribute other than the text message, the Event Attribute Structure must be used.
4. Domains
Domains enable developers to scope annotations. By default, all events and annotations are in the default domain. Additional domains can be registered. This allows developers to scope markers, ranges, and resources names to avoid conflicts.
The function nvtxDomainCreateA or ::nvtxDomainCreateW is used to create a named domain.
Each domain maintains its own
- categories,
- thread range stacks,
- registered strings.
The function nvtxDomainDestroy marks the end of the domain. Destroying a domain unregisters and destroys all objects associated with it such as registered strings, resource objects, named categories, and started ranges.
5. Resource Naming
This section covers calls that allow to annotate objects with user-provided names in order to allow for a better analysis of complex trace data. All of the functions take the handle or the ID of the object to name and the name. The functions can be called multiple times during the execution of an application, however, in that case it is implementation dependent which name will be reported by the tool.
5.1. Category Naming
Some functions in this library support associating an integer category to enable filtering and sorting. The category naming functions allow the application to associate a user-friendly name with the integer category. Support for domains have been added in NVTX_VERSION_2 to avoid collisions when domains are developed independently.
5.2. Resource Objects
Resource objects are a generic mechanism for attaching data to an application resource. The identifier field makes the association to a pointer or handle, while the type field helps provide deeper understanding of the identifier as well as enabling differentiation in cases where handles generated by different APIs may collide. The resource object may also have an associated message to associate with the application resource, enabling further annotation of this object and how it is used.
The resource object was introduced in NVTX_VERSION_2 to supersede existing naming functions and allow the application resource identified by those functions to be associated to a domain. The other naming functions are still supported for backward compatibility but will be associated only to the default domain.
5.3. Resource Naming
Some operating system resources creation APIs do not support providing a user friendly name, such as some OS thread creation APIs. This API support resource naming though both through resource objects and functions following the pattern nvtxName[RESOURCE_TYPE][A|W](identifier, name).
Resource objects introduced in NVTX_VERSION 2 supersede the other functions with a more general method of assigning names to OS resources, along with associating them to domains too. The older nvtxName* functions are only associated with the default domain.
6. Optional Extensions
Optional extensions will either appear within the existing sections the extend or appear in the "Related Pages" when they introduce new concepts.
Notices
Notice
This document is provided for information purposes only and shall not be regarded as a warranty of a certain functionality, condition, or quality of a product. NVIDIA Corporation (“NVIDIA”) makes no representations or warranties, expressed or implied, as to the accuracy or completeness of the information contained in this document and assumes no responsibility for any errors contained herein. NVIDIA shall have no liability for the consequences or use of such information or for any infringement of patents or other rights of third parties that may result from its use. This document is not a commitment to develop, release, or deliver any Material (defined below), code, or functionality.
NVIDIA reserves the right to make corrections, modifications, enhancements, improvements, and any other changes to this document, at any time without notice.
Customer should obtain the latest relevant information before placing orders and should verify that such information is current and complete.
NVIDIA products are sold subject to the NVIDIA standard terms and conditions of sale supplied at the time of order acknowledgement, unless otherwise agreed in an individual sales agreement signed by authorized representatives of NVIDIA and customer (“Terms of Sale”). NVIDIA hereby expressly objects to applying any customer general terms and conditions with regards to the purchase of the NVIDIA product referenced in this document. No contractual obligations are formed either directly or indirectly by this document.
NVIDIA products are not designed, authorized, or warranted to be suitable for use in medical, military, aircraft, space, or life support equipment, nor in applications where failure or malfunction of the NVIDIA product can reasonably be expected to result in personal injury, death, or property or environmental damage. NVIDIA accepts no liability for inclusion and/or use of NVIDIA products in such equipment or applications and therefore such inclusion and/or use is at customer’s own risk.
NVIDIA makes no representation or warranty that products based on this document will be suitable for any specified use. Testing of all parameters of each product is not necessarily performed by NVIDIA. It is customer’s sole responsibility to evaluate and determine the applicability of any information contained in this document, ensure the product is suitable and fit for the application planned by customer, and perform the necessary testing for the application in order to avoid a default of the application or the product. Weaknesses in customer’s product designs may affect the quality and reliability of the NVIDIA product and may result in additional or different conditions and/or requirements beyond those contained in this document. NVIDIA accepts no liability related to any default, damage, costs, or problem which may be based on or attributable to: (i) the use of the NVIDIA product in any manner that is contrary to this document or (ii) customer product designs.
No license, either expressed or implied, is granted under any NVIDIA patent right, copyright, or other NVIDIA intellectual property right under this document. Information published by NVIDIA regarding third-party products or services does not constitute a license from NVIDIA to use such products or services or a warranty or endorsement thereof. Use of such information may require a license from a third party under the patents or other intellectual property rights of the third party, or a license from NVIDIA under the patents or other intellectual property rights of NVIDIA.
Reproduction of information in this document is permissible only if approved in advance by NVIDIA in writing, reproduced without alteration and in full compliance with all applicable export laws and regulations, and accompanied by all associated conditions, limitations, and notices.
THIS DOCUMENT AND ALL NVIDIA DESIGN SPECIFICATIONS, REFERENCE BOARDS, FILES, DRAWINGS, DIAGNOSTICS, LISTS, AND OTHER DOCUMENTS (TOGETHER AND SEPARATELY, “MATERIALS”) ARE BEING PROVIDED “AS IS.” NVIDIA MAKES NO WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO THE MATERIALS, AND EXPRESSLY DISCLAIMS ALL IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL NVIDIA BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF ANY USE OF THIS DOCUMENT, EVEN IF NVIDIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Notwithstanding any damages that customer might incur for any reason whatsoever, NVIDIA’s aggregate and cumulative liability towards customer for the products described herein shall be limited in accordance with the Terms of Sale for the product.
VESA DisplayPort
DisplayPort and DisplayPort Compliance Logo, DisplayPort Compliance Logo for Dual-mode Sources, and DisplayPort Compliance Logo for Active Cables are trademarks owned by the Video Electronics Standards Association in the United States and other countries.
HDMI
HDMI, the HDMI logo, and High-Definition Multimedia Interface are trademarks or registered trademarks of HDMI Licensing LLC.