Re: [tree-ssa] cfg.texi needs reviewing by a native speaker (Was:Re: "Documentation by paper")

[Diego Novillo <dnovillo at redhat dot com>]

On Wed, 2004-02-04 at 15:05, Steven Bosscher wrote:

> doc/
> 	* cfg.texi: New chapter for the internals manual.  Briefly describes
> 	the data structures used to represent the control flow graph, and
> 	the issues and API to modify and maintain the CFG.
>
Looks good.  Thanks for getting things started!  A few comments below. 
Maybe Joseph can go over the formatting stuff.  It looked good to me,
but texinfo is not my thing.

> + 
> + @findex next_bb, prev_bb, FOR_EACH_BB
> + Two pointer members of the @code{basic_block} structure are the
> + pointers @code{next_bb} and @code{prev_bb}.  These are used to keep
> + doubly linked chain of basic blocks in the same order as the
> + underlying instruction stream.  The chain of basic blocks is updated
> + transparenly by the provided API for manupulating the CFG.  The macro
    ^^^^^^^^^^^^                         ^^^^^^^^^^^^
    transparently                        manipulating

> + @code{FOR_EACH_BB} can be used to visit all this order.
> +                                         ^^^^^^^^^^^^^^
all the basic blocks in lexicographical order.  Dominator traversals are
also possible using @code{walk_dominator_tree} [ Reference to dom-walker
API here ].

> + @findex NOTE_INSN_BASIC_BLOCK, CODE_LABEL, notes
> + For RTL, these pointers are @code{rtx head, end}.  In the RTL function
> + representation, the head pointer always points either to a
> + @code{NOTE_INSN_BASIC_BLOCK} or to a @code{CODE_LABEL}, if present.
> + In the RTL representation of a function, the instruction stream
> + contains not only the ``real'' instructions, but also @dfn{notes}.
> + Any function that moves or duplicates the basic blocks needs
> + to take care of updating of these notes.  Many of notes expect that
                                                     ^
                                                   these

> + @cindex block statement iterators
> + For the @code{tree} representation, the head and end of the basic block
> + are being pointed to by the @code{stmt_list} field, but this special
> + @code{tree} should never be referenced directly.  Instead, at the tree
> + level abstract containers and iterators are used to access statements
> + and expressions in basic blocks.  These iterators are called
> + @dfn{block statement iterators} (BSIs).  Grep for @code{^bsi}
>
[ Reference to iterators section ]

> + in the various @file{tree-*} files
> + 
@example
The following snippet will pretty-print all the statements of the
program in the GIMPLE representation.

FOR_EACH_BB (bb)
  {
     block_stmt_iterator si;

     for (si = bsi_start (bb); !bsi_end_p (si); bsi_next (&si))
       {
          tree stmt = bsi_stmt (si);
          print_generic_stmt (stderr, stmt, 0);
       }
  }
@end example

> + GCC has two major intermediate representations, and both use the
> + @code{basic_block} and @code{edge} data types to represent control
> + flow.  Both representations share as much of the CFG maintainance code
                                                         ^^^^^^^^^^^^
maintenance

> + as possible.  For each representation, a set of @dfn{hooks} is defined
> + so that each representation can provide its own implementation of CFG
> + manipulation routines when necessary.  These hooks are defined in
> + @file{cfghooks.h}.  There are hooks for almost all common CFG
> + manipulations, including block splitting and merging, edge redirection
> + and creating and deleting basic blocks.  These hooks should provide
> + everything you need to maintain and manipulate the CFG in both the RTL
> + and @code{tree} representation.
> + 
> + At the moment, the basic block boundaries are maintained transparently
> + when modifying instructions, so there rarely is a need to move them

> + manually (such as in case someone wants to output instruction outside
> + basic block explicitly).
>
The bracketed comment doesn't read too well.  I'm not quite sure what
you wanted to say here.

> + Often the CFG may be better viewed as integral part of instruction
> + chain, than structure built on the top of it.  However, in principle
> + the control flow graph for the @code{tree} representation is
> + @emph{not} an integral part of the representation, in that a function
> + tree may be expanded without first buildint a  flow graph for the
                                       ^^^^^^^^
building

> + In particular, statement insertion and removal has to be done with
> + care.  In fact, the whole @code{tree} representation can not be easily
> + used or maintained without proper maintainance of the CFG
                                      ^^^^^^^^^^^^
maintenance

> + 
> + @findex BB_HEAD, BB_END
> + In the RTL representation, the macros @code{BB_HEAD} and @code{BB_END}
> + may be used to get the head and end @code{rtx} of a basic block.  No
> + abstract iterators are defined for traversing the insns chain, but you
                                                      ^^^^^
insn

> + @findex find_sub_basic_blocks, split_block
> + It is also possible that a pass has to insert control flow instruction
> + into the middle of a basic block, thus creating an entry point in the
> + middle of the basic block, which is impossible by defintion: The
                                                      ^^^^^^^^^
definition

> + Note that at present, the representation of control flow in the
> + @code{tree} representation is discarded before expanding to RTL.  Long
> + term the CFG should be maintained and ``expanded to the RTL
                                          ^^^^^^^^^^^
missing closing ''

> + use@code{clear_bb_flags} before doing any modifications and then ask
> + the dataflow modulule to have liveness updated via the
>       ^^^^^^^^^^^^^^^^^
data flow [ I'm not sure what standard we use, actually.  I've seen the
three forms "dataflow", "data-flow" and "data flow" ].
s/modulule/module/



Diego.