README for the Branch Tracer for Linux (btrax)

This file contains the following sections:

I.   Introduction
II.  Installation
III. How to use
IV.  How to use (checking a system call coverage)
V.   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 by the HT(Hyper Threading) or the SMP configured
kernel.
It also can be operated by the Full-Preempt kernel if you use the 2.6.18 kernel.

Btrax requires below.
  * last branch recording mechanism of Pentium4, Xeon Processor or Pentium-M
  * kernel source code and non-compressed kernel (vmlinux)
  * kernel support for proc file system
  * kernel support for kallsyms
  * kernel support for apic
  * kernel support for relayfs and kprobes (only 2.6.18 kernel)
  * binutils (2.17 or later is needed for 2.6.18 kernel)

Btrax is checked on the following system.
  * RedHat Enterprise Linux 4 Update 1
  * RedHat Enterprise Linux 4 Update 1 with upstream kernel 2.6.18
  * RedHat Enterprise Linux 4 Update 3
  * Miracle Linux 4.0 SP1

If you use the 2.6.9 kernel, 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
================

Note that if you would like to use btrax on the different kernels, you need to
install for each kernel, because btrax contains the kernel modules.

1. Preparing kernel source code etc.

  a. Change to super-user

     $ su
     (input super-user password here)

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

     # rpm -i kernel-2.6.9-11.EL.src.rpm
     # rpmbuild -bp --target i686 /usr/src/redhat/SPECS/kernel-2.6.spec
     # 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

5. Create relayfs mount point

  # mkdir /mnt/relay


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!!
     If you use the 2.6.9 kernel, 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) -S $(SRC_DIR)
  # (mozilla etc.) file://$(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. How to Use (checking a system call coverage)
================================================

1. Create the program with system call

2. Start branch trace

     # bt_collect_log --syscall $(syscall_name) -d $(ODIR) -c $(program)

     Note that $(syscall_name) must be defined in kernel's 'sys_call_table'
     (e.g. sys_gettimeofday, old_mmap, etc).

3. Checking coverage

     To checking the system call coverage summary, do the next command.

     # cd $(ODIR)
     # bt_coverage --ker -f `echo $(ls cpu*)|sed 's/\s\+/,/g'`
         -I $(syscall_name) -s

     To checking the system call coverage detail, do the next command.

     # bt_coverage --ker -f `echo $(ls cpu*)|sed 's/\s\+/,/g'`
         -I $(syscall_name)

     If you want to exclude the function(s) from coverage result, use the -E
     option.

     # bt_coverage --ker -f `echo $(ls cpu*)|sed 's/\s\+/,/g'`
         -I $(syscall_name) -E schedule,printk

     To checking whether the codes in that system call was executed or not,
     do the next.

     # bt_coverage --ker -f `echo $(ls cpu*)|sed 's/\s\+/,/g'`
         -I $(syscall_name) -E schedule,printk
	 -o $(HTML_OUT_DIR) -S $(KERN_SRC_DIR)
     # (mozilla etc.) file://$(HTML_OUT_DIR)/top.html

     Note that html files are using the Javascript. If you have some trouble
     browsing, check the Javascript setting.


V. License
==========

COPYRIGHT (C) HITACHI,LTD. 2005-2007

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>
