2007-12-13 Masami Hiramatsu <mhiramat@redhat.com>

	* stap.1.in: Document about relay buffer sharing.
	* NEWS: Document about relay buffer sharing and staplog crash extension.

3 files changed, 41 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 85775b09..b4f41825 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2007-12-13  Masami Hiramatsu  <mhiramat@redhat.com>
+
+	* stap.1.in: Document about relay buffer sharing.
+	* NEWS: Document about relay buffer sharing and staplog crash extension.
+
 2007-12-12  Wenji Huang <wenji.huang@oracle.com>
 
         PR 5470
diff --git a/NEWS b/NEWS
index 930de31c..7b3e3265 100644
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,26 @@
 * What's new in version 0.6 / since version 0.5.15?
 
+- Crash utility can retrieve systemtap's relay buffer from a kernel dump
+  image by using staplog which is a crash extension module. To use this
+  feature, type commands as below from crash(8)'s command line:
+
+    crash> extend staplog.so
+    crash> help systemtaplog
+
+  Then, you can see more precise help message.
+
+- You can share a relay buffer amoung several scripts and merge outputs from
+  several scripts by using "-DRELAY_HOST" and "-DRELAY_GUEST" options.
+  For example:
+
+    # run a host script
+    % stap -ve 'probe begin{}' -o merged.out -DRELAY_HOST &
+    # wait until starting the host.
+    % stap -ve 'probe begin{print("hello ");exit()}' -DRELAY_GUEST
+    % stap -ve 'probe begin{print("world\n");exit()}' -DRELAY_GUEST
+
+  Then, you'll see "hello world" in merged.out.
+
 - You can add a conditional statement for each probe point or aliase, which
   is evaluated when the probe point is hit. If the condition is false, the
   whole probe body(including aliases) is skipped. For example:
diff --git a/stap.1.in b/stap.1.in
index 135e92f5..16a799cf 100644
--- a/stap.1.in
+++ b/stap.1.in
@@ -869,6 +869,21 @@ run a probe handler, default 1024.  This number should be large enough
 for the probe handler's own needs, plus a safety margin.
 
 .PP
+Multipule scripts can write data into a relay buffer concurrently. A host
+script provides an interface for accessing its relay buffer to guest scripts.
+Then, the output of the guests are merged into the output of the host.
+To run a script as a host, execute stap with
+.BR \-DRELAYHOST[=name]
+option. The
+.BR name
+identifies your host script among several hosts.
+While running the host, execute stap with
+.BR \-DRELAYGUEST[=name]
+to add a guest script to the host.
+Note that you must unload guests before unloading a host. If there are some
+guests connected to the host, unloading the host will be failed.
+
+.PP
 In case something goes wrong with 
 .IR stap " or " staprun
 after a probe has already started running, one may safely kill both