The itrace utility extracts and prints trace messages generated by the firmware of a ConnectX-2/ ConnectX-3/ConnectX-3 Pro adapter cards. These trace messages inform developers of software drivers about internal status, events, critical errors, etc., for each iRISC. Trace messages generated by iRISCs are stored in the trace buffer. The trace buffer is located in host memory for MemFree adapter cards (i.e., without on-board memory), and in adapter memory for adapter cards with on-board memory.
The utility is a command line application controlled by command line parameters. It prints trace messages in text format to the console.
In order to print the firmware traces, the following are required:
- Debug firmware is burnt and loaded on the device
- The driver is up, meaning:
- For adapters with on-board memory: The SYS_ENABLE command has been executed
- For adapters without on-board memory (MemFree): The RUN_FW command has been executed
- The desired trace mask is set (see the -m flag below)
The mst driver must be started prior to running itrace tool. To start itrace:
- Start the mst driver (mst start or mst restart).
Enter the following command:
|IRISC_NAME||The iRISC for which traces are to be printed. This can be specified once anywhere in the command line as a special option without the leading hyphen. Run ‘itrace -h’ to get a list of iRISC names for each adapter device.|
|-h, --help||Displays help about itrace usage.|
|-m --mask=TRACE_MASK||Sets the Trace Mask.|
To enable generating trace messages for an iRISC, the trace_mask register must be set according to the specifications in the device’s Programmer’s Reference Manual. Setting or clearing bits of the trace_mask register enables or disables, respectively, the generation of specific types of trace messages.
The trace_mask parameter must be either a hexadecimal or a decimal number and its value will be written into the trace_mask register. Changing the trace_mask parameter will not change or remove messages previously stored in the trace buffer, so disabled types of messages can still be displayed by itrace if they were previously generated.
|-w, --wait||Runs itrace in wait mode. itrace will exit only if you press <Ctrl-C>. This is not the default behavior of itrace. Without the -w option, itrace will exit if there have been no|
new traces in the last 0.5 seconds.
|-d, --device=DEVICE||Specifies the name of the mst device driver for accessing the cr-space. The default value is:/dev/mst/mt4099_pci_cr0.|
To run itrace via the I2C interface, use this option to specify the following:
-d=DEVICE, where the device is an I2C device (such as mtusb-1)
|-l, --nolock||Ignore NSI GW lock|
|--nomap||Sets the itrace to not access memory directly (via memory mapping) for reading the trace buffer, but to use the adapter memory access Gateway instead. By default, itrace|
accesses the memory directly. If the cr-space device specified by the -d parameter is one of the I2C devices, -nomap is switched on.
|--noddr||Use memory mapping to access trace buffer. Not supported in this version.|
|--mmap||Do not animate propeller while Waiting|
|--no-propel||Sets the itrace not to animate the propeller in wait mode (-w option). By default, animation is enabled.|
|-v, --version||Prints the MFT version and exits.|
|-c, --color||Enables color in trace output.|
|-D, --dump||Dumps the trace buffer and exits. This option is useful for debugging itrace; it dumps the contents of the trace buffer in row format.|
|Sets first message number to display.|
|--debug=TSTRING||Control trace. See: --help-debug.|
|--help-debug||Prints trace usage.|
For Linux, device names should be listed with the /dev/mst prefix. For Windows, no prefix is required.