Overview

JPROF, our Java Profiler, captures entry and exit events from method calls and uses these events to trigger the recording of various profiling statistics. Hookit is an attempt at extending the JPROF profiler so that the same can be done for compiled programs and libraries written in C. The end goal is to be able to gather callflow information from standalone C applications, Java native method calls, and calls to system libraries.

HookIt provides an implementation for the Microsoft Visual C++ _penter() and _pexit() instrumentation functions.

_penter(), if enabled via the /Gh compiler switch, is called on every function entry before the prologue code is executed. _pexit(), if enabled via the /GH compiler switch, is called on every exit (return) from a function, after the epilogue code is executed but before the return. The _penter/_pexit() implementation is provided in hookit.lib, which contains hookit.obj, and is used at link time to resolve _penter/_pexit().

HookIt calls into JProf on every function entry/exit.

Control Flow

Loader
  |
  +----> main(argc, argv)
            call _penter ---->  if (first_time) {initialize};
                         <---+  send event to jprof;
                             +-------
            push ebp
            mov ebp, esp
               *
               *
               *
            push arg2
            push arg1
            call function(arg1, arg2) ---+
                                         |
                                         +->  function()
                    <--------+                  call _penter --->  send event to jprof;
            add esp, 8       |                               <----------
               *             |                  push ebp
               *             |                  mov ebp,esp
               *             |                     *
               *             |                     *
               *             |                     *
               *             |                  call _pexit  --->  send event to jprof;
               *             |                               <----------
               *             +----------------- ret
               *
               *
             call _pexit ---->  send event to profiler
                         <----------
  <--------  ret
  add esp, 8
  process termination
  blah
  blah
   

Building your application

• Requires MS Visual C++ version 7 or above (Visual Studio .NET 2003 or above) If you don't have it then all you'll be able to get are entry hooks. Not sure what compiler you have? Enter "cl /?" and scroll thru the output. If you see the "/GH" option then you're OK.
   
• To build the application:
  1. Modify makefile(s) to add the following COMPILER flags:

     /Gh

     Causes a call to the _penter function at the start of every method or function.

     /GH

     Causes a call to the _pexit function at the end of every method or function.

     The following flags are optional:

     /Zi

     Enable debugging information.

     /Od

     Disable optimizations - inlining, etc.

     
     
  2. Modify makefile(s) to add the following LINKER flags:
     /DEBUG /PDB:whatever_filename.pdb
     
     
  3. Add hookit.lib to the list of .libs to link.
  
  
• Be careful when building instrumented dlls where you provide a Dllmain() function. HookIt may have problems with that. Chicken-and-egg kind of thing.

  Only one command needed to build a simple, instrumented application. For larger applications you will have to modify your makefile accordingly. The application is comprised of a C source file named foo.c. hookit.lib is located in the C:\ibmperf\lib directory.

  cl -GH -Gh -Zi foo.c C:\ibmperf\lib\hookit.lib -link -debug -pdb:foo.pdb

  The command compiles and links foo.exe and produces debug symbols in foo.pdb. The symbols are required if you want to see function names in the JProf reports.

Usage

Before running the application, the desired options need to be set in the JPROFOPTS environment variable. These are the normal JProf options with the exception that the ehi (enable hookit) option must be present for Hookit events to work. The JProf library (jprof.dll) and the A2N library (a2n.dll) must be either in the same directory as the application, or reacheable via the PATH environment variable.

Assuming jprof.dll and a2n.dll reside in directory C:\ibmperf\bin, the commands required are:

• Add the C:\ibmperf\bin directory to the PATH:
           set PATH=%PATH%;C:\ibmperf\bin
• Add required JProf options to JPROFOPTS:
           set JPROFOPTS=generic,ehi
• Run the application:
           foo

After setting the PATH and JPROFOPTS just run your application (.exe).

Miscellaneous Notes

Hookit is currently unable to parse command line arguments passed to the application being profiled. However, all the normal command line arguments may be passed to Hookit via the JPROFOPTS environment variable. The rtdriver interface should be fully functional as well. In the event that Hookit does not support a given option, it is simply ignored. When attempting to profile native code, the options passed through the JVM should be observed by Hookit as well.

Hookit can be configured to use other profiler libraries (besides JProf) by setting the HOOKIT_PROFILER environment variable. Similarly the HOOKIT_DEBUG environment variable may be used to display debug output from Hookit. In some cases the HOOKIT_PROFILING variable may be used to enable or disable profiling. However this is often overridden by the profiler itself.