doc: clean up tools docs
Made the titles consistent across the tools (some had capital letters). Fixed heading levels in acrnctl/acrnd doc (had two H1 headings). Changed a text-based drawing to use graphviz. Some general grammar tweaks as well. Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder
David Kinder
parent
38b9b7d37c
commit
e2ad788f63
|
|
@ -4,12 +4,13 @@ ACRN-Crashlog
|
|||
Introduction
|
||||
************
|
||||
|
||||
The ``ACRN-Crashlog`` is a joint name for the tools (``acrnprobe``,
|
||||
``usercrash_s``, ``usercrash_c``, ``debugger`` and etc.), which collect logs
|
||||
and information after each crash or event on ACRN platform, including the
|
||||
hypervisor, Service OS (SOS), and Android as a Guest (AaaG). The
|
||||
``ACRN-Crashlog`` provides a flexible way to configure which events are of
|
||||
interest, by using an XML configuration file.
|
||||
``ACRN-Crashlog`` is a joint name for the tools (``acrnprobe``,
|
||||
``usercrash_s``, ``usercrash_c``, ``debugger``, and more). Together
|
||||
these tools collect logs and information after each crash or event on an
|
||||
ACRN platform, including the hypervisor, Service OS (SOS), and Android
|
||||
as a Guest (AaaG). ``ACRN-Crashlog`` provides a flexible way to
|
||||
configure which events are of interest, by using an XML configuration
|
||||
file.
|
||||
|
||||
Building
|
||||
********
|
||||
|
|
@ -33,32 +34,35 @@ build environment, and follow the instructions below to build and configure the
|
|||
Build
|
||||
=====
|
||||
|
||||
To build the ``ACRN-Crashlog``, run below command under ``acrn-crashlog/``:
|
||||
To build the ``ACRN-Crashlog``, run:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ cd acrn-crashlog
|
||||
$ make
|
||||
|
||||
To remove all generated files and return the folder to its clean state, use
|
||||
below command under ``acrn-crashlog/``:
|
||||
To remove all generated files and return the folder to its clean state,
|
||||
use:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ cd acrn-crashlog
|
||||
$ make clean
|
||||
|
||||
Installing
|
||||
**********
|
||||
|
||||
To install the build
|
||||
To install the build:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ cd acrn-crashlog
|
||||
$ sudo make install
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
The ``acrnprobe`` can work in two ways according to the existence of
|
||||
The ``acrnprobe`` tool can work in two ways according to the existence of
|
||||
telemetrics-client on the system:
|
||||
|
||||
1. If telemetrics-client doesn't exist on the system, ``acrnprobe`` provides
|
||||
|
|
@ -70,14 +74,23 @@ telemetrics-client on the system:
|
|||
of the telemetrics-client: it runs as a daemon autostarted when the system
|
||||
boots, and sends the crashlog path to the telemetrics-client that records
|
||||
events of interest and reports them to the backend using ``telemd`` the
|
||||
telemetrics daemon. The work flow of ``acrnprobe`` and telemetrics-client is:
|
||||
telemetrics daemon. The work flow of ``acrnprobe`` and
|
||||
telemetrics-client is shown in :numref:`crashlog-workflow`:
|
||||
|
||||
::
|
||||
.. graphviz::
|
||||
:name: crashlog-workflow
|
||||
:align: center
|
||||
:caption: acrnprobe and telemetrics-client workflow
|
||||
|
||||
digraph {
|
||||
bgcolor=transparent; rankdir=LR;
|
||||
node [shape="rectangle" style="filled" color="lightblue"]
|
||||
edge [fontsize="12" fontcolor="blue"]
|
||||
|
||||
"acrnprobe" -> "telemetrics-client" [label="crashlog\npath"]
|
||||
"telemetrics-client" -> "backend" [label="log\ncontent"]
|
||||
}
|
||||
|
||||
+------------------------------------------------------------------+
|
||||
| crashlog path log content |
|
||||
| acrnprobe------------->telemetrics-client----------->backend |
|
||||
+------------------------------------------------------------------+
|
||||
|
||||
Crashlog can be retrieved with ``telem_journal`` command:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
.. _acrnprobe_doc:
|
||||
|
||||
Acrnprobe
|
||||
acrnprobe
|
||||
#########
|
||||
|
||||
Description
|
||||
|
|
|
|||
|
|
@ -1,26 +1,27 @@
|
|||
.. _usercrash_doc:
|
||||
|
||||
Usercrash
|
||||
usercrash
|
||||
#########
|
||||
|
||||
Description
|
||||
***********
|
||||
|
||||
The ``usercrash`` is to get the crash info for the crashing process in
|
||||
The ``usercrash`` tool gets the crash info for the crashing process in
|
||||
userpace. The collected information is saved as usercrash_xx under
|
||||
``/var/log/usercrashes/``.
|
||||
|
||||
Design
|
||||
******
|
||||
|
||||
The ``usercrash`` is designed as Client/Server model. The server is autostarted
|
||||
at boot, and the client is configured in ``core_pattern``, which will be
|
||||
triggered once crash occurs in userspace. Then client sends the crash event to
|
||||
server. The server will check the files under ``/var/log/usercrashes/`` and
|
||||
create a new file usercrash_xx(xx means the index of the crash files), then
|
||||
it will send the fd to client. The client will be responsible for collecting
|
||||
crash information and saving it in the crashlog file. After saving work is done,
|
||||
client will notify server. Then the server will clean up.
|
||||
``usercrash`` is designed using a Client/Server model. The server is
|
||||
autostarted at boot. The client is configured in ``core_pattern``, which
|
||||
will be triggered when a crash occurs in userspace. The client then
|
||||
sends the crash event to the server. The server checks the files under
|
||||
``/var/log/usercrashes/`` and creates a new file usercrash_xx (xx means
|
||||
the index of the crash file). Then it sends the file descriptor (fd) to
|
||||
the client. The client is responsible for collecting crash information
|
||||
and saving it in the crashlog file. After the saving work is done, the
|
||||
client notifies server and the server will clean up.
|
||||
|
||||
The work flow diagram:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
.. _acrnctl:
|
||||
|
||||
acrnctl
|
||||
#######
|
||||
acrnctl and acrnd
|
||||
#################
|
||||
|
||||
|
||||
Description
|
||||
|
|
@ -9,7 +9,7 @@ Description
|
|||
|
||||
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``.
|
||||
on ``acrn-dm``. The daemon for acrn-manager is `acrnd`_.
|
||||
|
||||
|
||||
|
||||
|
|
@ -96,13 +96,8 @@ Use the ``stop`` command to stop one or more running VM:
|
|||
.. _acrnd:
|
||||
|
||||
acrnd
|
||||
#######
|
||||
*****
|
||||
|
||||
|
||||
Description
|
||||
***********
|
||||
|
||||
The ``acrnd`` is the daemon for acrn-manager.
|
||||
The ``acrnd`` daemon process provides a way for launching or resuming a UOS
|
||||
should the UOS shut down, either planned or unexpected. A UOS can ask ``acrnd``
|
||||
to set up a timer to make sure the UOS is running, even if the SOS is
|
||||
|
|
@ -112,9 +107,6 @@ and sets an RTC timer to wake up the SOS or bring the SOS back up again.
|
|||
When ``acrnd`` daemon is restarted, it restores the previously saved timer
|
||||
list and launches the UOSs at the right time.
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
A ``systemd`` service file (``acrnd.service``) is installed by default that will
|
||||
start the ``acrnd`` daemon when the Service OS comes up.
|
||||
You can restart/stop acrnd service using ``systemctl``
|
||||
|
|
@ -122,7 +114,7 @@ You can restart/stop acrnd service using ``systemctl``
|
|||
Build and Install
|
||||
*****************
|
||||
|
||||
Source code for ``acrnctl`` and ``acrnd`` is in the ``tools/acrn-manager`` folder.
|
||||
Source code for both ``acrnctl`` and ``acrnd`` is in the ``tools/acrn-manager`` folder.
|
||||
Change to that folder and run:
|
||||
|
||||
.. code-block:: none
|
||||
|
|
|
|||
Loading…
Reference in New Issue