Cockroach is a probe utility that installs probes (pre-defined or/and
user-defined functions) at the specified addresses of the target
program according to a configuration file called a recipe file.

<Applications>
* A debugger that shows registers and values in memory at the
specified program address.
* A profiler to measure execution time and call frequency.
* A function-replace tool without the modification of the program.

<Features>
* No need to recompile a target program with certain options or libraries.
* Low overhead to call probes by using a jump instruction, not
  processor exceptions such as a trap instruction.
* Low overhead data recording framework using a shared memory.
* Can install user defined probes.
* Can install a probe at an arbitray address of the code.
* Can install probes both at the top of and the end of the function.
* Can skip an execution of the target function after the probe is executed.
  This enables users to replace a function into the user's prepared function.
* Built-in time measurement probe measures the execution time of a function.
  With the feature, cockroach can be used as a profiler.

<Currently supported platforms>
* x86_64(amd64)
* i386

==============================
How to build
==============================
* Depending libraries
If you run tests, the following libraries should be installed.
- cutter  (C/C++ unit test framework)
- glib
- boost headers
- boost thread library

$ ./autogen.sh
$ ./configure
$ make
$ sudo make install

==============================
How to run
==============================
$ cockroach recipe_file target_progam args

Actually, the above 'cockroach' is a shell script and runs the following
command internally.

$ LD_PRELOAD=cockroach.so COCKROACH_RECIPE=<path>/recipe_file target_program args

The body of the cockroach is a shared library loaded into the target program
by LD_PRELOAD environment variable. The recipe file is also specified by
the COCKROACH_RECIPE environment variable.

==============================
Format of recipe file
==============================
* comment line
# A comment line begins from '#'

* target limitation
TARGET_EXE <exe_path>

<exe_path> can be a file name or an absolute path. If this parameter is
omitted, cockroach installs probes to the programs in which it is loaded.
This option is useful when the target is spawned by other program. In such
case, LD_PRELOAD should be added in the command line to run the parent
program and cockroach is loaded in the parent program. If you want to avoid
cockroach from installing probes in the parent, you can use
'TARGET_EXE target_program' line in the recipe.

Note: This line must be written above probe definitions.

* probe definition
probe_type install_type lib_name symbol|offset(hex) [save_instruction_size(decimal)]

[probe_type]
T  : Built-in time measurement probe. It measures time from the probe point
     to the end of the function.
TSC: Built-in TSC (Time Stamp Counter) recorder probe. (Not implemented)
P  : User probe.

[install_type]
REL32  : overwrite relative 32bit jump [overwrite 5B at the target address]
ABS64  : overwrite absolute 64bit jump [overwrite 13B at the target address]
CJADDR : replace call or jump address in the code (Not implemented)
GOT    : replace the address in GOT (Global Offset Table) (Not implemented)

[offset]
The address of the function in the library, which can be gotten by
'nm' command and so on.

Ex.) When you install a probe to random(),
$ nm -D /lib/x86_64-linux-gnu/libc-2.15.so | grep \ random$
000000000003c0d0 W random

[save_instruction_size]
If this parameter is given, the specified bytes from the target address are
backed up to anothre memory region and executed after the probe is called.
Of course, this size must equal to or be larger than the overwrite size
(5B for REL32, 13B for ABS64) and be a boundary of instructions.

Ex.) When you probe random() whose assembly code is the following,
      you should specifiy 9 and 18 for REL32 and ABS64 respectively.

$ objdump -d /lib/x86_64-linux-gnu/libc-2.15.so | grep -A5 "<random>:"
000000000003c0d0 <random>:
   3c0d0:       48 83 ec 18             sub    $0x18,%rsp
   3c0d4:       be 01 00 00 00          mov    $0x1,%esi
   3c0d9:       31 c0                   xor    %eax,%eax
   3c0db:       83 3d 12 21 38 00 00    cmpl   $0x0,0x382112(%rip)        # 3be1f4 <argp_program_version_hook+0x1bc>
   3c0e2:       74 10                   je     3c0f4 <random+0x24>

If this parameter is omitted, cockroach calculates the size by perfoming
disassemble the code (some instructions have not been implemented yet).

<<< examples >>>
# This is comment
T REL32 libc.so 0000000000053840
T ABS64 libc.so memset                     (Symbol is not implemented)
P REL32 libc.so printf myprobe.so my_probe