README for the Branch Tracer for Linux (btrax)

This file contains the following sections:

I.   Introduction
II.  Installation
III. How to use
IV.  License


I. Introduction
===============

This program traces the branch executions of the target program, analyzes the
trace log file, and displays coverage information and execution path.
It's possible to trace it for the application program, the library, the kernel
module, and the kernel.

This program can be operated also by the HT(Hyper Threading) or the SMP
configured kernel, but couldn't operate by the preempt kernel.

Btrax requires below.
  * last branch recording mechanism of Pentium4 or Xeon Processor
  * kernel source code and non-compressed kernel (vmlinux)
  * kernel support for proc file system
  * kernel support for kallsyms
  * kernel support for apic
  * binutils

Btrax is checked on the following system.
  * RedHat Enterprise Linux 4 Update 1
  * RedHat Enterprise Linux 4 Update 3

This program uses the "djprobe" to catch the context switch, and to know
passing over an arbitrary address, etc.
Refer to the following URL for more detail about the djprobe.
(Note that there is a limitation on the probe address for the djprobe.)
   http://lkst.sourceforge.net/djprobe.html


II. Installation
================

1. Preparing kernel source code etc.

  a. Change to super-user

     $ su
     (input super-user password here)

  b. Install the kernel devel and debuginfo package from CD-ROM etc.

     # rpm -i kernel-devel-2.6.9-11.EL.i686.rpm
     # rpm -i kernel-debuginfo-2.6.9-11.EL.i686.rpm

  c. Install the binutils package if it's not installed.

    (confirm whether the binutils package has installed
     # rpm -qa|grep binutils)
     # rpm -i binutils-2.15.92.0.2-13.i386.rpm

2. Download btarx-XXX.tar.bz2 from the project page.

3. Extract and build the command

  $ cd $(WHERE_YOUR_WORK_DIRECTORY)
  $ tar jxvf btrax-XXX.tar.bz2
  $ cd btrax-XXX
  $ make

4. Install the command

  $ su (input super-user password here) 
  # make install

  If you don't want to install to the paths have /usr/local prefix, then do
  next command.

  # make install PREFIX=/other/prefix


III. How to Use
===============

1-a. Trace the application program or the library

  1) Execute the target program (e.g. top) and get pid

     # top &
     # ps -u root|grep top

  2) Start branch trace

     # bt_collect_log -p $(TOP_PID) -d $(ODIR)

  3) Stop branch trace

     # (input Ctrl-C key)

1-a'. Trace the application program with trace start/stop function

     If you need to trace the specified function(s), or to trace the program
     from the start, you need to use the trace start/stop function.
     It trace from the start function to the stop function repeatedly.

  1) Add the trace start/stop function to source code. For example:

        #include <stdio.h>
        #include <stdlib.h>
        #include "btrax/bt_for_ap.h" // add this include line.

        void main(void)
        {
                bt_start_from_ap();  // add trace start function.
                printf("hoge\n");
                bt_stop_from_ap();   // add trace stop function. (option)
        }

  2) Compile the source code. Remove the optimization option to prevent the
     source line number displayed when the log is analyzed from shifting.

  3) Start branch trace

     # bt_collect_log -d $(ODIR) -c $(compiled_executable)

  4) Stop branch trace

     # (input Ctrl-C key)

1-b. Trace the kernel module or the kernel

  1) Start branch trace

     First of all, it is necessary to decide for the trace to begins when
     which symbol is passed or which to trace until passing.

     !!CAUTION!!
     Trace start/stop point has the limitation by djprobe.
     Refer to the following URL for more detail about the djprobe.
         http://lkst.sourceforge.net/djprobe.html

     Then, do the following command.

     # bt_collect_log --start $(START_SYMBOL) -d $(ODIR)
     or
     # bt_collect_log --stop $(STOP_SYMBOL) -d $(ODIR)

     The trace ends automatically if the trace buffer is filled or the stop
     symbol is passed.
     When not automatically ending, you need to confirm the start/stop
     execution and input the Ctrl-C key.

     # (from other shell, check the start/stop execution)
     other-shell# cat /proc/btrax/cpu*/on_off_cnt
     # (input Ctrl-C key)

     If you'd like to trace the specified function repeatedly, do the
     following command.

     # bt_collect_log --start $(FUNC_START) --stop $(FUNC_END) -d $(ODIR)
     # (from other shell, check the start/stop execution)
     other-shell# cat /proc/btrax/cpu*/on_off_cnt
     # (input Ctrl-C key)

2. Split the trace log by each pid

  The trace log is saved in the file(s) of the name of cpuN (N is cpu number).
  If you'd like to analyze the trace log as each process's log, you need to
  divide the trace log.

  # bt_split -d $(ODIR)

3. Display the coverage information

  # bt_coverage --usr -f $(ODIR)/$(TOP_PID)
  or
  # bt_coverage --usr -f $(ODIR)/cpuN

4. Display the execution path

  # bt_execpath --usr -f $(ODIR)/$(TOP_PID)
  or
  # bt_execpath --usr -f $(ODIR)/cpuN

5. More analyze...

  You can get coverage output as html files, and check the executed source
  code and not executed code from the Web-browser.

  # bt_coverage --usr -f $(ODIR)/$(TOP_PID) -o $(HTML_OUT_DIR)
  # (mozilla etc.) $(HTML_OUT_DIR)/top.html

  You can also check the summary of execute path with -s option.

  # bt_execpath -s --usr -f $(ODIR)/$(TOP_PID)


IV. License
===========

COPYRIGHT (C) HITACHI,LTD. 2005-2006

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.



===
Yumiko Sugita <sugita@sdl.hitachi.co.jp> and
Satoshi Fujiwara <sa-fuji@sdl.hitachi.co.jp>
