doc: fix tools docs formatting and clarity
This continues the editing from PR #276 with formatting and clarity edits to have these tool documents blend in with the rest of the ACRN documentation. It also builds on PR #307 that set up the doc build infrastructure to allow leaving these tool docs within the tools/ folder. Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder
David Kinder
parent
adcfe03482
commit
50324e5876
|
|
@ -5,5 +5,6 @@ Tools
|
|||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
tools/**
|
||||
|
|
|
|||
|
|
@ -1,98 +1,100 @@
|
|||
``acrnctl``
|
||||
===========
|
||||
.. _acrnctl:
|
||||
|
||||
acrnctl
|
||||
#######
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
___________
|
||||
Description
|
||||
***********
|
||||
|
||||
``acrnctl``: The ``acrnctl`` tool can help user create, delete, launch and stop UOSs.
|
||||
It runs under Service OS, and UOSs should be based on ``acrn-dm``
|
||||
The ``acrnctl`` tool helps users create, delete, launch, and stop a User
|
||||
OS (UOS). The tool runs under the Service OS, and UOSs should be based
|
||||
on ``acrn-dm``.
|
||||
|
||||
|
||||
USAGE
|
||||
_____
|
||||
|
||||
To see what it can do, just run:
|
||||
Usage
|
||||
*****
|
||||
|
||||
::
|
||||
You can see the available ``acrnctl`` commands by running:
|
||||
|
||||
# acrnctl
|
||||
.. code-block:: none
|
||||
|
||||
# acrnctl help
|
||||
support:
|
||||
list
|
||||
start
|
||||
stop
|
||||
del
|
||||
add
|
||||
Use acrnctl [cmd] help for details
|
||||
|
||||
or
|
||||
Here are some usage examples:
|
||||
|
||||
::
|
||||
Add a VM
|
||||
========
|
||||
|
||||
# acrnctl help
|
||||
The ``add`` command lets you add a VM by specifying a
|
||||
script that will launch a UOS, for example ``launch_UOS.sh``:
|
||||
|
||||
you may see:
|
||||
.. code-block:: none
|
||||
|
||||
::
|
||||
# acrnctl add launch_UOS.sh -U 1
|
||||
vm1-14:59:30 added
|
||||
|
||||
support:
|
||||
list
|
||||
start
|
||||
stop
|
||||
del
|
||||
add
|
||||
Use acrnctl [cmd] help for details
|
||||
Note that the launch script must only launch one UOS instance.
|
||||
The VM name is important. ``acrnctl`` searches VMs by their
|
||||
names so duplicate VM names are not allowed. If the
|
||||
launch script changes the VM name at launch time, ``acrnctl``
|
||||
will not recognize it.
|
||||
|
||||
There are examples:
|
||||
Delete VMs
|
||||
==========
|
||||
|
||||
(1) add a VM
|
||||
Each time you can just add one VM. Suppose you have an UOS
|
||||
launch script, such as launch_UOS.sh
|
||||
Use the ``delete`` command with a VM name to delete that VM:
|
||||
|
||||
you can run:
|
||||
.. code-block:: none
|
||||
|
||||
::
|
||||
# acrnctl del vm1-14:59:30
|
||||
|
||||
# acrnctl add launch_UOS.sh -U 1
|
||||
vm1-14:59:30 added
|
||||
List VMs
|
||||
========
|
||||
|
||||
Note that, launch script shoud be able to launch ONE UOS. If
|
||||
it fail, it is better to print some error logs, to tell user
|
||||
the reason, so that he knows how to solve it.
|
||||
The vmname is important, the acrnctl searchs VMs by their
|
||||
names. so duplicated VM names are not allowed. Beside, if the
|
||||
launch script changes VM name at launch time, acrnctl will
|
||||
not recgonize it.
|
||||
Use the ``list`` command to display VMs and their state:
|
||||
|
||||
(2) delete VMs
|
||||
.. code-block:: none
|
||||
|
||||
::
|
||||
# acrnctl list
|
||||
vm1-14:59:30 untracked
|
||||
vm-yocto stopped
|
||||
vm-android stopped
|
||||
|
||||
# acrnctl del vm1-14:59:30
|
||||
Start VM
|
||||
========
|
||||
|
||||
(3) show VMs
|
||||
If a VM is in a ``stopped`` state, you can start it with the ``start``
|
||||
command:
|
||||
|
||||
::
|
||||
.. code-block:: none
|
||||
|
||||
# acrnctl list
|
||||
vm1-14:59:30 untracked
|
||||
vm-yocto stop
|
||||
vm-android stop
|
||||
# acrnctl start vm-yocto
|
||||
|
||||
(4) start VM
|
||||
Stop VM
|
||||
=======
|
||||
|
||||
you can start a vm with 'stop' status, each time can start
|
||||
one VM.
|
||||
Use the ``stop`` command to stop one or more running VM:
|
||||
|
||||
::
|
||||
.. code-block:: none
|
||||
|
||||
# acrnctl start vm-yocto
|
||||
# acrnctl stop vm-yocto vm1-14:59:30 vm-android
|
||||
|
||||
(5) stop VM
|
||||
Build and Install
|
||||
*****************
|
||||
|
||||
you can stop VMs, if their status is not 'stop'
|
||||
Source code for ``acrnctl`` is in the ``tools/acrn-manager`` folder.
|
||||
Change to that folder and run:
|
||||
|
||||
::
|
||||
.. code-block:: none
|
||||
|
||||
# acrnctl stop vm-yocto vm1-14:59:30 vm-android
|
||||
|
||||
BUILD
|
||||
_____
|
||||
|
||||
::
|
||||
|
||||
# make
|
||||
# make
|
||||
# make install
|
||||
|
|
|
|||
|
|
@ -1,63 +1,94 @@
|
|||
``acrnlog``
|
||||
===========
|
||||
.. _acrnlog:
|
||||
|
||||
DESCRIPTION
|
||||
###########
|
||||
``acrnlog`` is a userland tool to capture ACRN hypervisor log, it runs as an
|
||||
SOS service at boot. It captures two kinds of logs:
|
||||
acrnlog
|
||||
#######
|
||||
|
||||
- log of current running;
|
||||
Description
|
||||
***********
|
||||
|
||||
- log of last running if crashed and logs remaining.
|
||||
``acrnlog`` is a userland tool used to capture a ACRN hypervisor log. It runs as an
|
||||
SOS service at boot, capturing two kinds of logs:
|
||||
|
||||
The path to save log files is ``/tmp/acrnog/``, so the log files would be lost
|
||||
after reset.
|
||||
- log of the currently running hypervisor
|
||||
- log of last running hypervisor if it crashed and the logs remain.
|
||||
|
||||
USAGE
|
||||
#####
|
||||
The ``acrnlog`` tool is launched as a service at boot, with 4 1MB log files limited.
|
||||
To change the log file limitation:
|
||||
Log files are saved in ``/tmp/acrnlog/``, so the log files would be lost
|
||||
after a system reset.
|
||||
|
||||
- temporary change:
|
||||
Stop the ``acrnlog`` service:
|
||||
Usage
|
||||
*****
|
||||
|
||||
::
|
||||
|
||||
# systemctl disable acrnlog
|
||||
|
||||
Restart ``acrnlog`` running in backgroud with size and number of files.
|
||||
For example:
|
||||
|
||||
::
|
||||
|
||||
# acrnlog -n 8 -s 4 &
|
||||
|
||||
Use ``get_loglevel``/``set_loglevel`` to query and change the hypervisor loglevel.
|
||||
|
||||
The ``mem_loglevel`` controls log to be saved using ``acrnlog``, while
|
||||
``console_loglevel`` controls log to output to console. For example:
|
||||
|
||||
::
|
||||
|
||||
ACRN:\>get_loglevel
|
||||
console_loglevel: 2, mem_loglevel: 4
|
||||
ACRN:\>set_loglevel 2 5
|
||||
ACRN:\>get_loglevel
|
||||
console_loglevel: 2, mem_loglevel: 5
|
||||
|
||||
- permanent change:
|
||||
Edit ``/usr/lib/systemd/system/acrnlog.service`` to attached the ``-n`` and ``-s`` options to the ``ExecStart`` cmd, and restart the service. For example:
|
||||
|
||||
::
|
||||
|
||||
ExecStart=/usr/bin/acrnlog -n 8 -s 4
|
||||
The ``acrnlog`` tool is launched as a service at boot, and limited to
|
||||
supporting four 1MB log files by default. You can change this log file
|
||||
limitation temporarily or permanently.
|
||||
|
||||
|
||||
BUILD & INSTALL
|
||||
##################
|
||||
Temporary log file changes
|
||||
==========================
|
||||
|
||||
::
|
||||
You can temporarily change the log file setting by following these
|
||||
steps:
|
||||
|
||||
# make
|
||||
|
||||
copy acrnlog to ``/usr/bin/`` and copy ``acrnlog.service`` to ``/usr/lib/systemd/system/``
|
||||
1. Stop the ``acrnlog`` service:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# systemctl disable acrnlog
|
||||
|
||||
2. Restart ``acrnlog``, running in the background, and specify the new
|
||||
number of log files and their size (in MB). For example:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# acrnlog -n 8 -s 4 &
|
||||
|
||||
You can use ``get_loglevel`` and ``set_loglevel`` to query and change
|
||||
the hypervisor loglevel.
|
||||
|
||||
The ``mem_loglevel`` command controls the log to be saved using
|
||||
``acrnlog``, while the ``console_loglevel`` command controls the log
|
||||
output to the console. For example:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
ACRN:\>get_loglevel
|
||||
console_loglevel: 2, mem_loglevel: 4
|
||||
ACRN:\>set_loglevel 2 5
|
||||
ACRN:\>get_loglevel
|
||||
console_loglevel: 2, mem_loglevel: 5
|
||||
|
||||
Permanent log file changes
|
||||
==========================
|
||||
|
||||
You can also permanently change the log file settings by
|
||||
editing ``/usr/lib/systemd/system/acrnlog.service`` and use the ``-n``
|
||||
and ``-s`` options on the ``ExecStart`` cmd, and restart the service.
|
||||
For example, ``acrnlog.service`` could have these parameters added:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
ExecStart=/usr/bin/acrnlog -n 8 -s 4
|
||||
|
||||
and then restart the service with:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# systemctl daemon-reload
|
||||
# systemctl restart acrnlog
|
||||
|
||||
Build and Install
|
||||
*****************
|
||||
|
||||
Source code for the ``acrnlog`` tools is in the ``tools/acrnlog``
|
||||
folder. Build and install the tools from source using:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# make
|
||||
# make install
|
||||
|
||||
and if you changed the ``acrnlog.service`` file, install it using:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# cp acrnlog.service /usr/lib/systemd/system/
|
||||
|
|
|
|||
|
|
@ -1,73 +1,73 @@
|
|||
``acrntrace``
|
||||
==============
|
||||
.. _acrntrace:
|
||||
|
||||
DESCRIPTION
|
||||
###########
|
||||
acrntrace
|
||||
#########
|
||||
|
||||
``acrntrace``: is a tool running on SOS, to capture trace data.
|
||||
scripts directory includes scripts to analyze the trace data.
|
||||
Description
|
||||
***********
|
||||
|
||||
USAGE
|
||||
#####
|
||||
``acrntrace`` is a tool running on the Service OS (SOS) to capture trace data.
|
||||
A ``scripts`` directory includes scripts to analyze the trace data.
|
||||
|
||||
Capture trace data on SOS
|
||||
Usage
|
||||
*****
|
||||
|
||||
1) Launch ``acrntrace``
|
||||
1. On the SOS, clear buffers before starting a trace, with:
|
||||
|
||||
Capture buffered trace data:
|
||||
.. code-block:: none
|
||||
|
||||
::
|
||||
# acrntrace -c
|
||||
|
||||
# acrntrace
|
||||
#. Start capturing buffered trace data with:
|
||||
|
||||
or clear buffer before tracing start:
|
||||
.. code-block:: none
|
||||
|
||||
::
|
||||
# acrntrace
|
||||
|
||||
# acrntrace -c
|
||||
Trace files are created under ``/tmp/acrntrace/``, with a
|
||||
date-time-based directory name such as ``20171115-101605``
|
||||
|
||||
Trace files are created under ``/tmp/acrntrace/``, directory name with time string eg: ``20171115-101605``
|
||||
#. When done, stop a running ``acrntrace``, with:
|
||||
|
||||
2) To stop acrntrace
|
||||
.. code-block:: none
|
||||
|
||||
::
|
||||
q <enter>
|
||||
|
||||
# q <enter>
|
||||
#. 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):
|
||||
|
||||
3) Copy the trace data to linux pc
|
||||
.. code-block:: none
|
||||
|
||||
::
|
||||
# scp -r /tmp/acrntrace/20171115-101605/ \
|
||||
username@hostname:/home/username/trace_data
|
||||
|
||||
# scp -r /tmp/acrntrace/20171115-101605/ xxx@10.239.142.239:/home/xxxx/trace_data
|
||||
Replace username and hostname with appropriate values.
|
||||
|
||||
#. On the Linux system, run the provided python2 script to analyze the
|
||||
``vm_exits`` (currently only vm_exit analysis is supported):
|
||||
|
||||
**Analyze the trace data on Linux PC**
|
||||
.. code-block:: none
|
||||
|
||||
1) Run the python script to analyze the ``vm_exits``:
|
||||
# acrnalyze.py -i /home/xxxx/trace_data/20171115-101605/0 \
|
||||
-o /home/xxxx/trace_data/20171115-101605/cpu0 --vm_exit
|
||||
|
||||
::
|
||||
- A preprocess makes some changes to the datafile for processing but
|
||||
a copy of the original data file is saved with suffix ``.orig``.
|
||||
- Analysis report is written to stdout, or to a CSV file if
|
||||
a filename is specified using ``-o filename``.
|
||||
- The scripts require bash and python2.
|
||||
|
||||
# acrnalyze.py -i /home/xxxx/trace_data/20171115-101605/0 -o /home/xxxx/trac
|
||||
e_data/20171115-101605/cpu0 --vm_exit
|
||||
- "--vm_exit" specify the analysis to do, currently, only vm_exit analysis
|
||||
is supported.
|
||||
- A preprocess would be taken out to make the trace data start and end with
|
||||
an VM_ENTER, and a copy of original data file is saved with suffix ".orig";
|
||||
- Analysis report would be given on the std output and in a csv file with
|
||||
name specified via "-o outpu_file";
|
||||
Script usage:
|
||||
[Usage] acrnalyze.py [options] [value] ...
|
||||
[options]
|
||||
-h: print this message
|
||||
-i, --ifile=[string]: input file
|
||||
-o, --ofile=[string]: output file
|
||||
--vm_exit: to generate vm_exit report
|
||||
Build and Install
|
||||
*****************
|
||||
|
||||
The scripts require bash and python2.
|
||||
The source files for ``acrntrace`` are in the ``tools/acrntrace`` folder,
|
||||
and can be built and installed using:
|
||||
|
||||
BUILD
|
||||
#####
|
||||
.. code-block:: none
|
||||
|
||||
::
|
||||
# make
|
||||
# make install
|
||||
|
||||
# make
|
||||
The processing scripts are in ``tools/acrntrace/scripts`` and need to be
|
||||
copied to and run on your Linux system.
|
||||
|
|
|
|||
Loading…
Reference in New Issue