Important

This is the latest documentation for the unstable development branch of Project ACRN (master).
Use the drop-down menu on the left to select documentation for a stable release such as v3.2 or v3.0.

Acrntrace

Description

acrntrace is a tool running on the Service VM to capture trace data. A scripts directory includes scripts to analyze the trace data.

Usage

Acrntrace

The acrntrace tool runs on the Service VM to capture trace data and output the data to a trace file under ./acrntrace in raw (binary) data format.

Options:

-h

print this message

-i period

specify polling interval in milliseconds [1-999]

-t max_time

max time to capture trace data (in seconds)

-c

clear the buffered old data (deprecated)

-r

capture the buffered old data instead of clearing it

-a cpu-set

only capture the trace data on the configured cpu-set

acrntrace_format.py

The acrntrace_format.py is an offline tool for parsing trace data (as output by acrntrace) to human-readable formats based on a given format.

Here’s an explanation of the tool’s parameters:

acrntrace_format.py [options] [formats] [trace_data]

Options:

-h

print this message

The formats file specifies the rules to reformat the trace_data collected by acrntrace into a human-readable text form. The rules in this file follow this form:

event_id  text_format_string

The text_format_string may include format specifiers, such as %(cpu)d, %(tsc)d, %(event)d, %(1)d, and %(2)d. The ‘d’ format specifier outputs the data in decimal format. Alternatively, ‘x’ outputs the data in hexadecimal format, and ‘o’ outputs the data in octal format.

These respectively correspond to the CPU number (cpu), timestamp counter (tsc), event ID (event), and the data logged in the trace file. There can be only one such rule for each type of event.

An example formats file is available in the acrn_hypervisor repo in misc/debug_tools/acrn_trace/scripts.

acrnalyze.py

The acrnalyze.py is an offline tool to analyze trace data (as output by acrntrace) based on a given analyzer, such as vm_exit or irq.

Options:

-h

print this message

-i, --ifile=string

input file name

-o, --ofile=string

output file name

-f, --frequency=unsigned_int

TSC frequency in MHz

--vm_exit

generate a vm_exit report

--irq

generate an IRQ-related report

Note

The tool depends on TSC frequency to do time-based analysis. Be sure to configure the right TSC frequency that ACRN runs on. TSC frequency can be obtained from the ACRN console log (calibrate_tsc, tsc_hz=xxx) when the hypervisor boots.

The tool does not take into account CPU frequency variation that can occur during normal operation (aka CPU throttling) on a processor that doesn’t support an invariant TSC. The results may therefore not be completely accurate in that regard.

Typical Use Example

Here’s a typical use of acrntrace to capture trace data from the Service VM, convert the binary data to human-readable form, copy the processed trace data to your development computer (Linux system), and run the analysis tool.

  1. On the Service VM, start capturing buffered trace data:

    sudo acrntrace
    

    Trace files are created under the current directory where you launched acrntrace, with a date-time-based directory name such as ./acrntrace/20211027-101605.

  2. When done, stop a running acrntrace:

    q <enter>
    
  3. Convert trace data to human-readable format:

    sudo acrntrace_format.py formats trace_data
    

    Trace data will be converted to human-readable format based on a given format and printed to stdout.

  4. Analysis of the collected trace data is done on your development computer. Copy the collected trace data to your development computer via USB disk or scp as shown in this example:

    sudo scp -r ./acrntrace/20211027-101605/ \
        username@hostname:/home/username/trace_data
    

    Replace username and hostname with appropriate values.

  5. On the development computer, run the provided Python3 script to analyze, for example, the vm_exits, irq:

    sudo acrnalyze.py -i /home/xxxx/trace_data/20211027-101605/0 \
         -o /home/xxxx/trace_data/20211027-101605/cpu0 --vm_exit --irq
    
    • The analysis report is written to stdout, or to a CSV file if a file name is specified using -o filename.

    • The scripts require Python3.

Build and Install

The source files for acrntrace are in the misc/debug_tools/acrn_trace directory. To build and install acrntrace, run these commands:

make
sudo make install

The processing scripts are in misc/debug_tools/acrn_trace/scripts. The acrnalyze.py tool needs to be copied to and run on your development computer.