configfiles.texi (Configuration Files): Move info about conditionalizing $target-protos.h to...

2018-03-05  Sandra Loosemore  <sandra@codesourcery.com>

	gcc/
	* doc/configfiles.texi (Configuration Files): Move info about
	conditionalizing $target-protos.h to...
	* doc/sourcebuild.texi (Back End): Here.  Explain how $target.h
	differs from $target-protos.h.

From-SVN: r258240

3 files changed, 28 insertions, 6 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 4daf25f..bd2c768 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,10 @@
+2018-03-05  Sandra Loosemore  <sandra@codesourcery.com>
+
+	* doc/configfiles.texi (Configuration Files): Move info about
+	conditionalizing $target-protos.h to...
+	* doc/sourcebuild.texi (Back End): Here.  Explain how $target.h
+	differs from $target-protos.h.
+
 2018-03-05  Kito Cheng  <kito.cheng@gmail.com>
 	    Chung-Ju Wu  <jasonwucj@gmail.com>
 
diff --git a/gcc/doc/configfiles.texi b/gcc/doc/configfiles.texi
index 91045bd..fcd1d99 100644
--- a/gcc/doc/configfiles.texi
+++ b/gcc/doc/configfiles.texi
@@ -59,12 +59,10 @@ machine.
 @item
 @file{tm_p.h}, which includes the header @file{@var{machine}-protos.h}
 that contains prototypes for functions in the target
-@file{@var{machine}.c} file.  The header @file{@var{machine}-protos.h}
-can include prototypes of functions that use rtl and tree data
-structures inside appropriate @code{#ifdef RTX_CODE} and @code{#ifdef
-TREE_CODE} conditional code segements.  The
-@file{@var{machine}-protos.h} is included after the @file{rtl.h}
-and/or @file{tree.h} would have been included.  The @file{tm_p.h} also
+@file{@var{machine}.c} file.  The
+@file{@var{machine}-protos.h} header is included after the @file{rtl.h}
+and/or @file{tree.h} would have been included.
+The @file{tm_p.h} also
 includes the header @file{tm-preds.h} which is generated by
 @file{genpreds} program during the build to define the declarations
 and inline functions for the predicate functions.
diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi
index bf44d15..b9672ca 100644
--- a/gcc/doc/sourcebuild.texi
+++ b/gcc/doc/sourcebuild.texi
@@ -822,6 +822,23 @@ manual needs to be installed as info for this to work, or to be a
 chapter of this manual.
 @end itemize
 
+The @file{@var{machine}.h} header is included very early in GCC's
+standard sequence of header files, while @file{@var{machine}-protos.h}
+is included late in the sequence.  Thus @file{@var{machine}-protos.h}
+can include declarations referencing types that are not defined when
+@file{@var{machine}.h} is included, specifically including those from
+@file{rtl.h} and @file{tree.h}.  Since both RTL and tree types may not
+be available in every context where @file{@var{machine}-protos.h} is
+included, in this file you should guard declarations using these types
+inside appropriate @code{#ifdef RTX_CODE} or @code{#ifdef TREE_CODE}
+conditional code segments.
+
+If the backend uses shared data structures that require @code{GTY} markers 
+for garbage collection (@pxref{Type Information}), you must declare those
+in @file{@var{machine}.h} rather than @file{@var{machine}-protos.h}.  
+Any definitions required for building libgcc must also go in
+@file{@var{machine}.h}.
+
 GCC uses the macro @code{IN_TARGET_CODE} to distinguish between
 machine-specific @file{.c} and @file{.cc} files and
 machine-independent @file{.c} and @file{.cc} files.  Machine-specific