bitkeeper revision 1.784 (4050c414tIvxGfQ8IUNIXoAjpoXBVA)

Updated script names and added man pages for all the xentrace tools.

6 files changed, 109 insertions, 5 deletions

diff --git a/tools/xentrace/Makefile b/tools/xentrace/Makefile
index 5758f6a2e7..2e85fcbe1a 100644
--- a/tools/xentrace/Makefile
+++ b/tools/xentrace/Makefile
@@ -7,17 +7,18 @@ CFLAGS  += -I../../xenolinux-sparse/include
 HDRS     = $(wildcard *.h)
 OBJS     = $(patsubst %.c,%.o,$(wildcard *.c))
 
-BIN      = xentrace
-SCRIPTS  = $(wildcard *.py)
+BIN      = xentrace xentrace_cpusplit xentrace_format
+MAN1     = $(wildcard *.1)
+MAN8     = $(wildcard *.8)
 
 all: $(BIN)
 
 install: all
 	mkdir -p /usr/bin
 	cp $(BIN) /usr/bin
-	cp $(SCRIPTS) /usr/bin
-	chmod 755 /usr/bin/$(BIN)
-	for i in $(SCRIPTS); do chmod 755 /usr/bin/$$i; done
+	for i in $(BIN); do chmod 755 /usr/bin/$$i; done
+	for i in $(MAN1); do cp $$i /usr/man/man1/$$i; done
+	for i in $(MAN8); do cp $$i /usr/man/man8/$$i; done
 
 dist: all
 	mkdir -p ../../../install/bin
diff --git a/tools/xentrace/xentrace.8 b/tools/xentrace/xentrace.8
new file mode 100644
index 0000000000..b9720b9fbe
--- /dev/null
+++ b/tools/xentrace/xentrace.8
@@ -0,0 +1,38 @@
+.TH XENTRACE 8 "11 March 2004" "Xen domain 0 utils"
+.SH NAME
+xentrace \- capture Xen trace buffer data
+.SH SYNOPSIS
+.B xentrace
+[
+.I OPTIONS
+] [
+.I FILE
+]
+.SH DESCRIPTION
+.B xentrace
+is used to dump data from Xen's per-cpu trace buffers.  Records
+are dumped in ASCII format, onto the standard output or a \fIFILE\fP
+specified on the command line.
+Trace records are formatted as follows:
+.PP
+                    CPU TSC EVENT D1 D2 D3 D4 D5
+.PP
+Where CPU is the processor number, TSC is the record's timestamp
+(the value of the CPU cycle counter), EVENT is the event ID and
+D1...D5 are the trace data.
+
+.SS Options
+.TP
+.B -t, --log-thresh=l
+set the threshold number, l, of new records required to trigger a write of
+all new records to the output
+.TP
+.B -s, --poll-sleep=p
+set the time, p, (in milliseconds) to sleep between polling the buffers
+for new data.
+
+.SH AUTHOR
+Mark A. Williamson <mark.a.williamson@intel.com>
+
+.SH "SEE ALSO"
+xentrace_cpuinfo(1), xentrace_format(1)
diff --git a/tools/xentrace/xentrace_cpusplit.py b/tools/xentrace/xentrace_cpusplit
index 9847b79b38..9847b79b38 100644
--- a/tools/xentrace/xentrace_cpusplit.py
+++ b/tools/xentrace/xentrace_cpusplit
diff --git a/tools/xentrace/xentrace_cpusplit.1 b/tools/xentrace/xentrace_cpusplit.1
new file mode 100644
index 0000000000..9b35ed598c
--- /dev/null
+++ b/tools/xentrace/xentrace_cpusplit.1
@@ -0,0 +1,27 @@
+.TH XENTRACE_CPUSPLIT 1 "11 March 2004" "Xen domain 0 utils"
+.SH NAME
+xentrace_cpusplit \- separate Xen trace data into per-CPU log files
+.SH SYNOPSIS
+.B xentrace_cpusplit
+[
+.I BASE-NAME
+]
+.SH DESCRIPTION
+.B xentrace_cpusplit
+Separates ASCII trace buffer data from stdin into per-CPU trace
+files.  The trace files are named by appending the CPU number
+to the \fIBASE-NAME\fP supplied on the command line.
+
+The trace records in the per-CPU files are in identical format to the
+original output of \fBxentrace\fP and are in chronological order.
+
+Depending on your system and the rate at which trace data is produced,
+this script may not be able to keep up with the output of
+\fBxentrace\fP if it is piped directly.  In these circumstances you
+should have \fBxentrace\fP output to a file for processing off-line.
+
+.SH AUTHOR
+Mark A. Williamson <mark.a.williamson@intel.com>
+
+.SH "SEE ALSO"
+xentrace(8), xentrace_format(1)
diff --git a/tools/xentrace/xentrace_format.py b/tools/xentrace/xentrace_format
index b8f8d018ce..b8f8d018ce 100644
--- a/tools/xentrace/xentrace_format.py
+++ b/tools/xentrace/xentrace_format
diff --git a/tools/xentrace/xentrace_format.1 b/tools/xentrace/xentrace_format.1
new file mode 100644
index 0000000000..ef08224d9e
--- /dev/null
+++ b/tools/xentrace/xentrace_format.1
@@ -0,0 +1,38 @@
+.TH XENTRACE_FORMAT 1 "11 March 2004" "Xen domain 0 utils"
+.SH NAME
+xentrace_format \- pretty-print Xen trace data
+.SH SYNOPSIS
+.B xentrace_format
+[
+.I DEFS-FILE
+]
+.SH DESCRIPTION
+.B xentrace_format
+parses trace data from standard input and reformats it according to
+the rules in a file of definitions (\fIDEFS-FILE\fP), printing to
+standard output.
+
+The rules in \fIDEFS-FILE\fP should have the format shown below:
+
+\fIevent_id\fP \fIwhitespace\fP \fIformat\fP
+
+Each rule should start on a new line.
+
+The format string may include the following format specifiers:
+%(cpu)s, %(tsc), %(event)s, %(1)s, %(2)s, %(3)s, %(4)s, %(5)s
+
+These correspond to the CPU number, event ID, timestamp counter and
+the 5 data fields from the trace record.  There should be one such
+rule for each type of event to be pretty-printed (events which do not
+have formatting rules are ignored).
+          
+Depending on your system and the rate at which trace data is produced,
+this script may not be able to keep up with the output of
+\fBxentrace\fP if it is piped directly.  In these circumstances you
+should have \fBxentrace\fP output to a file for processing off-line.
+
+.SH AUTHOR
+Mark A. Williamson <mark.a.williamson@intel.com>
+
+.SH "SEE ALSO"
+xentrace(8), xentrace_cpusplit(1)