Remove {save|restore}_machine_status.

Document {init|mark|free}_machine_status.

From-SVN: r38882

gcc/ChangeLog

+2001-01-10  Nick Clifton  <nickc@redhat.com>
+
+	* function.h (save_machine_status): Delete.
+	(restore_machine_status): Delete.
+	Amend comment describing {init|mark|free}_machine_status.
+
+	* function.c (save_machine_status): Delete.
+	(restore_machine_status): Delete.
+	Amend comment describing {init|mark|free}_machine_status.
+	(push_function_context_to): Remove invocation of
+	save_machine_status.
+	(pop_function_context_from): Remove invocation of
+	restore_machine_status.
+
+	* emit-rtl.c (init_emit_once): Amend comment describing
+	{init|mark|free}_machine_status. 
+
+	* tm.texi (Per-Function Data): New node.  Describe the
+	INIT_EXPANDERS macro and the {init|mark|free}_machine_status
+	function pointers.
+
 2001-01-10  Neil Booth  <neil@daikokuya.demon.co.uk>
 
         * cppinit.c (OPT_g): Remove.

gcc/emit-rtl.c

@@ -4080,9 +4080,9 @@ init_emit_once (line_numbers)
   ggc_add_rtx_root (global_rtl, GR_MAX);
 
 #ifdef INIT_EXPANDERS
-  /* This is to initialize save_machine_status and restore_machine_status before
-     the first call to push_function_context_to.  This is needed by the Chill
-     front end which calls push_function_context_to before the first cal to
+  /* This is to initialize {init|mark|free}_machine_status before the first
+     call to push_function_context_to.  This is needed by the Chill front
+     end which calls push_function_context_to before the first cal to
      init_function_start.  */
   INIT_EXPANDERS;
 #endif

gcc/function.c

@@ -129,14 +129,14 @@ int current_function_uses_only_leaf_regs;
    assign_stack_local uses frame_pointer_rtx when this is nonzero.  */
 static int virtuals_instantiated;
 
-/* These variables hold pointers to functions to
-   save and restore machine-specific data,
-   in push_function_context and pop_function_context.  */
+/* These variables hold pointers to functions to create and destroy
+   target specific, per-function data structures.  */
 void (*init_machine_status) PARAMS ((struct function *));
-void (*save_machine_status) PARAMS ((struct function *));
-void (*restore_machine_status) PARAMS ((struct function *));
-void (*mark_machine_status) PARAMS ((struct function *));
 void (*free_machine_status) PARAMS ((struct function *));
+/* This variable holds a pointer to a function to register any
+   data items in the target specific, per-function data structure
+   that will need garbage collection.  */
+void (*mark_machine_status) PARAMS ((struct function *));
 
 /* Likewise, but for language-specific data.  */
 void (*init_lang_status) PARAMS ((struct function *));
@@ -358,8 +358,6 @@ push_function_context_to (context)
 
   if (save_lang_status)
     (*save_lang_status) (p);
-  if (save_machine_status)
-    (*save_machine_status) (p);
 
   cfun = 0;
 }
@@ -389,8 +387,6 @@ pop_function_context_from (context)
 
   restore_emit_status (p);
 
-  if (restore_machine_status)
-    (*restore_machine_status) (p);
   if (restore_lang_status)
     (*restore_lang_status) (p);
 

gcc/function.h

@@ -556,14 +556,14 @@ extern HOST_WIDE_INT get_frame_size	PARAMS ((void));
 /* Likewise, but for a different than the current function.  */
 extern HOST_WIDE_INT get_func_frame_size	PARAMS ((struct function *));
 
-/* These variables hold pointers to functions to
-   save and restore machine-specific data,
-   in push_function_context and pop_function_context.  */
+/* These variables hold pointers to functions to create and destroy
+   target specific, per-function data structures.  */
 extern void (*init_machine_status)	PARAMS ((struct function *));
-extern void (*mark_machine_status)	PARAMS ((struct function *));
-extern void (*save_machine_status)	PARAMS ((struct function *));
-extern void (*restore_machine_status)	PARAMS ((struct function *));
 extern void (*free_machine_status)	PARAMS ((struct function *));
+/* This variable holds a pointer to a function to register any
+   data items in the target specific, per-function data structure
+   that will need garbage collection.  */
+extern void (*mark_machine_status)	PARAMS ((struct function *));
 
 /* Likewise, but for language-specific data.  */
 extern void (*init_lang_status)         PARAMS ((struct function *));

gcc/tm.texi

@@ -22,6 +22,7 @@ includes @file{tm.h} and most compiler source files include
 @menu
 * Driver::              Controlling how the driver runs the compilation passes.
 * Run-time Target::     Defining @samp{-m} options like @samp{-m68000} and @samp{-m68020}.
+* Per-Function Data::   Defining data structures for per-function information.
 * Storage Layout::      Defining sizes and alignments of data.
 * Type Layout::         Defining sizes and properties of basic user data types.
 * Registers::           Naming and describing the hardware registers.
@@ -704,6 +705,80 @@ pointer.  If this macro is defined, GCC will turn on the
 @samp{-fomit-frame-pointer} option whenever @samp{-O} is specified.
 @end table
 
+@node Per-Function Data
+@section Defining data structures for per-function information.
+@cindex per-function data
+@cindex data structures
+
+If the target needs to store information on a per-function basis, GCC
+provides a macro and a couple of variables to allow this.  Note, just
+using statics to store the information is a bad idea, since GCC supports
+nested functions, so you can be halfway through encoding one function
+when another one comes along.
+
+GCC defines a data structure called @code{struct function} which
+contains all of the data specific to an individual function.  This
+structure contains a field called @code{machine} whose type is
+@code{struct machine_function *}, which can be used by targets to point
+to their own specific data.
+
+If a target needs per-function specific data it should define the type
+@code{struct machine_function} and also the macro
+@code{INIT_EXPANDERS}.  This macro should be used to initialise some or
+all of the function pointers @code{init_machine_status},
+@code{free_machine_status} and @code{mark_machine_status}.  These
+pointers are explained below. 
+
+One typical use of per-function, target specific data is to create an
+RTX to hold the register containing the function's return address.  This
+RTX can then be used to implement the @code{__builtin_return_address}
+function, for level 0.
+
+Note - earlier implementations of GCC used a single data area to hold
+all of the per-function information.  Thus when processing of a nested
+function began the old per-function data had to be pushed onto a
+stack, and when the processing was finished, it had to be popped off the
+stack.  GCC used to provide function pointers called
+@code{save_machine_status} and @code{restore_machine_status} to handle 
+the saving and restoring of the target specific information.  Since the
+single data area approach is no longer used, these pointers are no
+longer supported.
+
+The macro and function pointers are described below.
+
+@table @code
+@findex INIT_EXPANDERS
+@item   INIT_EXPANDERS
+Macro called to initialise any target specific information.  This macro
+is called once per function, before generation of any RTL has begun.
+The intention of this macro is to allow the initialisation of the
+function pointers below.
+
+@findex init_machine_status
+@item   init_machine_status
+This is a @code{void (*)(struct function *)} function pointer.  If this
+pointer is non-NULL it will be called once per function, before function
+compilation starts, in order to allow the target to perform any target
+specific initialisation of the @code{struct function} structure.  It is
+intended that this would be used to initialise the @code{machine} of
+that struture.
+
+@findex free_machine_status
+@item   free_machine_status
+This is a @code{void (*)(struct function *)} function pointer.  If this
+pointer is non-NULL it will be called once per function, after the
+function has been compiled, in order to allow any memory allocated
+during the @code{init_machine_status} function call to be freed.
+
+@findex mark_machine_status
+@item   mark_machine_status
+This is a @code{void (*)(struct function *)} function pointer.  If this
+pointer is non-NULL it will be called once per function in order to mark
+any data items in the @code{struct machine_function} structure which
+need garbage collection.
+
+@end table
+
 @node Storage Layout
 @section Storage Layout
 @cindex storage layout