Following up on discussion in gcc@, how does this documentation patch look?
https://gcc.gnu.org/ml/gcc/2018-02/msg00139.html
-Sandra
2018-02-25 Sandra Loosemore <san...@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.
Index: gcc/doc/configfiles.texi
===================================================================
--- gcc/doc/configfiles.texi (revision 257967)
+++ gcc/doc/configfiles.texi (working copy)
@@ -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.
Index: gcc/doc/sourcebuild.texi
===================================================================
--- gcc/doc/sourcebuild.texi (revision 257967)
+++ gcc/doc/sourcebuild.texi (working copy)
@@ -822,6 +822,23 @@ manual needs to be installed as info for
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
