qemu-etrace
-----------
qemu-etrace is a tool to process QEMU binary execution traces.
It can display the binary logs in a human readable way and generate
coverage and profiling reports. The traces can be generated and processed
without modifying the guest application, i.e it is to some extent
un-intrusive.

BUILD
-----
qemu-etrace depends on dwarfdump, binutils libraries and on binutils programs at runtime.
On debian/ubuntu machines, the packages to install are
dwarfdump, binutils and binutils-dev.

Preferably the binutils installation should be multi-arch.

If your system is lacking these, you will have to download binutils and
install it somewhere. Plus edit the Makefile.

To simplify the binutils build, the Makefile has a rule that will download,
build and install a local binutils installation (in the qemu-etrace src dir).

For convenience, the Makefile also generates a qemu-etrace.sh shell script
that pre-sets some qemu-etrace arguments pointing to binutils program paths
into to the local binutils install.

The make binutils step is optional, depending on your system:
$ make binutils -j4

To build qemu-etrace:
$ make -j4

Copy qemu-etrace.sh (if you used a local binutils) or qemu-etrace if you
installed the system packages to somewhere in your PATH.

$ cp qemu-etrace.sh ~/bin/

USAGE
-----
QEMU needs to run with etrace tracing.
Flags -etrace-flags exec enables the execution tracing.
'-d nochain' disables direct tb jumps so that QEMU can trace all executed code.
-accel tcg,thread=single disables MTTCG (etrace is not yet thread safe).

$ qemu ... -kernel vmlinux -etrace /tmp/elog -etrace-flags exec -d nochain -accel tcg,thread=single

Examples:
To view a trace:
$ qemu-etrace --trace /tmp/elog

To view a trace (with symbol info):
$ qemu-etrace --trace /tmp/elog --elf vmlinux

To create coverage ASCII etrace style info:
$ qemu-etrace --trace /tmp/elog --elf vmlinux --coverage-output cov.etrace --coverage-format etrace --trace-output none

To create coverage lcov style info:
$ qemu-etrace --trace /tmp/elog --elf vmlinux --coverage-output cov.info --coverage-format lcov --trace-output none

Lcov info files need to be furthered processed by lcov tools, in this case
genhtml to create beautiful html reports.

genhtml is part of lcov. You can either install it via your distro (e.g
apt-get install lcov) or you can find the latest version of genhtml in
the lcov git repo:
wget https://github.com/linux-test-project/lcov/raw/master/bin/genhtml

Example (cov.info beeing the output from qemu-etrace):
$ mkdir html-outputdir
$ genhtml -o html-outputdir cov.info

# Add --ignore-errors source in case not all source is available.
$ genhtml -o html-outputdir --ignore-errors source cov.info

These etrace (tmp/elog) files can quickly get very large. It is also possible to do
the trace processing online (without intermediate files). This is done
through UNIX sockets. To use a UNIX socket, prepend the trace path
with unix:.

Example:
$ qemu-etrace --trace unix:/tmp/my-etrace-socket ...

The QEMU side supports the same format.

$ qemu ... -etrace unix:/tmp/my-etrace-socket ...

Using with simple-trace format
------------------------------
The patch for QEMU to support this is still under review and may not be applied.But here's some info on howto run it anyways.

This version makes use of the `tb_enter_exec` trace to perform coverage
analysis. So it requires a QEMU version with this trace available. Note
that this trace is sufficient in itself and does not require QEMU to be
run in `nochain` mode. This leads to good overall performances when
doing coverage analysis. One known limitation is the fact that QEMU can
abort execution in the middle of a TB (e.g. when an simulated
instruction causes an exception to be raised). It can introduce an small
error in the report, because it will think that the TB has been executed to
the end. This case is quite rare though and should mainly happen in big
firmware (e.g. with Linux).

Here is an example of how to use it:

echo tb_enter_exec >/tmp/events

qemu-system-aarch64 -M xlnx-zcu102 \
    -cpu cortex-a53 \
    -kernel "$ELF" \
    -trace file=trace-out,events=/tmp/events

qemu-etrace
    --trace-in-format qemu-simple \
    --trace trace-out \
    --coverage-format lcov \
    --coverage-output cov.output \
    --elf "$ELF" \
    --trace-output none


Binutils
--------
qemu-etrace uses binutils, both its libraries and its programs (nm,
objdump, addr2line). It was tested with binutils 2.22 and binutils 2.34.
qemu-etrace has cmdline options to choose which binutils programs to
use, see --help, --nm, --addr2line, --objdump.

Coverage
--------
qemu-etrace is able to process and collect execution statistics
in a way that allows it to generate coverage and profiling information.
It supports several coverage or profiling output file-formats.

etrace
	An internal ASCII format, human readable. May change at
	any time so don't build tools around this yet.

cachegrind
	cachegrind compatible profiling format.

qcov
	Creates qcov files, which are a variation of .gcov files similar to
	what the gcov tool would emit.

lcov
	Generates an lcov info file to be further processed
	by genhtml to generate coverage reports.

gcov-bad
	Generates binary gcov gcda files. This format does not work
	very well. It was an experiment that turns out to be hard to
	support.

etrace-view
-----------
./etrace-view.py --trace ~/work/xilinx/m-arch/sw/tbm/apu.elog  --elf ~/work/xilinx/m-arch/sw/tbm/build/ronaldo/apu/ctest-bare


LICENSE
-------
This project is released under the GPLv2.

TODO
----
1. Add sorting support when displaying traces.
   Possibly with a barrier package in the trace.

2. Stop using binutils programs and instead implement the features directly
   towards libbfd and friends (+ possibly libelf, libdwarf).