Laplace: Raw Trace Formats

We describe here the basic trace format emitted by Laplace. Note that this format provides a trace that very closely resembles, in some sense, the sequences of memory references and kernel events as they are collected by Laplace itself. It is possible to modify Laplace to process these sequences in arbitrary ways before they are emitted. It is also possible simply to pipe these traces, described below, into separate utilities that perform such processing. The former approach has the advantage that the I/O work performed on the original sequence need not be performed at all.

The raw reference trace

The first component of Laplace, implemented within the machine simulator, emits a log of memory references performed by the processor. Each load, store, and instruction fetch is recorded. Because the speed with which this log can be recorded is the most limiting factor on the performance of trace collection, the format is not converted into a human-readable form within Laplace. Instead, it is emitted in a simple binary format, described below. For those who wish to convert this binary format into a human readable format, we have implemented raw-reference-binary-to-text -- a simple utility that performs this conversion.

Each memory reference is stored as one record within the raw refeerence trace. Each such record is stored as a 5-tuple whose fields take the following form (given in pseudo-code): 

    struct reference_record_s {
      8-bit char type;
      64-bit unsigned int timestamp;
      8-bit unsigned int length;
      32-bit unsigned int virtual_address_space;
      32-bit unsigned int virtual_address;
    }

Thus, each trace record comprises 144 bits (18 bytes), where each field has a fixed size. We now give a description of the values that could be stored in each one of these fields, and thus how they could be interpreted:

The raw-reference-binary-to-text utility can read this format and instead emit records, in text, of the following form: 

    r 123456789abcdef0 4 9f8e7 9a8b7c6d

Here, the order of the fields and their meaning is identical to the above. Each line of text represents one record with five fields of the same length, where the numerical values are given in hexidecimal. We recommend the use of the human-readable text format as the canonical format that other utilities can read and perhaps as the primary format for storage. The binary format exists only for speed of logging at trace collection time. Throughout the rest of the documentation, we assume the use of the text format.

The kernel event trace

While the kernel may be made to log any arbitrary event, we list here the selected kernel events that we have found useful towards the simulation of a multi-programmed, multi-threaded workload on a system capable of different scheduling and memory management disciplines. Because kernel events are generated at a far lower rate than memory references, logging kernel events is not a performance bottleneck. Therefore, the kernel reference is recorded by Laplace in a human readable format, described below.

A kernel event is recorded as a single trace record. The format of each record depends on the type of kernel event. However, each record begins with the same two fields -- a type tag and a timestamp -- and ends with a newline character. The type tag is used to determine how to parse the remainder of the record. The timestamp value is taken from the same cycle counting register that is used for the raw reference trace. We catalog here each type of kernel event that is logged, as well as the record format used for that event type.

Scott F. Kaplan
Last modified: Fri Nov 29 17:20:41 EST 2002