[PCH] internal docs

[PCH] internal docs

[Geoffrey Keating]

This updates the internals documentation for PCH.

Tested with 'make info' on powerpc-eabisim.

-- 
- Geoffrey Keating <geoffk@apple.com>

===File ~/patches/pchbranch-pchintdoc.patch=================
2002-12-14  Geoffrey Keating  <geoffk@apple.com>

	* doc/gty.texi (GTY Options): Document chain_next, chain_prev,
	reorder options.
	(Type Information): Mention that the information is also
	used to implement PCH.
	* doc/passes.texi (Passes): Improve documentation of
	language-specific files.

Index: doc/gty.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/gty.texi,v
retrieving revision 1.1.2.9
diff -u -p -u -p -r1.1.2.9 gty.texi
--- doc/gty.texi	25 Sep 2002 19:17:49 -0000	1.1.2.9
+++ doc/gty.texi	19 Dec 2002 05:45:16 -0000
@@ -10,7 +10,8 @@
 
 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.
+source code and using this information to perform garbage collection and
+implement precompiled headers.
 
 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
@@ -226,6 +227,39 @@ the structure that this fields points to
 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 chain_next
+@findex chain_prev
+@item chain_next
+@itemx chain_prev
+
+It's helpful for the type machinery to know if objects are often
+chained together in long lists; this lets it generate code that uses
+less stack space by iterating along the list instead of recursing down
+it.  @code{chain_next} is an expression for the next item in the list,
+@code{chain_prev} is an expression for the previous item.  The
+machinery requires that taking the next item of the previous item
+gives the original item.
+
+@findex reorder
+@item reorder
+
+Some data structures depend on the relative ordering of pointers.  If
+the type machinery needs to change that ordering, it will call the
+function referenced by the @code{reorder} option, before changing the
+pointers in the object that's pointed to by the field the option
+applies to.  The function must be of the type @code{void ()(void *,
+void *, gt_pointer_operator, void *)}.  The second parameter is the
+pointed-to object; the third parameter is a routine that, given a
+pointer, can update it to its new value.  The fourth parameter is a
+cookie to be passed to the third parameter.  The first parameter is
+the structure that contains the object, or the object itself if it is
+a structure.
+
+No data structure may depend on the absolute value of pointers.  Even
+relying on relative orderings and using @code{reorder} functions can
+be expensive.  It is better to depend on properties of the data, like
+an ID number or the hash of a string instead.
 
 @findex special
 @item special
Index: doc/passes.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/passes.texi,v
retrieving revision 1.6.6.4
diff -u -p -u -p -r1.6.6.4 passes.texi
--- doc/passes.texi	13 Aug 2002 17:57:43 -0000	1.6.6.4
+++ doc/passes.texi	19 Dec 2002 05:45:16 -0000
@@ -1,4 +1,4 @@
-@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
+@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2002,
 @c 1999, 2000, 2001 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
@@ -73,54 +73,22 @@ performed by cpplib, which is covered in
 particular, the internals are covered in @xref{Top, ,Cpplib internals,
 cppinternals, Cpplib Internals}.
 
-@c Avoiding overfull is tricky here.
-The source files to parse C are
-@file{c-convert.c},
-@file{c-decl.c},
-@file{c-errors.c},
-@file{c-lang.c},
-@file{c-objc-common.c},
-@file{c-parse.in},
-@file{c-aux-info.c},
-and
-@file{c-typeck.c},
-along with a header file
-@file{c-tree.h}
-and some files shared with Objective-C and C++.
-
-The source files for parsing C++ are in @file{cp/}.
-They are @file{parse.y},
-@file{class.c},
-@file{cvt.c}, @file{decl.c}, @file{decl2.c},
-@file{except.c},
-@file{expr.c}, @file{init.c}, @file{lex.c},
-@file{method.c}, @file{ptree.c},
-@file{search.c}, @file{spew.c},
-@file{semantics.c}, @file{tree.c},
-@file{typeck2.c}, and
-@file{typeck.c}, along with header files @file{cp-tree.def},
-@file{cp-tree.h}, and @file{decl.h}.
-
-The special source files for parsing Objective-C are in @file{objc/}.
-They are @file{objc-act.c}, @file{objc-tree.def}, and @file{objc-act.h}.
-Certain C-specific files are used for this as well.
-
-The files
-@file{c-common.c},
+The source files to parse C are found in the toplevel directory, and
+by convention are named @file{c-*}.  Some of these are also used by
+the other C-like languages: @file{c-common.c},
 @file{c-common.def},
 @file{c-format.c},
 @file{c-opts.c},
 @file{c-pragma.c},
 @file{c-semantics.c},
-and
 @file{c-lex.c},
-along with header files
 @file{c-common.h},
 @file{c-dump.h},
 and
 @file{c-pragma.h},
-are also used for all of the above languages.
 
+Files specific to each language are in subdirectories named after the
+language in question, like @file{ada}, @file{objc}, @file{cp} (for C++).
 
 @cindex Tree optimization
 @item
============================================================