Patch v3 have been confirmed by local doc building system. I put the
"images/dot files" into conf.rst, since the doc building system collects only rst
files to doc directory.

-----Original Message-----
From: acrn-dev@... [mailto:acrn-dev@...]
On Behalf Of Liu xinwu
Sent: Monday, August 13, 2018 4:38 AM
To: VanCutsem, Geoffroy <geoffroy.vancutsem@...>; acrn-
dev@...
Cc: Chen, Gang C <gang.c.chen@...>; Zhang, Di <di.zhang@...>;
Jin, Zhi <zhi.jin@...>; Liu, Xiaojing <xiaojing.liu@...>
Subject: Re: [acrn-dev] [PATCH v2] tools:acrn-crashlog: Document of
configuration file

I send out the patch V3


On 08/10/2018 03:04 PM, VanCutsem, Geoffroy wrote:

Just a couple of nitpicks below then you can move forward with my ACK.

I'm sure David will have suggestions for you but these are best addressed
directly in the PR phase.

Corrected.

I'm assuming you have built that documentation locally and verified it, can

you just confirm?

Patch v3 have been confirmed by local doc building system. I put the
"images/dot files" into conf.rst, since the doc building system collects only rst
files to doc directory.

Thanks,
Geoffroy

-----Original Message-----
From: acrn-dev@...
[mailto:acrn-dev@...]
On Behalf Of Liu xinwu
Sent: Thursday, August 2, 2018 8:23 AM
To: acrn-dev@...
Cc: Chen, Gang C <gang.c.chen@...>; Zhang, Di
<di.zhang@...>; Liu, Xinwu <xinwu.liu@...>; Jin, Zhi
<zhi.jin@...>; Liu, Xiaojing <xiaojing.liu@...>;
VanCutsem, Geoffroy <geoffroy.vancutsem@...>
Subject: [acrn-dev] [PATCH v2] tools:acrn-crashlog: Document of
configuration file

This document explains all feilds in acrnprobe.xml.

s/fields/fields

User could use it to control acrnprobe's behavior and configure their
own events.

Signed-off-by: Liu, Xinwu <xinwu.liu@...>
---

v1->v2:
1. refer conf.rst from README.rst
2. drawing by graphviz instead of raw text.

tools/acrn-crashlog/acrnprobe/README.rst | 2 +
tools/acrn-crashlog/acrnprobe/conf.rst | 337
+++++++++++++++++++++
.../acrn-crashlog/acrnprobe/images/build-crash.dot | 21 ++
.../acrn- crashlog/acrnprobe/images/crash-match.dot | 25 ++
4 files changed, 385 insertions(+)
create mode 100644 tools/acrn-crashlog/acrnprobe/conf.rst
create mode 100644 tools/acrn-crashlog/acrnprobe/images/build-

crash.dot

create mode 100644 tools/acrn-crashlog/acrnprobe/images/crash-
match.dot

diff --git a/tools/acrn-crashlog/acrnprobe/README.rst b/tools/acrn-
crashlog/acrnprobe/README.rst index fa137f3..5f537ae 100644
--- a/tools/acrn-crashlog/acrnprobe/README.rst
+++ b/tools/acrn-crashlog/acrnprobe/README.rst
@@ -175,4 +175,6 @@ Configuration files

Custom configuration file that ``acrnprobe`` reads.

+More details about configuration file, please refer to :ref:`acrnprobe-

conf`.

+
.. _`telemetrics-client`:
https://github.com/clearlinux/telemetrics-client
diff --git a/tools/acrn-crashlog/acrnprobe/conf.rst b/tools/acrn-
crashlog/acrnprobe/conf.rst new file mode 100644 index
0000000..7d8ec40
--- /dev/null
+++ b/tools/acrn-crashlog/acrnprobe/conf.rst
@@ -0,0 +1,337 @@
+.. _acrnprobe-conf:
+
+Configuration Of Acrnprobe
+##########################
+
+Description
+***********
+``Acrnprobe`` uses XML as the format of its configuration file,
+namely ``acrnprobe.xml``, so the configuration file should reach the
+`XML standard`_ at least.
+
+Layout
+******
+
+.. code-block:: xml
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <conf>
+ Root node of configuration.
+
+ <senders>
+ Configuration section of senders.
+ </senders>
+
+ <triggers>
+ Configuration section of triggers.
+ </triggers>
+
+ <vms>
+ Configuration section of virtual machines.
+ </vms>
+
+ <logs>
+ Configuration section of logs.
+ </logs>
+
+ <crashes>
+ Configuration section of crashes.
+ Note that this section should be configured after triggers and logs, as
+ crashes depend on these two sections.
+ </crashes>
+
+ <infos>
+ Configuration section of infos.
+ Note that this section should be configured after triggers and logs, as
+ infos depend on these two sections.
+ </infos>
+
+ </conf>
+
+As for the definition of ``sender``, ``trigger``, ``crash`` and
+``info`` and information of supported ``vm``, please refer to
:ref:`acrnprobe_doc`.
+
+Properties of modules
+*********************
+
+Common properties
+=================
+
+- ``id``:
+ The index, which grows from 1, in its group.
+- ``enable``:
+ This part of configuration can only take effect when the value is ``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:: images/build-crash.dot
+ :name: build-crash
+ :align: center
+ :caption: Build crash tree in configuration
+
+Crash type matches at runtime
+=============================
+
+In order to find a more specific type, if one crash type matches
+successfully ``acrnprobe`` will do match for each child of it (if it
+has) continually, and return the last successful one.
+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:: images/crash-match.dot
+ :name: crash-match
+ :align: center
+ :caption: Crash type matches at runtime
+
+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.
+ 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 back to 0 if
+it reaches
+ the maximum. Only used by sender crashlog.
+* ``maxlines``:
+ The maximum lines of file ``history_event``. It will trigger
+action
+ ``"mv history_event history_event.bak"`` that the lines of
+``history_event``
+ reaches the ``maxlines``.
+* ``spacequota``:
+ ``Acrnprobe`` will stop collecting logs if it is true that
+ ``(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>
+
+* ``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.
+ ``Types`` have been implemented:
+
+ + ``node``:
+ ``Path`` can not support ``mmap(2)-like`` operations.
+ ``Acrnprobe`` can

"cannot" in one word.

+ only use ``read(2)`` to get its content.
+ + ``file``:
+ ``Path`` is a regular file which supports ``mmap(2)-like`` operations.
+ + ``dir``:
+ ``Path`` is a directory.
+ + ``rebootreason``:
+ The reboot reason of system. The content of ``rebootreason`` is not
+ obtained in a common way. So, it doesn't work with ``path``.
+ + ``cmd``:
+ ``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.
+
+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 generated ``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
diff --git a/tools/acrn-crashlog/acrnprobe/images/build-crash.dot
b/tools/acrn-crashlog/acrnprobe/images/build-crash.dot
new file mode 100644
index 0000000..08e7628
--- /dev/null
+++ b/tools/acrn-crashlog/acrnprobe/images/build-crash.dot
@@ -0,0 +1,21 @@
+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" ];
+}
diff --git a/tools/acrn-crashlog/acrnprobe/images/crash-match.dot
b/tools/acrn-crashlog/acrnprobe/images/crash-match.dot
new file mode 100644
index 0000000..7da5ce0
--- /dev/null
+++ b/tools/acrn-crashlog/acrnprobe/images/crash-match.dot
@@ -0,0 +1,25 @@
+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
+}
--
2.7.4