-@c Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
+@c Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004, 2005
@c Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
Occasionally, a particular tree slot (like an operand to an expression,
or a particular field in a declaration) will be referred to as
-``reserved for the back end.'' These slots are used to store RTL when
+``reserved for the back end''. These slots are used to store RTL when
the tree is converted to RTL for use by the GCC back end. However, if
that process is not taking place (e.g., if the front end is being hooked
up to an intelligent editor), then those slots may be used by the
@ftable @code
@item LOCAL_CLASS_P
-This predicate holds if the class is local class @emph{i.e.} declared
+This predicate holds if the class is local class @emph{i.e.}@: declared
inside a function body.
@item TYPE_POLYMORPHIC_P
(represented by @code{FUNCTION_DECL} nodes), which are described in
@ref{Functions}.
+@menu
+* Working with declarations:: Macros and functions that work on
+declarations.
+* Internal structure:: How declaration nodes are represented.
+@end menu
+
+@node Working with declarations
+@subsection Working with declarations
+
Some macros can be used with any kind of declaration. These include:
@ftable @code
@item DECL_NAME
@end table
+@node Internal structure
+@subsection Internal structure
+
+@code{DECL} nodes are represented internally as a hierarchy of
+structures.
+
+@menu
+* Current structure hierarchy:: The current DECL node structure
+hierarchy.
+* Adding new DECL node types:: How to add a new DECL node to a
+frontend.
+@end menu
+
+@node Current structure hierarchy
+@subsubsection Current structure hierarchy
+
+@table @code
+
+@item struct tree_decl_minimal
+This is the minimal structure to inherit from in order for common
+@code{DECL} macros to work. The fields it contains are a unique ID,
+source location, context, and name.
+
+@item struct tree_decl_common
+This structure inherits from @code{struct tree_decl_minimal}. It
+contains fields that most @code{DECL} nodes need, such as a field to
+store alignment, machine mode, size, and attributes.
+
+@item struct tree_field_decl
+This structure inherits from @code{struct tree_decl_common}. It is
+used to represent @code{FIELD_DECL}.
+
+@item struct tree_label_decl
+This structure inherits from @code{struct tree_decl_common}. It is
+used to represent @code{LABEL_DECL}.
+
+@item struct tree_translation_unit_decl
+This structure inherits from @code{struct tree_decl_common}. It is
+used to represent @code{TRANSLATION_UNIT_DECL}.
+
+@item struct tree_decl_with_rtl
+This structure inherits from @code{struct tree_decl_common}. It
+contains a field to store the low-level RTL associated with a
+@code{DECL} node.
+
+@item struct tree_result_decl
+This structure inherits from @code{struct tree_decl_with_rtl}. It is
+used to represent @code{RESULT_DECL}.
+
+@item struct tree_const_decl
+This structure inherits from @code{struct tree_decl_with_rtl}. It is
+used to represent @code{CONST_DECL}.
+
+@item struct tree_parm_decl
+This structure inherits from @code{struct tree_decl_with_rtl}. It is
+used to represent @code{PARM_DECL}.
+
+@item struct tree_decl_with_vis
+This structure inherits from @code{struct tree_decl_with_rtl}. It
+contains fields necessary to store visibility information, as well as
+a section name and assembler name.
+
+@item struct tree_var_decl
+This structure inherits from @code{struct tree_decl_with_vis}. It is
+used to represent @code{VAR_DECL}.
+
+@item struct tree_function_decl
+This structure inherits from @code{struct tree_decl_with_vis}. It is
+used to represent @code{FUNCTION_DECL}.
+
+@end table
+@node Adding new DECL node types
+@subsubsection Adding new DECL node types
+
+Adding a new @code{DECL} tree consists of the following steps
+
+@table @asis
+
+@item Add a new tree code for the @code{DECL} node
+For language specific @code{DECL} nodes, there is a @file{.def} file
+in each frontend directory where the tree code should be added.
+For @code{DECL} nodes that are part of the middle-end, the code should
+be added to @file{tree.def}.
+
+@item Create a new structure type for the @code{DECL} node
+These structures should inherit from one of the existing structures in
+the language hierarchy by using that structure as the first member.
+
+@smallexample
+struct tree_foo_decl
+@{
+ struct tree_decl_with_vis common;
+@}
+@end smallexample
+
+Would create a structure name @code{tree_foo_decl} that inherits from
+@code{struct tree_decl_with_vis}.
+
+For language specific @code{DECL} nodes, this new structure type
+should go in the appropriate @file{.h} file.
+For @code{DECL} nodes that are part of the middle-end, the structure
+type should go in @file{tree.h}.
+
+@item Add a member to the tree structure enumerator for the node
+For garbage collection and dynamic checking purposes, each @code{DECL}
+node structure type is required to have a unique enumerator value
+specified with it.
+For language specific @code{DECL} nodes, this new enumerator value
+should go in the appropriate @file{.def} file.
+For @code{DECL} nodes that are part of the middle-end, the enumerator
+values are specified in @file{treestruct.def}.
+
+@item Update @code{union tree_node}
+In order to make your new structure type usable, it must be added to
+@code{union tree_node}.
+For language specific @code{DECL} nodes, a new entry should be added
+to the appropriate @file{.h} file of the form
+@smallexample
+ struct tree_foo_decl GTY ((tag ("TS_VAR_DECL"))) foo_decl;
+@end smallexample
+For @code{DECL} nodes that are part of the middle-end, the additional
+member goes directly into @code{union tree_node} in @file{tree.h}.
+
+@item Update dynamic checking info
+In order to be able to check whether accessing a named portion of
+@code{union tree_node} is legal, and whether a certain @code{DECL} node
+contains one of the enumerated @code{DECL} node structures in the
+hierarchy, a simple lookup table is used.
+This lookup table needs to be kept up to date with the tree structure
+hierarchy, or else checking and containment macros will fail
+inappropriately.
+
+For language specific @code{DECL} nodes, their is an @code{init_ts}
+function in an appropriate @file{.c} file, which initializes the lookup
+table.
+Code setting up the table for new @code{DECL} nodes should be added
+there.
+For each @code{DECL} tree code and enumerator value representing a
+member of the inheritance hierarchy, the table should contain 1 if
+that tree code inherits (directly or indirectly) from that member.
+Thus, a @code{FOO_DECL} node derived from @code{struct decl_with_rtl},
+and enumerator value @code{TS_FOO_DECL}, would be set up as follows
+@smallexample
+tree_contains_struct[FOO_DECL][TS_FOO_DECL] = 1;
+tree_contains_struct[FOO_DECL][TS_DECL_WRTL] = 1;
+tree_contains_struct[FOO_DECL][TS_DECL_COMMON] = 1;
+tree_contains_struct[FOO_DECL][TS_DECL_MINIMAL] = 1;
+@end smallexample
+
+For @code{DECL} nodes that are part of the middle-end, the setup code
+goes into @file{tree.c}.
+
+@item Add macros to access any new fields and flags
+
+Each added field or flag should have a macro that is used to access
+it, that performs appropriate checking to ensure only the right type of
+@code{DECL} nodes access the field.
+
+These macros generally take the following form
+@smallexample
+#define FOO_DECL_FIELDNAME(NODE) FOO_DECL_CHECK(NODE)->foo_decl.fieldname
+@end smallexample
+However, if the structure is simply a base class for further
+structures, something like the following should be used
+@smallexample
+#define BASE_STRUCT_CHECK(T) CONTAINS_STRUCT_CHECK(T, TS_BASE_STRUCT)
+#define BASE_STRUCT_FIELDNAME(NODE) \
+ (BASE_STRUCT_CHECK(NODE)->base_struct.fieldname
+@end smallexample
+
+@end table
+
+
@c ---------------------------------------------------------------------
@c Functions
@c ---------------------------------------------------------------------
@findex IF_COND
@findex THEN_CLAUSE
@findex ELSE_CLAUSE
-@tindex RETURN_INIT
@tindex RETURN_STMT
@findex RETURN_EXPR
@tindex SUBOBJECT
@{
case IF_STMT:
process_stmt (THEN_CLAUSE (stmt));
- /* More processing here. */
+ /* @r{More processing here.} */
break;
@dots{}
@code{IDENTIFIER_NODE} giving the name of the label can be obtained from
the @code{LABEL_DECL} with @code{DECL_NAME}.
-@item RETURN_INIT
-
-If the function uses the G++ ``named return value'' extension, meaning
-that the function has been defined like:
-@smallexample
-S f(int) return s @{@dots{}@}
-@end smallexample
-then there will be a @code{RETURN_INIT}. There is never a named
-returned value for a constructor. The first argument to the
-@code{RETURN_INIT} is the name of the object returned; the second
-argument is the initializer for the object. The object is initialized
-when the @code{RETURN_INIT} is encountered. The object referred to is
-the actual object returned; this extension is a manual way of doing the
-``return-value optimization.'' Therefore, the object must actually be
-constructed in the place where the object will be returned.
-
@item RETURN_STMT
Used to represent a @code{return} statement. The @code{RETURN_EXPR} is
@item SWITCH_STMT
-Used to represent a @code{switch} statement. The @code{SWITCH_COND} is
-the expression on which the switch is occurring. See the documentation
+Used to represent a @code{switch} statement. The @code{SWITCH_STMT_COND}
+is the expression on which the switch is occurring. See the documentation
for an @code{IF_STMT} for more information on the representation used
-for the condition. The @code{SWITCH_BODY} is the body of the switch
-statement. The @code{SWITCH_TYPE} is the original type of switch
+for the condition. The @code{SWITCH_STMT_BODY} is the body of the switch
+statement. The @code{SWITCH_STMT_TYPE} is the original type of switch
expression as given in the source, before any compiler conversions.
@item TRY_BLOCK
@tindex EXACT_DIV_EXPR
@tindex ARRAY_REF
@tindex ARRAY_RANGE_REF
+@tindex TARGET_MEM_REF
@tindex LT_EXPR
@tindex LE_EXPR
@tindex GT_EXPR
high-order bits should be zero-filled when the expression has unsigned
type and filled with the sign bit when the expression has signed type.
Note that the result is undefined if the second operand is larger
-than the first operand's type size.
+than or equal to the first operand's type size.
@item BIT_IOR_EXPR
result. @code{TRUNC_DIV_EXPR} rounds towards zero, @code{FLOOR_DIV_EXPR}
rounds towards negative infinity, @code{CEIL_DIV_EXPR} rounds towards
positive infinity and @code{ROUND_DIV_EXPR} rounds to the closest integer.
-Integer division in C and C++ is truncating, i.e@. @code{TRUNC_DIV_EXPR}.
+Integer division in C and C++ is truncating, i.e.@: @code{TRUNC_DIV_EXPR}.
The behavior of these operations on signed arithmetic overflow, when
dividing the minimum signed integer by minus one, is controlled by the
The integer modulus of two operands @code{a} and @code{b} is
defined as @code{a - (a/b)*b} where the division calculated using
the corresponding division operator. Hence for @code{TRUNC_MOD_EXPR}
-this definition assumes division using truncation towards zero, i.e@.
+this definition assumes division using truncation towards zero, i.e.@:
@code{TRUNC_DIV_EXPR}. Integer remainder in C and C++ uses truncating
-division, i.e@. @code{TRUNC_MOD_EXPR}.
+division, i.e.@: @code{TRUNC_MOD_EXPR}.
@item EXACT_DIV_EXPR
The @code{EXACT_DIV_EXPR} code is used to represent integer divisions where
type is the same as that of the first operand. The range of that array
type determines the amount of data these expressions access.
+@item TARGET_MEM_REF
+These nodes represent memory accesses whose address directly map to
+an addressing mode of the target architecture. The first argument
+is @code{TMR_SYMBOL} and must be a @code{VAR_DECL} of an object with
+a fixed address. The second argument is @code{TMR_BASE} and the
+third one is @code{TMR_INDEX}. The fourth argument is
+@code{TMR_STEP} and must be an @code{INTEGER_CST}. The fifth
+argument is @code{TMR_OFFSET} and must be an @code{INTEGER_CST}.
+Any of the arguments may be NULL if the appropriate component
+does not appear in the address. Address of the @code{TARGET_MEM_REF}
+is determined in the following way.
+
+@smallexample
+&TMR_SYMBOL + TMR_BASE + TMR_INDEX * TMR_STEP + TMR_OFFSET
+@end smallexample
+
+The sixth argument is the reference to the original memory access, which
+is preserved for the purposes of the RTL alias analysis. The seventh
+argument is a tag representing the results of tree level alias analysis.
+
@item LT_EXPR
@itemx LE_EXPR
@itemx GT_EXPR
These nodes represent non-static data member accesses. The first
operand is the object (rather than a pointer to it); the second operand
is the @code{FIELD_DECL} for the data member. The third operand represents
-the byte offset of the field, but should not be used directly; call
+the byte offset of the field, but should not be used directly; call
@code{component_ref_field_offset} instead.
@item COMPOUND_EXPR
If the @code{TREE_TYPE} of the @code{CONSTRUCTOR} is an
@code{ARRAY_TYPE}, then the @code{TREE_PURPOSE} of each element in the
-@code{TREE_LIST} will be an @code{INTEGER_CST}. This constant indicates
-which element of the array (indexed from zero) is being assigned to;
-again, the @code{TREE_VALUE} is the corresponding initializer. If the
-@code{TREE_PURPOSE} is @code{NULL_TREE}, then the initializer is for the
-next available array element.
+@code{TREE_LIST} will be an @code{INTEGER_CST} or a @code{RANGE_EXPR} of
+two @code{INTEGER_CST}s. A single @code{INTEGER_CST} indicates which
+element of the array (indexed from zero) is being assigned to. A
+@code{RANGE_EXPR} indicates an inclusive range of elements to
+initialize. In both cases the @code{TREE_VALUE} is the corresponding
+initializer. It is re-evaluated for each element of a
+@code{RANGE_EXPR}. If the @code{TREE_PURPOSE} is @code{NULL_TREE}, then
+the initializer is for the next available array element.
In the front end, you should not depend on the fields appearing in any
particular order. However, in the middle end, fields must appear in