1.. _acrntrace:
2
3Acrntrace
4#########
5
6Description
7***********
8
9``acrntrace`` is a tool running on the Service VM to capture trace data.
10A ``scripts`` directory includes scripts to analyze the trace data.
11
12Usage
13*****
14
15Acrntrace
16=========
17
18The ``acrntrace`` tool runs on the Service VM to capture trace data and output
19the data to a trace file under ``./acrntrace`` in raw (binary) data format.
20
21Options:
22
23-h                      print this message
24-i period               specify polling interval in milliseconds [1-999]
25-t max_time             max time to capture trace data (in seconds)
26-c                      clear the buffered old data (deprecated)
27-r                      capture the buffered old data instead of clearing it
28-a cpu-set              only capture the trace data on the configured cpu-set
29
30acrntrace_format.py
31===================
32
33The ``acrntrace_format.py`` is an offline tool for parsing trace data (as output
34by ``acrntrace``) to human-readable formats based on a given format.
35
36Here's an explanation of the tool's parameters:
37
38.. code-block:: none
39
40   acrntrace_format.py [options] [formats] [trace_data]
41
42Options:
43
44-h    print this message
45
46The *formats* file specifies the rules to reformat the *trace_data* collected by
47``acrntrace`` into a human-readable text form. The rules in this file follow
48this form::
49
50   event_id  text_format_string
51
52The ``text_format_string`` may include format specifiers, such as ``%(cpu)d``,
53``%(tsc)d``, ``%(event)d``, ``%(1)d``, and ``%(2)d``. The 'd' format specifier
54outputs the data in decimal format. Alternatively, 'x' outputs the data in
55hexadecimal format, and 'o' outputs the data in octal format.
56
57These respectively correspond to the CPU number (cpu), timestamp
58counter (tsc), event ID (event), and the data logged in the trace file.
59There can be only one such rule for each type of event.
60
61An example *formats* file is available in the ``acrn_hypervisor`` repo in
62``misc/debug_tools/acrn_trace/scripts``.
63
64acrnalyze.py
65============
66
67The ``acrnalyze.py`` is an offline tool to analyze trace data (as output by
68``acrntrace``) based on a given analyzer, such as ``vm_exit`` or ``irq``.
69
70Options:
71
72-h                                print this message
73-i, --ifile=string                input file name
74-o, --ofile=string                output file name
75-f, --frequency=unsigned_int      TSC frequency in MHz
76--vm_exit                         generate a vm_exit report
77--irq                             generate an IRQ-related report
78--cpu_usage                       generate a cpu_usage report
79
80.. note:: The tool depends on TSC frequency to do time-based analysis. Be sure
81   to configure the right TSC frequency that ACRN runs on. TSC frequency can be
82   obtained from the ACRN console log (``calibrate_tsc, tsc_hz=xxx``) when the
83   hypervisor boots.
84
85   The tool does not take into account CPU frequency variation that can
86   occur during normal operation (aka CPU throttling) on a processor that
87   doesn't support an invariant TSC. The results may therefore not be
88   completely accurate in that regard.
89
90Typical Use Example
91===================
92
93Here's a typical use of ``acrntrace`` to capture trace data from the Service VM,
94convert the binary data to human-readable form, copy the processed trace
95data to your development computer (Linux system), and run the analysis tool.
96
971. On the Service VM, start capturing buffered trace data:
98
99   .. code-block:: none
100
101      sudo acrntrace
102
103   Trace files are created under the current directory where you launched
104   ``acrntrace``, with a date-time-based directory name such as
105   ``./acrntrace/20211027-101605``.
106
107#. When done, stop a running ``acrntrace``:
108
109   .. code-block:: none
110
111      q <enter>
112
113#. Convert trace data to human-readable format:
114
115   .. code-block:: none
116
117      sudo acrntrace_format.py formats trace_data
118
119   Trace data will be converted to human-readable format based on a given format
120   and printed to stdout.
121
122#. Analysis of the collected trace data is done on your development computer.
123   Copy the collected trace data to your development computer via USB disk or
124   ``scp`` as shown in this example:
125
126   .. code-block:: none
127
128      sudo scp -r ./acrntrace/20211027-101605/ \
129          username@hostname:/home/username/trace_data
130
131   Replace username and hostname with appropriate values.
132
133#. On the development computer, run the provided Python3 script to analyze, for
134   example, the ``vm_exits``, ``irq``:
135
136   .. code-block:: none
137
138      sudo acrnalyze.py -i /home/xxxx/trace_data/20211027-101605/0 \
139           -o /home/xxxx/trace_data/20211027-101605/cpu0 --vm_exit --irq
140
141   - The analysis report is written to stdout, or to a CSV file if
142     a file name is specified using ``-o filename``.
143   - The scripts require Python3.
144   - If want to analyze cpu usage of each VM in cpu-sharing case, use ``--cpu_usage``
145     to replace.
146
147Build and Install
148*****************
149
150The source files for ``acrntrace`` are in the ``misc/debug_tools/acrn_trace``
151directory. To build and install ``acrntrace``, run these commands:
152
153.. code-block:: none
154
155   make
156   sudo make install
157
158The processing scripts are in ``misc/debug_tools/acrn_trace/scripts``. The
159``acrnalyze.py`` tool needs to be copied to and run on your development
160computer.
161