File itrace-add-doc.patch of Package itrace

---
 doc/ITrace_Off.3       |    1 
 doc/ITrace_On_CurPID.3 |   47 ++++++++++++++++++++
 doc/ITrace_On_GTPID.3  |    1 
 doc/it_setup.1         |   43 ++++++++++++++++++
 doc/it_teardown.1      |   35 +++++++++++++++
 doc/itracepids.1       |   42 ++++++++++++++++++
 doc/pi_load.sh.8       |   24 ++++++++++
 doc/pi_unload.sh.8     |    1 
 doc/post.1             |   62 ++++++++++++++++++++++++++
 doc/swtrace.1          |  114 +++++++++++++++++++++++++++++++++++++++++++++++++
 10 files changed, 370 insertions(+)

--- /dev/null
+++ b/doc/ITrace_Off.3
@@ -0,0 +1 @@
+.so man3/ITrace_On_CurPID.3
--- /dev/null
+++ b/doc/ITrace_On_CurPID.3
@@ -0,0 +1,47 @@
+.\" Process this file with:
+.\" groff -man -Tascii ITrace_On_CurPID.3
+.\"
+.TH ITRACE_ON_CURPID 1 "Fri 18 February 2005"
+.SH NAME
+ITrace_On_CurPID \- Start collecting trace data
+.br
+ITrace_Off \- Stop collecting trace data
+.SH SYNOPSIS
+.B #include <perfutil.h>
+.PP
+.B int ITrace_On_CurPID(void);
+.br
+.B int ITrace_On_GTPID(unsigned long pid);
+.br
+.B int ITrace_Off(void);
+.SH DESCRIPTION
+.B ITrace_On_CurPID
+is used to start collecting trace data for the current running process.  That
+process and all of its children are traced.
+.PP
+.B ITrace_On_GTPID
+is used for collecting branch mode trace data on multiple
+processes simultaneously.  The
+.I pid
+parameter is the starting process ID; all processes equal to and greater than
+the starting process ID are traced.
+.I NOTE:
+Use this function with care.  Variables, such as the level of activity on your system,
+may result in an apparent system hang when a large number of processes are traced.
+.PP
+.B ITrace_Off
+is used to stop collecting trace data for all processes.
+.SH "RETURN VALUE"
+On success, zero is returned.  If -1 returned, the ioctl call to the driver
+failed; see the
+.B errno
+variable for more information.  If the call fails because the kernel module
+cannot be opened, these calls will return the value
+.B PITRACE_ERROR.
+.SH "SEE ALSO"
+.BR pi_load.sh(8),
+.BR pi_unload.sh(8),
+.BR it_setup(1),
+.BR it_teardown(1),
+.BR post(1),
+.BR swtrace(1)
--- /dev/null
+++ b/doc/ITrace_On_GTPID.3
@@ -0,0 +1 @@
+.so man3/ITrace_On_CurPID.3
--- /dev/null
+++ b/doc/it_setup.1
@@ -0,0 +1,43 @@
+.\" Process this file with:
+.\" groff -man -Tascii it_setup.1
+.\"
+.TH IT_SETUP 1 "Fri 18 February 2005"
+.SH NAME
+it_setup \- Set up machine for ITrace
+.SH SYNOPSIS
+.B it_setup
+[
+.I options
+]
+.SH DESCRIPTION
+.B it_setup
+sets up the machine for the collection of ITrace data.
+.SH OPTIONS
+.TP
+.B --help / -?
+Show help message.
+.TP
+.B --verbose / -v
+Write verbose output to stdout.
+.TP
+.B --step-trace
+Prepare machine to run trace in single step mode.  (This is the default trace
+mode.)  This will allow you to gather more data in your trace, such as the
+targe adresses for loads and stores.
+.TP
+.B --branch-trace
+Prepare machine to run trace in branch mode.  In this type of trace, data is
+only collected on branch instructions.
+.TP
+.B --buffer-size=num
+Set the size of each trace buffer in MB.  ITrace allocates a separate buffer for
+each processor.  The default buffer size is 50MB.
+.SH "SEE ALSO"
+.BR pi_load.sh(8),
+.BR pi_unload.sh(8),
+.BR it_teardown(1),
+.BR post(1),
+.BR swtrace(1),
+.BR ITrace_On_CurPID(3),
+.BR ITrace_On_GTPID(3),
+.BR ITrace_Off(3)
--- /dev/null
+++ b/doc/it_teardown.1
@@ -0,0 +1,35 @@
+.\" Process this file with:
+.\" groff -man -Tascii it_teardown.1
+.\"
+.TH IT_TEARDOWN 1 "Fri 18 February 2005"
+.SH NAME
+it_teardown \- Complete trace collecting and output trace data
+.SH SYNOPSIS
+.B it_teardown
+[
+.I options
+]
+.SH DESCRIPTION
+.B it_teardown
+halts the ITrace data collection and generates a file in the current directory
+that contains the collected trace data in nrm2 format.  See post(1) for
+information about how you can process this file.
+.SH OPTIONS
+.TP
+.B --help / -?
+Show help message.
+.TP
+.B --verbose / -v
+Write verbose output to stdout.
+.TP
+.B --trace-output=file
+Set the name of the output file for the collected trace data.
+.SH "SEE ALSO"
+.BR pi_load.sh(8),
+.BR pi_unload.sh(8),
+.BR it_setup(1),
+.BR post(1),
+.BR swtrace(1),
+.BR ITrace_On_CurPID(3),
+.BR ITrace_On_GTPID(3),
+.BR ITrace_Off(3)
--- /dev/null
+++ b/doc/itracepids.1
@@ -0,0 +1,42 @@
+.\" Process this file with:
+.\" groff -man -Tascii post.1
+.\"
+.TH ITRACEPIDS 1 "Fri 18 February 2005"
+.SH NAME
+itracepids \- ITrace tracing for a list of process IDs
+.SH SYNOPSIS
+.B itracepids
+[
+.I options
+]
+.SH DESCRIPTION
+.B itracepids
+is used to start tracing on one or more processes.  Prior to invoking
+.B itracepids
+, you must run the other normal ITrace setup commands; that is, either run the
+.B it_setup
+script or run the individual ITrace commands invoked by that script.
+.PP
+After starting the application you wish to trace, start
+.B itracepids
+and pass in the process ID(s) you wish to trace, and press Enter to
+begin tracing.  Press Enter again to stop tracing.  You must then
+run the normal ITrace shutdown commands; that is, either run the
+.B it_teardown
+script or run the individual ITrace commands invoked by that script.
+.SH OPTIONS
+.TP
+.B no options
+Show help message.
+.TP
+.B pid <pid [...]>
+One or more process IDs (separated by spaces) that you wish to trace.
+.SH "SEE ALSO"
+.BR pi_load.sh(8),
+.BR pi_unload.sh(8),
+.BR it_setup(1),
+.BR it_teardown(1),
+.BR swtrace(1),
+.BR ITrace_On_CurPID(3),
+.BR ITrace_On_GTPID(3),
+.BR ITrace_Off(3)
--- /dev/null
+++ b/doc/pi_load.sh.8
@@ -0,0 +1,24 @@
+.\" Process this file with:
+.\" groff -man -Tascii pi_load.sh.8
+.\"
+.TH pi_load.sh 8 "Fri 18 February 2005"
+.SH NAME
+pi_load.sh \- Prepare machine for running ITrace
+pi_unload.sh \- Clean machine up after running ITrace
+.SH SYNOPSIS
+.B pi_load
+.br
+.B pi_unload
+.SH DESCRIPTION
+.B pi_load
+loads the ITrace kernel module and creates the necessary /dev files for ITrace.
+.B pi_unload
+will reverse this.
+.SH "SEE ALSO"
+.BR it_setup(1),
+.BR it_teardown(1),
+.BR post(1),
+.BR swtrace(1),
+.BR ITrace_On_CurPID(3),
+.BR ITrace_On_GTPID(3),
+.BR ITrace_Off(3)
--- /dev/null
+++ b/doc/pi_unload.sh.8
@@ -0,0 +1 @@
+.so man8/pi_load.sh.3
--- /dev/null
+++ b/doc/post.1
@@ -0,0 +1,62 @@
+.\" Process this file with:
+.\" groff -man -Tascii post.1
+.\"
+.TH POST 1 "Fri 18 February 2005"
+.SH NAME
+post \- ITrace post processor
+.SH SYNOPSIS
+.B post
+[
+.I options
+]
+.SH DESCRIPTION
+.B post
+is used to reduce and process ITrace data gathered by the
+.B swtrace
+trace mechanism.
+.SH OPTIONS
+.TP
+.B -?
+Show help message.
+.TP
+.B -r nrm2
+Input nrm2 file.  (Uses swtrace.nrm2 by default.)
+.TP
+.B -show
+Generate ascii dump of nrm2 data into post.show file.
+.TP
+.B -nv
+Don't validate kernel symbols.  Use this option to reduce a trace taken with a
+kernel other than the currently running one. In this case you may also need to
+use the -k option to point to the correct non-stripped kernel.
+.TP
+.B -k kpath
+This option gives the path to a non-stripped Linux kernel to use as the source
+of kernel symbols.
+.TP
+.B -arc
+Generate arc file, which contains the subroutine flow.
+.TP
+.B -qt
+Generate qtrace output file.
+.TP
+.B -ss
+Show individual instructions.
+.TP
+.B -ssi
+Show individual instructions with opcodes.
+.SH "TODO"
+.B post
+has other options that are not covered here yet.  These should be covered in
+this man page.  Run
+.I post -?
+for more info.
+.SH "SEE ALSO"
+.BR pi_load.sh(8),
+.BR pi_unload.sh(8),
+.BR it_setup(1),
+.BR it_teardown(1),
+.BR swtrace(1),
+.BR ITrace_On_CurPID(3),
+.BR ITrace_On_GTPID(3),
+.BR ITrace_Off(3)
--- /dev/null
+++ b/doc/swtrace.1
@@ -0,0 +1,114 @@
+.\" Process this file with:
+.\" groff -man -Tascii swtrace.1
+.\"
+.TH SWTRACE 1 "Fri 18 February 2005"
+.SH NAME
+swtrace \- Low level ITrace control
+.SH SYNOPSIS
+.B swtrace
+.I command
+[
+.I options
+]
+.SH DESCRIPTION
+.B swtrace
+is a software tracing mechanism.
+.B swtrace
+is normally run from a command prompt by issuing the
+.B swtrace
+command with the appropriate arguments.
+.PP
+.B swtrace
+uses software trace hooks to collect data. Trace hooks are identified by both a
+major code and a minor code. Trace data is collected to a trace buffer that is
+allocated when
+.B swtrace
+is initialized or when
+.B swtrace
+is turned on. The size of the trace buffer can be set when
+.B swtrace
+is initialized. The
+.B swtrace
+command allows the user to select which major codes are traced, when tracing
+starts, when tracing stops, when data is transferred from the trace buffer to
+disk and formatting of the trace data.
+.SH COMMANDS
+.TP
+.B init [ -s buffsize ]
+Initializes/reinitializes
+.B swtrace.
+This command causes the buffers to be allocated if necessary, but does not turn
+tracing on. The default buffer size per processor is 3 MB, which can be changed
+using the
+.I -s
+option. Note that if buffers exist at the time of this command, no new buffers
+will be allocated.
+.TP
+.B free
+Frees
+.B swtrace
+buffer(s). If
+.B swtrace
+is on, this command turns tracing off.  Whether
+.B swtrace
+was on or off, any allocated trace buffers will be freed and the contents
+discarded.
+.TP
+.B enable [ n1 n2 n3 ... ]
+Enables tracing for the specified major codes. Major codes can be specified in
+decimal (##) or hexadecimal (0x##). If no major codes are specified, tracing
+for all major codes is enabled. Actual data collection is controlled by the
+.B on
+and
+.B off
+arguments.
+.TP
+.B disable [ n1 n2 n3 ... ]
+Disables tracing for the specified major codes. Major codes can be specified in
+decimal (##) or hexadecimal (0x##). If no major codes are specified, tracing
+for all major codes is disabled. Actual data collection is controlled by the
+.B on
+and
+.B off
+arguments.
+.TP
+.B on
+Turns
+.B swtrace
+on. If
+.B swtrace
+is currently on, this command has no effect. The
+.B swtrace
+facility must have been previously initialzed via the
+.B init
+command.
+.TP
+.B off
+Turns
+.B swtrace
+off. If
+.B swtrace
+is on, this command turns tracing off. The buffers are not freed. If
+.B swtrace
+is currently off, this command has no effect.
+.TP
+.B get filename
+Returns a copy of the trace buffers. This command returns all trace data to the
+user in a binary file, in the current directory, called
+.IB swtrace.nrm2.
+If a different filename is specified then that filename is used. This command
+does not alter the state of tracing.
+.SH "TODO"
+.B swtrace --help
+provides more detail that is not covered here yet.  These should be covered in
+this man page.
+.SH "SEE ALSO"
+.BR pi_load.sh(8),
+.BR pi_unload.sh(8),
+.BR it_setup(1),
+.BR it_teardown(1),
+.BR itracepids(1),
+.BR post(1),
+.BR ITrace_On_CurPID(3),
+.BR ITrace_On_GTPID(3),
+.BR ITrace_Off(3)