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>

misc/debug_tools/acrn_trace/README.rst

@@ -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
+The ``acrntrace`` tool runs on the Service VM to capture trace data and output
-output to trace file under ``./acrntrace`` with raw (binary) data format.
+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
+The ``text_format_string`` may include format specifiers, such as ``%(cpu)d``,
-``%(cpu)d``, ``%(tsc)d``, ``%(event)d``, ``%(1)d``, and ``%(2)d``.
+``%(tsc)d``, ``%(event)d``, ``%(1)d``, and ``%(2)d``. The 'd' format specifier
-The 'd' format specifier outputs decimals. Alternatively 'x' will
+outputs the data in decimal format. Alternatively, 'x' outputs the data in
-output in hexadecimals and 'o' will output in octals.
+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
+An example *formats* file is available in the ``acrn_hypervisor`` repo in
-``hypervisor/tools/acrntrace/scripts/formats``.
+``misc/debug_tools/acrn_trace/scripts``.
 
 acrnalyze.py
 ============
 
-The ``acrnalyze.py`` is a offline tool to analyze trace data (as output by
+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``.
+``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
+.. note:: The tool depends on TSC frequency to do time-based analysis. Be sure
-   the right TSC frequency that acrn runs on. TSC frequency can be obtained
+   to configure the right TSC frequency that ACRN runs on. TSC frequency can be
-   from the ACRN console log (calibrate_tsc, tsc_hz=xxx) when the hypervisor boots.
+   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
+   occur during normal operation (aka CPU throttling) on a processor that
-   doesn't support for an invariant TSC. The results may therefore not be
+   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,
+   Trace files are created under the current directory where you launched
-   with a date-time-based directory name such as ``./acrntrace/20171115-101605``
+   ``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
+#. Analysis of the collected data is done on your development computer. Copy
-   to copy the collected trace data to your Linux system (using ``scp`` is
+   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,
+The source files for ``acrntrace`` are in the ``misc/debug_tools/acrn_trace``
-and can be built and installed using:
+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
+The processing scripts are in ``misc/debug_tools/acrn_trace/scripts`` and need
-copied to and run on your Linux system.
+to be copied to and run on your development computer.