Code coverage analysis tools for PIN.

Developed by:

Oleksiuk Dmitry, eSage Lab mailto:[email protected] http://www.esagelab.com/

My article about PIN and this tools: http://d-olex.blogspot.com/2011/03/blog-post.html (in Russian, use Google Translate)

============================================================== ARCHIVE CONTENTS

./Coverager.dll - PIN instrumentation module for code coverage analysis. ./coverage_test.exe - Test application to buid code coverage map for Internet Explorer process. ./coverage_parse.py - Program for parsing the logs, that has been generated by instrumentation module. ./coverage_to_callgraph.py - Program to generates log files in Calltree Profile Format. ./symlib.pyd - PDB symbols library for Python 2.6 (see symlib_test.py for usage details). ./symlib25.pyd - PDB symbols library for Python 2.5 ./EXAMPLES/ - Samples of output logs.

============================================================== BUILDING CODE COVERAGE MAP BY FUNCTIONS AND BASIC BLOCKS

1. Download and install PIN toolkit (http://www.pintool.org).

2. Copy Coverager.dll into the PIN toolkit root directory.

3. Edit execute_pin.bat scenario and put PIN toolkit root directory path into the PINPATH variable.

4. Use execute_pin.bat from command line to run some aaplication and generate code coverage map for it. Example:

   execute_pin.bat "C:\Program Files\Internet Explorer\iexplore.exe"

5. After the target applicaion termination 4 log files will be created (CoverageData.log, CoverageData.log.modules, CoverageData.log.routines and CoverageData.log.blocks).

6. Use coverage_parse.py program to extract information from the generated logs. Example:

   
    C:\> python coverage_parse.py Coverager.log --dump-routines --modules "iexplore, ieframe" --outfile routines.txt
    
    SYMLIB: DLL_PROCESS_ATTACH
    SYMLIB: Symbols path is "C:\Symbols;SRV*C:\Symbols*http://msdl.microsoft.com/download/symbols"
   
    Code Coverage Analysis Tool for PIN
    by Oleksiuk Dmitry, eSage Lab ([email protected])
   
    Filtering by module name "iexplore"
    Filtering by module name "ieframe"
    [+] Output file: "routines.txt"
    [+] Parsing routines list, please wait...
   
    SYMLIB: Module loaded from "c:\Program Files\Internet Explorer\iexplore.exe"
    SYMLIB: 395 symbols loaded for "c:\Program Files\Internet Explorer\iexplore.exe"
    SYMLIB: Module loaded from "C:\Windows\system32\IEFRAME.dll"
    SYMLIB: 33516 symbols loaded for "C:\Windows\system32\IEFRAME.dll"
   
    [+] Processed modules list:
   
    #
    # Routines count -- Module Name
    #
               3576 -- flash10n.ocx
                 47 -- jp2ssv.dll
                195 -- wdmaud.drv
                 15 -- rasadhlp.dll
                208 -- msls31.dll
   
                ... skipped ...
   
    [+] DONE
   
    SYMLIB: DLL_PROCESS_DETACH
    
   

Sample log file from the coverage_parse.py can be found in ./EXAMPLES/IEXPLORE_Routines.txt For detailed information about coverage_parse.py usage see comments in the Python source.

============================================================== BUILDING AND EXPLORING CALL TREE MAP

1. To enable call tree logging execute your target applicaion with execute_pin_calls.bat scenario:

   execute_pin_calls.bat "C:\Program Files\Internet Explorer\iexplore.exe"

2. After the target applicaion termination in addidition to CoverageData.log, CoverageData.log.modules, CoverageData.log.routines and CoverageData.log.blocks also will be created a few files with the names like CoverageData.log., where - thread number.

3. Use coverage_to_callgraph.py scenario to converting CoverageData.log. files into the Calltree Profile Format (that uses in Valgrind):

   
    C:\> python coverage_to_callgraph.py CoverageData.log *
    SYMLIB: DLL_PROCESS_ATTACH
    SYMLIB: Symbols path is "C:\Symbols;SRV*C:\Symbols*http://msdl.microsoft.com/download/symbols"
   
    Code Coverage Analysis Tool for PIN
    by Oleksiuk Dmitry, eSage Lab ([email protected])
   
    [!] Psyco is not available
    [+] Input file(s): CoverageData.log.0, CoverageData.log.1, CoverageData.log.10, CoverageData.lo
    g.11, CoverageData.log.12, CoverageData.log.13, CoverageData.log.14, CoverageData.log.15, Cover
    ageData.log.16, CoverageData.log.17, CoverageData.log.18, CoverageData.log.19, CoverageData.log
    .2, CoverageData.log.20, CoverageData.log.21, CoverageData.log.22, CoverageData.log.3, Coverage
    Data.log.4, CoverageData.log.5, CoverageData.log.6, CoverageData.log.7, CoverageData.log.8, Cov
    erageData.log.9
    [+] Output file: Callgrind.out
    [+] 80 modules readed
    [+] Parsing routines list, please wait...
   
    [+] 27806 routines readed
    [+] Parsing call tree, please wait...
   
    SYMLIB: Module loaded from "C:\Windows\SYSTEM32\ntdll.dll"
    SYMLIB: 4239 symbols loaded for "C:\Windows\SYSTEM32\ntdll.dll"
    SYMLIB: Module loaded from "C:\Windows\system32\IEFRAME.dll"
    SYMLIB: 33516 symbols loaded for "C:\Windows\system32\IEFRAME.dll"
    SYMLIB: Module loaded from "C:\Windows\System32\mshtml.dll"
    SYMLIB: 35150 symbols loaded for "C:\Windows\System32\mshtml.dll"
    SYMLIB: Module loaded from "C:\Windows\system32\OLEAUT32.dll"
    SYMLIB: 3940 symbols loaded for "C:\Windows\system32\OLEAUT32.dll"
   
    ... skipped ...
   
    [+] DONE (15 mins., 33 secs.)
   
    SYMLIB: DLL_PROCESS_DETACH
   
   

coverage_to_callgraph.py creates Callgrind.out file, that can be explored with Kcachegrind program. Sample Callgrind.out for Internet Explorer process execution can be found in ./EXAMPLES/ directory. For detailed information about coverage_to_callgraph.py usage see comments in the Python source.

Useful liks:

• Official Kcachegrind page: http://kcachegrind.sourceforge.net/html/Home.html

• Windows port of Kcachegrind (by Lailin Chen): http://sourceforge.net/projects/precompiledbin/

• Calltree Profile Format specification: http://valgrind.org/docs/manual/cl-format.html