NVTXT File Extension


The NVIDIA Tools Extension SDK (NVTX) is a C-based Application Programming Interface (API) for annotating an application. Emitted NVTX annotations are captured and visualized in NVIDIA Nsight on the timeline and custom report pages. In some cases the C-based API might not be applicable or already existing logging infrastructures are difficult to output annotations through the NVTX API.

To address that, NVIDIA Nsight introduces NVTXT, a text version of the Tools Extension SDK. It is based on human-readable *.nvtxt files that can be added to an analysis report to annotate a trace capture. It supports the same marker and ranges events (Markers, Push/Pop Ranges, Start/End Ranges), and the annotations are visualized the same way on the timeline as NVTX annotations. It is possible to use NVTX and NVTXT at the same time.

NVTXT File Format

An NVTXT file is a plain text file with an .nvtxt file extension and can be opened and read by any text editor. Each line contains either one NVTXT instruction or a comment.

There are 3 kinds of NVTXT instructions available:

A comment line begins with a pound sign (#). All characters on that line will be treated as comments and will consequently be ignored by the parser.

Variable Assignments

Variables allow referencing values by name in subsequent instructions. Variables are valid from the point they get defined first until the end of the NVTXT file. Their value remains constant from the initial assignment up to either, the end of the file or the next assignment to the same variable.

NVTXT supports 2 kinds of variables: Strings and Integers.

In order to be valid, a String must have one of the following two characteristics:

In order to be valid, an Integer must have one of the following two characteristics:

As an example, all of the following variables are considered to be valid:

Assignment Instruction

A variable assignment takes this form:

Variable[white-space]=[white-space]value

The left-operand of the assignment is the variable name and it must consist solely of letters, digits, and the '_' (underscore) and cannot begin with a digit.

Variable Expansion

A variable can be expanded anywhere (except between single and double quotes) to retrieve its value. The variable expansion is done during the lexing stage.

To expand a variable, place a dollar sign ($) before a previously assigned variable name.

Note that trying to expand an undefined variable will result in a lexing error.

Command Definitions

NVTXT contains a finite set of commands, with each one containing a predefined list of arguments. Some arguments can be made static, which means that their value will not be read from the command call, but instead from a variable with the same name.

A command definition always begins with the at sign (@) prepended to a valid command name, and is followed by a series of valid argument names, delimited by a comma (,). For example: 

@CommandName,[whitespace]Property1,[whitespace]Property2,[whitespace]Property3

A command definition is valid for all subsequent calls of this command. A command definition can be redefined multiple times in a single NVTXT file.

For example, the RangeStartEnd command's default format is as follows:

@RangeStartEnd, Start, End, TimeBase, ProcessId, ThreadId, CategoryId, Color, Message, Payload
Supported Commands

The following defines all available commands supported in NVTXT. Optional parameters are denoted in italics.

Supported Arguments

The arguments to the commands are defined in the following list. The type of the argument is specified in square brackets. Multiple brackets denote distinct options to define the argument value.

Example

Below you will find an example of defining the RangeStartEnd in a custom way. The arguments where the ProcessId, ThreadId, CategoryId, Color, and TimeBase are defined as static variables. That way, those arguments do not have to be repeated for every call to this command.

@RangeStartEnd, Start, End, Message
ProcessId = 1844
ThreadId = 4880
CategoryId = 1
Color = Blue
TimeBase = Qpc
RangeStartEnd, 8236719005, 8236928073, "My Message"
Command calls

A previously defined command can be issued by Command Calls. A command call always begins with a Command Name followed by a list of values corresponding to the command’s definition. Every value must have the right type and there must be the exact amount of arguments.

CommandName,[whitespace]ValueForProperty1, [whitespace]ValueForProperty2

NVTXT Report Files

NVTXT files that are collocated with NVIDIA Nsight's capture output get automatically loaded when a report is opened. Multiple NVTXT files can be used to annotate a report. However, each input file is handled separately; sharing of IDs, Variables, or Command Definitions across NVTXT files is not supported.

File Location

The NVTXT files can be placed at two locations in the report hierarchy to be properly loaded with a report. Any arbitrary number of NVTXT files can co-exist and be loaded at the same time. Note that the order in which they are loaded is not defined. The two locations are:

1. Capture Directory

Like any file loaded alongside the report, the NVTXT file can be located in the capture folder.

For example, if the Report Directory is set to C:\temp, then the NVTXT file will be located in C:\temp\[project name]\[project name]_Capture_000\.

2. Session Directory

In the Analysis tab of the Nsight Options menu, the user can choose to enable NVTXT file loading from the session folder. Note that the default value is set to True.

By doing so, NVTXT files can also be located in the Session directory. For example, if the Report Directory is set to C:\temp, the NVTXT file will be placed in C:\temp\[project name]\.

To avoid the need to manually copy NVTXT files into the report directory structure after a capture is completed, NVIDIA Nsight provides an environment variable that points to the current session directory. This environment variable, called NSIGHT_ANALYSIS_SESSION_OUTPUT_PATH, is automatically set for the target process and remains valid during the lifetime of a session.

Note that for a remote session, every NVTXT file present in the session directory will be synchronized at the end of every capture session. Therefore, if a session contains multiple captures, old files are likely overridden. It is also the user’s responsibility to properly close any handles to the NVTXT files located in NSIGHT_ANALYSIS_SESSION_OUTPUT_PATH to make them available for file synchronization between the target and host machines.

NVTXT Report Output

Report Summary

An NVTXT file is treated like any other loadable file and will be present in the Report Summary. If it contains errors, a warning message will be shown.

For more information about the errors, you can follow the link to the Session Summary, where all of the lexing, parsing, and loading error messages will be displayed for each of the loaded NVTXT files.

Timeline

NVTXT data will be displayed on the Timeline in the very same way that NVTX data is shown. However, there are two notable differences:

 


NVIDIA® GameWorks™ Documentation Rev. 1.0.200605 ©2014-2020. NVIDIA Corporation. All Rights Reserved.