Subversion Repositories openrisc

@c Copyright (c) 2004, 2005, 2007, 2008, 2010 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.

@menu

* Deficiencies::                Topics net yet covered in this document.

* Tree overview::               All about @code{tree}s.

* Types::                       Fundamental and aggregate types.

* Declarations::                Type declarations and variables.

* Attributes::                  Declaration and type attributes.

* Expressions: Expression trees.            Operating on data.

* Statements::                  Control flow and related trees.

* Functions::                   Function bodies, linkage, and other aspects.

* Language-dependent trees::    Topics and trees specific to language front ends.

* C and C++ Trees::             Trees specific to C and C++.

* Java Trees::                  Trees specific to Java.

@end menu

@c ---------------------------------------------------------------------

@c Deficiencies

@c ---------------------------------------------------------------------

@node Deficiencies

@section Deficiencies

There are many places in which this document is incomplet and incorrekt.

It is, as of yet, only @emph{preliminary} documentation.

@c ---------------------------------------------------------------------

@c Overview

@c ---------------------------------------------------------------------

@node Tree overview

@section Overview

@cindex tree

@findex TREE_CODE

The central data structure used by the internal representation is the

@code{tree}.  These nodes, while all of the C type @code{tree}, are of

many varieties.  A @code{tree} is a pointer type, but the object to

which it points may be of a variety of types.  From this point forward,

we will refer to trees in ordinary type, rather than in @code{this

font}, except when talking about the actual C type @code{tree}.

You can tell what kind of node a particular tree is by using the

@code{TREE_CODE} macro.  Many, many macros take trees as input and

return trees as output.  However, most macros require a certain kind of

tree node as input.  In other words, there is a type-system for trees,

but it is not reflected in the C type-system.

For safety, it is useful to configure GCC with @option{--enable-checking}.

Although this results in a significant performance penalty (since all

tree types are checked at run-time), and is therefore inappropriate in a

release version, it is extremely helpful during the development process.

Many macros behave as predicates.  Many, although not all, of these

predicates end in @samp{_P}.  Do not rely on the result type of these

macros being of any particular type.  You may, however, rely on the fact

that the type can be compared to @code{0}, so that statements like

@smallexample

if (TEST_P (t) && !TEST_P (y))

  x = 1;

@end smallexample

@noindent

and

@smallexample

int i = (TEST_P (t) != 0);

@end smallexample

@noindent

are legal.  Macros that return @code{int} values now may be changed to

return @code{tree} values, or other pointers in the future.  Even those

that continue to return @code{int} may return multiple nonzero codes

where previously they returned only zero and one.  Therefore, you should

not write code like

@smallexample

if (TEST_P (t) == 1)

@end smallexample

@noindent

as this code is not guaranteed to work correctly in the future.

You should not take the address of values returned by the macros or

functions described here.  In particular, no guarantee is given that the

values are lvalues.

In general, the names of macros are all in uppercase, while the names of

functions are entirely in lowercase.  There are rare exceptions to this

rule.  You should assume that any macro or function whose name is made

up entirely of uppercase letters may evaluate its arguments more than

once.  You may assume that a macro or function whose name is made up

entirely of lowercase letters will evaluate its arguments only once.

The @code{error_mark_node} is a special tree.  Its tree code is

@code{ERROR_MARK}, but since there is only ever one node with that code,

the usual practice is to compare the tree against

@code{error_mark_node}.  (This test is just a test for pointer

equality.)  If an error has occurred during front-end processing the

flag @code{errorcount} will be set.  If the front end has encountered

code it cannot handle, it will issue a message to the user and set

@code{sorrycount}.  When these flags are set, any macro or function

which normally returns a tree of a particular kind may instead return

the @code{error_mark_node}.  Thus, if you intend to do any processing of

erroneous code, you must be prepared to deal with the

@code{error_mark_node}.

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

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

back end presently in use.

If you encounter situations that do not match this documentation, such

as tree nodes of types not mentioned here, or macros documented to

return entities of a particular kind that instead return entities of

some different kind, you have found a bug, either in the front end or in

the documentation.  Please report these bugs as you would any other

bug.

@menu

* Macros and Functions::Macros and functions that can be used with all trees.

* Identifiers::         The names of things.

* Containers::          Lists and vectors.

@end menu

@c ---------------------------------------------------------------------

@c Trees

@c ---------------------------------------------------------------------

@node Macros and Functions

@subsection Trees

@cindex tree

@findex TREE_CHAIN

@findex TREE_TYPE

All GENERIC trees have two fields in common.  First, @code{TREE_CHAIN}

is a pointer that can be used as a singly-linked list to other trees.

The other is @code{TREE_TYPE}.  Many trees store the type of an

expression or declaration in this field.

These are some other functions for handling trees:

@ftable @code

@item tree_size

Return the number of bytes a tree takes.

@item build0

@itemx build1

@itemx build2

@itemx build3

@itemx build4

@itemx build5

@itemx build6

These functions build a tree and supply values to put in each

parameter.  The basic signature is @samp{@w{code, type, [operands]}}.

@code{code} is the @code{TREE_CODE}, and @code{type} is a tree

representing the @code{TREE_TYPE}.  These are followed by the

operands, each of which is also a tree.

@end ftable

@c ---------------------------------------------------------------------

@c Identifiers

@c ---------------------------------------------------------------------

@node Identifiers

@subsection Identifiers

@cindex identifier

@cindex name

@tindex IDENTIFIER_NODE

An @code{IDENTIFIER_NODE} represents a slightly more general concept

that the standard C or C++ concept of identifier.  In particular, an

@code{IDENTIFIER_NODE} may contain a @samp{$}, or other extraordinary

characters.

There are never two distinct @code{IDENTIFIER_NODE}s representing the

same identifier.  Therefore, you may use pointer equality to compare

@code{IDENTIFIER_NODE}s, rather than using a routine like

@code{strcmp}.  Use @code{get_identifier} to obtain the unique

@code{IDENTIFIER_NODE} for a supplied string.

You can use the following macros to access identifiers:

@ftable @code

@item IDENTIFIER_POINTER

The string represented by the identifier, represented as a

@code{char*}.  This string is always @code{NUL}-terminated, and contains

no embedded @code{NUL} characters.

@item IDENTIFIER_LENGTH

The length of the string returned by @code{IDENTIFIER_POINTER}, not

including the trailing @code{NUL}.  This value of

@code{IDENTIFIER_LENGTH (x)} is always the same as @code{strlen

(IDENTIFIER_POINTER (x))}.

@item IDENTIFIER_OPNAME_P

This predicate holds if the identifier represents the name of an

overloaded operator.  In this case, you should not depend on the

contents of either the @code{IDENTIFIER_POINTER} or the

@code{IDENTIFIER_LENGTH}.

@item IDENTIFIER_TYPENAME_P

This predicate holds if the identifier represents the name of a

user-defined conversion operator.  In this case, the @code{TREE_TYPE} of

the @code{IDENTIFIER_NODE} holds the type to which the conversion

operator converts.

@end ftable

@c ---------------------------------------------------------------------

@c Containers

@c ---------------------------------------------------------------------

@node Containers

@subsection Containers

@cindex container

@cindex list

@cindex vector

@tindex TREE_LIST

@tindex TREE_VEC

@findex TREE_PURPOSE

@findex TREE_VALUE

@findex TREE_VEC_LENGTH

@findex TREE_VEC_ELT

Two common container data structures can be represented directly with

tree nodes.  A @code{TREE_LIST} is a singly linked list containing two

trees per node.  These are the @code{TREE_PURPOSE} and @code{TREE_VALUE}

of each node.  (Often, the @code{TREE_PURPOSE} contains some kind of

tag, or additional information, while the @code{TREE_VALUE} contains the

majority of the payload.  In other cases, the @code{TREE_PURPOSE} is

simply @code{NULL_TREE}, while in still others both the

@code{TREE_PURPOSE} and @code{TREE_VALUE} are of equal stature.)  Given

one @code{TREE_LIST} node, the next node is found by following the

@code{TREE_CHAIN}.  If the @code{TREE_CHAIN} is @code{NULL_TREE}, then

you have reached the end of the list.

A @code{TREE_VEC} is a simple vector.  The @code{TREE_VEC_LENGTH} is an

integer (not a tree) giving the number of nodes in the vector.  The

nodes themselves are accessed using the @code{TREE_VEC_ELT} macro, which

takes two arguments.  The first is the @code{TREE_VEC} in question; the

second is an integer indicating which element in the vector is desired.

The elements are indexed from zero.

@c ---------------------------------------------------------------------

@c Types

@c ---------------------------------------------------------------------

@node Types

@section Types

@cindex type

@cindex pointer

@cindex reference

@cindex fundamental type

@cindex array

@tindex VOID_TYPE

@tindex INTEGER_TYPE

@tindex TYPE_MIN_VALUE

@tindex TYPE_MAX_VALUE

@tindex REAL_TYPE

@tindex FIXED_POINT_TYPE

@tindex COMPLEX_TYPE

@tindex ENUMERAL_TYPE

@tindex BOOLEAN_TYPE

@tindex POINTER_TYPE

@tindex REFERENCE_TYPE

@tindex FUNCTION_TYPE

@tindex METHOD_TYPE

@tindex ARRAY_TYPE

@tindex RECORD_TYPE

@tindex UNION_TYPE

@tindex UNKNOWN_TYPE

@tindex OFFSET_TYPE

@findex TYPE_UNQUALIFIED

@findex TYPE_QUAL_CONST

@findex TYPE_QUAL_VOLATILE

@findex TYPE_QUAL_RESTRICT

@findex TYPE_MAIN_VARIANT

@cindex qualified type

@findex TYPE_SIZE

@findex TYPE_ALIGN

@findex TYPE_PRECISION

@findex TYPE_ARG_TYPES

@findex TYPE_METHOD_BASETYPE

@findex TYPE_OFFSET_BASETYPE

@findex TREE_TYPE

@findex TYPE_CONTEXT

@findex TYPE_NAME

@findex TYPENAME_TYPE_FULLNAME

@findex TYPE_FIELDS

@findex TYPE_CANONICAL

@findex TYPE_STRUCTURAL_EQUALITY_P

@findex SET_TYPE_STRUCTURAL_EQUALITY

All types have corresponding tree nodes.  However, you should not assume

that there is exactly one tree node corresponding to each type.  There

are often multiple nodes corresponding to the same type.

For the most part, different kinds of types have different tree codes.

(For example, pointer types use a @code{POINTER_TYPE} code while arrays

use an @code{ARRAY_TYPE} code.)  However, pointers to member functions

use the @code{RECORD_TYPE} code.  Therefore, when writing a

@code{switch} statement that depends on the code associated with a

particular type, you should take care to handle pointers to member

functions under the @code{RECORD_TYPE} case label.

The following functions and macros deal with cv-qualification of types:

@ftable @code

@item TYPE_MAIN_VARIANT

This macro returns the unqualified version of a type.  It may be applied

to an unqualified type, but it is not always the identity function in

that case.

@end ftable

A few other macros and functions are usable with all types:

@ftable @code

@item TYPE_SIZE

The number of bits required to represent the type, represented as an

@code{INTEGER_CST}.  For an incomplete type, @code{TYPE_SIZE} will be

@code{NULL_TREE}.

@item TYPE_ALIGN

The alignment of the type, in bits, represented as an @code{int}.

@item TYPE_NAME

This macro returns a declaration (in the form of a @code{TYPE_DECL}) for

the type.  (Note this macro does @emph{not} return an

@code{IDENTIFIER_NODE}, as you might expect, given its name!)  You can

look at the @code{DECL_NAME} of the @code{TYPE_DECL} to obtain the

actual name of the type.  The @code{TYPE_NAME} will be @code{NULL_TREE}

for a type that is not a built-in type, the result of a typedef, or a

named class type.

@item TYPE_CANONICAL

This macro returns the ``canonical'' type for the given type

node. Canonical types are used to improve performance in the C++ and

Objective-C++ front ends by allowing efficient comparison between two

type nodes in @code{same_type_p}: if the @code{TYPE_CANONICAL} values

of the types are equal, the types are equivalent; otherwise, the types

are not equivalent. The notion of equivalence for canonical types is

the same as the notion of type equivalence in the language itself. For

instance,

When @code{TYPE_CANONICAL} is @code{NULL_TREE}, there is no canonical

type for the given type node. In this case, comparison between this

type and any other type requires the compiler to perform a deep,

``structural'' comparison to see if the two type nodes have the same

form and properties.

The canonical type for a node is always the most fundamental type in

the equivalence class of types. For instance, @code{int} is its own

canonical type. A typedef @code{I} of @code{int} will have @code{int}

as its canonical type. Similarly, @code{I*}@ and a typedef @code{IP}@

(defined to @code{I*}) will has @code{int*} as their canonical

type. When building a new type node, be sure to set

@code{TYPE_CANONICAL} to the appropriate canonical type. If the new

type is a compound type (built from other types), and any of those

other types require structural equality, use

@code{SET_TYPE_STRUCTURAL_EQUALITY} to ensure that the new type also

requires structural equality. Finally, if for some reason you cannot

guarantee that @code{TYPE_CANONICAL} will point to the canonical type,

use @code{SET_TYPE_STRUCTURAL_EQUALITY} to make sure that the new

type--and any type constructed based on it--requires structural

equality. If you suspect that the canonical type system is

miscomparing types, pass @code{--param verify-canonical-types=1} to

the compiler or configure with @code{--enable-checking} to force the

compiler to verify its canonical-type comparisons against the

structural comparisons; the compiler will then print any warnings if

the canonical types miscompare.

@item TYPE_STRUCTURAL_EQUALITY_P

This predicate holds when the node requires structural equality

checks, e.g., when @code{TYPE_CANONICAL} is @code{NULL_TREE}.

@item SET_TYPE_STRUCTURAL_EQUALITY

This macro states that the type node it is given requires structural

equality checks, e.g., it sets @code{TYPE_CANONICAL} to

@code{NULL_TREE}.

@item same_type_p

This predicate takes two types as input, and holds if they are the same

type.  For example, if one type is a @code{typedef} for the other, or

both are @code{typedef}s for the same type.  This predicate also holds if

the two trees given as input are simply copies of one another; i.e.,

there is no difference between them at the source level, but, for

whatever reason, a duplicate has been made in the representation.  You

should never use @code{==} (pointer equality) to compare types; always

use @code{same_type_p} instead.

@end ftable

Detailed below are the various kinds of types, and the macros that can

be used to access them.  Although other kinds of types are used

elsewhere in G++, the types described here are the only ones that you

will encounter while examining the intermediate representation.

@table @code

@item VOID_TYPE

Used to represent the @code{void} type.

@item INTEGER_TYPE

Used to represent the various integral types, including @code{char},

@code{short}, @code{int}, @code{long}, and @code{long long}.  This code

is not used for enumeration types, nor for the @code{bool} type.

The @code{TYPE_PRECISION} is the number of bits used in

the representation, represented as an @code{unsigned int}.  (Note that

in the general case this is not the same value as @code{TYPE_SIZE};

suppose that there were a 24-bit integer type, but that alignment

requirements for the ABI required 32-bit alignment.  Then,

@code{TYPE_SIZE} would be an @code{INTEGER_CST} for 32, while

@code{TYPE_PRECISION} would be 24.)  The integer type is unsigned if

@code{TYPE_UNSIGNED} holds; otherwise, it is signed.

The @code{TYPE_MIN_VALUE} is an @code{INTEGER_CST} for the smallest

integer that may be represented by this type.  Similarly, the

@code{TYPE_MAX_VALUE} is an @code{INTEGER_CST} for the largest integer

that may be represented by this type.

@item REAL_TYPE

Used to represent the @code{float}, @code{double}, and @code{long

double} types.  The number of bits in the floating-point representation

is given by @code{TYPE_PRECISION}, as in the @code{INTEGER_TYPE} case.

@item FIXED_POINT_TYPE

Used to represent the @code{short _Fract}, @code{_Fract}, @code{long

_Fract}, @code{long long _Fract}, @code{short _Accum}, @code{_Accum},

@code{long _Accum}, and @code{long long _Accum} types.  The number of bits

in the fixed-point representation is given by @code{TYPE_PRECISION},

as in the @code{INTEGER_TYPE} case.  There may be padding bits, fractional

bits and integral bits.  The number of fractional bits is given by

@code{TYPE_FBIT}, and the number of integral bits is given by @code{TYPE_IBIT}.

The fixed-point type is unsigned if @code{TYPE_UNSIGNED} holds; otherwise,

it is signed.

The fixed-point type is saturating if @code{TYPE_SATURATING} holds; otherwise,

it is not saturating.

@item COMPLEX_TYPE

Used to represent GCC built-in @code{__complex__} data types.  The

@code{TREE_TYPE} is the type of the real and imaginary parts.

@item ENUMERAL_TYPE

Used to represent an enumeration type.  The @code{TYPE_PRECISION} gives

(as an @code{int}), the number of bits used to represent the type.  If

there are no negative enumeration constants, @code{TYPE_UNSIGNED} will

hold.  The minimum and maximum enumeration constants may be obtained

with @code{TYPE_MIN_VALUE} and @code{TYPE_MAX_VALUE}, respectively; each

of these macros returns an @code{INTEGER_CST}.

The actual enumeration constants themselves may be obtained by looking

at the @code{TYPE_VALUES}.  This macro will return a @code{TREE_LIST},

containing the constants.  The @code{TREE_PURPOSE} of each node will be

an @code{IDENTIFIER_NODE} giving the name of the constant; the

@code{TREE_VALUE} will be an @code{INTEGER_CST} giving the value

assigned to that constant.  These constants will appear in the order in

which they were declared.  The @code{TREE_TYPE} of each of these

constants will be the type of enumeration type itself.

@item BOOLEAN_TYPE

Used to represent the @code{bool} type.

@item POINTER_TYPE

Used to represent pointer types, and pointer to data member types.  The

@code{TREE_TYPE} gives the type to which this type points.

@item REFERENCE_TYPE

Used to represent reference types.  The @code{TREE_TYPE} gives the type

to which this type refers.

@item FUNCTION_TYPE

Used to represent the type of non-member functions and of static member

functions.  The @code{TREE_TYPE} gives the return type of the function.

The @code{TYPE_ARG_TYPES} are a @code{TREE_LIST} of the argument types.

The @code{TREE_VALUE} of each node in this list is the type of the

corresponding argument; the @code{TREE_PURPOSE} is an expression for the

default argument value, if any.  If the last node in the list is

@code{void_list_node} (a @code{TREE_LIST} node whose @code{TREE_VALUE}

is the @code{void_type_node}), then functions of this type do not take

variable arguments.  Otherwise, they do take a variable number of

arguments.

Note that in C (but not in C++) a function declared like @code{void f()}

is an unprototyped function taking a variable number of arguments; the

@code{TYPE_ARG_TYPES} of such a function will be @code{NULL}.

@item METHOD_TYPE

Used to represent the type of a non-static member function.  Like a

@code{FUNCTION_TYPE}, the return type is given by the @code{TREE_TYPE}.

The type of @code{*this}, i.e., the class of which functions of this

type are a member, is given by the @code{TYPE_METHOD_BASETYPE}.  The

@code{TYPE_ARG_TYPES} is the parameter list, as for a

@code{FUNCTION_TYPE}, and includes the @code{this} argument.

@item ARRAY_TYPE

Used to represent array types.  The @code{TREE_TYPE} gives the type of

the elements in the array.  If the array-bound is present in the type,

the @code{TYPE_DOMAIN} is an @code{INTEGER_TYPE} whose

@code{TYPE_MIN_VALUE} and @code{TYPE_MAX_VALUE} will be the lower and

upper bounds of the array, respectively.  The @code{TYPE_MIN_VALUE} will

always be an @code{INTEGER_CST} for zero, while the

@code{TYPE_MAX_VALUE} will be one less than the number of elements in

the array, i.e., the highest value which may be used to index an element

in the array.

@item RECORD_TYPE

Used to represent @code{struct} and @code{class} types, as well as

pointers to member functions and similar constructs in other languages.

@code{TYPE_FIELDS} contains the items contained in this type, each of

which can be a @code{FIELD_DECL}, @code{VAR_DECL}, @code{CONST_DECL}, or

@code{TYPE_DECL}.  You may not make any assumptions about the ordering

of the fields in the type or whether one or more of them overlap.

@item UNION_TYPE

Used to represent @code{union} types.  Similar to @code{RECORD_TYPE}

except that all @code{FIELD_DECL} nodes in @code{TYPE_FIELD} start at

bit position zero.

@item QUAL_UNION_TYPE

Used to represent part of a variant record in Ada.  Similar to

@code{UNION_TYPE} except that each @code{FIELD_DECL} has a

@code{DECL_QUALIFIER} field, which contains a boolean expression that

indicates whether the field is present in the object.  The type will only

have one field, so each field's @code{DECL_QUALIFIER} is only evaluated

if none of the expressions in the previous fields in @code{TYPE_FIELDS}

are nonzero.  Normally these expressions will reference a field in the

outer object using a @code{PLACEHOLDER_EXPR}.

@item LANG_TYPE

This node is used to represent a language-specific type.  The front

end must handle it.

@item OFFSET_TYPE

This node is used to represent a pointer-to-data member.  For a data

member @code{X::m} the @code{TYPE_OFFSET_BASETYPE} is @code{X} and the

@code{TREE_TYPE} is the type of @code{m}.

@end table

There are variables whose values represent some of the basic types.

These include:

@table @code

@item void_type_node

A node for @code{void}.

@item integer_type_node

A node for @code{int}.

@item unsigned_type_node.

A node for @code{unsigned int}.

@item char_type_node.

A node for @code{char}.

@end table

@noindent

It may sometimes be useful to compare one of these variables with a type

in hand, using @code{same_type_p}.

@c ---------------------------------------------------------------------

@c Declarations

@c ---------------------------------------------------------------------

@node Declarations

@section Declarations

@cindex declaration

@cindex variable

@cindex type declaration

@tindex LABEL_DECL

@tindex CONST_DECL

@tindex TYPE_DECL

@tindex VAR_DECL

@tindex PARM_DECL

@tindex DEBUG_EXPR_DECL

@tindex FIELD_DECL

@tindex NAMESPACE_DECL

@tindex RESULT_DECL

@tindex TEMPLATE_DECL

@tindex THUNK_DECL

@findex THUNK_DELTA

@findex DECL_INITIAL

@findex DECL_SIZE

@findex DECL_ALIGN

@findex DECL_EXTERNAL

This section covers the various kinds of declarations that appear in the

internal representation, except for declarations of functions

(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

This macro returns an @code{IDENTIFIER_NODE} giving the name of the

entity.

@item TREE_TYPE

This macro returns the type of the entity declared.

@item EXPR_FILENAME

This macro returns the name of the file in which the entity was

declared, as a @code{char*}.  For an entity declared implicitly by the

compiler (like @code{__builtin_memcpy}), this will be the string

@code{"<internal>"}.

@item EXPR_LINENO

This macro returns the line number at which the entity was declared, as

an @code{int}.

@item DECL_ARTIFICIAL

This predicate holds if the declaration was implicitly generated by the

compiler.  For example, this predicate will hold of an implicitly

declared member function, or of the @code{TYPE_DECL} implicitly

generated for a class type.  Recall that in C++ code like:

@smallexample

struct S @{@};

@end smallexample

@noindent

is roughly equivalent to C code like:

@smallexample

struct S @{@};

typedef struct S S;

@end smallexample

The implicitly generated @code{typedef} declaration is represented by a

@code{TYPE_DECL} for which @code{DECL_ARTIFICIAL} holds.

@end ftable

The various kinds of declarations include:

@table @code

@item LABEL_DECL

These nodes are used to represent labels in function bodies.  For more

information, see @ref{Functions}.  These nodes only appear in block

scopes.

@item CONST_DECL

These nodes are used to represent enumeration constants.  The value of

the constant is given by @code{DECL_INITIAL} which will be an

@code{INTEGER_CST} with the same type as the @code{TREE_TYPE} of the

@code{CONST_DECL}, i.e., an @code{ENUMERAL_TYPE}.

@item RESULT_DECL

These nodes represent the value returned by a function.  When a value is

assigned to a @code{RESULT_DECL}, that indicates that the value should

be returned, via bitwise copy, by the function.  You can use

@code{DECL_SIZE} and @code{DECL_ALIGN} on a @code{RESULT_DECL}, just as

with a @code{VAR_DECL}.

@item TYPE_DECL

These nodes represent @code{typedef} declarations.  The @code{TREE_TYPE}

is the type declared to have the name given by @code{DECL_NAME}.  In

some cases, there is no associated name.

@item VAR_DECL

These nodes represent variables with namespace or block scope, as well

as static data members.  The @code{DECL_SIZE} and @code{DECL_ALIGN} are

analogous to @code{TYPE_SIZE} and @code{TYPE_ALIGN}.  For a declaration,

you should always use the @code{DECL_SIZE} and @code{DECL_ALIGN} rather

than the @code{TYPE_SIZE} and @code{TYPE_ALIGN} given by the

@code{TREE_TYPE}, since special attributes may have been applied to the

variable to give it a particular size and alignment.  You may use the

predicates @code{DECL_THIS_STATIC} or @code{DECL_THIS_EXTERN} to test

whether the storage class specifiers @code{static} or @code{extern} were

used to declare a variable.

If this variable is initialized (but does not require a constructor),

the @code{DECL_INITIAL} will be an expression for the initializer.  The

initializer should be evaluated, and a bitwise copy into the variable

performed.  If the @code{DECL_INITIAL} is the @code{error_mark_node},

there is an initializer, but it is given by an explicit statement later

in the code; no bitwise copy is required.

GCC provides an extension that allows either automatic variables, or

global variables, to be placed in particular registers.  This extension

is being used for a particular @code{VAR_DECL} if @code{DECL_REGISTER}

holds for the @code{VAR_DECL}, and if @code{DECL_ASSEMBLER_NAME} is not

equal to @code{DECL_NAME}.  In that case, @code{DECL_ASSEMBLER_NAME} is

the name of the register into which the variable will be placed.

@item PARM_DECL

Used to represent a parameter to a function.  Treat these nodes

similarly to @code{VAR_DECL} nodes.  These nodes only appear in the

@code{DECL_ARGUMENTS} for a @code{FUNCTION_DECL}.

The @code{DECL_ARG_TYPE} for a @code{PARM_DECL} is the type that will

actually be used when a value is passed to this function.  It may be a

wider type than the @code{TREE_TYPE} of the parameter; for example, the

ordinary type might be @code{short} while the @code{DECL_ARG_TYPE} is

@code{int}.

@item DEBUG_EXPR_DECL

Used to represent an anonymous debug-information temporary created to

hold an expression as it is optimized away, so that its value can be

referenced in debug bind statements.

@item FIELD_DECL

These nodes represent non-static data members.  The @code{DECL_SIZE} and

@code{DECL_ALIGN} behave as for @code{VAR_DECL} nodes.

The position of the field within the parent record is specified by a

combination of three attributes.  @code{DECL_FIELD_OFFSET} is the position,

counting in bytes, of the @code{DECL_OFFSET_ALIGN}-bit sized word containing

the bit of the field closest to the beginning of the structure.

@code{DECL_FIELD_BIT_OFFSET} is the bit offset of the first bit of the field

within this word; this may be nonzero even for fields that are not bit-fields,

since @code{DECL_OFFSET_ALIGN} may be greater than the natural alignment

of the field's type.

If @code{DECL_C_BIT_FIELD} holds, this field is a bit-field.  In a bit-field,

@code{DECL_BIT_FIELD_TYPE} also contains the type that was originally

specified for it, while DECL_TYPE may be a modified type with lesser precision,

according to the size of the bit field.

@item NAMESPACE_DECL

Namespaces provide a name hierarchy for other declarations.  They

appear in the @code{DECL_CONTEXT} of other @code{_DECL} nodes.

@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 Attributes

@c ---------------------------------------------------------------------

@node Attributes

@section Attributes in trees

@cindex attributes

Attributes, as specified using the @code{__attribute__} keyword, are

represented internally as a @code{TREE_LIST}.  The @code{TREE_PURPOSE}