OVERVIEW

ITrace is a software tracing mechanism that runs on Linux.  ITrace traces
through application and kernel code, and can produce human-readable ASCII
output or qtrace output, suitable for analysis by packages such as the IBM
Performance Simulator for Linux on POWER (simppc).

Currently, this package has been tested only on 2.6.5 - 2.6.16 releases  
of the Linux kernel.  Some kernel patches are required for some early
2.6.5-based kernels.  See installation steps for details.


INSTALLATION STEPS

NOTE:  
  -If you are building this package on SLES 9 SP2 or later (including
   (SLES 10 or a kernel release >= 2.6.16) and if CONFIG_KPROBES is set to
   'yes' for your kernel configuration, skip to step 2.  
  -If using a supported SLES/kernel release, but your kernel configuration
   does not have CONFIG_KPROBES set to 'yes', start at the 'make oldconfig'
   part of step 1; then continue throughstep 2.
  -For all other cases, start at the beginning of step 1.

1)  Prepare your kernel:

    First, ensure the kernel sources are available.
    SLES 9 (GA or SP1): Install the kernel-sources RPM.

    # Copy kernel tree
    cp -rp /usr/src/linux-<version> /usr/src/linux-itrace

    # Patch kernel sources (using the sles or rhel patches as appropriate)
    cd /usr/src/linux-itrace
    patch --strip 1 --verbose \
        < <package-dir>/patches/ppc64/sles9_r1_irq_export.patch \
        > sles9_r1_irq_export.patch.output
    patch --strip 1 --verbose \
        < <package-dir>/patches/ppc64/sles9_r1_kernel.patch \
        > sles9_r1_kernel.patch.output
    # Verify that output files contain no errors

    # Configure the kernel 
    make oldconfig

    make menuconfig
        * ensure Kprobes is enabled

    build and install kernel as usual.

2)  cd <package-dir>
    ./tinstall.appl <my_install_dir>
    ./tinstall.drv (as root)

USAGE

To load the pitrace kernel module and create necessary /dev files, run
pi_load.sh (as root).  When you're done collecting traces, you can unload the
kernel module by running pi_unload.sh (as root).

You can use one of two methods to issue trace commands.

Option 1:
(This is the preferred way, but you must recompile your testcase in
order to do this.)
First, identify the portion of your testcase that you want to trace.  At the
start of this section, add a call to ITrace_On_CurPID().  At the end, add a
call to ITrace_Off().  These calls are in the archive libperfutil.a, and
declared in perfutil.h.  Recompile your testcase.

Then run these commands:
it_setup
<run your testcase>
it_teardown --trace-output=trace.nrm2
post -qt -r trace.nrm2

Option 2:
(In case you can't recompile your testcase.)
Run these commands:
it_setup
swtrace itracepids <pid> # start tracing the given pid
<collect trace data>
swtrace off
it_teardown --trace-output=trace.nrm2
post -qt -r trace.nrm2

You will typically want to collect only a few seconds worth of data.  The last
step in each of these options produces the file "output.qt" which you can use
as input to simppc.  Alternatively, you can produce ASCII output of your trace
with the following command:
post -arc -ssi -r trace.nrm2
This will produce a text file named "arc".

For more information about simppc, and to download a copy, visit 
http://alphaworks.ibm.com/tech/simppc.

See the following man pages for more details:
pi_load.sh(8)
pi_unload.sh(8)
it_setup(1)
it_teardown(1)
swtrace(1)
post(1)
ITrace_On_CurPID(3)
ITrace_Off(3)
