Added a makefile, added additional commenting, expanded README

README.md

@@ -13,7 +13,53 @@ xref_finder will generate a log of caller to callee mappings.
 The second, xref_parser, is an IDAPython plugin which parses this log, 
 determines whether or not a particular mapping is eligible to be added as
 a cross-reference (valid address range, is not an existing cross-reference)
-and adds the cross-references accordingly.
+and adds the cross-references accordingly. To highlight what new cross-
+references have been built, the script will add regular comments next to
+each "call" instruction.
 
 This tool is intended to solve a very specific purpose, but Pin and 
 IDAPython could be further utilized to do a lot more interesting things.
+
+Pre-requisites
+===========
+These tools are designed for use with IDA Pro. You'll also need IDAPython
+and Pin.
+
+Building the Pin tool
+===========
+Note: This Pin tool has only been tested on Windows, using Visual Studio 
+2010. 
+
+Move the xref_finder directory into the source/tools/ directory within your
+Pin directory. From a Visual Studio command prompt, change into the 
+xref_finder directory and simply type "nmake". By default, the resulting
+tool can be found within a new "obj-ia32" directory (on x86 architecture).
+
+Running the Pin tool
+===========
+Pin tools are essentially libraries, intended to be used with the Pin 
+application. From your Pin directory, run something like the following.
+
+pin -t path\to\xref_finder.dll -- calc.exe
+
+In this example, "calc.exe" will launch and a file called "xrefs_omg.out" 
+will be created in the directory from which Pin was run.
+
+The tool doesn't account for child processes (yet?) so mileage may vary.
+
+Running the IDAPython script
+===========
+I suspect that this is self-explanatory. Suck in the output the xref_finder
+output (by default, "xref_omg.out").
+
+Quirks
+===========
+There may be some. They may be more obvious to you than to me. Because I 
+wrote this tool to actually use, I am interested in improving its 
+functionality and reliability. There's a very good chance that you are a
+better Python and/or C++ programmer with a better understanding of how
+software works. Please be sure to share any suggestions, comments, or
+criticisms.
+
+bNull
+bnull@offenseindepth.com

makefile

@@ -0,0 +1,19 @@
+######################################################################################
+# This is the NMAKE file for building and testing PIN toos contained in one of the
+# subdirectories of the PinTool project or PIN kit. 
+#
+# For description of targets and options, see Nmakefile in the root directory.  
+######################################################################################
+
+!if "$(PIN_HOME)"==""
+PIN_HOME=..
+!endif
+
+# Define tools to be buit and tested
+######################################################################################
+COMMON_TOOLS= xref_finder.dll
+
+# Include building and testing rules from the root Nmakefile. 
+######################################################################################
+INCLUDE_SUB_RULES=1
+!INCLUDE $(PIN_HOME)\Nmakefile 

xref_finder.cpp

@@ -8,7 +8,6 @@
 #include <string.h>
 #include "pin.H"
 
-
 // trace log
 FILE * trace;
 
@@ -23,6 +22,10 @@ VOID RecordCall(VOID * ip, VOID * addr)
 
     if (calls.count(keyedpair) == 0)
     {
+        // Efficiency note: while it would be more efficient to write out
+        // the contents of the "calls" set when the program executes (in the
+        // Fini() function), we take a hit to reliability. If the application
+        // terminates unexpectedly, we might not get our log output.
         fprintf(trace,"%s\n", keyedpair);
         calls.insert(keyedpair);
     }

xref_parser.py

@@ -148,7 +148,8 @@ def parse_lines(call_list):
     return stats
 
 
-
+# if you decide to change the extension of the output file in the Pin tool, be sure
+# to update the call to AskFile() below.
 input_file = AskFile(0, "*.out", "Select icalltrace input log")
 f = open(input_file, 'rb')