Repository navigation
Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
E870
| ||||
Repository files navigation
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 GLib, dwarfdump, the Binutils libraries, and the
Binutils programs `nm`, `objdump`, and `addr2line`. The default build uses the
system Binutils installation. On Debian and Ubuntu, install the prerequisites
with:
$ sudo apt install build-essential pkg-config python3 libglib2.0-dev \
dwarfdump binutils binutils-dev zlib1g-dev
Then build qemu-etrace with:
$ make -j4
The runtime Binutils programs and dwarfdump are resolved through `PATH`.
Command-line options such as `--nm`, `--objdump`, `--addr2line`, and
`--dwarfdump` can select different programs or explicit paths.
If suitable Binutils libraries are not available on the host, build the local
Binutils 2.42 fallback and select it explicitly:
$ make binutils -j4
$ make USE_LOCAL_BINUTILS=1 -j4
Local mode links against the Binutils installation in this source tree and
also creates `qemu-etrace.sh`. The wrapper selects the matching local `nm`,
`objdump`, and `addr2line` programs. It is intended for running qemu-etrace
from the build tree and is not installed by `make install`.
TESTS
-----
The test suite requires Python 3 with pytest. Run the C unit tests and
command-line integration tests with:
$ make check
QEMU TCG PLUGIN
---------------
The `libqemu-etrace.so` plugin lets an unmodified upstream QEMU generate
ETrace execution logs. The plugin must be compiled against the plugin header
from the QEMU version that will load it. By default, the build looks for a
QEMU source tree in `../qemu`:
$ make plugin
Select another QEMU source tree when needed:
$ make plugin QEMU_SRC=/path/to/qemu
The default installation prefix is `/usr/local`. The plugin is host executable
code, so it is installed under `lib`, not `share`:
$ sudo make install QEMU_SRC=/path/to/qemu
This installs:
/usr/local/bin/qemu-etrace
/usr/local/bin/etrace-view
/usr/local/share/qemu-etrace/etrace-view.py
/usr/local/share/qemu-etrace/etrace.py
/usr/local/share/qemu-etrace/addr2line.py
/usr/local/lib/qemu-etrace/plugins/5/libqemu-etrace.so
The numeric directory is the QEMU plugin API version read from the selected
QEMU header. This allows plugins for incompatible QEMU versions to be installed
side by side. Print the installation path for the selected header with:
$ make -s print-plugin-path QEMU_SRC=/path/to/qemu
For a distribution-style `/usr` installation, use:
$ sudo make install prefix=/usr QEMU_SRC=/path/to/qemu
`DESTDIR` and `libdir` can be overridden for packaging and multiarch layouts.
USAGE
-----
With upstream QEMU, load the TCG plugin and select an output file:
$ qemu-system-aarch64 ... \
-accel tcg \
-plugin /usr/local/lib/qemu-etrace/plugins/5/libqemu-etrace.so,out=/tmp/elog \
-kernel vmlinux
The plugin records execution callbacks for chained translation blocks, so
`-d nochain` is not needed. Output writes are serialized for MTTCG. The plugin
records accurate execution ranges with zero duration, which supports coverage
but does not provide time-based profiling. API version 1 uses one host callback
per instruction. Newer APIs delay each TB record until execution is resolved:
an inline progress update before each instruction records the exact dispatched
prefix, including virtualization transitions without discontinuity callbacks.
The ETrace format assumes that execution ranges are accurate; no opt-in flag is
required. Instruction observation establishes dispatch, not architectural
retirement. An instruction that raises an exception might not complete and, on
some exception paths, is represented by a discontinuity rather than an
ordinary execution range.
When the selected QEMU header provides discontinuity callbacks, the plugin also
records interrupts, exceptions, and host calls with their source and destination
PCs. The build detects this declaration directly because QEMU 10.1 and 10.2 use
the same plugin API version even though only 10.2 provides the callback.
Plugin-produced traces advertise and end with a producer-status record. The
status reports unresolved TB, discontinuity, and vCPU-exit ranges together
with output errors. Conversion fails when the required final record is missing
or contains a correctness error, preventing incomplete coverage from being
accepted as a successful result. Plugin shutdown flushes pending ranges for
every vCPU observed by the plugin, including CPUs that remain realized when
QEMU invokes plugin atexit callbacks.
Add `compress=gzip` to compress the trace while QEMU runs. Compression level 1
is the default and levels from 0 through 9 can be selected with `level=`:
$ qemu-system-aarch64 ... \
-accel tcg \
-plugin /usr/local/lib/qemu-etrace/plugins/5/libqemu-etrace.so,out=/tmp/elog.gz,compress=gzip,level=1 \
-kernel vmlinux
`qemu-etrace` transparently reads raw and gzip-compressed ETrace input, so the
compressed file can be processed directly:
$ qemu-etrace --trace /tmp/elog.gz --elf vmlinux
Raw output remains the default. The gzip stream is finalized when QEMU exits
normally; an abruptly terminated QEMU process may leave a truncated gzip
stream. The `out=` option accepts a regular file, a pre-created FIFO, or a UNIX
socket connection. Start qemu-etrace first so it owns the listening socket,
then use `out=unix:/path` in the plugin.
The plugin writes the legacy ETrace 0.0 execution-range format by default. Its
opt-in ETrace 1.0 mode emits translation-block definitions once and compact
execution records that qemu-etrace expands into the same internal ranges:
$ qemu-system-x86_64 ... \
-plugin /path/libqemu-etrace.so,out=/tmp/elog,format=v1
Version 1 requires QEMU plugin API 2 or newer. Context registers are captured
only when requested. `context-registers=basic` selects mode and address-space
registers for x86, AArch64, or RISC-V; `context-register=NAME` can be repeated
for an explicit set. Numeric execution mappings can be added with
`exec-mapping=on`, which requires plugin API 5 or newer.
An explicit range-based hypervisor filter is available in version 1:
$ qemu-system-x86_64 ... \
-plugin /path/libqemu-etrace.so,out=/tmp/xen.elog,format=v1,context=hypervisor,context-range=0xffff82d040000000:0x6b1198
Repeat `context-range=` for early or relocated mappings. Filtered intervals are
represented by gap records so downstream control-flow analysis cannot connect
unrelated retained ranges. See `docs/etrace-v1.md` for the event model,
complete option reference, QEMU API requirements, and mapping limitations.
If the early physical load address is unknown, add
`context-unmatched=keep,exec-mapping=on` and enable the analyzer's sparse image
resolver:
$ qemu-etrace --trace /tmp/xen.elog --elf xen-syms.debug --auto-map ...
The resolver defers unmatched TB executions until a byte-verified linked
mapping covers them. Unique code-byte matches remain unverified candidates
and cannot create mappings or credit coverage on their own. Linked mappings
assume a stable image in the selected trace address space; see the attribution
contract in `docs/etrace-v1.md`. `--unresolved-limit` bounds pending execution
aggregates and fails conversion on overflow.
Add `--preserve-order` when chronological consumers need individual dynamic
events rather than coverage-only aggregates. Dynamic events are journaled to a
temporary file and replayed after mapping resolution. `--event-spool` selects a
retained journal and `--event-spool-
72F8
limit` bounds its compressed storage size.
`--event-spool-decoded-limit` independently bounds decoded work. Replay checks
frame checksums and the full event-stream digest; see `docs/event-journal.md`.
Runtime address mapping
-----------------------
Use a repeatable `--address-map` option when code executes at a loader-selected
runtime address before reaching its linked ELF virtual address:
$ qemu-etrace \
--trace /tmp/elog.gz \
--elf xen-syms.debug \
--address-map 0x1d600000:0xffff82d040000000:0x6b1198 \
--coverage-format lcov \
--coverage-output coverage.info \
--trace-output none
Each value is hexadecimal and describes `runtime-start:linked-start:size`.
Mappings use half-open ranges, may be repeated, and must not contain conflicting
runtime overlaps. Execution ranges crossing a mapping boundary are split before
coverage is recorded. Addresses outside the configured mappings are unchanged.
Address maps work with regular files, gzip files, standard input, and UNIX
sockets because they are supplied before trace processing starts. The stored
trace remains unchanged. Decoded output shows both runtime and linked addresses
when normalization occurs.
See `docs/address-maps.md` for detailed semantics and examples.
The Xilinx QEMU fork can instead use its built-in ETrace options.
`-etrace-flags exec` enables execution tracing, `-d nochain` disables direct TB
jumps so all executed code is traced, and `-accel tcg,thread=single` disables
MTTCG because the built-in ETrace implementation is not 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
The legacy `etrace` coverage value is duration distributed across each byte.
Use `etrace-v2` to report execution count and duration separately:
$ qemu-etrace --trace /tmp/elog --elf vmlinux --coverage-output cov.etrace-v2 --coverage-format etrace-v2 --trace-output none
The version 2 columns are `count duration address symbol source`. Count is the
execution count attributed to the byte. Duration is the producer-supplied
duration distributed across the range. The QEMU plugin
records dispatch counts with zero duration because it does not observe elapsed
guest execution time. The final `x unknown` row totals execution count and
duration which could not be attributed to an ELF symbol.
To create coverage lcov style info:
$ qemu-etrace --trace /tmp/elog --elf vmlinux --coverage-output cov.info --coverage-format lcov --trace-output none
By default, LCOV function hits represent entry into retained ELF symbols. To
count execution of inlined source bodies as function hits, use:
$ qemu-etrace --trace /tmp/elog --elf vmlinux --coverage-output cov.info --coverage-format lcov --function-hit-policy source --trace-output none
See `docs/coverage-model.md` for the exact semantics and known limitations.
See `docs/assembly-coverage.md` for DWARF line intervals, assembly function
selection, and machine-readable function inventory output.
Add `--coverage-inventory` when generating LCOV to record why each retained
text symbol is emitted, inferred, deduplicated, or omitted:
$ qemu-etrace ... \
--coverage-format lcov \
--coverage-output coverage.info \
--coverage-inventory functions.jsonl
Add `--coverage-attribution attribution.jsonl` to export DWARF source ranges,
columns, discriminators, statement markers, and observed byte-address counts.
This diagnostic leaves LCOV hits unchanged and requires no GCOV instrumentation
or GCC build dumps. See `docs/coverage-model.md` for its format and limits.
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 files can quickly get very large. It is also possible to process a
trace online through a UNIX socket. qemu-etrace listens and the upstream plugin
connects, so start the analyzer first:
$ qemu-etrace --trace unix:/tmp/my-etrace-socket --server 0 ... &
$ while test ! -S /tmp/my-etrace-socket; do sleep 0.01; done
$ qemu-system-x86_64 ... \
-plugin /path/libqemu-etrace.so,out=unix:/tmp/my-etrace-socket,format=v1
The plugin is connect-only and never unlinks or listens on the socket path. A
connection failure aborts plugin installation. If the analyzer disconnects,
QEMU reports an output error and the incomplete stream cannot satisfy the
required final-status check.
The Xilinx QEMU built-in ETrace producer also accepts `-etrace unix:/path`.
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). The build expects the Binutils 2.29 or newer disassembler
API. System Binutils is used by default; set `USE_LOCAL_BINUTILS=1` to use the
local Binutils 2.42 build described above. `libiberty-dev` is not required with
the shared Binutils libraries provided by Debian and Ubuntu.
qemu-etrace searches `PATH` for the Binutils programs and dwarfdump. It also
has command-line options to choose each program; see `--help`, `--nm`,
`--addr2line`, `--objdump`, and `--dwarfdump`.
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
-----------
The interactive Python viewer is installed as `etrace-view`:
$ etrace-view --trace /tmp/elog --elf vmlinux
Run `./etrace-view.py` instead when working directly from the source tree.
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).