README for the Branch Tracer for Linux (btrax)

This file contains the following sections:

I.   Introduction
II.  Installation
III. How to use - checking an application program coverage
IV.  How to use - checking kernel coverage
V.   How to use - checking a system call coverage
VI.  License


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

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

This program can be used on the HT(Hyper Threading) or the SMP configured
kernel.
It also can be used on the Full-Preempt kernel if your kernel supports
'kprobes'.

Btrax requires below.
  * last branch recording mechanism on the Pentium4, Xeon, Core and Pentium-M
    processors
  * kernel source code and non-compressed kernel (vmlinux)
  * kernel supports which described below
    - proc file system (CONFIG_PROC_FS)
    - kallsyms (CONFIG_PROC_FS)
    - apic (CONFIG_X86_LOCAL_APIC, CONFIG_X86_IO_APIC)
    - relayfs and kprobes (CONFIG_DEBUG_FS, CONFIG_RELAY, CONFIG_KPROBES)
      are needed for linux 2.6.18 or later
  * binutils (2.17 or later is needed for linux 2.6.18 or later)
  * elfutils

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
  * RedHat Enterprise Linux 5 Update 0
  * RedHat Enterprise Linux 5 Update 0 with upstream kernel 2.6.21

If your kernel does not support 'kprobes', 'btrax' uses the 'djprobe' instead
to catch the context switch, and user specified address.
Note that there is a limitation on the probe address by the 'djprobe'.
Refer to the following URL for more detail about the 'djprobe'.
   http://lkst.sourceforge.net/djprobe.html

Note that btrax using TSC (Time Stamp Counter) as time-stamp for the log file.
If you use btrax on the note-book PCs, the CPU frequency maybe change and
cause of the wrong coverage.


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

1. Preparing kernel source code etc.

  a. become super-user

     $ su
     (input super-user's 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-smp-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 btrax archive file (btarx-XXX.tar.bz2) from it's project page.
   (http://sourceforge.net/projects/btrax/)

3. Extract the archive file and build

  $ tar jxvf btrax-XXX.tar.bz2
  $ cd btrax-XXX
  $ ./configure
  $ make

4. Install

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

5. Create mount point for the relayfs

  # mkdir /mnt/relay

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


III. How to Use - checking an application program coverage
==========================================================

1-a. Trace a application program (or the library)

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

     # top &
     # ps -u root | grep top

  2) Start trace

     # bt_collect_log -p $(pid) -d $(log_dir)

  3) Stop trace

     press Ctrl-C key

1-b. Trace the application program with trace start/stop macro

     If you would like to trace the specified function(s), or to trace the
     program from the beginning (this means 'from "main" function'), you need
     to add the trace start/stop macro to target application's source code and
     re-compile it.
     'btrax' traces from the start macro to the stop macro repeatedly.

  1) Add the trace start/stop macro 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 macro.
                printf("hoge\n");
                bt_stop_from_ap();   // add trace stop macro. (optional)
        }

  2) Re-compile the source code. Note that you should remove the compiler's
     optimization option.

  3) Start trace

     # bt_collect_log -d $(log_dir) -c $(target_application)

  4) Stop trace

     press Ctrl-C key

2. Convert traced log

  The traced log(s) is saved by each processor which name is 'cpuN' (N is cpu
  number). If you'd like to analyze the application's traced log, you need to
  convert traced log as process's log.

  # cd $(log_dir)
  # bt_split -d .

3. Display the coverage information

  # bt_coverage --usr -f $(pid)

4. Display the execution path

  # bt_execpath --usr -f $(pid)

5. More analyze...

  You can get coverage output as html files. In the html files, each line of
  the source codes is colored by it's execution status.

  # bt_coverage --usr -f $(pid) -o $(html_out_dir) -S $(src_dir)
  # (mozilla etc.) file://$(html_out_dir)/top.html

  You can also check the summary of the execution path by '-s' option.

  # bt_execpath --usr -f $(pid) -s


IV. How to Use - checking kernel coverage
=========================================

1. Trace the kernel (or the kernel module)

  For the kernel trace, you can choose one of following three options (or the
  'system call trace' which described in the next section).

  1) From '--start' symbol, to one of the relayfs sub-buffer is filled

     # bt_collect_log --start $(symbol) -d $(log_dir)

     The trace ends automatically if the buffer is filled.

  2) One of the relayfs sub-buffer to '--stop' symbol

     # bt_collect_log --stop $(symbol) -d $(log_dir)

     The trace ends automatically if the stop symbol is passed.

  3) From '--start' symbol to '--stop' symbol (repeatedly)

     # bt_collect_log --start $(symbol) --stop $(symbol) -d $(log_dir)

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

     (press Ctrl-C key)

2. Display the coverage information

  # cd $(log_dir)
  # bt_coverage --ker -f cpu0

  If your system supports 'SMP' or 'HT', then you need to specify the '-f'
  option as follows.

  # bt_coverage --ker -f cpu0,cpu1
                              ^^^^
3. Display the execution path

  # bt_execpath --ker -f cpu0

4. More analyze...

  See the section III.


V. How to Use - checking a system call coverage
===============================================

1. Trace a target application program

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

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

2. Checking coverage

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

  # cd $(log_dir)
  # bt_coverage --ker -f cpu0 -I $(syscall_name)

  By using '-I' option, the coverage result shows you the function tree which
  begin with the '-I' option's function.

  If you'd like to exclude the execution of the specified function(s) from
  coverage result, you can use the '-E' option.

  # bt_coverage --ker -f cpu0 -I $(syscall_name) -E schedule,printk

  To checking the system call coverage by html files, do the next command.

  # bt_coverage --ker -f cpu0 -I $(syscall_name) -E schedule,printk \
      -o $(html_out_dir) -S $(kernel_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.

4. Compare the system call coverage

  To compare the same kernel's system call covergage, do the next command.
  (In this example, each log directory is shown as 'log1' and 'log2'.)

  # bt_coverage --ker -I $(syscall_name) -E schedule,printk \
      -o $(html_out_dir) -S $(kernel_src_dir)               \
      -f log1/cpu0 --f2 log2/cpu0
  # (mozilla etc.) file://$(html_out_dir)/top.html

  If you had traced the system call on differnt kernels, you can also compare
  these logs. To compare the system call coverage of these different
  kernels, do the next command.
  (In this example, each log directory, kernel version, and kernel source
   directory is shown as 'log1' and 'log2', 'uname1' and 'uname2', and
   'src1' and 'src2' respectively.)

  # bt_coverage --ker -I $(syscall_name) -E schedule,dump_stack,printk \
      -o $(HTML_OUT_DIR)                                               \
      -u uname_r1 --u2 uname_r2 -S src1 --S2 src2                      \
      -f log1/cpu0 --f2 log2/cpu0
  # (mozilla etc.) file://$(HTML_OUT_DIR)/top.html


VI. License
===========

COPYRIGHT (C) HITACHI,LTD. 2005-2008

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 <yumiko.sugita.yf@hitachi.com> and
Satoshi Fujiwara <sa-fuji@sdl.hitachi.co.jp>
