Re: [RFC] Preliminary target abstraction patch

["Joseph S. Myers" <jsm28 at cam dot ac dot uk>]

On Thu, 21 Jun 2001, Neil Booth wrote:

> This is an initial version of a patch to get the target framework in
> place.  It puts 4 functions into a "gcc_target" structure, with an
> external instance of that structure called "target".  arm is the most
> interesting target - 3 of the 4 are overridden.

As promised, here is the corresponding documentation patch.

--- gcc.texi.orig	Thu Jun 21 18:23:08 2001
+++ gcc.texi	Thu Jun 21 18:37:38 2001
@@ -266,7 +266,7 @@
 * Trees::           The source representation used by the C and C++ front ends.
 * RTL::             The intermediate representation that most passes work on.
 * Machine Desc::    How to write machine description instruction patterns.
-* Target Macros::   How to write the machine description C macros.
+* Target Macros::   How to write the machine description C macros and functions.
 * Config::          Writing the @file{xm-@var{machine}.h} file.
 * Fragments::       Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
 @end ifset
--- tm.texi.orig	Thu Jun 21 18:23:08 2001
+++ tm.texi	Thu Jun 21 19:09:22 2001
@@ -4,7 +4,7 @@
 @c For copying conditions, see the file gcc.texi.
 
 @node Target Macros
-@chapter Target Description Macros
+@chapter Target Description Macros and Functions
 @cindex machine description macros
 @cindex target description macros
 @cindex macros, target description
@@ -12,14 +12,19 @@
 
 In addition to the file @file{@var{machine}.md}, a machine description
 includes a C header file conventionally given the name
-@file{@var{machine}.h}.  This header file defines numerous macros
+@file{@var{machine}.h} and a C source file named @file{@var{machine}.c}.
+The header file defines numerous macros
 that convey the information about the target machine that does not fit
 into the scheme of the @file{.md} file.  The file @file{tm.h} should be
 a link to @file{@var{machine}.h}.  The header file @file{config.h}
 includes @file{tm.h} and most compiler source files include
-@file{config.h}.
+@file{config.h}.  The source file defines a variable @code{target},
+which is a structure containing pointers to functions and data relating
+to the target machine, as well as those functions and data and other
+functions called from macros defined in the @file{.h} file.
 
 @menu
+* Target Structure::    The @code{target} variable.
 * Driver::              Controlling how the driver runs the compilation passes.
 * Run-time Target::     Defining @samp{-m} options like @option{-m68000} and @option{-m68020}.
 * Per-Function Data::   Defining data structures for per-function information.
@@ -43,6 +48,38 @@
 * Misc::                Everything else.
 @end menu
 
+@node Target Structure
+@section The Global @code{target} Variable
+@cindex target hooks
+@cindex target functions
+
+@deftypevar {struct gcc_target} target
+The target @file{.c} file must define the global @code{target} variable
+which contains pointers to functions and data relating to the target
+machine.  The variable is declared in @file{target.h};
+@file{target-def.h} defines the macro @code{TARGET_INITIALIZER} which is
+used to initialize the variable, and macros for the default initializers
+for elements of the structure.  The @file{.c} file should override those
+macros for which the default definition is inappropriate.  For example:
+@smallexample
+#include "target.h"
+#include "target-def.h"
+
+/* @r{Initialize the GCC target structure.}  */
+
+#undef TARGET_VALID_TYPE_ATTRIBUTE
+#define TARGET_VALID_TYPE_ATTRIBUTE @var{machine}_valid_type_attribute_p
+
+struct gcc_target target = TARGET_INITIALIZER;
+@end smallexample
+@end deftypevar
+
+Where a macro should be defined in the @file{.c} file in this manner to
+form part of the @code{target} structure, it is documented below as a
+``Target Hook'' with a prototype.  Many macros will change in future
+from being defined in the @file{.h} file to being part of the
+@code{target} structure.
+
 @node Driver
 @section Controlling the Compilation Driver, @file{gcc}
 @cindex driver
@@ -8204,19 +8241,21 @@
 invocations of this pragma cause the previous values to be stacked, so
 that invocations of @samp{#pragma pack(pop)} will return to the previous
 value.
+@end table
 
-@findex VALID_MACHINE_DECL_ATTRIBUTE
-@item VALID_MACHINE_DECL_ATTRIBUTE (@var{decl}, @var{attributes}, @var{identifier}, @var{args})
-If defined, a C expression whose value is nonzero if @var{identifier} with
+@deftypefn {Target Hook} int TARGET_VALID_DECL_ATTRIBUTE (tree @var{decl}, tree @var{attributes}, tree @var{identifier}, tree @var{args})
+If defined, this target hook is a function which returns nonzero if @var{identifier} with
 arguments @var{args} is a valid machine specific attribute for @var{decl}.
 The attributes in @var{attributes} have previously been assigned to @var{decl}.
+@end deftypefn
 
-@findex VALID_MACHINE_TYPE_ATTRIBUTE
-@item VALID_MACHINE_TYPE_ATTRIBUTE (@var{type}, @var{attributes}, @var{identifier}, @var{args})
-If defined, a C expression whose value is nonzero if @var{identifier} with
+@deftypefn {Target Hook} int TARGET_VALID_TYPE_ATTRIBUTE (tree @var{type}, tree @var{attributes}, tree @var{identifier}, tree @var{args})
+If defined, this target hook is a function which returns nonzero if @var{identifier} with
 arguments @var{args} is a valid machine specific attribute for @var{type}.
 The attributes in @var{attributes} have previously been assigned to @var{type}.
+@end deftypefn
 
+@table @code
 @findex COMP_TYPE_ATTRIBUTES
 @item COMP_TYPE_ATTRIBUTES (@var{type1}, @var{type2})
 If defined, a C expression whose value is zero if the attributes on
@@ -8228,23 +8267,28 @@
 @item SET_DEFAULT_TYPE_ATTRIBUTES (@var{type})
 If defined, a C statement that assigns default attributes to
 newly defined @var{type}.
+@end table
 
-@findex MERGE_MACHINE_TYPE_ATTRIBUTES
-@item MERGE_MACHINE_TYPE_ATTRIBUTES (@var{type1}, @var{type2})
-Define this macro if the merging of type attributes needs special handling.
-If defined, the result is a list of the combined TYPE_ATTRIBUTES of
-@var{type1} and @var{type2}.  It is assumed that comptypes has already been
-called and returned 1.
-
-@findex MERGE_MACHINE_DECL_ATTRIBUTES
-@item MERGE_MACHINE_DECL_ATTRIBUTES (@var{olddecl}, @var{newdecl})
-Define this macro if the merging of decl attributes needs special handling.
-If defined, the result is a list of the combined DECL_MACHINE_ATTRIBUTES of
-@var{olddecl} and @var{newdecl}.  @var{newdecl} is a duplicate declaration
-of @var{olddecl}.  Examples of when this is needed are when one attribute
-overrides another, or when an attribute is nullified by a subsequent
-definition.
+@deftypefn {Target Hook} tree TARGET_MERGE_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2})
+Define this target hook if the merging of type attributes needs special
+handling.  If defined, the result is a list of the combined
+@code{TYPE_ATTRIBUTES} of @var{type1} and @var{type2}.  It is assumed
+that @code{comptypes} has already been called and returned 1.  This
+function may call @code{merge_attributes} to handle machine-independent
+merging.
+@end deftypefn
+
+@deftypefn {Target Hook} tree TARGET_MERGE_DECL_ATTRIBUTES (tree @var{olddecl}, tree @var{newdecl})
+Define this target hook if the merging of decl attributes needs special
+handling.  If defined, the result is a list of the combined
+@code{DECL_MACHINE_ATTRIBUTES} of @var{olddecl} and @var{newdecl}.
+@var{newdecl} is a duplicate declaration of @var{olddecl}.  Examples of
+when this is needed are when one attribute overrides another, or when an
+attribute is nullified by a subsequent definition.  This function may
+call @code{merge_attributes} to handle machine-independent merging.
+@end deftypefn
 
+@table @code
 @findex INSERT_ATTRIBUTES
 @item INSERT_ATTRIBUTES (@var{node}, @var{attr_ptr}, @var{prefix_ptr})
 Define this macro if you want to be able to add attributes to a decl

-- 
Joseph S. Myers
jsm28@cam.ac.uk