* Application name: Dynamic Callgraph
* Contact: William Cohen, wochen@redhat.com

* Motivation:

Dynamic Callgraph would provide information to allow developers to see
what other functions a function is calling. This could show that some
unexpected functions are getting called. DTrace has a instrumentation
provider that generates a trace of the functions called and returned.

* Background:

There have been times that people in Red Hat support have narrowed a
problem to a specific function and the functions it calls.  Rather
than instrumenting the function's children by hand, a tapset that
provides a dynamic callgraph would allow quicker determination of the
things called.  There are cases in the kernel code where determining
the function being called cannot be determined statically,
e.g. function to call is stored in a data structure.

* Target software:

Ideally both kernel and user space, but kernel space only would
be sufficient for many cases.

* Type of description:  tapset and scripting command
  tapset to provide to support to capture call return information
  scripting commands to turn on and off the capture

* Interesting probe points:

* Interesting values:

* Dependencies:
- P6/x86-64 processors have the debug hardware to trap control flow chgs.
- Need to have the kernel maintain the debug hardware on a per process basis.
       The DebugCtlMSR is not currently stored in the context
	   (only debug registers 0, 1, 2, 3, 6, and 7 are virtualized)

* Restrictions:
  May be difficult to implement on ppc: returns may look like regular jumps
      and trapping on all branches could cause problems with atomic operations
  Won't work on pre p6 x86 processors
  Won't provide data for inlined funcions

* Data collection:
  Track whether the instruction was a call or a return and the target address.

* Data presentation:
  -processing address in userspace to convert addresses into function names
  -trace showing calls and returns
  -maybe further post process to build dynamic callgraph
	 determine that a function is being called way too often

* Competition:
  DTrace already implements tracing of function calls and returns.

* Cross-references:

* Associated files:

  $dynamic_call_graph = 1; // turn on tracing of calls for thread
  $dynamic_call_graph = 0; // turn off tracing of calls for thread