TRDB – Library and CLI Tools for RISC-V Processor Tracing

This library provides software tooling for decompressing, compressing and disassembling captured execution traces of a RISC-V Core and is compliant with the RISC-V Processor Trace Specification. It is used together with the hardware trace module of the PULP project.

Features

libtrdb provides routines that can be used to

• decompress trace packets
• disassemble traces
• model a trace encoding source (processor interface to trace packets)
• used as part of a RTL testbench through DPI

The trdb command line tool is used to provide a command line interface to libtrdb functionalities.

The trace source model accepts a stimuli/trace file and produces the sequence of packages that the PULP RTL IP would. An example of how such a trace file looks like can be found in data/trdb_stimuli. This is what the RISC-V core sends to the PULP hardware trace debugger each cycle. It is used by the testbench of the PULP hardware tracer in by employing via the DPI.

The trdb binary provides functionality to decompress recorded packages and to compress stimuli/trace files.

Build

To build trdb, tests and libtrdb.a call

autoreconf -vif
./configure
make

or if you want a debug build (debug symbols, asserts, address sanitizer, debug level logging, no optimizations) use the helper script

./configure-debug

instead of ./configure.

libtrdb.so is a library for providing the C-model, decompression, disassembly functionality and a simple interface using the SystemVerilog DPI.

Run

make doxygen-doc

to build the documentation with doxygen. It will be put under doc/.

Usage of trdb

Compression

./trdb --compress TRACE-FILE to compress the instruction sequence given in TRACE-FILE to a sequence of packets printed in a human readable format to stdout. Add --binary-format pulp to produce binary data matching the PULP hardware trace debugger output.

Decompression

By calling ./trdb --extract --bfd ELF-BINARY PULP-BINARY-PACKETS you can reconstruct the original instruction sequence, which was generated by running ELF-BINARY, from a packet sequence PULP-BINARY-PACKETS. The output will be a dump of the instruction information which could be recovered.

Disassembly

Most of the times one is interested in the diassembled instruction sequence. For that there are the flags --disassemble (disassemble code), --function-context (clearly delimit when we are entering a function), --line-numbers (show file names and line numbers) and --source (mix disassembly with source code) which can be added to the decompression command. Those flags are similar to the ones in GNU objdump.

For more information about the options, run trdb --help.

Example

The file at data/trdb_stimuli was produced by running data/interrupt on PULPissimo. It contains the executed instruction sequence and some meta information. The executable itself is the compiled version of this example.

Let us first emulate the trace debugger hardware by calling

./trdb --binary-format pulp --compress -o my_packets data/trdb_stimuli

The generated packets can be inspected with

./trdb --binary-format pulp --dump my_packets

Now we can try to recover the original instruction sequence by running

./trdb --binary-format pulp --bfd data/interrupt --extract my_packets

or even better to see some disassembly

./trdb -dSsl --binary-format pulp --bfd data/interrupt --extract my_packets

Usage of libtrdb

Always first initialize and hold a trdb_ctx struct by calling trdb_new(), which contains the context and state of the trace debugger functions. On creation it will use some sane configuration settings.

Feel free to control the logging level by setting either the environment variable TRDB_LOG to err, info or debug before calling trdb_new() or during runtime with trdb_set_log_priority. Furthermore you can also hook your own logging function by setting it with trdb_set_log_fn. By default everything will be printf’d to stderr.

To run the C-model call trdb_compress_trace_step for each cycle and keep passing in struct tr_instr describing the retired instruction of the CPU. The state of the execution will be recorded in trdb_ctx. Generated packet will be added to the struct trdb_packet_head pointer. Such a packet list must be freed by the user by calling trdb_free_packet_list.

To reset a trdb_ctx to its initial state use trdb_reset_compression or trdb_reset_decompression depending on your usage.

Remember to release the library context after you are finished with trdb_free.

Benchmarks

By default a benchmarking executable is built

Call

./benchmarks

to run the built-in benchmarks.

Tests

Simply run

./tests

parse-opcodes

The code in riscv_encoding.h was generated with riscv-opcodes, a forked version which also incorporates PULP specific instructions.