mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-06-19 12:12:16 +00:00
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::
|
.. toctree::
|
||||||
:glob:
|
:glob:
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
tools/**
|
tools/**
|
||||||
|
|||||||
@ -1,34 +1,26 @@
|
|||||||
``acrnctl``
|
.. _acrnctl:
|
||||||
===========
|
|
||||||
|
acrnctl
|
||||||
|
#######
|
||||||
|
|
||||||
|
|
||||||
DESCRIPTION
|
Description
|
||||||
___________
|
***********
|
||||||
|
|
||||||
``acrnctl``: The ``acrnctl`` tool can help user create, delete, launch and stop UOSs.
|
The ``acrnctl`` tool helps users create, delete, launch, and stop a User
|
||||||
It runs under Service OS, and UOSs should be based on ``acrn-dm``
|
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
|
||||||
|
|
||||||
|
|
||||||
or
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
# acrnctl help
|
# acrnctl help
|
||||||
|
|
||||||
you may see:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
support:
|
support:
|
||||||
list
|
list
|
||||||
start
|
start
|
||||||
@ -37,62 +29,72 @@ you may see:
|
|||||||
add
|
add
|
||||||
Use acrnctl [cmd] help for details
|
Use acrnctl [cmd] help for details
|
||||||
|
|
||||||
There are examples:
|
Here are some usage examples:
|
||||||
|
|
||||||
(1) add a VM
|
Add a VM
|
||||||
Each time you can just add one VM. Suppose you have an UOS
|
========
|
||||||
launch script, such as launch_UOS.sh
|
|
||||||
|
|
||||||
you can run:
|
The ``add`` command lets you add a VM by specifying a
|
||||||
|
script that will launch a UOS, for example ``launch_UOS.sh``:
|
||||||
|
|
||||||
::
|
.. code-block:: none
|
||||||
|
|
||||||
# acrnctl add launch_UOS.sh -U 1
|
# acrnctl add launch_UOS.sh -U 1
|
||||||
vm1-14:59:30 added
|
vm1-14:59:30 added
|
||||||
|
|
||||||
Note that, launch script shoud be able to launch ONE UOS. If
|
Note that the launch script must only launch one UOS instance.
|
||||||
it fail, it is better to print some error logs, to tell user
|
The VM name is important. ``acrnctl`` searches VMs by their
|
||||||
the reason, so that he knows how to solve it.
|
names so duplicate VM names are not allowed. If the
|
||||||
The vmname is important, the acrnctl searchs VMs by their
|
launch script changes the VM name at launch time, ``acrnctl``
|
||||||
names. so duplicated VM names are not allowed. Beside, if the
|
will not recognize it.
|
||||||
launch script changes VM name at launch time, acrnctl will
|
|
||||||
not recgonize it.
|
|
||||||
|
|
||||||
(2) delete VMs
|
Delete VMs
|
||||||
|
==========
|
||||||
|
|
||||||
::
|
Use the ``delete`` command with a VM name to delete that VM:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
# acrnctl del vm1-14:59:30
|
# acrnctl del vm1-14:59:30
|
||||||
|
|
||||||
(3) show VMs
|
List VMs
|
||||||
|
========
|
||||||
|
|
||||||
::
|
Use the ``list`` command to display VMs and their state:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
# acrnctl list
|
# acrnctl list
|
||||||
vm1-14:59:30 untracked
|
vm1-14:59:30 untracked
|
||||||
vm-yocto stop
|
vm-yocto stopped
|
||||||
vm-android stop
|
vm-android stopped
|
||||||
|
|
||||||
(4) start VM
|
Start VM
|
||||||
|
========
|
||||||
|
|
||||||
you can start a vm with 'stop' status, each time can start
|
If a VM is in a ``stopped`` state, you can start it with the ``start``
|
||||||
one VM.
|
command:
|
||||||
|
|
||||||
::
|
.. code-block:: none
|
||||||
|
|
||||||
# acrnctl start vm-yocto
|
# acrnctl start vm-yocto
|
||||||
|
|
||||||
(5) stop VM
|
Stop VM
|
||||||
|
=======
|
||||||
|
|
||||||
you can stop VMs, if their status is not 'stop'
|
Use the ``stop`` command to stop one or more running VM:
|
||||||
|
|
||||||
::
|
.. code-block:: none
|
||||||
|
|
||||||
# acrnctl stop vm-yocto vm1-14:59:30 vm-android
|
# acrnctl stop vm-yocto vm1-14:59:30 vm-android
|
||||||
|
|
||||||
BUILD
|
Build and Install
|
||||||
_____
|
*****************
|
||||||
|
|
||||||
::
|
Source code for ``acrnctl`` is in the ``tools/acrn-manager`` folder.
|
||||||
|
Change to that folder and run:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
# make
|
# make
|
||||||
|
# make install
|
||||||
|
|||||||
@ -1,43 +1,55 @@
|
|||||||
``acrnlog``
|
.. _acrnlog:
|
||||||
===========
|
|
||||||
|
|
||||||
DESCRIPTION
|
acrnlog
|
||||||
###########
|
#######
|
||||||
``acrnlog`` is a userland tool to capture ACRN hypervisor log, it runs as an
|
|
||||||
SOS service at boot. It captures two kinds of logs:
|
|
||||||
|
|
||||||
- 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
|
- log of the currently running hypervisor
|
||||||
after reset.
|
- log of last running hypervisor if it crashed and the logs remain.
|
||||||
|
|
||||||
USAGE
|
Log files are saved in ``/tmp/acrnlog/``, so the log files would be lost
|
||||||
#####
|
after a system reset.
|
||||||
The ``acrnlog`` tool is launched as a service at boot, with 4 1MB log files limited.
|
|
||||||
To change the log file limitation:
|
|
||||||
|
|
||||||
- temporary change:
|
Usage
|
||||||
Stop the ``acrnlog`` service:
|
*****
|
||||||
|
|
||||||
::
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
Temporary log file changes
|
||||||
|
==========================
|
||||||
|
|
||||||
|
You can temporarily change the log file setting by following these
|
||||||
|
steps:
|
||||||
|
|
||||||
|
1. Stop the ``acrnlog`` service:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
# systemctl disable acrnlog
|
# systemctl disable acrnlog
|
||||||
|
|
||||||
Restart ``acrnlog`` running in backgroud with size and number of files.
|
2. Restart ``acrnlog``, running in the background, and specify the new
|
||||||
For example:
|
number of log files and their size (in MB). For example:
|
||||||
|
|
||||||
::
|
.. code-block:: none
|
||||||
|
|
||||||
# acrnlog -n 8 -s 4 &
|
# acrnlog -n 8 -s 4 &
|
||||||
|
|
||||||
Use ``get_loglevel``/``set_loglevel`` to query and change the hypervisor loglevel.
|
You can use ``get_loglevel`` and ``set_loglevel`` to query and change
|
||||||
|
the hypervisor loglevel.
|
||||||
|
|
||||||
The ``mem_loglevel`` controls log to be saved using ``acrnlog``, while
|
The ``mem_loglevel`` command controls the log to be saved using
|
||||||
``console_loglevel`` controls log to output to console. For example:
|
``acrnlog``, while the ``console_loglevel`` command controls the log
|
||||||
|
output to the console. For example:
|
||||||
|
|
||||||
::
|
.. code-block:: none
|
||||||
|
|
||||||
ACRN:\>get_loglevel
|
ACRN:\>get_loglevel
|
||||||
console_loglevel: 2, mem_loglevel: 4
|
console_loglevel: 2, mem_loglevel: 4
|
||||||
@ -45,19 +57,38 @@ The ``mem_loglevel`` controls log to be saved using ``acrnlog``, while
|
|||||||
ACRN:\>get_loglevel
|
ACRN:\>get_loglevel
|
||||||
console_loglevel: 2, mem_loglevel: 5
|
console_loglevel: 2, mem_loglevel: 5
|
||||||
|
|
||||||
- permanent change:
|
Permanent log file changes
|
||||||
Edit ``/usr/lib/systemd/system/acrnlog.service`` to attached the ``-n`` and ``-s`` options to the ``ExecStart`` cmd, and restart the service. For example:
|
==========================
|
||||||
|
|
||||||
::
|
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
|
ExecStart=/usr/bin/acrnlog -n 8 -s 4
|
||||||
|
|
||||||
|
and then restart the service with:
|
||||||
|
|
||||||
BUILD & INSTALL
|
.. 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
|
||||||
|
# make install
|
||||||
|
|
||||||
copy acrnlog to ``/usr/bin/`` and copy ``acrnlog.service`` to ``/usr/lib/systemd/system/``
|
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.
|
Description
|
||||||
scripts directory includes scripts to analyze the trace data.
|
***********
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
or clear buffer before tracing start:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
# acrntrace -c
|
# acrntrace -c
|
||||||
|
|
||||||
Trace files are created under ``/tmp/acrntrace/``, directory name with time string eg: ``20171115-101605``
|
#. Start capturing buffered trace data with:
|
||||||
|
|
||||||
2) To stop acrntrace
|
.. code-block:: none
|
||||||
|
|
||||||
::
|
# acrntrace
|
||||||
|
|
||||||
# q <enter>
|
Trace files are created under ``/tmp/acrntrace/``, with a
|
||||||
|
date-time-based directory name such as ``20171115-101605``
|
||||||
|
|
||||||
3) Copy the trace data to linux pc
|
#. When done, stop a running ``acrntrace``, with:
|
||||||
|
|
||||||
::
|
.. code-block:: none
|
||||||
|
|
||||||
# scp -r /tmp/acrntrace/20171115-101605/ xxx@10.239.142.239:/home/xxxx/trace_data
|
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):
|
||||||
|
|
||||||
**Analyze the trace data on Linux PC**
|
.. code-block:: none
|
||||||
|
|
||||||
1) Run the python script to analyze the ``vm_exits``:
|
# scp -r /tmp/acrntrace/20171115-101605/ \
|
||||||
|
username@hostname:/home/username/trace_data
|
||||||
|
|
||||||
::
|
Replace username and hostname with appropriate values.
|
||||||
|
|
||||||
# acrnalyze.py -i /home/xxxx/trace_data/20171115-101605/0 -o /home/xxxx/trac
|
#. On the Linux system, run the provided python2 script to analyze the
|
||||||
e_data/20171115-101605/cpu0 --vm_exit
|
``vm_exits`` (currently only vm_exit analysis is supported):
|
||||||
- "--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
|
|
||||||
|
|
||||||
The scripts require bash and python2.
|
.. code-block:: none
|
||||||
|
|
||||||
BUILD
|
# 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.
|
||||||
|
|
||||||
|
Build and Install
|
||||||
|
*****************
|
||||||
|
|
||||||
|
The source files for ``acrntrace`` are in the ``tools/acrntrace`` folder,
|
||||||
|
and can be built and installed using:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
# make
|
# make
|
||||||
|
# make install
|
||||||
|
|
||||||
|
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
Block a user