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.

In this program, there are the following two trace modes.
  1. Application mode
     It catches context switching and traces only target process(es).
     This mode is used for tracing the application program or the library.
     In this mode, trace capacity is limited by the capacity of hard disk.
  2. Kernel mode
     It traces all branch executions including kernel.
     This mode is used for tracing the kernel module or the kernel.
     In this mode, trace capacity is limited by the capacity of the relayfs
     buffer.

This program can be operated also by the HT(Hyper Threading) or the SMP
configured kernel, but coudln'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
  * binutils

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

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
================

This version of the btrax wouldn't install anything to the system at all.
Only it builds the command, and change the PATH environment variable if
necessary.

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


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

1. Load the module

  $ su (input super-user password here) 
  # cd $(WHERE_YOUR_WORK_DIRECTORY)/btrax-XXX
  # ./script/bt_load_module

2-a. Trace the application program or the library (Application mode)

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

     # top &
     # ps aux|grep top

  2) Start branch trace

     # ./script/bt_collect_log.RHEL4U1 -p $(TOP_PID) -d $(ODIR)

  3) Stop branch trace

     # (input Ctrl-C key)

2-b. Trace the kernel module or the kernel (Kernel mode)

  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.
     Then, do the following command.

     # ./script/bt_collect_log.RHEL4U1 --start $(START_SYMBOL) -d $(ODIR)
     or
     # ./script/bt_collect_log.RHEL4U1 --stop $(STOP_SYMBOL) -d $(ODIR)

     The trace ends automatically if the trace buffer is filled or the stop
     symbol is passed.

3. Split the trace log by each pid (Application mode only)

  The trace log is saved in the file(s) of the name of cpuN (N is cpu number).
  It is necessary to divide into the log of each process beforehand for an
  analyze step when tracing it in the application mode.

  # ./application/bt_split/bt_split -d $(ODIR)

4. Display the coverage information

  # ./application/bt_coverage/bt_coverage -a 0:0xbfffffff -f $(ODIR)/$(TOP_PID)
  or
  # ./application/bt_coverage/bt_coverage -a 0xc0000000:0xffffffff -f $(ODIR)/cpuN

5. Display the execution path

  # ./application/bt_execpath/bt_execpath -a 0:0xbfffffff -f $(ODIR)/$(TOP_PID)
  or
  # ./application/bt_coverage/bt_execpath -a 0xc0000000:0xffffffff -f $(ODIR)/cpuN


IV. Lincense
============

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>
