From: Stefan Hajnoczi <stefanha@redhat.com>
Date: Tue, 11 Apr 2017 09:56:54 +0000 (+0100)
Subject: simpletrace: document Analyzer method signatures
X-Git-Tag: qemu-xen-4.10.0-rc1~316^2
X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=659370f71f2c3d4105b04178abd751242e1c1b68;p=qemu-xen.git

simpletrace: document Analyzer method signatures

Users can inherit from the simpletrace.Analyzer class and receive
callbacks when events of interest occur in a trace file.  The method
signature is a little magic because the timestamp and pid arguments are
optional.  Document this.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Message-id: 20170411095654.18383-1-stefanha@redhat.com
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---

diff --git a/scripts/simpletrace.py b/scripts/simpletrace.py
index 4c990047b6..d60b3a08f7 100755
--- a/scripts/simpletrace.py
+++ b/scripts/simpletrace.py
@@ -116,7 +116,28 @@ class Analyzer(object):
     is invoked.
 
     If a method matching a trace event name exists, it is invoked to process
-    that trace record.  Otherwise the catchall() method is invoked."""
+    that trace record.  Otherwise the catchall() method is invoked.
+
+    Example:
+    The following method handles the runstate_set(int new_state) trace event::
+
+      def runstate_set(self, new_state):
+          ...
+
+    The method can also take a timestamp argument before the trace event
+    arguments::
+
+      def runstate_set(self, timestamp, new_state):
+          ...
+
+    Timestamps have the uint64_t type and are in nanoseconds.
+
+    The pid can be included in addition to the timestamp and is useful when
+    dealing with traces from multiple processes::
+
+      def runstate_set(self, timestamp, pid, new_state):
+          ...
+    """
 
     def begin(self):
         """Called at the start of the trace."""