Skip to content
Permalink
Browse files

doc: fix use of double dashes

Sphinx transforms ``--`` into an en-dash within a paragraph (not within
a code, pre, or kbd block though).  This presents a problem documenting
command parameters such as ``--name`` where the ``--`` is transformed
into a single en-dash.  Rather than disabling all smartquote
transformations in the Sphinx conf.py (setting ``smartquotes = False``),
we fixes cases where ``--`` should not be transformed by using a block
that is ignored by the smartquote transformation.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
  • Loading branch information...
dbkinder committed Dec 12, 2018
1 parent 6dec166 commit e4143ca13897eb21d6948061a4cd0bd6134b5413
Showing with 54 additions and 29 deletions.
  1. +2 −2 doc/release_notes_0.3.rst
  2. +1 −1 doc/release_notes_0.4.rst
  3. +20 −20 doc/user-guides/acrn-dm-parameters.rst
  4. +31 −6 tools/acrntrace/README.rst
@@ -430,8 +430,8 @@ release in Sep 2018 (click on the CommitID link to see details):
- :acrn-commit:`49b476bb` hv: vm_load: set zeropage just past boot args
- :acrn-commit:`9368373f` tools: acrn-crashlog: check the pointer after getting sender
- :acrn-commit:`2973db78` DM: VMcfg: generated example header
- :acrn-commit:`c86da003` DM: VMcfg: support --dump options
- :acrn-commit:`67d72920` DM: VMcfg: support --vmcfg options
- :acrn-commit:`c86da003` DM: VMcfg: support ``--dump`` options
- :acrn-commit:`67d72920` DM: VMcfg: support ``--vmcfg`` options
- :acrn-commit:`321021eb` DM: VMcfg: mrb-env-setup.sh
- :acrn-commit:`d2ed9955` DM: VMcfg: support VM1 on MRB
- :acrn-commit:`ae5b32dc` DM: VMcfg: build-in vm configurations
@@ -211,7 +211,7 @@ release in Nov 2018 (click on the CommitID link to see details):
- :acrn-commit:`eec3a342` dm: fix the race issue in mevent_del
- :acrn-commit:`87e7bdb9` DM: updating launch_uos.sh
- :acrn-commit:`9e0562f4` hv: add obvious comment for empty else clause following else if
- :acrn-commit:`d36b44f2` hv: avoid to use "++" or "--" operators in an expression
- :acrn-commit:`d36b44f2` hv: avoid to use ``++`` or ``--`` operators in an expression
- :acrn-commit:`f33edc67` hv: fix reference parameter to procedure is reassigned
- :acrn-commit:`36be890e` hv: fix included file not protected with #define
- :acrn-commit:`ae9d4361` hv: minimize the case of "identifier reuse"
@@ -14,15 +14,15 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
:widths: 22 78
:header-rows: 0

* - \-A, --acpi
* - :kbd:`-A, --acpi`
- Create ACPI tables.
With this option, DM will build an ACPI table into its VMs F-Segment
(0xf2400). This ACPI table includes full tables for RSDP, RSDT, XSDT,
MADT, FADT, HPET, MCFG, FACS, and DSDT. All these items are programmed
according to acrn-dm command line configuration and derived from their
default value.

* - \-B, --bootargs <bootargs>
* - :kbd:`-B, --bootargs <bootargs>`
- Set the UOS kernel command line arguments.
The maximum length is 1023.
The bootargs string will be passed to the kernel as its cmdline.
@@ -33,12 +33,12 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:

specifies the kernel log level at 7

* - \-c, --ncpus <cpus>
* - :kbd:`-c, --ncpus <cpus>`
- Set number of CPUs for UOS. This number is an integer and must not be
more than the total number of CPUs in the system, minus one (which is
used by the SOS).

* - \--enable_trusty
* - :kbd:`--enable_trusty`
- Enable trusty for guest.
For Android guest OS, ACRN provides a VM environment with two worlds:
normal world and trusty world. The Android OS runs in the the normal
@@ -48,7 +48,7 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:

By default, the trusty world is disabled. Use this option to enable it.

* - \-G, --gvtargs <GVT_args>
* - :kbd:`-G, --gvtargs <GVT_args>`
- ACRN implements GVT-g for graphics virtualization (aka AcrnGT). This
option allows you to set some of its parameters.

@@ -67,10 +67,10 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
sets up 10Mb for GVT-g aperture, 128M for GVT-g hidden
memory, and 6 fence registers.

* - \-h, --help
* - :kbd:`-h, --help`
- Show a summary of commands.

* - \-i, --ioc_node <ioc_mediator_parameters>
* - :kbd:`-i, --ioc_node <ioc_mediator_parameters>`
- IOC (IO Controller) is a bridge of an SoC to communicate with Vehicle Bus.
It routes Vehicle Bus signals, for example extracted from CAN messages,
from IOC to the SoC and back, as well as controlling the onboard
@@ -107,45 +107,45 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
-i /run/acrn/ioc_$vm_name,0x20
-l com2,/run/acrn/ioc_$vm_name

* - \-k, --kernel <kernel_image_path>
* - :kbd:`-k, --kernel <kernel_image_path>`
- Set the kernel (full path) for the UOS kernel. The maximum path length is
1023 characters. The DM handles bzImage image format.

usage: ``-k /path/to/your/kernel_image``

* - \-l, --lpc <lpc_device_configuration>
- (See **-i, --ioc_node**)
* - :kbd:`-l, --lpc <lpc_device_configuration>`
- (See :kbd:`-i, --ioc_node`)

* - \-m, --memsize <memory_size>
* - :kbd:`-m, --memsize <memory_size>`
- Setup total memory size for UOS.

memory_size format is: "<size>{K/k, B/b, M/m, G/g}", and size is an
integer.

usage: ``-m 4g``: set UOS memory to 4 gigabytes.

* - \-p, --pincpu <vcpu:hostcpu>
* - :kbd:`-p, --pincpu <vcpu:hostcpu>`
- Pin host CPU to appointed vCPU:

- ``vcpu`` is the ID of the CPU seen by the UOS, and
- ``hostcpu`` is the physical CPU ID on the system.

Example: ``-p "1:2"`` means pin the 2nd physical cpu to 1st vcpu in UOS

* - \--ptdev_no_reset
* - :kbd:`--ptdev_no_reset`
- Disable reset check for pci device.
When assigning a PCI device as a passthrough device, we will reset it
first to get it to a valid device state. So if the device doesn't have
the reset capability, the passthrough will fail. The PCI device reset
can be disabled using this option.

* - \-r, --ramdisk <ramdisk_image_path>
* - :kbd:`-r, --ramdisk <ramdisk_image_path>`
- Set the ramdisk (full path) for the UOS. The maximum length is 1023.
The supported ramdisk format depends on your UOS kernel configuration.

usage: ``-r /path/to/your/ramdisk_image``

* - \-s, --pci_slot <slot_config>
* - :kbd:`-s, --pci_slot <slot_config>`
- Setup PCI device configuration.

slot_config format is::
@@ -178,7 +178,7 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
This add virtual block in PCI slot 9 and use "/root/test.img" as the
disk image

* - \-U, --uuid <uuid>
* - :kbd:`-U, --uuid <uuid>`
- Set UUID for a VM.
Every VM is identified by a UUID. You can define that UUID with this
option. If you don't use this option, a default one
@@ -190,10 +190,10 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:

set the newly created VM's UUID to "42795636-1d31-6512-7432-087d33b34756"

* - \-v, --version
* - :kbd:`-v, --version`
- Show Device Model version

* - \--vsbl <vsbl_file_path>
* - :kbd:`--vsbl <vsbl_file_path>`
- Virtual Slim bootloader (vSBL) is the virtual bootloader supporting
booting of the UOS on the ACRN hypervisor platform. The vSBL design is
derived from Slim Bootloader, which follows a staged design approach
@@ -213,13 +213,13 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:

uses ``/usr/share/acrn/bios/VSBL.bin`` as the vSBL image

* - \-W, --virtio_msix
* - :kbd:`-W, --virtio_msix`
- This option forces virtio to use single-vector MSI.
By default, any virtio-based devices will use MSI-X as its interrupt
method. If you want to use single-vector MSI interrupt, you can do so
using this option.

* - \-Y, --mptgen
* - :kbd:`-Y, --mptgen`
- Disable MPtable generation.
The MultiProcessor Specification (MPS) for the x86 architecture is an
open standard describing enhancements to both operating systems and
@@ -12,6 +12,9 @@ A ``scripts`` directory includes scripts to analyze the trace data.
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.

@@ -22,6 +25,9 @@ Options:
-t max_time max time to capture trace data (in second)
-c clear the buffered old data

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.

@@ -53,17 +59,33 @@ 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``.

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``.

Options:

-h print this message
-i, --ifile=string input file name
-o, --ofile=string output filename
-f, --frequency=unsigned_int TSC frequency in MHz
--vm_exit generate a vm_exit report
--irq generate an IRQ-related report
.. list-table::

* - :kbd:`-h`
- print this message

* - :kbd:`-i, --ifile=string`
- input file name

* - :kbd:`-o, --ofile=string`
- output filename

* - :kbd:`-f, --frequency=unsigned_int`
- TSC frequency in MHz

* - :kbd:`--vm_exit`
- generate a vm_exit report

* - :kbd:`--irq`
- generate an IRQ-related report

.. note:: We depend on TSC frequency to do time-based analysis. Please configure
the right TSC frequency that acrn runs on. TSC frequency can be obtained
@@ -74,6 +96,9 @@ Options:
doesn't support for 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.

0 comments on commit e4143ca

Please sign in to comment.
You can’t perform that action at this time.