Re: [RFA/DOC] record pic

[Joel Brobecker <brobecker@adacore.com>]

> Hui: With your permission, I wold like to take this patch over.

Here is, in short, what I have found out from reverse-engineering
the code.  That should allow me to write some half-decent documentation
for this feature.  However, before you read on, and before I do so,
I would like to recommend that this feature be actually backed out.
More about this in the appropriate thread.

-------------------------------------------------------------------------

This feature produces a graph description using the VCG syntax.
Graphs essentially have two elements: nodes and edges (the edges
connect one node to the next).

Notations: `[source name]' means optional source name
           `<source name>' means mandatory source name

There are 3 types of edges:

  - Edges that correspond to a function call (drawn in red)
  - Edges that correspond to a function return (drawn in blue)
  - All other edges (drawn in the default color, I assume black)

  In the VCG file, the edges are written as:
  edge: {[color:<red|blue>] sourcename: "<from>" target_name: "<to>"}

There are two kinds of nodes.  Only one kind gets used for a given
graph. Which kind is used is determined by the user setting "set record
pic type <line|function>".  Nodes have a `title', which is displayed in
the node contents by the viewers.

  - Nodes associated to functions
    [filename-if-available] <function linkage name|function addr>

  - Nodes associated to source lines either:
      (a) <filename>:<line> [function linkage name] <addr> 
    or:
      (b) [function linkage name] [line number] <addr>

    (a) is used in the case when the new instruction corresponds
        to a different frame from the previous instruction (either
        a function call or a return) AND when the new instruction
        has a symtab (debug info)

    (b) is used otherwise.

    The `function linkage name' is provided when known.
    WARNING: The code only checks the symbol table, and ignores
             debugging info. This is a problem on platforms where
             the linker eliminates static functions.

    The line number is provided if known (symtab). This is the case
    where we have debugging info, but it's still in the same frame.

Effect of the various user settings:

  - set record pic hide-nofunction <on|off>
    If set to on, then nodes associated to instructions for which
    we cannot find a function in the symbol table are not included
    in the graph.

  - set record pic hide-nosource <on|off>
    If on, filters out the nodes associated to instructions for which
    no debugging information is available (typically, code compiled
    without debugging information, or code that got stripped).

  - set record pic hide-sameaddr <on|off>
    If on, nodes corresponding to the same address get merged.
    For "function" graphs, the merging stops as soon as the associated
    function returns. For line graphs, the merging is always done.
    The number of nodes being merged is indicated at the end of the node
    title as c:<N> where <N> is the number of times this node was found.

    If off, nodes are not merged.  Instead of the cound, the intruction
    number, whetever that might be, is indicated at the end of the node
    title as i:<N> where <N> is that instruction number.

-- 
Joel