[patch rfc; rfa:doco] Deprecate save_dummy_frame_tos

[Andrew Cagney <ac131313 at redhat dot com>]

Made redundant by UNWIND_DUMMY_ID and PUSH_DUMMY_CALL.

I'll commit in a few days,
Andrew

Index: doc/ChangeLog
2003-06-13  Andrew Cagney  <cagney@redhat.com>

	* gdbint.texinfo (Target Architecture Definition): Deprecate
	SAVE_DUMMY_FRAME_TOS.  Update description of "unwind_dummy_id".

2003-06-13  Andrew Cagney  <cagney@redhat.com>

	* gdbarch.sh (SAVE_DUMMY_FRAME_TOS): Deprecate.
	* gdbarch.h, gdbarch.c: Re-generate.
	* xstormy16-tdep.c (xstormy16_gdbarch_init): Update.
	* s390-tdep.c (s390_gdbarch_init): Update.
	* rs6000-tdep.c (rs6000_gdbarch_init): Update.
	* mn10300-tdep.c (mn10300_gdbarch_init): Update.
	* mips-tdep.c (mips_gdbarch_init): Update.
	* mcore-tdep.c (mcore_gdbarch_init): Update.
	* cris-tdep.c (cris_gdbarch_init): Update.
	* infcall.c (call_function_by_hand): Update.
	* ia64-tdep.c (ia64_push_arguments): Update comment.
	* frame.c (legacy_get_prev_frame): Do not assume
	SAVE_DUMMY_FRAME_TOS_P.
	* dummy-frame.c (find_dummy_frame): Update comment.

Index: cris-tdep.c
===================================================================
RCS file: /cvs/src/src/gdb/cris-tdep.c,v
retrieving revision 1.78
diff -u -r1.78 cris-tdep.c
--- cris-tdep.c	13 Jun 2003 04:40:31 -0000	1.78
+++ cris-tdep.c	13 Jun 2003 23:08:40 -0000
@@ -4295,7 +4295,7 @@
   set_gdbarch_deprecated_saved_pc_after_call (gdbarch, cris_saved_pc_after_call);
 
   /* Helpful for backtracing and returning in a call dummy.  */
-  set_gdbarch_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
+  set_gdbarch_deprecated_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
 
   /* Should be using push_dummy_call.  */
   set_gdbarch_deprecated_dummy_write_sp (gdbarch, deprecated_write_sp);
Index: dummy-frame.c
===================================================================
RCS file: /cvs/src/src/gdb/dummy-frame.c,v
retrieving revision 1.24
diff -u -r1.24 dummy-frame.c
--- dummy-frame.c	13 Jun 2003 20:37:27 -0000	1.24
+++ dummy-frame.c	13 Jun 2003 23:08:41 -0000
@@ -99,7 +99,7 @@
              FP against the saved SP and FP.  NOTE: If you're trying
              to fix a problem with GDB not correctly finding a dummy
              frame, check the comments that go with FRAME_ALIGN() and
-             SAVE_DUMMY_FRAME_TOS().  */
+             UNWIND_DUMMY_ID().  */
 	  if (fp != dummyframe->fp && fp != dummyframe->sp)
 	    continue;
 	}
Index: frame.c
===================================================================
RCS file: /cvs/src/src/gdb/frame.c,v
retrieving revision 1.122
diff -u -r1.122 frame.c
--- frame.c	13 Jun 2003 20:37:27 -0000	1.122
+++ frame.c	13 Jun 2003 23:08:43 -0000
@@ -1373,10 +1373,6 @@
 	     or some random address on the stack.  Trying to use that
 	     PC to apply standard frame ID unwind techniques is just
 	     asking for trouble.  */
-	  /* Assume call_function_by_hand(), via SAVE_DUMMY_FRAME_TOS,
-	     previously saved the dummy frame's ID.  Things only work
-	     if the two return the same value.  */
-	  gdb_assert (SAVE_DUMMY_FRAME_TOS_P ());
 	  /* Use an architecture specific method to extract the prev's
 	     dummy ID from the next frame.  Note that this method uses
 	     frame_register_unwind to obtain the register values
Index: gdbarch.sh
===================================================================
RCS file: /cvs/src/src/gdb/gdbarch.sh,v
retrieving revision 1.249
diff -u -r1.249 gdbarch.sh
--- gdbarch.sh	13 Jun 2003 23:07:06 -0000	1.249
+++ gdbarch.sh	13 Jun 2003 23:12:58 -0000
@@ -503,7 +503,7 @@
 M::UNWIND_DUMMY_ID:struct frame_id:unwind_dummy_id:struct frame_info *info:info::0:0
 # Implement UNWIND_DUMMY_ID and PUSH_DUMMY_CALL, then delete
 # SAVE_DUMMY_FRAME_TOS.
-F:2:SAVE_DUMMY_FRAME_TOS:void:save_dummy_frame_tos:CORE_ADDR sp:sp::0:0
+F:2:DEPRECATED_SAVE_DUMMY_FRAME_TOS:void:deprecated_save_dummy_frame_tos:CORE_ADDR sp:sp
 # Implement UNWIND_DUMMY_ID and PUSH_DUMMY_CALL, then delete
 # DEPRECATED_FP_REGNUM.
 v:2:DEPRECATED_FP_REGNUM:int:deprecated_fp_regnum::::-1:-1::0
Index: ia64-tdep.c
===================================================================
RCS file: /cvs/src/src/gdb/ia64-tdep.c,v
retrieving revision 1.87
diff -u -r1.87 ia64-tdep.c
--- ia64-tdep.c	13 Jun 2003 04:40:32 -0000	1.87
+++ ia64-tdep.c	13 Jun 2003 23:08:55 -0000
@@ -2002,14 +2002,15 @@
   /* Sync gdb's idea of what the registers are with the target. */
   target_store_registers (-1);
 
-  /* FIXME: This doesn't belong here!  Instead, SAVE_DUMMY_FRAME_TOS needs
-     to be defined to call generic_save_dummy_frame_tos().  But at the
-     time of this writing, SAVE_DUMMY_FRAME_TOS wasn't gdbarch'd, so
-     I chose to put this call here instead of using the old mechanisms. 
-     Once SAVE_DUMMY_FRAME_TOS is gdbarch'd, all we need to do is add the
-     line
+  /* FIXME: This doesn't belong here!  Instead,
+     DEPRECATED_SAVE_DUMMY_FRAME_TOS needs to be defined to call
+     generic_save_dummy_frame_tos().  But at the time of this writing,
+     DEPRECATED_SAVE_DUMMY_FRAME_TOS wasn't gdbarch'd, so I chose to
+     put this call here instead of using the old mechanisms.  Once
+     DEPRECATED_SAVE_DUMMY_FRAME_TOS is gdbarch'd, all we need to do
+     is add the line
 
-	set_gdbarch_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
+	set_gdbarch_deprecated_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
 
      to ia64_gdbarch_init() and remove the line below. */
   generic_save_dummy_frame_tos (sp);
Index: infcall.c
===================================================================
RCS file: /cvs/src/src/gdb/infcall.c,v
retrieving revision 1.16
diff -u -r1.16 infcall.c
--- infcall.c	13 Jun 2003 20:37:28 -0000	1.16
+++ infcall.c	13 Jun 2003 23:08:59 -0000
@@ -423,11 +423,11 @@
       A follow-on change is to modify this interface so that it takes
       thread OR frame OR tpid as a parameter, and returns a dummy
       frame handle.  The handle can then be used further down as a
-      parameter SAVE_DUMMY_FRAME_TOS.  Hmm, thinking about it, since
-      everything is ment to be using generic dummy frames, why not
-      even use some of the dummy frame code to here - do a regcache
-      dup and then pass the duped regcache, along with all the other
-      stuff, at one single point.
+      parameter to generic_save_dummy_frame_tos().  Hmm, thinking
+      about it, since everything is ment to be using generic dummy
+      frames, why not even use some of the dummy frame code to here -
+      do a regcache dup and then pass the duped regcache, along with
+      all the other stuff, at one single point.
 
       In fact, you can even save the structure's return address in the
       dummy frame and fix one of those nasty lost struct return edge
@@ -474,15 +474,14 @@
 		    || (INNER_THAN (2, 1) && sp >= old_sp));
       }
     else
-      /* FIXME: cagney/2002-09-18: Hey, you loose!  Who knows how
-	 badly aligned the SP is!  Further, per comment above, if the
-	 generic dummy frame ends up empty (because nothing is pushed)
-	 GDB won't be able to correctly perform back traces.  If a
-	 target is having trouble with backtraces, first thing to do
-	 is add FRAME_ALIGN() to its architecture vector.  After that,
-	 try adding SAVE_DUMMY_FRAME_TOS() and modifying
-	 DEPRECATED_FRAME_CHAIN so that when the next outer frame is a
-	 generic dummy, it returns the current frame's base.  */
+      /* FIXME: cagney/2002-09-18: Hey, you loose!
+
+	 Who knows how badly aligned the SP is!  Further, per comment
+	 above, if the generic dummy frame ends up empty (because
+	 nothing is pushed) GDB won't be able to correctly perform
+	 back traces.  If a target is having trouble with backtraces,
+	 first thing to do is add FRAME_ALIGN() to the architecture
+	 vector. If that fails, try unwind_dummy_id().  */
       sp = old_sp;
   }
 
@@ -831,8 +830,8 @@
       gdb_assert (DEPRECATED_USE_GENERIC_DUMMY_FRAMES);
       generic_save_dummy_frame_tos (sp);
     }
-  else if (SAVE_DUMMY_FRAME_TOS_P ())
-    SAVE_DUMMY_FRAME_TOS (sp);
+  else if (DEPRECATED_SAVE_DUMMY_FRAME_TOS_P ())
+    DEPRECATED_SAVE_DUMMY_FRAME_TOS (sp);
 
   /* Now proceed, having reached the desired place.  */
   clear_proceed_status ();
Index: mcore-tdep.c
===================================================================
RCS file: /cvs/src/src/gdb/mcore-tdep.c,v
retrieving revision 1.69
diff -u -r1.69 mcore-tdep.c
--- mcore-tdep.c	13 Jun 2003 04:40:33 -0000	1.69
+++ mcore-tdep.c	13 Jun 2003 23:08:59 -0000
@@ -1079,7 +1079,7 @@
 
   set_gdbarch_deprecated_call_dummy_words (gdbarch, call_dummy_words);
   set_gdbarch_deprecated_sizeof_call_dummy_words (gdbarch, 0);
-  set_gdbarch_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
+  set_gdbarch_deprecated_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
   set_gdbarch_deprecated_saved_pc_after_call (gdbarch, mcore_saved_pc_after_call);
   set_gdbarch_function_start_offset (gdbarch, 0);
   set_gdbarch_decr_pc_after_break (gdbarch, 0);
Index: mips-tdep.c
===================================================================
RCS file: /cvs/src/src/gdb/mips-tdep.c,v
retrieving revision 1.214
diff -u -r1.214 mips-tdep.c
--- mips-tdep.c	13 Jun 2003 04:40:33 -0000	1.214
+++ mips-tdep.c	13 Jun 2003 23:09:03 -0000
@@ -5953,7 +5953,7 @@
   set_gdbarch_call_dummy_address (gdbarch, mips_call_dummy_address);
   set_gdbarch_deprecated_pop_frame (gdbarch, mips_pop_frame);
   set_gdbarch_frame_align (gdbarch, mips_frame_align);
-  set_gdbarch_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
+  set_gdbarch_deprecated_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
   set_gdbarch_deprecated_register_convertible (gdbarch, mips_register_convertible);
   set_gdbarch_deprecated_register_convert_to_virtual (gdbarch, mips_register_convert_to_virtual);
   set_gdbarch_deprecated_register_convert_to_raw (gdbarch, mips_register_convert_to_raw);
Index: mn10300-tdep.c
===================================================================
RCS file: /cvs/src/src/gdb/mn10300-tdep.c,v
retrieving revision 1.82
diff -u -r1.82 mn10300-tdep.c
--- mn10300-tdep.c	13 Jun 2003 04:40:33 -0000	1.82
+++ mn10300-tdep.c	13 Jun 2003 23:09:04 -0000
@@ -1201,7 +1201,7 @@
   set_gdbarch_deprecated_push_arguments (gdbarch, mn10300_push_arguments);
   set_gdbarch_reg_struct_has_addr (gdbarch, mn10300_reg_struct_has_addr);
   set_gdbarch_deprecated_push_return_address (gdbarch, mn10300_push_return_address);
-  set_gdbarch_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
+  set_gdbarch_deprecated_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
   set_gdbarch_use_struct_convention (gdbarch, mn10300_use_struct_convention);
 
   tdep->am33_mode = am33_mode;
Index: rs6000-tdep.c
===================================================================
RCS file: /cvs/src/src/gdb/rs6000-tdep.c,v
retrieving revision 1.144
diff -u -r1.144 rs6000-tdep.c
--- rs6000-tdep.c	13 Jun 2003 04:40:33 -0000	1.144
+++ rs6000-tdep.c	13 Jun 2003 23:09:05 -0000
@@ -2940,7 +2940,7 @@
 
   set_gdbarch_deprecated_fix_call_dummy (gdbarch, rs6000_fix_call_dummy);
   set_gdbarch_frame_align (gdbarch, rs6000_frame_align);
-  set_gdbarch_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
+  set_gdbarch_deprecated_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
   set_gdbarch_deprecated_push_return_address (gdbarch, ppc_push_return_address);
   set_gdbarch_believe_pcc_promotion (gdbarch, 1);
 
Index: s390-tdep.c
===================================================================
RCS file: /cvs/src/src/gdb/s390-tdep.c,v
retrieving revision 1.103
diff -u -r1.103 s390-tdep.c
--- s390-tdep.c	13 Jun 2003 04:40:33 -0000	1.103
+++ s390-tdep.c	13 Jun 2003 23:09:05 -0000
@@ -1860,7 +1860,7 @@
   set_gdbarch_deprecated_pc_in_call_dummy (gdbarch, deprecated_pc_in_call_dummy_at_entry_point);
   set_gdbarch_frame_align (gdbarch, s390_frame_align);
   set_gdbarch_deprecated_push_arguments (gdbarch, s390_push_arguments);
-  set_gdbarch_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
+  set_gdbarch_deprecated_save_dummy_frame_tos (gdbarch, generic_save_dummy_frame_tos);
   set_gdbarch_deprecated_push_return_address (gdbarch,
                                               s390_push_return_address);
   set_gdbarch_deprecated_sizeof_call_dummy_words (gdbarch, sizeof (s390_call_dummy_words));
Index: xstormy16-tdep.c
===================================================================
RCS file: /cvs/src/src/gdb/xstormy16-tdep.c,v
retrieving revision 1.57
diff -u -r1.57 xstormy16-tdep.c
--- xstormy16-tdep.c	13 Jun 2003 04:40:34 -0000	1.57
+++ xstormy16-tdep.c	13 Jun 2003 23:09:05 -0000
@@ -1104,7 +1104,7 @@
 
   set_gdbarch_stack_align (gdbarch, xstormy16_stack_align);
 
-  set_gdbarch_save_dummy_frame_tos (gdbarch, xstormy16_save_dummy_frame_tos);
+  set_gdbarch_deprecated_save_dummy_frame_tos (gdbarch, xstormy16_save_dummy_frame_tos);
 
   set_gdbarch_skip_trampoline_code (gdbarch, xstormy16_skip_trampoline_code);
 
Index: doc/gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.151
diff -u -r1.151 gdbint.texinfo
--- doc/gdbint.texinfo	13 Jun 2003 18:30:38 -0000	1.151
+++ doc/gdbint.texinfo	13 Jun 2003 23:09:08 -0000
@@ -3701,7 +3701,9 @@
 @var{nargs}, the code should push @var{struct_addr} (when
 @var{struct_return}), and the return address (@var{bp_addr}).
 
-Returns the updated top-of-stack pointer.
+Returns the stack part of a frame ID that will be used to re-identify
+the dummy-frame after the called function returns.  The value must match
+the value returned by @code{unwind_dummy_id} (@pxref{unwind_dummy_id}).
 
 This method replaces @code{DEPRECATED_PUSH_ARGUMENTS}.
 
@@ -3753,13 +3755,14 @@
 Define this to return 1 if the given type will be passed by pointer
 rather than directly.
 
-@item SAVE_DUMMY_FRAME_TOS (@var{sp})
-@findex SAVE_DUMMY_FRAME_TOS
-@anchor{SAVE_DUMMY_FRAME_TOS} Used in @samp{call_function_by_hand} to
-notify the target dependent code of the top-of-stack value that will be
-passed to the the inferior code.  This is the value of the @code{SP}
-after both the dummy frame and space for parameters/results have been
-allocated on the stack.  @xref{unwind_dummy_id}.
+@item DEPRECATED_SAVE_DUMMY_FRAME_TOS (@var{sp})
+@findex DEPRECATED_SAVE_DUMMY_FRAME_TOS
+@anchor{DEPRECATED_SAVE_DUMMY_FRAME_TOS} Used in
+@samp{call_function_by_hand} to notify the target dependent code of the
+top-of-stack value that will be passed to the the inferior code.  This
+is the value of the @code{SP} after both the dummy frame and space for
+parameters/results have been allocated on the stack.
+@xref{unwind_dummy_id}.
 
 @item SDB_REG_TO_REGNUM
 @findex SDB_REG_TO_REGNUM
@@ -3945,9 +3948,12 @@
 @findex unwind_dummy_id
 @anchor{unwind_dummy_id} Given @var{frame} return a @code{struct
 frame_id} that uniquely identifies an inferior function call's dummy
-frame.  The value returned must match the dummy frame stack value
-previously saved using @code{SAVE_DUMMY_FRAME_TOS}.
-@xref{SAVE_DUMMY_FRAME_TOS}.
+frame.
+
+The returned frame ID's stack address must match the address previously
+returned by @code{push_dummy_call}, and the returned frame ID's code
+address must match the address of the breakpoint instruction that the
+called function returns to (@pxref{push_dummy_call}).
 
 @item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
 @findex USE_STRUCT_CONVENTION