Skip to content

Commit 50324e5

Browse files
dbkinderdbkinder
committed
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>
1 parent adcfe03 commit 50324e5

File tree

4 files changed

+183
-149
lines changed

4 files changed

+183
-149
lines changed

‎doc/tools.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,6 @@ Tools
55

66
.. toctree::
77
:glob:
8+
:maxdepth: 1
89

910
tools/**

‎tools/acrn-manager/README.rst

Lines changed: 64 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,100 @@
1-
``acrnctl``
2-
===========
1+
.. _acrnctl:
32

3+
acrnctl
4+
#######
45

5-
DESCRIPTION
6-
___________
76

8-
``acrnctl``: The ``acrnctl`` tool can help user create, delete, launch and stop UOSs.
9-
It runs under Service OS, and UOSs should be based on ``acrn-dm``
7+
Description
8+
***********
109

10+
The ``acrnctl`` tool helps users create, delete, launch, and stop a User
11+
OS (UOS). The tool runs under the Service OS, and UOSs should be based
12+
on ``acrn-dm``.
1113

12-
USAGE
13-
_____
1414

15-
To see what it can do, just run:
1615

17-
::
16+
Usage
17+
*****
1818

19-
# acrnctl
19+
You can see the available ``acrnctl`` commands by running:
2020

21+
.. code-block:: none
2122
22-
or
23+
# acrnctl help
24+
support:
25+
list
26+
start
27+
stop
28+
del
29+
add
30+
Use acrnctl [cmd] help for details
2331
24-
::
32+
Here are some usage examples:
2533

26-
# acrnctl help
34+
Add a VM
35+
========
2736

28-
you may see:
37+
The ``add`` command lets you add a VM by specifying a
38+
script that will launch a UOS, for example ``launch_UOS.sh``:
2939

30-
::
40+
.. code-block:: none
3141
32-
support:
33-
list
34-
start
35-
stop
36-
del
37-
add
38-
Use acrnctl [cmd] help for details
42+
# acrnctl add launch_UOS.sh -U 1
43+
vm1-14:59:30 added
3944
40-
There are examples:
45+
Note that the launch script must only launch one UOS instance.
46+
The VM name is important. ``acrnctl`` searches VMs by their
47+
names so duplicate VM names are not allowed. If the
48+
launch script changes the VM name at launch time, ``acrnctl``
49+
will not recognize it.
4150

42-
(1) add a VM
43-
Each time you can just add one VM. Suppose you have an UOS
44-
launch script, such as launch_UOS.sh
51+
Delete VMs
52+
==========
4553

46-
you can run:
54+
Use the ``delete`` command with a VM name to delete that VM:
4755

48-
::
56+
.. code-block:: none
4957
50-
# acrnctl add launch_UOS.sh -U 1
51-
vm1-14:59:30 added
58+
# acrnctl del vm1-14:59:30
5259
53-
Note that, launch script shoud be able to launch ONE UOS. If
54-
it fail, it is better to print some error logs, to tell user
55-
the reason, so that he knows how to solve it.
56-
The vmname is important, the acrnctl searchs VMs by their
57-
names. so duplicated VM names are not allowed. Beside, if the
58-
launch script changes VM name at launch time, acrnctl will
59-
not recgonize it.
60+
List VMs
61+
========
6062

61-
(2) delete VMs
63+
Use the ``list`` command to display VMs and their state:
6264

63-
::
65+
.. code-block:: none
6466
65-
# acrnctl del vm1-14:59:30
67+
# acrnctl list
68+
vm1-14:59:30 untracked
69+
vm-yocto stopped
70+
vm-android stopped
6671
67-
(3) show VMs
72+
Start VM
73+
========
6874

69-
::
75+
If a VM is in a ``stopped`` state, you can start it with the ``start``
76+
command:
7077

71-
# acrnctl list
72-
vm1-14:59:30 untracked
73-
vm-yocto stop
74-
vm-android stop
78+
.. code-block:: none
7579
76-
(4) start VM
80+
# acrnctl start vm-yocto
7781
78-
you can start a vm with 'stop' status, each time can start
79-
one VM.
82+
Stop VM
83+
=======
8084

81-
::
85+
Use the ``stop`` command to stop one or more running VM:
8286

83-
# acrnctl start vm-yocto
87+
.. code-block:: none
8488
85-
(5) stop VM
89+
# acrnctl stop vm-yocto vm1-14:59:30 vm-android
8690
87-
you can stop VMs, if their status is not 'stop'
91+
Build and Install
92+
*****************
8893

89-
::
94+
Source code for ``acrnctl`` is in the ``tools/acrn-manager`` folder.
95+
Change to that folder and run:
9096

91-
# acrnctl stop vm-yocto vm1-14:59:30 vm-android
97+
.. code-block:: none
9298
93-
BUILD
94-
_____
95-
96-
::
97-
98-
# make
99+
# make
100+
# make install

‎tools/acrnlog/README.rst

Lines changed: 72 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,94 @@
1-
``acrnlog``
2-
===========
1+
.. _acrnlog:
32

4-
DESCRIPTION
5-
###########
6-
``acrnlog`` is a userland tool to capture ACRN hypervisor log, it runs as an
7-
SOS service at boot. It captures two kinds of logs:
3+
acrnlog
4+
#######
85

9-
- log of current running;
6+
Description
7+
***********
108

11-
- log of last running if crashed and logs remaining.
9+
``acrnlog`` is a userland tool used to capture a ACRN hypervisor log. It runs as an
10+
SOS service at boot, capturing two kinds of logs:
1211

13-
The path to save log files is ``/tmp/acrnog/``, so the log files would be lost
14-
after reset.
12+
- log of the currently running hypervisor
13+
- log of last running hypervisor if it crashed and the logs remain.
1514

16-
USAGE
17-
#####
18-
The ``acrnlog`` tool is launched as a service at boot, with 4 1MB log files limited.
19-
To change the log file limitation:
15+
Log files are saved in ``/tmp/acrnlog/``, so the log files would be lost
16+
after a system reset.
2017

21-
- temporary change:
22-
Stop the ``acrnlog`` service:
18+
Usage
19+
*****
2320

24-
::
21+
The ``acrnlog`` tool is launched as a service at boot, and limited to
22+
supporting four 1MB log files by default. You can change this log file
23+
limitation temporarily or permanently.
2524

26-
# systemctl disable acrnlog
2725

28-
Restart ``acrnlog`` running in backgroud with size and number of files.
29-
For example:
26+
Temporary log file changes
27+
==========================
3028

31-
::
29+
You can temporarily change the log file setting by following these
30+
steps:
3231

33-
# acrnlog -n 8 -s 4 &
32+
1. Stop the ``acrnlog`` service:
3433

35-
Use ``get_loglevel``/``set_loglevel`` to query and change the hypervisor loglevel.
34+
.. code-block:: none
3635
37-
The ``mem_loglevel`` controls log to be saved using ``acrnlog``, while
38-
``console_loglevel`` controls log to output to console. For example:
36+
# systemctl disable acrnlog
3937
40-
::
38+
2. Restart ``acrnlog``, running in the background, and specify the new
39+
number of log files and their size (in MB). For example:
4140

42-
ACRN:\>get_loglevel
43-
console_loglevel: 2, mem_loglevel: 4
44-
ACRN:\>set_loglevel 2 5
45-
ACRN:\>get_loglevel
46-
console_loglevel: 2, mem_loglevel: 5
41+
.. code-block:: none
4742
48-
- permanent change:
49-
Edit ``/usr/lib/systemd/system/acrnlog.service`` to attached the ``-n`` and ``-s`` options to the ``ExecStart`` cmd, and restart the service. For example:
43+
# acrnlog -n 8 -s 4 &
5044
51-
::
45+
You can use ``get_loglevel`` and ``set_loglevel`` to query and change
46+
the hypervisor loglevel.
5247

53-
ExecStart=/usr/bin/acrnlog -n 8 -s 4
48+
The ``mem_loglevel`` command controls the log to be saved using
49+
``acrnlog``, while the ``console_loglevel`` command controls the log
50+
output to the console. For example:
5451

52+
.. code-block:: none
5553
56-
BUILD & INSTALL
57-
##################
54+
ACRN:\>get_loglevel
55+
console_loglevel: 2, mem_loglevel: 4
56+
ACRN:\>set_loglevel 2 5
57+
ACRN:\>get_loglevel
58+
console_loglevel: 2, mem_loglevel: 5
5859
59-
::
60+
Permanent log file changes
61+
==========================
6062

61-
# make
62-
63-
copy acrnlog to ``/usr/bin/`` and copy ``acrnlog.service`` to ``/usr/lib/systemd/system/``
63+
You can also permanently change the log file settings by
64+
editing ``/usr/lib/systemd/system/acrnlog.service`` and use the ``-n``
65+
and ``-s`` options on the ``ExecStart`` cmd, and restart the service.
66+
For example, ``acrnlog.service`` could have these parameters added:
67+
68+
.. code-block:: none
69+
70+
ExecStart=/usr/bin/acrnlog -n 8 -s 4
71+
72+
and then restart the service with:
73+
74+
.. code-block:: none
75+
76+
# systemctl daemon-reload
77+
# systemctl restart acrnlog
78+
79+
Build and Install
80+
*****************
81+
82+
Source code for the ``acrnlog`` tools is in the ``tools/acrnlog``
83+
folder. Build and install the tools from source using:
84+
85+
.. code-block:: none
86+
87+
# make
88+
# make install
89+
90+
and if you changed the ``acrnlog.service`` file, install it using:
91+
92+
.. code-block:: none
93+
94+
# cp acrnlog.service /usr/lib/systemd/system/

0 commit comments

Comments
 (0)