Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
openSUSE:Evergreen:11.1:Test
itrace
itrace-add-doc.patch
Overview
Repositories
Revisions
Requests
Users
Attributes
Meta
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)
Locations
Projects
Search
Status Monitor
Help
OpenBuildService.org
Documentation
API Documentation
Code of Conduct
Contact
Support
@OBShq
Terms
openSUSE Build Service is sponsored by
The Open Build Service is an
openSUSE project
.
Sign Up
Log In
Places
Places
All Projects
Status Monitor
