172 lines
4.7 KiB
ReStructuredText
172 lines
4.7 KiB
ReStructuredText
.. _acrntrace:
|
|
|
|
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
|
|
|
|
acrntrace_format.py
|
|
===================
|
|
|
|
The ``acrntrace_format.py`` is a offline tool for parsing trace data (as output
|
|
by acrntrace) to human-readable formats based on given format.
|
|
|
|
Here's an explanation of the tool's parameters:
|
|
|
|
.. code-block:: none
|
|
|
|
acrntrace_format.py [options] [formats] [trace_data]
|
|
|
|
Options:
|
|
|
|
-h print this message
|
|
|
|
*formats* file specifies the rules to reformat the *trace_data* collected by
|
|
``acrntrace`` into a human-readable text form. The rules in this file are of
|
|
the 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 in decimal, alternatively 'x' will
|
|
output in hexadecimal and 'o' will output in octal.
|
|
|
|
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 given analyzer, such as ``vm_exit`` or ``irq``.
|
|
|
|
Options:
|
|
|
|
.. list-table::
|
|
|
|
* - :kbd:`-h`
|
|
- print this message
|
|
|
|
* - :kbd:`-i, --ifile=string`
|
|
- input file name
|
|
|
|
* - :kbd:`-o, --ofile=string`
|
|
- output filename
|
|
|
|
* - :kbd:`-f, --frequency=unsigned_int`
|
|
- TSC frequency in MHz
|
|
|
|
* - :kbd:`--vm_exit`
|
|
- generate a vm_exit report
|
|
|
|
* - :kbd:`--irq`
|
|
- generate an IRQ-related report
|
|
|
|
.. note:: We depend on TSC frequency to do time-based analysis. Please 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 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,
|
|
converting the binary data to human-readable form, copying the processed trace
|
|
data to your linux system, and running the analysis tool.
|
|
|
|
1. On the SOS, clear buffers before starting a trace, with:
|
|
|
|
.. code-block:: none
|
|
|
|
# acrntrace -c
|
|
|
|
#. Start capturing buffered trace data with:
|
|
|
|
.. code-block:: none
|
|
|
|
# acrntrace
|
|
|
|
Trace files are created under current directory where we launch acrntrace,
|
|
with a date-time-based directory name such as ``./acrntrace/20171115-101605``
|
|
|
|
#. When done, stop a running ``acrntrace``, with:
|
|
|
|
.. code-block:: none
|
|
|
|
q <enter>
|
|
|
|
#. Convert trace data to human-readable format, with:
|
|
|
|
.. code-block:: none
|
|
|
|
# acrntrace_format.py formats trace_data
|
|
|
|
Trace data will be converted to human-readable format based on 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):
|
|
|
|
.. code-block:: none
|
|
|
|
# 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``:
|
|
|
|
.. code-block:: none
|
|
|
|
# acrnalyze.py -i /home/xxxx/trace_data/20171115-101605/0 \
|
|
-o /home/xxxx/trace_data/20171115-101605/cpu0 --vm_exit --irq
|
|
|
|
- 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:
|
|
|
|
.. code-block:: none
|
|
|
|
# make
|
|
# make install
|
|
|
|
The processing scripts are in ``tools/acrntrace/scripts`` and need to be
|
|
copied to and run on your Linux system.
|