Adapting a Third Party Visualizer

TotalView passes a stream of datasets to the Visualizer encoded in the format described below, thus supporting the use of this data with other programs, with these requirements:

TotalView and the Visualizer must be running on the same machine architectures; that is, TotalView assumes that word lengths, byte order, and floating-point representations are identical. While sufficient information in the dataset header exists to detect when this is not the case (with the exception of floating-point representation), no method for translating this information is supplied.

TotalView transmits datasets down the pipe in a simple unidirectional flow. There is no handshaking protocol in the interface. This requires the Visualizer to be an eager reader on the pipe. If the Visualizer does not read eagerly, the pipe will back up and block TotalView.

Visualizer dataset format

The dataset format is described in the TotalView distribution in a header file named include/visualize.h in the TotalView installation directory. Each dataset is encoded with a fixed-length header followed by a stream of array elements. The header contains the following fields:

vh_axis_order

Contains one of the constants vis_ao_row_major or vis_ao_column_major.

vh_dims

Contains information on each dimension of the dataset. This includes a base, count, and stride. Only the count is required to correctly parse the dataset. The base and stride give information only on the valid indices in the original data.

Note that all VIS_MAXDIMS of dimension information is included in the header, even if the data has fewer dimensions.

vh_effective_rank

Contains the number of dimensions that have an extent larger than 1.

vh_id

Contains the dataset ID. Every dataset in a stream of datasets is numbered with a unique ID so that updates to a previous dataset can be distinguished from new datasets.

vh_item_count

Contains the total number of expected elements.

vh_item_length

Contains the length (in bytes) of a single element of the array.

vh_magic

Contains VIS_MAGIC, a symbolic constant to provide a check that this is a dataset header and that byte order is compatible.

vh_title

Contains a plain text string of length VIS_MAXSTRING that annotates the dataset.

vh_type

Contains one of the constants vis_signed_int, vis_unsigned_int, or vis_float.

vh_version

Contains VIS_VERSION, a symbolic constant to provide a check that the reader understands the protocol.

Types in the dataset are encoded by a combination of the vh_type field and the vh_item_length field. This allows the format to handle arbitrary sizes of both signed and unsigned integers, and floating-point numbers.

The vis_float constant corresponds to the default floating-point format (usually, IEEE) of the target machine. The Visualizer does not handle values other than the default on machines that support more than one floating-point format.

Although a three-byte integer is expressible in the Visualizer’s dataset format, it is unlikely that the Visualizer will handle one. The Visualizer handles only data types that correspond to the C data types permitted on the machine where the Visualizer is running.

Similarly, the long double type varies significantly depending on the C compiler and target machine. Therefore, visualization of the long double type is unlikely to work if you run the Visualizer on a machine different from the one where you extracted the data.

In addition, be aware of these data type differences if you write your own visualizer and plan to run it on a machine that is different from the one where you extract the data.

The data following the header is a stream of consecutive data values of the type indicated in the header. Consecutive data values in the input stream correspond to adjacent elements in vh_dims[0].

You can verify that your reader’s idea of the size of this type is consistent with TotalView by checking that the value of the n_bytes field of the header matches the product of the size of the type and the total number of array elements.