better explain $target.h vs $target-protos.h in internals manual

Message ID 3a12166e-783a-70d3-4d13-22eb7e6ce573@codesourcery.com
State New
Headers show
Series
  • better explain $target.h vs $target-protos.h in internals manual
Related show

Commit Message

Sandra Loosemore Feb. 26, 2018, 1:49 a.m.
Following up on discussion in gcc@, how does this documentation patch look?

https://gcc.gnu.org/ml/gcc/2018-02/msg00139.html

-Sandra

Comments

Richard Sandiford Feb. 27, 2018, 7:20 p.m. | #1
Sandra Loosemore <sandra@codesourcery.com> writes:
> Following up on discussion in gcc@, how does this documentation patch look?

>

> https://gcc.gnu.org/ml/gcc/2018-02/msg00139.html


Looks good to me FWIW.

Richard

Patch

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