acrntrace¶

Description¶

acrntrace is a tool running on the Service OS (SOS) to capture trace data. A scripts directory includes scripts to analyze the trace data.

Usage¶

acrntrace¶

The acrntrace tool runs on the Service OS (SOS) to capture trace data and output to trace file under ./acrntrace with 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 second)
`-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 decimals. Alternatively ‘x’ will output in hexadecimals and ‘o’ will output in octals.

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 hypervisor/tools/acrntrace/scripts/formats.

acrnalyze.py¶

The acrnalyze.py is a 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 filename
`-f, --frequency=unsigned_int`	TSC frequency in MHz
`--vm_exit`	generate a vm_exit report
`--irq`	generate an IRQ-related report

Note

We depend 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 the processor which doesn’t support for 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 SOS, convert the binary data to human-readable form, copy the processed trace data to your Linux system, and run the analysis tool.

On the SOS, clear buffers before starting a trace using:
```
# acrntrace -c
```
Start capturing buffered trace data using:
```
# acrntrace
```
Trace files are created under the current directory where we launch acrntrace, with a date-time-based directory name such as ./acrntrace/20171115-101605
When done, stop a running acrntrace using:
```
q <enter>
```
Convert trace data to human-readable format using:
```
# acrntrace_format.py formats trace_data
```
Trace data will be converted to human-readable format based on a given format and printed to stdout.
Analysis of the collected data is done on a Linux PC so you’ll need to copy the collected trace data to your Linux system (using scp is recommended):
```
# scp -r ./acrntrace/20171115-101605/ \
    username@hostname:/home/username/trace_data
```
Replace username and hostname with appropriate values.
On the Linux system, run the provided Python3 script to analyze the vm_exits, irq:
```
# acrnalyze.py -i /home/xxxx/trace_data/20171115-101605/0 \
     -o /home/xxxx/trace_data/20171115-101605/cpu0 --vm_exit --irq
```
- The analysis report is written to stdout, or to a CSV file if a filename is specified using -o filename.
- The scripts require Python3.

Build and Install¶

The source files for acrntrace are in the tools/acrntrace folder, and can be built and installed using:

# make
# make install

The processing scripts are in tools/acrntrace/scripts and need to be copied to and run on your Linux system.