Document callgraph analysis code

doc/HACKING

@@ -265,6 +265,23 @@ Here are some basic instructions
    * "opreport -l that_dir/*"
  - Profit
 
+Generating and analyzing a callgraph
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Run ./scripts/maint/generate_callgraph.sh .  This will generate a
+   bunch of files in a new ./callgraph directory.
+
+2. Run ./scripts/maint/analyze_callgraph.py callgraph/src/*/* .  This
+   will do a lot of graph operations and then dump out a new
+   "callgraph.pkl" file, containing data in Python's "pickle" format.
+
+3. Run ./scripts/maint/display_callgraph.py .  It will display:
+    - the number of functions reachable from each function.
+    - all strongly-connnected components in the Tor callgraph
+    - the largest bottlenecks in the largest SCC in the Tor callgraph.
+
+Note that currently the callgraph generator can't detect calls that pass
+through function pointers.
 
 Coding conventions
 ------------------

scripts/maint/generate_callgraph.sh

@@ -8,6 +8,7 @@ mkdir -p callgraph/src/or
 mkdir -p callgraph/src/tools
 
 for fn in $C_FILES; do
+  echo $fn
   clang $CFLAGS  -S -emit-llvm -fno-inline -o - $fn  | \
-    opt -analyze -print-callgraph 2> "callgraph/${fn}allgraph"
+    opt -analyze -print-callgraph >/dev/null 2> "callgraph/${fn}allgraph"
 done