mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-08-19 08:42:22 +00:00
doc: terminology cleanup in acrntrace readme
- Replace SOS with Service VM - Update file paths to acrntrace directory - Clean up some of the grammar Signed-off-by: Amy Reyes <amy.reyes@intel.com>
This commit is contained in:
Amy Reyes
David Kinder
parent
da6957f0e7
commit
59f9e6c853
@ -6,7 +6,7 @@ Acrntrace
|
||||
Description
|
||||
***********
|
||||
|
||||
``acrntrace`` is a tool running on the Service OS (SOS) to capture trace data.
|
||||
``acrntrace`` is a tool running on the Service VM to capture trace data.
|
||||
A ``scripts`` directory includes scripts to analyze the trace data.
|
||||
|
||||
Usage
|
||||
@ -15,14 +15,14 @@ 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.
|
||||
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 second)
|
||||
-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
|
||||
@ -31,7 +31,7 @@ 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.
|
||||
by ``acrntrace``) to human-readable formats based on a given format.
|
||||
|
||||
Here's an explanation of the tool's parameters:
|
||||
|
||||
@ -49,84 +49,86 @@ 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.
|
||||
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
|
||||
``hypervisor/tools/acrntrace/scripts/formats``.
|
||||
An example *formats* file is available in the ``acrn_hypervisor`` repo in
|
||||
``misc/debug_tools/acrn_trace/scripts``.
|
||||
|
||||
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``.
|
||||
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:
|
||||
|
||||
.. list-table::
|
||||
|
||||
* - :kbd:`-h`
|
||||
* - ``-h``
|
||||
- print this message
|
||||
|
||||
* - :kbd:`-i, --ifile=string`
|
||||
* - ``-i, --ifile=string``
|
||||
- input file name
|
||||
|
||||
* - :kbd:`-o, --ofile=string`
|
||||
* - ``-o, --ofile=string``
|
||||
- output file name
|
||||
|
||||
* - :kbd:`-f, --frequency=unsigned_int`
|
||||
* - ``-f, --frequency=unsigned_int``
|
||||
- TSC frequency in MHz
|
||||
|
||||
* - :kbd:`--vm_exit`
|
||||
* - ``--vm_exit``
|
||||
- generate a vm_exit report
|
||||
|
||||
* - :kbd:`--irq`
|
||||
* - ``--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.
|
||||
.. 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 the processor which
|
||||
doesn't support for an invariant TSC. The results may therefore not be
|
||||
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 SOS,
|
||||
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 Linux system, and run the analysis tool.
|
||||
data to your development computer (Linux system), and run the analysis tool.
|
||||
|
||||
1. On the SOS, clear buffers before starting a trace using:
|
||||
1. On the Service VM, clear buffers before starting a trace:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# acrntrace -c
|
||||
|
||||
#. Start capturing buffered trace data using:
|
||||
#. Start capturing buffered trace data:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# 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``
|
||||
Trace files are created under the current directory where you launched
|
||||
``acrntrace``, with a date-time-based directory name such as
|
||||
``./acrntrace/20171115-101605``.
|
||||
|
||||
#. When done, stop a running ``acrntrace`` using:
|
||||
#. When done, stop a running ``acrntrace``:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
q <enter>
|
||||
|
||||
#. Convert trace data to human-readable format using:
|
||||
#. Convert trace data to human-readable format:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -135,8 +137,8 @@ data to your Linux system, and run the analysis tool.
|
||||
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
|
||||
#. Analysis of the collected data is done on your development computer. Copy
|
||||
the collected trace data to your development computer (using ``scp`` is
|
||||
recommended):
|
||||
|
||||
.. code-block:: none
|
||||
@ -146,7 +148,7 @@ data to your Linux system, and run the analysis tool.
|
||||
|
||||
Replace username and hostname with appropriate values.
|
||||
|
||||
#. On the Linux system, run the provided Python3 script to analyze the
|
||||
#. On the development computer, run the provided Python3 script to analyze the
|
||||
``vm_exits``, ``irq``:
|
||||
|
||||
.. code-block:: none
|
||||
@ -161,13 +163,13 @@ data to your Linux system, and run the analysis tool.
|
||||
Build and Install
|
||||
*****************
|
||||
|
||||
The source files for ``acrntrace`` are in the ``tools/acrntrace`` folder,
|
||||
and can be built and installed using:
|
||||
The source files for ``acrntrace`` are in the ``misc/debug_tools/acrn_trace``
|
||||
directory. To build and install ``acrntrace``, run these commands:
|
||||
|
||||
.. 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.
|
||||
The processing scripts are in ``misc/debug_tools/acrn_trace/scripts`` and need
|
||||
to be copied to and run on your development computer.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user