--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/gcc/doc/generic.texi	Fri Jul 17 14:47:48 2009 +0900
@@ -0,0 +1,179 @@
+@c Copyright (c) 2004, 2005, 2007, 2008 Free Software Foundation, Inc.
+@c Free Software Foundation, Inc.
+@c This is part of the GCC manual.
+@c For copying conditions, see the file gcc.texi.
+
+@c ---------------------------------------------------------------------
+@c GENERIC
+@c ---------------------------------------------------------------------
+
+@node GENERIC
+@chapter GENERIC
+@cindex GENERIC
+
+The purpose of GENERIC is simply to provide a
+language-independent way of representing an entire function in
+trees.  To this end, it was necessary to add a few new tree codes
+to the back end, but most everything was already there.  If you
+can express it with the codes in @code{gcc/tree.def}, it's
+GENERIC@.
+
+Early on, there was a great deal of debate about how to think
+about statements in a tree IL@.  In GENERIC, a statement is
+defined as any expression whose value, if any, is ignored.  A
+statement will always have @code{TREE_SIDE_EFFECTS} set (or it
+will be discarded), but a non-statement expression may also have
+side effects.  A @code{CALL_EXPR}, for instance.
+
+It would be possible for some local optimizations to work on the
+GENERIC form of a function; indeed, the adapted tree inliner
+works fine on GENERIC, but the current compiler performs inlining
+after lowering to GIMPLE (a restricted form described in the next
+section). Indeed, currently the frontends perform this lowering
+before handing off to @code{tree_rest_of_compilation}, but this
+seems inelegant.
+
+If necessary, a front end can use some language-dependent tree
+codes in its GENERIC representation, so long as it provides a
+hook for converting them to GIMPLE and doesn't expect them to
+work with any (hypothetical) optimizers that run before the
+conversion to GIMPLE@. The intermediate representation used while
+parsing C and C++ looks very little like GENERIC, but the C and
+C++ gimplifier hooks are perfectly happy to take it as input and
+spit out GIMPLE@.
+
+@menu
+* Statements::
+@end menu
+
+@node Statements
+@section Statements
+@cindex Statements
+
+Most statements in GIMPLE are assignment statements, represented by
+@code{GIMPLE_ASSIGN}.  No other C expressions can appear at statement level;
+a reference to a volatile object is converted into a
+@code{GIMPLE_ASSIGN}.
+
+There are also several varieties of complex statements.
+
+@menu
+* Blocks::
+* Statement Sequences::
+* Empty Statements::
+* Jumps::
+* Cleanups::
+@end menu
+
+@node Blocks
+@subsection Blocks
+@cindex Blocks
+
+Block scopes and the variables they declare in GENERIC are
+expressed using the @code{BIND_EXPR} code, which in previous
+versions of GCC was primarily used for the C statement-expression
+extension.
+
+Variables in a block are collected into @code{BIND_EXPR_VARS} in
+declaration order.  Any runtime initialization is moved out of
+@code{DECL_INITIAL} and into a statement in the controlled block.
+When gimplifying from C or C++, this initialization replaces the
+@code{DECL_STMT}.
+
+Variable-length arrays (VLAs) complicate this process, as their
+size often refers to variables initialized earlier in the block.
+To handle this, we currently split the block at that point, and
+move the VLA into a new, inner @code{BIND_EXPR}.  This strategy
+may change in the future.
+
+A C++ program will usually contain more @code{BIND_EXPR}s than
+there are syntactic blocks in the source code, since several C++
+constructs have implicit scopes associated with them.  On the
+other hand, although the C++ front end uses pseudo-scopes to
+handle cleanups for objects with destructors, these don't
+translate into the GIMPLE form; multiple declarations at the same
+level use the same @code{BIND_EXPR}.
+
+@node Statement Sequences
+@subsection Statement Sequences
+@cindex Statement Sequences
+
+Multiple statements at the same nesting level are collected into
+a @code{STATEMENT_LIST}.  Statement lists are modified and
+traversed using the interface in @samp{tree-iterator.h}.
+
+@node Empty Statements
+@subsection Empty Statements
+@cindex Empty Statements
+
+Whenever possible, statements with no effect are discarded.  But
+if they are nested within another construct which cannot be
+discarded for some reason, they are instead replaced with an
+empty statement, generated by @code{build_empty_stmt}.
+Initially, all empty statements were shared, after the pattern of
+the Java front end, but this caused a lot of trouble in practice.
+
+An empty statement is represented as @code{(void)0}.
+
+@node Jumps
+@subsection Jumps
+@cindex Jumps
+
+Other jumps are expressed by either @code{GOTO_EXPR} or
+@code{RETURN_EXPR}.
+
+The operand of a @code{GOTO_EXPR} must be either a label or a
+variable containing the address to jump to.
+
+The operand of a @code{RETURN_EXPR} is either @code{NULL_TREE},
+@code{RESULT_DECL}, or a @code{MODIFY_EXPR} which sets the return
+value.  It would be nice to move the @code{MODIFY_EXPR} into a
+separate statement, but the special return semantics in
+@code{expand_return} make that difficult.  It may still happen in
+the future, perhaps by moving most of that logic into
+@code{expand_assignment}.
+
+@node Cleanups
+@subsection Cleanups
+@cindex Cleanups
+
+Destructors for local C++ objects and similar dynamic cleanups are
+represented in GIMPLE by a @code{TRY_FINALLY_EXPR}.
+@code{TRY_FINALLY_EXPR} has two operands, both of which are a sequence
+of statements to execute.  The first sequence is executed.  When it
+completes the second sequence is executed.
+
+The first sequence may complete in the following ways:
+
+@enumerate
+
+@item Execute the last statement in the sequence and fall off the
+end.
+
+@item Execute a goto statement (@code{GOTO_EXPR}) to an ordinary
+label outside the sequence.
+
+@item Execute a return statement (@code{RETURN_EXPR}).
+
+@item Throw an exception.  This is currently not explicitly represented in
+GIMPLE.
+
+@end enumerate
+
+The second sequence is not executed if the first sequence completes by
+calling @code{setjmp} or @code{exit} or any other function that does
+not return.  The second sequence is also not executed if the first
+sequence completes via a non-local goto or a computed goto (in general
+the compiler does not know whether such a goto statement exits the
+first sequence or not, so we assume that it doesn't).
+
+After the second sequence is executed, if it completes normally by
+falling off the end, execution continues wherever the first sequence
+would have continued, by falling off the end, or doing a goto, etc.
+
+@code{TRY_FINALLY_EXPR} complicates the flow graph, since the cleanup
+needs to appear on every edge out of the controlled block; this
+reduces the freedom to move code across these edges.  Therefore, the
+EH lowering pass which runs before most of the optimization passes
+eliminates these expressions by explicitly adding the cleanup to each
+edge.  Rethrowing the exception is represented using @code{RESX_EXPR}.