trace_format.rst

Trace file contents

A trace file essentially consists in

• A header with general information about the trace generation context (name of the binary executable passed to , --tag argument value, production date & time, ...), followed by
• The machine execution trace entries (roughly, one per execution basic block, with information on the branch decision at the end)

offers a dump-trace option to display the contents of trace files passed as arguments, displaying tags passed to amongst other things. For example:

gnatcov dump-trace test_divmod2.trace

Tag  : DATE_TIME (Date)
Len  : 8
Data : dc 07 02 15 08 00 25 00
       2012-02-21 08:00:37

Tag  : EXEC_FILE_NAME
Len  : 16
Data : obj/test_divmod2

Tag  : USER_DATA (User_Tag)
Len  : 10
Data : sample tag

Traces:
fffffffc-fffffffb ?: 20 ---- fault
fffffffc-ffffffff ?: 11 ---t block
fff0067c-fff006b3 ?: 11 ---t block
fff006bc-fff006bf ?: 12 --t- block
[...]

Prior to the execution traces per-se (list of executed instruction blocks past the Traces: label), we see a few information entries aimed at helping and users on various accounts. Each entry has a tag identifying it's kind, then some associated data dependent on the kind. Our example above features the following information entries:

DATE_TIME :

The trace production time stamp, always 8 bytes long.

EXEC_FILE_NAME :

Path to the binary program that was executed to produce the trace. This path can be exactly the one that was passed to or a derived path, for instance if had to add an extension to find the actual file (see target_specific_notes). uses this path to find the program file again at analysis time, to find which machine code corresponds to which address for example.

USER_DATA :

User string tag for this trace, when one was passed with -T to .

The precise structure is described in the qemu_traces.ads unit of the gnatcov sources.