15. Datagrind: a data accessor logger

To run Datagrind on a program prog, run:

valgrind --tool=exp-datagrind prog

The program will execute. Datagrind does not normally output any diagnostic messages. By default, the output log will be written to datagrind.out.pid, but this can be changed by passing the option --datagrind-out-file=filename.out to Valgrind.

dg_view is a viewer for the output of datagrind, distributed and built separately. It uses GTK+ for display.

To use dg_view, simply run

dg_view datagrind.out.pid

This will open a window showing the data accesses. Green and red dots show read and write accesses respectively; yellows shows pixels where both reads and writes occur. The X axis shows address, while the Y axis shows the instruction count.

To keep the display manageable, not all of the address space is shown. White vertical lines show discontinuities in the address space, where addresses have been omitted. Grey lines show page boundaries, and reddish lines show cache-line boundaries (currently the page and cache-line sizes are hard-coded to 4096 and 64 respectively, rather than obtained from the target machine). The page and cache-line boundaries are only shown when the zoom level is sufficient to avoid them overlapping.

In the initial view, all events and all accessed events are shown, which gives a good overview but makes fine details difficult to see. You can click and drag a rectangle (using the left mouse button) to zoom in on it. The toolbar icons can also be used to zoom in or out in either dimension.

The output format consists of a sequence of records. Each record contains enough information for the record to be skipped without understanding it. Values are encoded in the target's endianness; the file contains sufficient information to determine the endianness, although dg_view currently does not support viewing a file with a different endianness to the host on which it is running. Similarly, all addresses and many sizes are stored using the word (pointer) size of the target machine, with sufficient header information to determine this. dg_view currently supports viewing files with either 32-bit or 64-bit words, regardless of the word size of the machine on which it is run.

Each record begins with a byte identifying the record type. For record types 0-127, the second byte is a length field, indicating the length of the rest of the record (excluding the initial two bytes). A length of 255 is special: it indicates that the actual length is encoded in the following 64 bits. For record types 128-255, the record type is followed by a single byte of payload, giving a two-byte record. The numeric values of the record types can be found in dg_record.h.

Strings are null-terminated. The character set and encoding generally depends on the C code that defines the string, but UTF-8 is recommended.

Records are described with a C-like notation, but these structures will not actually be usable for accessing the file, because the file does not contain any padding between fields (thus, many fields are not aligned). The variable-length encoding of the record length (described above) is denoted by a length type.

The first record in the file is a header record. This is the only place the header record may appear. The signature identifies the general structure of the file, and readers that recognise this signature can be confident of parsing the file, with the exception of values that are specifically reserved, and unknown record types.

The header will never use the extended form of the length field, because it cannot be correctly interpreted until the file endianness is known, and the endianness is itself encoded in the header.

struct header
{
    byte record_type;   // DG_R_HEADER
    length record_length;
    char signature[11] = "DATAGRIND1\0";
    byte version;
    byte endian;        // 0 for little-endian, 1 for big-endian
    byte word_size;
};

Client requests for range tracking are recorded as records as well.

struct track_range
{
    byte record_type;   // DG_R_TRACK_RANGE
    length record_length;
    word address;
    word length;
    string type_name;
    string label;
};

struct untrack_range
{
    byte record_type;   // DG_R_UNTRACK_RANGE
    length record_length;
    word address;
    word length;
};

Like range requests, client requests for event tracking are recorded. The label is truncated to ensure that the record is less than 255 bytes long.

struct event
{
    byte record_type;   // DG_R_START_EVENT or DG_R_END_EVENT
    length record_length;
    string label;
};

Basic blocks are first defined, then later run. A basic block is actually a superblock, so may cover discontiguous addresses and have internal exits. The block definition describes the read and write accesses in the block, as instruction counts relative to the start of the block. The bbdef_entry fields correspond to IMark and data access tags in the VEX IR.

Basic block definitions are limited to 255 instructions and accesses, and should not cross function boundaries, so they may be smaller than VEX basic blocks.

struct bbdef_instr
{
    word addr;
    byte size;
};

struct bbdef_access
{
    byte dir;            // DG_ACC_READ or DG_ACC_WRITE
    byte size;           // size of data access
    byte iseq;           // index into the instruction array
};

struct bbdef
{
    byte record_type;    // DG_R_BBDEF
    length record_length;
    byte n_instrs;       // number of instructions
    word n_accesses;     // number of data accesses
    bbdef_instr instrs[n_instr];
    bbdef_access accesses[n_accesses];
};

It is common to reach the same basic block with the same execution stack multiple times. Each such event is recorded as a context. It refers to the basic block definition by its position in the file, starting from zero.

struct context
{
    word bbdef_index;
    byte n_stack;
    word stack[n_stack];
};

When a block is run, it will refer to a previously defined context by index (its position in the file). It then contains the addresses of the data accesses, in the same order as the data-access entries in the definition. Because a basic block can be exited early, there is an instruction count in the record, and only the data accesses for this many instructions will be reported.

struct bbrun
{
    byte record_type;     // DG_R_CONTEXT
    length record_length;
    word context_index;   // index into sequence of contexts in the file
    byte n_instrs;        // number of instructions executed before leaving
    word addrs[];         // length determined from record size
};