8000 GitHub - edgarigl/qemu-etrace: Qemu Etrace · GitHub
[go: up one dir, main page]

Skip to content

About

Qemu Etrace

Resources

Stars

19 stars

Watchers

2 watching

Forks

Latest commit

 

History

213 Commits

Folders and files

NameName
Last commit message
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).

About

Qemu Etrace

Resources

Stars

19 stars

Watchers

2 watching

Forks

Releases

Packages

Contributors

Languages

0