Arm is proud to announce the initial release of Tarmac Trace Utilities, an open-source code base for analyzing and browsing trace files in Tarmac trace format.
“Tarmac” is a textual format that logs the instructions executed by a CPU, and their effects. It lists every value written to a register, and every value read and written from memory. and other events such as interrupts and exceptions. It is generated by a range of Arm products, including Fast Models and Cycle Models, and even direct simulations of a specific CPU from its RTL. It might look like this, for example:
These trace files are very detailed, but not always easy to read. They have to list events in chronological order, and that is not always the order the reader finds most useful. The simplest way to examine one is to use an ordinary text editor, or a file viewer like less. But suppose you need to know what was in a particular part of memory at a certain point in time? It is hard to find that out using only a text editor. You would have to search back through the trace file for the most recent memory-write operation that touched the address in question – and that might not be easy to find, because memory writes can be done in lots of ways. (For example, your piece of memory might have been written all at once, or 1 byte at a time, or as a small part of a larger write.)
less
If you spent a lot of time trying to figure out what had happened in Tarmac traces, you would like some software to help you with tasks like that.
Tarmac Trace Utilities is a suite of tools that give you that help. They begin by reading your trace file and building up an index alongside it, which records the known state of the system at every point in the trace. From that index file, it is easy to look up answers to questions like "What was in memory location X / register R at line N of the trace?", or "What was the last instruction that wrote to that memory and register?", or "Which parts of memory changed between lines N and M?"
Then, each tool uses that same index file in a different way. Some of them produce reports and summaries as output; alternatively, you can interactively browse the trace and see what is going on in detail.
The biggest tool in Tarmac Trace Utilities is tarmac-browser. This lets you page through a trace file just as if it was in an ordinary text editor or file viewer. But wherever the cursor is, the browser shows you the current state of all the registers. It also shows the contents of memory as well, if you ask it to:
tarmac-browser
In this screenshot, the topmost pane shows the contents of the trace file itself, with the horizontal line indicating the current position we are looking at. The next pane shows the state of all the registers, as of the point in time indicated by that horizontal line. The bottom pane shows the contents of memory in the region of the stack pointer. These displays make it easier to understand what is going on in the code.
(But the tool can only show registers and memory that have been mentioned in the trace file. For example, nothing in the trace before this point has shown any value being written into r4. Therefore, the browser cannot show the contents of r4 at this location, because the trace file does not specify it. Similarly, locations in memory are marked with ?? if nothing in the trace has ever accessed them.)
The browsing tool also provides a way to quickly jump to trace positions that might be of interest. For example, suppose you want to know why some register or piece of memory had a particular value. (Perhaps it was a value you were not expecting.) Then tarmac-browser provides keystrokes that will jump to the most recent instruction that wrote to the register or memory in question.
Another handy feature is the ability to “fold up” function calls in the trace. This will hide the details of what happened inside the function. You see the call instruction, immediately followed by the instruction after the function returned. So it looks as if the call instruction did the whole job itself. (Rather like stepping over a function call in a debugger.)
In addition to this interactive browsing tool, Tarmac Trace Utilities can reuse the same analysis and indexing system to produce reports and translations of the trace.
For example, we have written a tool that will translate a Tarmac trace into IEEE 1364 Value Change Dump format (VCD files). That is a standard format that other software already understands. In particular, you can view a VCD file graphically using tools like gtkwave.
gtkwave
Several of the other tools use the fact that the index has to identify function calls and returns, for the browser's folding feature. So they reconstruct the whole function call tree from the same data, and do useful things with it. For example, we provide a tool that simply prints the whole tree, with line numbers showing where all the calls start and end. (This lets you find the part of the trace you want to examine in more detail.) Also, we have provided tools that produce profiling information about where all the time is spent in the trace. One writes out its own simple human-readable format; another generates output that can be consumed by Brendan Gregg's "flame graph" system.
Those are only the starting set. The tools are open-source, and it does not take a lot of code to add further reporting utilities. There is no end of scope for other things you could write along these lines. Statistics about memory access patterns or register usage? Reconstituting the logged memory contents into a core-dump or image file? Finding copies of sensitive data that were not erased when a secure function terminated? Translate Tarmac trace into other emulators' trace formats so you can see where two models disagree on something? We would love to see what other people come up with.
The tools are available on Github, at ARM-software/tarmac-trace-utilities. They are open-source, under the Apache-2.0 license.