Doc: Content edits to the acrntrace README file.
Signed-off-by: Deb Taylor <deb.taylor@intel.com>
This commit is contained in:
parent
6289124e7c
commit
ba5099e69f
|
@ -25,13 +25,13 @@ Options:
|
||||||
-t max_time max time to capture trace data (in second)
|
-t max_time max time to capture trace data (in second)
|
||||||
-c clear the buffered old data (deprecated)
|
-c clear the buffered old data (deprecated)
|
||||||
-r capture the buffered old data instead of clearing it
|
-r capture the buffered old data instead of clearing it
|
||||||
-a cpu-set only capture the trace data on these configured cpu-set
|
-a cpu-set only capture the trace data on the configured cpu-set
|
||||||
|
|
||||||
acrntrace_format.py
|
acrntrace_format.py
|
||||||
===================
|
===================
|
||||||
|
|
||||||
The ``acrntrace_format.py`` is a offline tool for parsing trace data (as output
|
The ``acrntrace_format.py`` is an offline tool for parsing trace data (as output
|
||||||
by acrntrace) to human-readable formats based on given format.
|
by acrntrace) to human-readable formats based on a given format.
|
||||||
|
|
||||||
Here's an explanation of the tool's parameters:
|
Here's an explanation of the tool's parameters:
|
||||||
|
|
||||||
|
@ -43,19 +43,19 @@ Options:
|
||||||
|
|
||||||
-h print this message
|
-h print this message
|
||||||
|
|
||||||
*formats* file specifies the rules to reformat the *trace_data* collected by
|
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 are of
|
``acrntrace`` into a human-readable text form. The rules in this file follow
|
||||||
the form::
|
this form::
|
||||||
|
|
||||||
event_id text_format_string
|
event_id text_format_string
|
||||||
|
|
||||||
The text_format_string may include format specifiers, such as
|
The ``text_format_string`` may include format specifiers, such as
|
||||||
``%(cpu)d``, ``%(tsc)d``, ``%(event)d``, ``%(1)d``, and ``%(2)d``.
|
``%(cpu)d``, ``%(tsc)d``, ``%(event)d``, ``%(1)d``, and ``%(2)d``.
|
||||||
The 'd' format specifier outputs in decimal, alternatively 'x' will
|
The 'd' format specifier outputs decimals. Alternatively 'x' will
|
||||||
output in hexadecimal and 'o' will output in octal.
|
output in hexadecimals and 'o' will output in octals.
|
||||||
|
|
||||||
These respectively correspond to the CPU number (cpu), timestamp
|
These respectively correspond to the CPU number (cpu), timestamp
|
||||||
counter (tsc), event ID (event) and the data logged in the trace file.
|
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.
|
There can be only one such rule for each type of event.
|
||||||
|
|
||||||
An example *formats_file* is available in the acrn_hypervisor repo in
|
An example *formats_file* is available in the acrn_hypervisor repo in
|
||||||
|
@ -65,7 +65,7 @@ acrnalyze.py
|
||||||
============
|
============
|
||||||
|
|
||||||
The ``acrnalyze.py`` is a offline tool to analyze trace data (as output by
|
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``.
|
acrntrace) based on a given analyzer, such as ``vm_exit`` or ``irq``.
|
||||||
|
|
||||||
Options:
|
Options:
|
||||||
|
|
||||||
|
@ -89,53 +89,53 @@ Options:
|
||||||
* - :kbd:`--irq`
|
* - :kbd:`--irq`
|
||||||
- generate an IRQ-related report
|
- generate an IRQ-related report
|
||||||
|
|
||||||
.. note:: We depend on TSC frequency to do time-based analysis. Please configure
|
.. 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
|
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.
|
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
|
The tool does not take into account CPU frequency variation that can
|
||||||
occur during normal operation (aka CPU throttling) on the processor which
|
occur during normal operation (aka CPU throttling) on the processor which
|
||||||
doesn't support for invariant TSC. The results may therefore not be
|
doesn't support for an invariant TSC. The results may therefore not be
|
||||||
completely accurate in that regard.
|
completely accurate in that regard.
|
||||||
|
|
||||||
Typical use example
|
Typical use example
|
||||||
===================
|
===================
|
||||||
|
|
||||||
Here's a typical use of ``acrntrace`` to capture trace data from the SOS,
|
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
|
convert the binary data to human-readable form, copy the processed trace
|
||||||
data to your linux system, and running the analysis tool.
|
data to your Linux system, and run the analysis tool.
|
||||||
|
|
||||||
1. On the SOS, clear buffers before starting a trace, with:
|
1. On the SOS, clear buffers before starting a trace using:
|
||||||
|
|
||||||
.. code-block:: none
|
.. code-block:: none
|
||||||
|
|
||||||
# acrntrace -c
|
# acrntrace -c
|
||||||
|
|
||||||
#. Start capturing buffered trace data with:
|
#. Start capturing buffered trace data using:
|
||||||
|
|
||||||
.. code-block:: none
|
.. code-block:: none
|
||||||
|
|
||||||
# acrntrace
|
# acrntrace
|
||||||
|
|
||||||
Trace files are created under current directory where we launch 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``
|
with a date-time-based directory name such as ``./acrntrace/20171115-101605``
|
||||||
|
|
||||||
#. When done, stop a running ``acrntrace``, with:
|
#. When done, stop a running ``acrntrace`` using:
|
||||||
|
|
||||||
.. code-block:: none
|
.. code-block:: none
|
||||||
|
|
||||||
q <enter>
|
q <enter>
|
||||||
|
|
||||||
#. Convert trace data to human-readable format, with:
|
#. Convert trace data to human-readable format using:
|
||||||
|
|
||||||
.. code-block:: none
|
.. code-block:: none
|
||||||
|
|
||||||
# acrntrace_format.py formats trace_data
|
# acrntrace_format.py formats trace_data
|
||||||
|
|
||||||
Trace data will be converted to human-readable format based on given format
|
Trace data will be converted to human-readable format based on a given format
|
||||||
and printed to stdout.
|
and printed to stdout.
|
||||||
|
|
||||||
#. Analysis of the collected data is done on a Linux PC, so you'll need
|
#. 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
|
to copy the collected trace data to your Linux system (using ``scp`` is
|
||||||
recommended):
|
recommended):
|
||||||
|
|
||||||
|
@ -154,7 +154,7 @@ data to your linux system, and running the analysis tool.
|
||||||
# acrnalyze.py -i /home/xxxx/trace_data/20171115-101605/0 \
|
# acrnalyze.py -i /home/xxxx/trace_data/20171115-101605/0 \
|
||||||
-o /home/xxxx/trace_data/20171115-101605/cpu0 --vm_exit --irq
|
-o /home/xxxx/trace_data/20171115-101605/cpu0 --vm_exit --irq
|
||||||
|
|
||||||
- Analysis report is written to stdout, or to a CSV file if
|
- The analysis report is written to stdout, or to a CSV file if
|
||||||
a filename is specified using ``-o filename``.
|
a filename is specified using ``-o filename``.
|
||||||
- The scripts require Python3.
|
- The scripts require Python3.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue