diff --git a/misc/tools/acrntrace/README.rst b/misc/tools/acrntrace/README.rst index d0823be62..03de2abfe 100644 --- a/misc/tools/acrntrace/README.rst +++ b/misc/tools/acrntrace/README.rst @@ -25,13 +25,13 @@ Options: -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 these configured cpu-set +-a cpu-set only capture the trace data on the configured cpu-set 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. +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: @@ -43,19 +43,19 @@ 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:: +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 +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. +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. +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 @@ -65,7 +65,7 @@ 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``. +acrntrace) based on a given analyzer, such as ``vm_exit`` or ``irq``. Options: @@ -89,53 +89,53 @@ Options: * - :kbd:`--irq` - 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 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 + 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, -converting the binary data to human-readable form, copying the processed trace -data to your linux system, and running the analysis tool. +convert the binary data to human-readable form, copy the processed trace +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 # acrntrace -c -#. Start capturing buffered trace data with: +#. Start capturing buffered trace data using: .. code-block:: none # 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`` -#. When done, stop a running ``acrntrace``, with: +#. When done, stop a running ``acrntrace`` using: .. code-block:: none q -#. Convert trace data to human-readable format, with: +#. Convert trace data to human-readable format using: .. code-block:: none # 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. -#. 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 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 \ -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``. - The scripts require Python3.