From 50324e58764d90d9551575755268ffe40ae1e79c Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Tue, 29 May 2018 15:54:57 -0700 Subject: [PATCH] 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 --- doc/tools.rst | 1 + tools/acrn-manager/README.rst | 128 ++++++++++++++++---------------- tools/acrnlog/README.rst | 135 +++++++++++++++++++++------------- tools/acrntrace/README.rst | 92 +++++++++++------------ 4 files changed, 195 insertions(+), 161 deletions(-) diff --git a/doc/tools.rst b/doc/tools.rst index c262a14b5..a18016692 100644 --- a/doc/tools.rst +++ b/doc/tools.rst @@ -5,5 +5,6 @@ Tools .. toctree:: :glob: + :maxdepth: 1 tools/** diff --git a/tools/acrn-manager/README.rst b/tools/acrn-manager/README.rst index 7252dbe0d..21403f7e1 100644 --- a/tools/acrn-manager/README.rst +++ b/tools/acrn-manager/README.rst @@ -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 diff --git a/tools/acrnlog/README.rst b/tools/acrnlog/README.rst index dd19e862c..0376601ec 100644 --- a/tools/acrnlog/README.rst +++ b/tools/acrnlog/README.rst @@ -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/ diff --git a/tools/acrntrace/README.rst b/tools/acrntrace/README.rst index f5efbe2d6..a23d673f6 100644 --- a/tools/acrntrace/README.rst +++ b/tools/acrntrace/README.rst @@ -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 - # q +#. 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.