tools:acrn-crashlog: Document of configuration file

This document explains all fields in acrnprobe.xml.
User could use it to control acrnprobe's behavior and configure their
own events.

Tracked-On: #1024
Signed-off-by: Liu, Xinwu <xinwu.liu@intel.com>
Reviewed-by: David B. Kinder <david.b.kinder@intel.com>
Acked-by: Chen Gang <gang.c.chen@intel.com>
Acked-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>

tools/acrn-crashlog/acrnprobe/README.rst

@@ -39,8 +39,8 @@ To see the version of ``acrnprobe``.
 Architecture
 ************
 
-Syntax
+Terms
-======
+=====
 
 - channel :
   Channel represents a way of detecting the system's events. There are 3
@@ -50,6 +50,19 @@ Syntax
   + polling: run a detecting job with fixed time interval.
   + inotify: monitor the change of file or dir.
 
+- trigger :
+  Essentially, trigger represents one section of content. It could be
+  a file's content, a directory's content, or a memory's content which can be
+  obtained. By monitoring it ``acrnprobe`` could detect certain events which
+  happened in the system.
+
+- crash :
+  A subtype of event. It often corresponds to a crash of programs, system, or
+  hypervisor. ``acrnprobe`` detects it and reports it as ``CRASH``.
+
+- info :
+  A subtype of event. ``acrnprobe`` detects it and reports it as ``INFO``.
+
 - event queue :
   There is a global queue to receive all events detected.
   Generally, events are enqueued in channel, and dequeued in event handler.
@@ -136,15 +149,15 @@ Source files
 - main.c
   Entry of ``acrnprobe``.
 - channel.c
-  The implementation of *channel* (see `Syntax`_).
+  The implementation of *channel* (see `Terms`_).
 - crash_reclassify.c
   Analyzing the detailed types for crash event.
 - probeutils.c
   Provide some utils ``acrnprobe`` needs.
 - event_queue.c
-  The implementation of *event queue* (see `Syntax`_).
+  The implementation of *event queue* (see `Terms`_).
 - event_handler.c
-  The implementation of *event handler* (see `Syntax`_).
+  The implementation of *event handler* (see `Terms`_).
 - history.c
   There is a history_event file to manage all logs that ``acrnprobe`` archived.
   "history.c" provides the interfaces to modify the file in fixed format.
@@ -154,7 +167,7 @@ Source files
   The ``acrnprobe`` needs to know some HW/SW properties, such as board version,
   build version. These properties are managed centrally in this file.
 - sender.c
-  The implementation of *sender* (see `Syntax`_).
+  The implementation of *sender* (see `Terms`_).
 - startupreason.c
   This file provides the function to get system reboot reason from kernel
   command line.
@@ -175,4 +188,6 @@ Configuration files
 
   Custom configuration file that ``acrnprobe`` reads.
 
+For details about configuration file, please refer to :ref:`acrnprobe-conf`.
+
 .. _`telemetrics-client`: https://github.com/clearlinux/telemetrics-client

tools/acrn-crashlog/acrnprobe/conf.rst

@@ -0,0 +1,416 @@
+.. _acrnprobe-conf:
+
+acrnprobe Configuration
+#######################
+
+Description
+***********
+``acrnprobe`` uses XML as the format of its configuration file, namely
+``acrnprobe.xml``, following the `XML standard`_.
+
+Layout
+******
+
+.. code-block:: xml
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <conf>
+   Root node of configuration.
+
+   <senders>
+   Configuration section of senders.
+   <sender id='1'>Configuration of sender 1</sender>
+   <sender id='2'>Configuration of sender 2</sender>
+   </senders>
+
+   <triggers>
+   Configuration section of triggers.
+   <trigger id='1'>Configuration of trigger 1</trigger>
+   <trigger id='2'>Configuration of trigger 2</trigger>
+   </triggers>
+
+   <vms>
+   Configuration section of virtual machines.
+   <vm id='1'>Configuration of vm 1</vm>
+   <vm id='2'>Configuration of vm 2</vm>
+   </vms>
+
+   <logs>
+   Configuration section of logs.
+   <log id='1'>Configuration of log 1</log>
+   <log id='2'>Configuration of log 2</log>
+   </logs>
+
+   <crashes>
+   Configuration section of crashes.
+   Note that this section must be configured after triggers and logs, as
+   crashes depend on these two sections.
+   <crash id='1'>Configuration of crash 1</crash>
+   <crash id='2'>Configuration of crash 2</crash>
+   </crashes>
+
+   <infos>
+   Configuration section of infos.
+   Note that this section must be configured after triggers and logs, as
+   infos depend on these two sections.
+   <info id='1'>Configuration of info 1</info>
+   <info id='2'>Configuration of info 2</info>
+   </infos>
+
+   </conf>
+
+As for the definition of ``sender``, ``trigger``, ``crash`` and ``info``
+please refer to :ref:`acrnprobe_doc`.
+
+Properties of group members
+***************************
+
+``acrnprobe`` defined different groups in configuration file, which are
+``senders``, ``triggers``, ``crashes`` and ``infos``.
+
+Common properties
+=================
+
+- ``id``:
+  The index, which grows from 1 consecutively, in its group.
+- ``enable``:
+  This group member will be ignored if the value is NOT ``true``.
+
+Other properties
+================
+
+- ``inherit``:
+  Specify a parent for a certain crash.
+  The child crash will inherit all configurations from the specified (by id)
+  crash. These inherited configurations could be overwritten by new ones.
+  Also, this property helps build the crash tree in ``acrnprobe``.
+- ``expression``:
+  See `Crash`_.
+
+Crash tree in acrnprobe
+***********************
+
+There could be a parent-child relationship between crashes. Refer to the
+diagrams below, crash B and D are the children of crash A, because crash B and
+D inherit from crash A, and crash C is the child of crash B.
+
+Build crash tree in configuration
+=================================
+
+.. graphviz::
+
+   digraph {
+      {
+         node [shape=plaintext];
+         "level 1" -> "level 2" -> "level 3";
+      }
+
+      node [shape=box;style="rounded,filled";color=AntiqueWhite;];
+      c1 [ label="crash A\nid 1\ncrash root" ];
+      c2 [ label="crash B\nid 2" ];
+      c3 [ label="crash C\nid 3\ncrash leaf" ];
+      c4 [ label="crash D\nid 4\ncrash leaf" ];
+      c5 [ label="crash E\nid 5\ncrash root\ncrash leaf" ];
+      { rank = same; "level 1"; c1; c5;}
+      { rank = same; "level 2"; c2; c4;}
+      { rank = same; "level 3"; c3;}
+
+      node [shape=box;color="transparent";];
+      "None" -> {c1 c5} [ label="inherit 0" ];
+      c1 -> {c2 c4} [ label="inherit 1" ];
+      c2 -> c3 [ label="inherit 2" ];
+   }
+
+Match crash at runtime
+======================
+
+In order to find a more specific type, if one crash type matches
+successfully ``acrnprobe`` will do a match for each child of it (if it has any)
+continually, and return the last successful one.
+About how to determine a match is successful, please refer to the ``content`` of
+`Crash`_.
+
+Supposing these crash trees are like the diagram above at runtime:
+If a crash E is triggered, crash E will be returned immediately.
+If a crash A is triggered, then the candidates are crash A, B, C and D.
+The following diagram describes what ``acrnprobe`` will do if the matched
+result is crash D.
+
+.. graphviz::
+
+   digraph {
+      {
+         node [shape=plaintext];
+         "level 1" -> "level 2" -> "level 3";
+      }
+
+      node [shape=box;style="rounded,filled";color=AntiqueWhite;];
+      c1 [ label="crash A\nid 1\ncrash root" ];
+      c2 [ label="crash B\nid 2" ];
+      c3 [ label="crash C\nid 3\ncrash leaf" ];
+      c4 [ label="crash D\nid 4\ncrash leaf" ];
+      { rank = same; "level 1"; c1;}
+      { rank = same; "level 2"; c2; c4;}
+      { rank = same; "level 3"; c3;}
+
+      node [shape=box;style="rounded,dashed";];
+      exp1 [ label="crash B matches fail\nmatch for the next child\nof crash A"];
+      exp2 [ label="crash D matches successfully\nreturn crash D"];
+
+      node [shape=box;style="invis";];
+      "channel" -> c1 [ label="trigger" ]
+      c1 -> {exp1 exp2}
+      exp1 -> c2 -> c3 [ style=dashed dir=none]
+      exp2 -> c4
+   }
+
+Sections
+********
+
+Sender
+======
+
+Example:
+
+.. code-block:: xml
+
+   <sender id="1" enable="true">
+           <name>crashlog</name>
+           <outdir>/var/log/crashlog</outdir>
+           <maxcrashdirs>1000</maxcrashdirs>
+           <maxlines>5000</maxlines>
+           <spacequota>90</spacequota>
+           <uptime>
+                   <name>UPTIME</name>
+                   <frequency>5</frequency>
+                   <eventhours>6</eventhours>
+           </uptime>
+   </sender>
+
+* ``name``:
+  Name of sender. ``acrnprobe`` uses this label to distinguish different
+  senders.
+  For more information about sender, please refer to :ref:`acrnprobe_doc`.
+* ``outdir``:
+  Directory to store generated files of sender. ``acrnprobe`` will create
+  this directory if it doesn't exist.
+* ``maxcrashdirs``:
+  The maximum serial number of generated ``crash directories``,
+  ``stat directories`` and ``vmevent directories``. The serial number will be
+  reset to 0 if it reaches the specified maximum (``maxcrashdirs``).
+  Only used by sender crashlog.
+* ``maxlines``:
+  If the number of lines in the ``history_event`` file reaches the specified
+  ``maxlines``, the ``history_event`` file will be renamed to
+  ``history_event.bak`` and logging will continue with a now empty
+  ``history_event`` file.
+* ``spacequota``:
+  ``acrnprobe`` will stop collecting logs if
+  ``(used space / total space) * 100 > spacequota``. Only used by sender
+  crashlog.
+* ``uptime``:
+  Configuration to trigger ``UPTIME`` event.
+  sub-nodes:
+
+  + ``name``:
+    The name of event.
+  + ``frequency``:
+    Time interval in seconds to trigger ``uptime`` event.
+  + ``eventhours``:
+    Time interval in hours to generate a record.
+
+
+Trigger
+=======
+
+Example:
+
+.. code-block:: xml
+
+   <trigger id="1" enable="true">
+           <name>t_pstore</name>
+           <type>node</type>
+           <path>/sys/fs/pstore/console-ramoops-0</path>
+   </trigger>
+   <trigger id="2" enable="true">
+           <name>t_acrnlog_last</name>
+           <type>file</type>
+           <path>/tmp/acrnlog/acrnlog_last.[*]</path>
+   </trigger>
+
+* ``name``:
+  The name of trigger. It's used by crash and info configuration module.
+* ``type`` and ``path``:
+  These two labels are used to get the content of trigger files.
+  ``type`` have been implemented:
+
+  + ``node``:
+    It means that ``path`` is a device node on virtual file system, which cannot
+    support ``mmap(2)-like`` operations. ``acrnprobe`` can use only ``read(2)``
+    to get its content.
+  + ``file``:
+    It means that ``path`` is a regular file which supports ``mmap(2)-like``
+    operations.
+  + ``dir``:
+    It means that ``path`` is a directory.
+  + ``rebootreason``:
+    It means that the trigger's content is the reboot reason of system. The
+    content of ``rebootreason`` is not obtained in a common way. So, it doesn't
+    work with ``path``.
+  + ``cmd``:
+    It means that ``path`` is a command which will be launched by ``execvp(3)``.
+
+  Some programs often use format ``string%d`` instead of static file name to
+  generate target file dynamically. So ``path`` supports simple formats for
+  these cases:
+
+  + /.../dir/string[*] --> all files with prefix "string" under dir.
+  + /.../dir/string[0] --> the first file of files, sorted by ``alphasort(3)``,
+    with prefix "string" under dir.
+  + /.../dir/string[-1] --> the last file of files, sorted by ``alphasort(3)``,
+    with prefix "string" under dir.
+
+  Example of formats:
+  If there are 4 files under ``/tmp``:
+  ``acrnlog_last.1`` ``acrnlog_last.2`` ``acrnlog_last.3`` ``other.txt``
+
+  + ``/tmp/acrnlog_last.[-1]`` indicates ``acrnlog_last.3``.
+  + ``/tmp/acrnlog_last.[0]`` indicates ``acrnlog_last.1``.
+  + ``/tmp/acrnlog_last.[*]`` indicates the file set including
+    ``acrnlog_last.1``, ``acrnlog_last.2`` and ``acrnlog_last.3``.
+
+
+Vm
+==
+
+Example:
+
+.. code-block:: xml
+
+   <vm id="1" enable="true">
+           <name>VM1</name>
+           <channel>polling</channel>
+           <interval>60</interval>
+           <syncevent id="1">CRASH/TOMBSTONE</syncevent>
+           <syncevent id="2">CRASH/UIWDT</syncevent>
+           <syncevent id="3">CRASH/IPANIC</syncevent>
+           <syncevent id="4">REBOOT</syncevent>
+   </vm>
+
+* ``name``:
+  The name of virtual machine.
+* ``channel``:
+  The ``channel`` name to get the virtual machine events.
+* ``interval``:
+  Time interval in seconds of polling vm's image.
+* ``syncevent``:
+  Event type ``acrnprobe`` will synchronize from virtual machine's ``crashlog``.
+  User could specify different types by id. The event type can also be
+  indicated by ``type/subtype``.
+
+Log
+===
+
+Example:
+
+.. code-block:: xml
+
+   <log id="1" enable="true">
+           <name>pstore</name>
+           <type>node</type>
+           <path>/sys/fs/pstore/console-ramoops-0</path>
+   </log>
+
+* ``name``:
+  By default, ``acrnprobe`` will take this ``name`` as generated log's name in
+  ``outdir`` of sender crashlog.
+  If ``path`` is specified by simple formats (includes [*], [0] or [-1]) the
+  file name of generated logs will be the same as original. More details about
+  simple formats, see `Trigger`_.
+* ``type`` and ``path``:
+  Same as `Trigger`_.
+* ``lines``:
+  By default, all contents in the original will be copied to generated log.
+  If this label is configured, only the ``lines`` at the end in the original
+  will be copied to the generated log. It takes effect only when the ``type`` is
+  ``file``.
+
+Crash
+=====
+
+Example:
+
+.. code-block:: xml
+
+   <crash id='1' inherit='0' enable='true'>
+           <name>UNKNOWN</name>
+           <trigger>t_rebootreason</trigger>
+           <channel>oneshot</channel>
+           <content id='1'>WARM</content>
+           <log id='1'>pstore</log>
+           <log id='2'>acrnlog_last</log>
+   </crash>
+   <crash id='2' inherit='1' enable='true'>
+           <name>IPANIC</name>
+           <trigger>t_pstore</trigger>
+           <content id='1'> </content>
+           <mightcontent expression='1' id='1'>Kernel panic - not syncing:</mightcontent>
+           <mightcontent expression='1' id='2'>BUG: unable to handle kernel</mightcontent>
+           <data id='1'>kernel BUG at</data>
+           <data id='2'>EIP is at</data>
+           <data id='3'>Comm:</data>
+   </crash>
+
+* ``name``:
+  The type of the ``crash``.
+* ``trigger``:
+  The trigger name of the crash.
+* ``channel``:
+  The name of channel crash use.
+* ``content`` and ``mightcontent``:
+  They're used to match crash type. The match is successful if all the
+  following conditions are met:
+
+  a. All ``contents`` with different ``ids`` are included in trigger's
+     content.
+  b. One of ``mightcontents`` with the same ``expression`` is included in
+     trigger's content at least.
+  c. If there are ``mightcontents`` with different ``expressions``, each group
+     with the same ``expression`` should meet condition b.
+* ``log``:
+  The log to be collected. The value is the configured ``name`` in log module.
+  User could specify different logs by ``id``.
+* ``data``:
+  It is used to generate ``DATA`` fields in ``crashfile``. ``acrnprobe`` will
+  copy the line which starts with configured ``data`` in trigger's content
+  to ``DATA`` fields. There are 3 fields in ``crashfile`` and they could be
+  specified by ``id`` 1, 2, 3.
+
+Info
+=====
+
+Example:
+
+.. code-block:: xml
+
+   <info id='1' enable='true'>
+           <name>BOOT_LOGS</name>
+           <trigger>t_boot</trigger>
+           <channel>oneshot</channel>
+           <log id='1'>kmsg</log>
+           <log id='2'>cmdline</log>
+           <log id='3'>acrnlog_cur</log>
+           <log id='4'>acrnlog_last</log>
+   </info>
+
+* ``name``:
+  The type of info.
+* ``trigger``:
+  The trigger name of the info.
+* ``channel``:
+  The name of channel info use.
+* ``log``:
+  The log to be collected. The value is the configured name in log module. User
+  could specify different logs by id.
+
+.. _`XML standard`: http://www.w3.org/TR/REC-xml