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>

tools/acrn-crashlog/README.rst

@@ -4,12 +4,13 @@ ACRN-Crashlog
 Introduction
 ************
 
-The ``ACRN-Crashlog`` is a joint name for the tools (``acrnprobe``,
+``ACRN-Crashlog`` is a joint name for the tools (``acrnprobe``,
-``usercrash_s``, ``usercrash_c``, ``debugger`` and etc.), which collect logs
+``usercrash_s``, ``usercrash_c``, ``debugger``, and more). Together
-and information after each crash or event on ACRN platform, including the
+these tools collect logs and information after each crash or event on an
-hypervisor, Service OS (SOS), and Android as a Guest (AaaG). The
+ACRN platform, including the hypervisor, Service OS (SOS), and Android
-``ACRN-Crashlog`` provides a flexible way to configure which events are of
+as a Guest (AaaG). ``ACRN-Crashlog`` provides a flexible way to
-interest, by using an XML configuration file.
+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
+To remove all generated files and return the folder to its clean state,
-below command under ``acrn-crashlog/``:
+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:
 

tools/acrn-crashlog/acrnprobe/README.rst

@@ -1,6 +1,6 @@
 .. _acrnprobe_doc:
 
-Acrnprobe
+acrnprobe
 #########
 
 Description

tools/acrn-crashlog/usercrash/README.rst

@@ -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
+``usercrash`` is designed using a  Client/Server model. The server is
-at boot, and the client is configured in ``core_pattern``, which will be
+autostarted at boot. The client is configured in ``core_pattern``, which
-triggered once crash occurs in userspace. Then client sends the crash event to
+will be triggered when a crash occurs in userspace. The client then
-server. The server will check the files under ``/var/log/usercrashes/`` and
+sends the crash event to the server. The server checks the files under
-create a new file usercrash_xx(xx means the index of the crash files), then
+``/var/log/usercrashes/`` and creates a new file usercrash_xx (xx means
-it will send the fd to client. The client will be responsible for collecting
+the index of the crash file).  Then it sends the file descriptor (fd) to
-crash information and saving it in the crashlog file. After saving work is done,
+the client. The client is responsible for collecting crash information
-client will notify server. Then the server will clean up.
+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:
 

tools/acrn-manager/README.rst

@@ -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