329 lines
11 KiB
Plaintext
329 lines
11 KiB
Plaintext
|
@c Copyright (C) 2002, 2003
|
||
|
|
@c Free Software Foundation, Inc.
|
||
|
|
@c This is part of the GCC manual.
|
||
|
|
@c For copying conditions, see the file gcc.texi.
|
||
|
|
|
||
|
|
@node Type Information
|
||
|
|
@chapter Memory Management and Type Information
|
||
|
|
@cindex GGC
|
||
|
|
@findex GTY
|
||
|
|
|
||
|
|
GCC uses some fairly sophisticated memory management techniques, which
|
||
|
|
involve determining information about GCC's data structures from GCC's
|
||
|
|
source code and using this information to perform garbage collection.
|
||
|
|
|
||
|
|
A full C parser would be too overcomplicated for this task, so a limited
|
||
|
|
subset of C is interpreted and special markers are used to determine
|
||
|
|
what parts of the source to look at. The parser can also detect
|
||
|
|
simple typedefs of the form @code{typedef struct ID1 *ID2;} and
|
||
|
|
@code{typedef int ID3;}, and these don't need to be specially marked.
|
||
|
|
|
||
|
|
The two forms that do need to be marked are:
|
||
|
|
@verbatim
|
||
|
|
struct ID1 GTY(([options]))
|
||
|
|
{
|
||
|
|
[fields]
|
||
|
|
};
|
||
|
|
|
||
|
|
typedef struct ID2 GTY(([options]))
|
||
|
|
{
|
||
|
|
[fields]
|
||
|
|
} ID3;
|
||
|
|
@end verbatim
|
||
|
|
|
||
|
|
@menu
|
||
|
|
* GTY Options:: What goes inside a @code{GTY(())}.
|
||
|
|
* GGC Roots:: Making global variables GGC roots.
|
||
|
|
* Files:: How the generated files work.
|
||
|
|
@end menu
|
||
|
|
|
||
|
|
@node GTY Options
|
||
|
|
@section The Inside of a @code{GTY(())}
|
||
|
|
|
||
|
|
Sometimes the C code is not enough to fully describe the type structure.
|
||
|
|
Extra information can be provided by using more @code{GTY} markers.
|
||
|
|
These markers can be placed:
|
||
|
|
@itemize @bullet
|
||
|
|
@item
|
||
|
|
In a structure definition, before the open brace;
|
||
|
|
@item
|
||
|
|
In a global variable declaration, after the keyword @code{static} or
|
||
|
|
@code{extern}; and
|
||
|
|
@item
|
||
|
|
In a structure field definition, before the name of the field.
|
||
|
|
@end itemize
|
||
|
|
|
||
|
|
The format of a marker is
|
||
|
|
@verbatim
|
||
|
|
GTY (([name] ([param]), [name] ([param]) ...))
|
||
|
|
@end verbatim
|
||
|
|
The parameter is either a string or a type name.
|
||
|
|
|
||
|
|
When the parameter is a string, often it is a fragment of C code. Three
|
||
|
|
special escapes may be available:
|
||
|
|
|
||
|
|
@cindex % in GTY option
|
||
|
|
@table @code
|
||
|
|
@item %h
|
||
|
|
This expands to an expression that evaluates to the current structure.
|
||
|
|
@item %1
|
||
|
|
This expands to an expression that evaluates to the structure that
|
||
|
|
immediately contains the current structure.
|
||
|
|
@item %0
|
||
|
|
This expands to an expression that evaluates to the outermost structure
|
||
|
|
that contains the current structure.
|
||
|
|
@item %a
|
||
|
|
This expands to the string of the form @code{[i1][i2]...} that indexes
|
||
|
|
the array item currently being marked. For instance, if the field
|
||
|
|
being marked is @code{foo}, then @code{%1.foo%a} is the same as @code{%h}.
|
||
|
|
@end table
|
||
|
|
|
||
|
|
The available options are:
|
||
|
|
|
||
|
|
@table @code
|
||
|
|
@findex length
|
||
|
|
@item length
|
||
|
|
|
||
|
|
There are two places the type machinery will need to be explicitly told
|
||
|
|
the length of an array. The first case is when a structure ends in a
|
||
|
|
variable-length array, like this:
|
||
|
|
@verbatim
|
||
|
|
struct rtvec_def GTY(()) {
|
||
|
|
int num_elem; /* number of elements */
|
||
|
|
rtx GTY ((length ("%h.num_elem"))) elem[1];
|
||
|
|
};
|
||
|
|
@end verbatim
|
||
|
|
In this case, the @code{length} option is used to override the specified
|
||
|
|
array length (which should usually be @code{1}). The parameter of the
|
||
|
|
option is a fragment of C code that calculates the length.
|
||
|
|
|
||
|
|
The second case is when a structure or a global variable contains a
|
||
|
|
pointer to an array, like this:
|
||
|
|
@smallexample
|
||
|
|
tree *
|
||
|
|
GTY ((length ("%h.regno_pointer_align_length"))) regno_decl;
|
||
|
|
@end smallexample
|
||
|
|
In this case, @code{regno_decl} has been allocated by writing something like
|
||
|
|
@smallexample
|
||
|
|
x->regno_decl =
|
||
|
|
ggc_alloc (x->regno_pointer_align_length * sizeof (tree));
|
||
|
|
@end smallexample
|
||
|
|
and the @code{length} provides the length of the field.
|
||
|
|
|
||
|
|
This second use of @code{length} also works on global variables, like:
|
||
|
|
@verbatim
|
||
|
|
static GTY((length ("reg_base_value_size")))
|
||
|
|
rtx *reg_base_value;
|
||
|
|
@end verbatim
|
||
|
|
|
||
|
|
@findex skip
|
||
|
|
@item skip
|
||
|
|
|
||
|
|
If @code{skip} is applied to a field, the type machinery will ignore it.
|
||
|
|
This is somewhat dangerous; the only safe use is in a union when one
|
||
|
|
field really isn't ever used.
|
||
|
|
|
||
|
|
@findex desc
|
||
|
|
@findex tag
|
||
|
|
@findex default
|
||
|
|
@item desc
|
||
|
|
@itemx tag
|
||
|
|
@itemx default
|
||
|
|
|
||
|
|
The type machinery needs to be told which field of a @code{union} is
|
||
|
|
currently active. This is done by giving each field a constant @code{tag}
|
||
|
|
value, and then specifying a discriminator using @code{desc}. For example,
|
||
|
|
@smallexample
|
||
|
|
struct tree_binding GTY(())
|
||
|
|
@{
|
||
|
|
struct tree_common common;
|
||
|
|
union tree_binding_u @{
|
||
|
|
tree GTY ((tag ("0"))) scope;
|
||
|
|
struct cp_binding_level * GTY ((tag ("1"))) level;
|
||
|
|
@} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) scope;
|
||
|
|
tree value;
|
||
|
|
@};
|
||
|
|
@end smallexample
|
||
|
|
|
||
|
|
In the @code{desc} option, the ``current structure'' is the union that
|
||
|
|
it discriminates. Use @code{%1} to mean the structure containing it.
|
||
|
|
(There are no escapes available to the @code{tag} option, since it's
|
||
|
|
supposed to be a constant.)
|
||
|
|
|
||
|
|
Each @code{tag} should be different. If no @code{tag} is matched,
|
||
|
|
the field marked with @code{default} is used if there is one, otherwise
|
||
|
|
no field in the union will be marked.
|
||
|
|
|
||
|
|
@findex param_is
|
||
|
|
@findex use_param
|
||
|
|
@item param_is
|
||
|
|
@itemx use_param
|
||
|
|
|
||
|
|
Sometimes it's convenient to define some data structure to work on
|
||
|
|
generic pointers (that is, @code{PTR}) and then use it with a specific
|
||
|
|
type. @code{param_is} specifies the real type pointed to, and
|
||
|
|
@code{use_param} says where in the generic data structure that type
|
||
|
|
should be put.
|
||
|
|
|
||
|
|
For instance, to have a @code{htab_t} that points to trees, one should write
|
||
|
|
@verbatim
|
||
|
|
htab_t GTY ((param_is (union tree_node))) ict;
|
||
|
|
@end verbatim
|
||
|
|
|
||
|
|
@findex param@var{n}_is
|
||
|
|
@findex use_param@var{n}
|
||
|
|
@item param@var{n}_is
|
||
|
|
@itemx use_param@var{n}
|
||
|
|
|
||
|
|
In more complicated cases, the data structure might need to work on
|
||
|
|
several different types, which might not necessarily all be pointers.
|
||
|
|
For this, @code{param1_is} through @code{param9_is} may be used to
|
||
|
|
specify the real type of a field identified by @code{use_param1} through
|
||
|
|
@code{use_param9}.
|
||
|
|
|
||
|
|
@findex use_params
|
||
|
|
@item use_params
|
||
|
|
|
||
|
|
When a structure contains another structure that is parameterized,
|
||
|
|
there's no need to do anything special, the inner structure inherits the
|
||
|
|
parameters of the outer one. When a structure contains a pointer to a
|
||
|
|
parameterized structure, the type machinery won't automatically detect
|
||
|
|
this (it could, it just doesn't yet), so it's necessary to tell it that
|
||
|
|
the pointed-to structure should use the same parameters as the outer
|
||
|
|
structure. This is done by marking the pointer with the
|
||
|
|
@code{use_params} option.
|
||
|
|
|
||
|
|
@findex deletable
|
||
|
|
@item deletable
|
||
|
|
|
||
|
|
@code{deletable}, when applied to a global variable, indicates that when
|
||
|
|
garbage collection runs, there's no need to mark anything pointed to
|
||
|
|
by this variable, it can just be set to @code{NULL} instead. This is used
|
||
|
|
to keep a list of free structures around for re-use.
|
||
|
|
|
||
|
|
@findex if_marked
|
||
|
|
@item if_marked
|
||
|
|
|
||
|
|
Suppose you want some kinds of object to be unique, and so you put them
|
||
|
|
in a hash table. If garbage collection marks the hash table, these
|
||
|
|
objects will never be freed, even if the last other reference to them
|
||
|
|
goes away. GGC has special handling to deal with this: if you use the
|
||
|
|
@code{if_marked} option on a global hash table, GGC will call the
|
||
|
|
routine whose name is the parameter to the option on each hash table
|
||
|
|
entry. If the routine returns nonzero, the hash table entry will
|
||
|
|
be marked as usual. If the routine returns zero, the hash table entry
|
||
|
|
will be deleted.
|
||
|
|
|
||
|
|
The routine @code{ggc_marked_p} can be used to determine if an element
|
||
|
|
has been marked already; in fact, the usual case is to use
|
||
|
|
@code{if_marked ("ggc_marked_p")}.
|
||
|
|
|
||
|
|
@findex maybe_undef
|
||
|
|
@item maybe_undef
|
||
|
|
|
||
|
|
When applied to a field, @code{maybe_undef} indicates that it's OK if
|
||
|
|
the structure that this fields points to is never defined, so long as
|
||
|
|
this field is always @code{NULL}. This is used to avoid requiring
|
||
|
|
backends to define certain optional structures. It doesn't work with
|
||
|
|
language frontends.
|
||
|
|
|
||
|
|
@findex special
|
||
|
|
@item special
|
||
|
|
|
||
|
|
The @code{special} option is used for those bizarre cases that are just
|
||
|
|
too hard to deal with otherwise. Don't use it for new code.
|
||
|
|
|
||
|
|
@end table
|
||
|
|
|
||
|
|
@node GGC Roots
|
||
|
|
@section Marking Roots for the Garbage Collector
|
||
|
|
@cindex roots, marking
|
||
|
|
@cindex marking roots
|
||
|
|
|
||
|
|
In addition to keeping track of types, the type machinery also locates
|
||
|
|
the global variables that the garbage collector starts at. There are
|
||
|
|
two syntaxes it accepts to indicate a root:
|
||
|
|
|
||
|
|
@enumerate
|
||
|
|
@item
|
||
|
|
@verb{|extern GTY (([options])) [type] ID;|}
|
||
|
|
@item
|
||
|
|
@verb{|static GTY (([options])) [type] ID;|}
|
||
|
|
@end enumerate
|
||
|
|
|
||
|
|
These are the only syntaxes that are accepted. In particular, if you
|
||
|
|
want to mark a variable that is only declared as
|
||
|
|
@verbatim
|
||
|
|
int ID;
|
||
|
|
@end verbatim
|
||
|
|
or similar, you should either make it @code{static} or you should create
|
||
|
|
a @code{extern} declaration in a header file somewhere.
|
||
|
|
|
||
|
|
@node Files
|
||
|
|
@section Source Files Containing Type Information
|
||
|
|
@cindex generated files
|
||
|
|
@cindex files, generated
|
||
|
|
|
||
|
|
Whenever you add @code{GTY} markers to a new source file, there are three
|
||
|
|
things you need to do:
|
||
|
|
|
||
|
|
@enumerate
|
||
|
|
@item
|
||
|
|
You need to add the file to the list of source files the type
|
||
|
|
machinery scans. There are three cases:
|
||
|
|
|
||
|
|
@enumerate a
|
||
|
|
@item
|
||
|
|
For a back-end file, this is usually done
|
||
|
|
automatically; if not, you should add it to @code{target_gtfiles} in
|
||
|
|
the appropriate port's entries in @file{config.gcc}.
|
||
|
|
|
||
|
|
@item
|
||
|
|
For files shared by all front ends, this is done by adding the
|
||
|
|
filename to the @code{GTFILES} variable in @file{Makefile.in}.
|
||
|
|
|
||
|
|
@item
|
||
|
|
For any other file used by a front end, this is done by adding the
|
||
|
|
filename to the @code{gtfiles} variable defined in
|
||
|
|
@file{config-lang.in}. For C, the file is @file{c-config-lang.in}.
|
||
|
|
This list should include all files that have GTY macros in them that
|
||
|
|
are used in that front end, other than those defined in the previous
|
||
|
|
list items. For example, it is common for front end writers to use
|
||
|
|
@file{c-common.c} and other files from the C front end, and these
|
||
|
|
should be included in the @file{gtfiles} variable for such front ends.
|
||
|
|
|
||
|
|
@end enumerate
|
||
|
|
|
||
|
|
@item
|
||
|
|
If the file was a header file, you'll need to check that it's included
|
||
|
|
in the right place to be visible to the generated files. For a back-end
|
||
|
|
header file, this should be done automatically. For a front-end header
|
||
|
|
file, it needs to be included by the same file that includes
|
||
|
|
@file{gtype-@var{lang}.h}. For other header files, it needs to be
|
||
|
|
included in @file{gtype-desc.c}, which is a generated file, so add it to
|
||
|
|
@code{ifiles} in @code{open_base_file} in @file{gengtype.c}.
|
||
|
|
|
||
|
|
For source files that aren't header files, the machinery will generate a
|
||
|
|
header file that should be included in the source file you just changed.
|
||
|
|
The file will be called @file{gt-@var{path}.h} where @var{path} is the
|
||
|
|
pathname relative to the @file{gcc} directory with slashes replaced by
|
||
|
|
@verb{|-|}, so for example the header file to be included in
|
||
|
|
@file{objc/objc-parse.c} is called @file{gt-objc-objc-parse.c}. The
|
||
|
|
generated header file should be included after everything else in the
|
||
|
|
source file. Don't forget to mention this file as a dependency in the
|
||
|
|
@file{Makefile}!
|
||
|
|
|
||
|
|
@item
|
||
|
|
If a new @file{gt-@var{path}.h} file is needed, you need to arrange to
|
||
|
|
add a @file{Makefile} rule that will ensure this file can be built.
|
||
|
|
This is done by making it a dependency of @code{s-gtype}, like this:
|
||
|
|
@verbatim
|
||
|
|
gt-path.h : s-gtype ; @true
|
||
|
|
@end verbatim
|
||
|
|
@end enumerate
|
||
|
|
|
||
|
|
For language frontends, there is another file that needs to be included
|
||
|
|
somewhere. It will be called @file{gtype-@var{lang}.h}, where
|
||
|
|
@var{lang} is the name of the subdirectory the language is contained in.
|
||
|
|
It will need @file{Makefile} rules just like the other generated files.
|