c-tree.texi

理解和实践操作系统的一本好书

@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 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
@xref{Namespaces}.

@item TEMPLATE_DECL

These nodes are used to represent class, function, and variable (static
data member) templates.  The @code{DECL_TEMPLATE_SPECIALIZATIONS} are a
@code{TREE_LIST}.  The @code{TREE_VALUE} of each node in the list is a
@code{TEMPLATE_DECL}s or @code{FUNCTION_DECL}s representing
specializations (including instantiations) of this template.  Back ends
can safely ignore @code{TEMPLATE_DECL}s, but should examine
@code{FUNCTION_DECL} nodes on the specializations list just as they
would ordinary @code{FUNCTION_DECL} nodes.

For a class template, the @code{DECL_TEMPLATE_INSTANTIATIONS} list
contains the instantiations.  The @code{TREE_VALUE} of each node is an
instantiation of the class.  The @code{DECL_TEMPLATE_SPECIALIZATIONS}
contains partial specializations of the class.

@item USING_DECL

Back ends can safely ignore these 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 Functions
@c ---------------------------------------------------------------------

@node Functions
@section Functions
@cindex function
@tindex FUNCTION_DECL
@tindex OVERLOAD
@findex OVL_CURRENT
@findex OVL_NEXT

A function is represented by a @code{FUNCTION_DECL} node.  A set of
overloaded functions is sometimes represented by a @code{OVERLOAD} node.

An @code{OVERLOAD} node is not a declaration, so none of the
@samp{DECL_} macros should be used on an @code{OVERLOAD}.  An
@code{OVERLOAD} node is similar to a @code{TREE_LIST}.  Use
@code{OVL_CURRENT} to get the function associated with an
@code{OVERLOAD} node; use @code{OVL_NEXT} to get the next
@code{OVERLOAD} node in the list of overloaded functions.  The macros
@code{OVL_CURRENT} and @code{OVL_NEXT} are actually polymorphic; you can
use them to work with @code{FUNCTION_DECL} nodes as well as with
overloads.  In the case of a @code{FUNCTION_DECL}, @code{OVL_CURRENT}
will always return the function itself, and @code{OVL_NEXT} will always
be @code{NULL_TREE}.

To determine the scope of a function, you can use the
@code{DECL_CONTEXT} macro.  This macro will return the class
(either a @code{RECORD_TYPE} or a @code{UNION_TYPE}) or namespace (a
@code{NAMESPACE_DECL}) of which the function is a member.  For a virtual
function, this macro returns the class in which the function was
actually defined, not the base class in which the virtual declaration
occurred.

If a friend function is defined in a class scope, the
@code{DECL_FRIEND_CONTEXT} macro can be used to determine the class in
which it was defined.  For example, in
@smallexample
class C @{ friend void f() @{@} @};
@end smallexample
@noindent
the @code{DECL_CONTEXT} for @code{f} will be the
@code{global_namespace}, but the @code{DECL_FRIEND_CONTEXT} will be the
@code{RECORD_TYPE} for @code{C}.

In C, the @code{DECL_CONTEXT} for a function maybe another function.
This representation indicates that the GNU nested function extension
is in use.  For details on the semantics of nested functions, see the
GCC Manual.  The nested function can refer to local variables in its
containing function.  Such references are not explicitly marked in the
tree structure; back ends must look at the @code{DECL_CONTEXT} for the
referenced @code{VAR_DECL}.  If the @code{DECL_CONTEXT} for the
referenced @code{VAR_DECL} is not the same as the function currently
being processed, and neither @code{DECL_EXTERNAL} nor
@code{DECL_STATIC} hold, then the reference is to a local variable in
a containing function, and the back end must take appropriate action.

@menu
* Function Basics::     Function names, linkage, and so forth.
* Function Bodies::     The statements that make up a function body.
@end menu

@c ---------------------------------------------------------------------
@c Function Basics
@c ---------------------------------------------------------------------

@node Function Basics
@subsection Function Basics
@cindex constructor
@cindex destructor