Merge from pch-branch up to tag pch-commit-20020603.

git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@54232 138bc75d-0d04-0410-961f-82ee72b054a4

3 files changed, 265 insertions, 18 deletions

diff --git a/gcc/doc/gccint.texi b/gcc/doc/gccint.texi
index 82a7d317a40..35bd02cc21a 100644
--- a/gcc/doc/gccint.texi
+++ b/gcc/doc/gccint.texi
@@ -169,6 +169,7 @@ Additional tutorial information is linked to from
 * Fragments::       Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
 * Collect2::        How @code{collect2} works; how it finds @code{ld}.
 * Header Dirs::     Understanding the standard header file directories.
+* Type Information:: GCC's memory management; generating type information.
 
 * Funding::         How to help assure funding for free software.
 * GNU Project::     The GNU Project and GNU/Linux.
@@ -196,6 +197,7 @@ Additional tutorial information is linked to from
 @include fragments.texi
 @include collect2.texi
 @include headerdirs.texi
+@include gty.texi
 
 @include funding.texi
 @include gnu.texi
diff --git a/gcc/doc/gty.texi b/gcc/doc/gty.texi
new file mode 100644
index 00000000000..132cd415fa1
--- /dev/null
+++ b/gcc/doc/gty.texi
@@ -0,0 +1,257 @@
+@c Copyright (C) 2002
+@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.
+@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:
+@verbatim
+  tree * GTY ((length ("%h.regno_pointer_align_length"))) regno_decl;
+@end verbatim
+In this case, @code{regno_decl} has been allocated by writing something like
+@verbatim
+  x->regno_decl = ggc_alloc (x->regno_pointer_align_length * sizeof (tree));
+@end verbatim
+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 always
+@item desc
+@itemx tag
+@itemx always
+
+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,
+@verbatim
+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 verbatim
+
+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.)
+
+You can use @code{always} to mean that this field is always used.
+
+@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 specific types.
+@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 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
+
+@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.  For a back-end file, this is done automatically.  For a
+front-end file, this is done by adding the filename to the
+@code{gtfiles} variable defined in @file{config-lang.in}.  For other
+files, this is done by adding the filename to the @code{GTFILES} variable
+in @file{Makefile.in}.
+
+@item
+You need to include the file that the type machinery will generate in
+the source file you just changed.  The file will be called
+@file{gt-@var{path}.h} where @var{path} is the pathname from the
+@file{gcc} directory with slashes replaced by @verb{|-|}.  Don't forget
+to mention this file as a dependency in the @file{Makefile}!
+
+@item
+Finally, you need 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.
diff --git a/gcc/doc/tm.texi b/gcc/doc/tm.texi
index cc87da63325..45a65ce25d7 100644
--- a/gcc/doc/tm.texi
+++ b/gcc/doc/tm.texi
@@ -824,11 +824,9 @@ structure contains a field called @code{machine} whose type is
 to their own specific data.
 
 If a target needs per-function specific data it should define the type
-@code{struct machine_function} and also the macro
-@code{INIT_EXPANDERS}.  This macro should be used to initialize some or
-all of the function pointers @code{init_machine_status},
-@code{free_machine_status} and @code{mark_machine_status}.  These
-pointers are explained below.
+@code{struct machine_function} and also the macro @code{INIT_EXPANDERS}.
+This macro should be used to initialize the function pointer
+@code{init_machine_status}.  This pointer is explained below.
 
 One typical use of per-function, target specific data is to create an
 RTX to hold the register containing the function's return address.  This
@@ -864,19 +862,9 @@ specific initialization of the @code{struct function} structure.  It is
 intended that this would be used to initialize the @code{machine} of
 that structure.
 
-@findex free_machine_status
-@item   free_machine_status
-This is a @code{void (*)(struct function *)} function pointer.  If this
-pointer is non-@code{NULL} it will be called once per function, after the
-function has been compiled, in order to allow any memory allocated
-during the @code{init_machine_status} function call to be freed.
-
-@findex mark_machine_status
-@item   mark_machine_status
-This is a @code{void (*)(struct function *)} function pointer.  If this
-pointer is non-@code{NULL} it will be called once per function in order to mark
-any data items in the @code{struct machine_function} structure which
-need garbage collection.
+@code{struct machine_function} structures are expected to be freed by GC.
+Generally, any memory that they reference must be allocated by using
+@code{ggc_alloc}, including the structure itself.
 
 @end table