Re: RFA: document frame types, plus add missing ones

[Tom Tromey <tromey at redhat dot com>]

>> +@item gdb.SIGTRAMP_FRAME
>> +A frame in a signal handler.

Mark> Hmm, actualy, the frame for what most people consider the signal
Mark> handler is a NORMAL_FRAME.  The SIGTRAMP_FRAME is the frame
Mark> immediately preceding the signal handler.  It is for the "signal
Mark> trampoline", the bit of (low-level) code provided by the kernel or
Mark> libc that runs the true signal handler.

I updated this.  Thanks.

>> +@item gdb.ARCH_FRAME
>> +A fake stack frame representing a cross-architecture call.

Mark> Oh, we have those now?

Yes, I think for the SPU only.  See ppc-linux-tdep.c and spu-tdep.c.

>> +@item gdb.SENTINEL_FRAME
>> +This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
>> +newest frame.

Mark> Ah, so by "newest frame" you really mean "innermost frame".

Yes.  My recollection is that when exporting this to Python, there was
some confusion about terms like "inner" and "outer", or "up" and "down",
or "next" and "previous".  So, we went with "newer" and "older", which
seem less confusion-provoking... unless one is already a gdb developer :)

Tom

2011-01-05  Tom Tromey  <tromey@redhat.com>

	* python/py-frame.c (gdbpy_initialize_frames): Add INLINE_FRAME
	and ARCH_FRAME.

2011-01-05  Tom Tromey  <tromey@redhat.com>

	PR python/12133:
	* gdb.texinfo (Frames In Python): Document various frame
	constants.

Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.783
diff -u -r1.783 gdb.texinfo
--- doc/gdb.texinfo	5 Jan 2011 05:09:52 -0000	1.783
+++ doc/gdb.texinfo	5 Jan 2011 21:03:32 -0000
@@ -22536,9 +22536,30 @@
 @end defmethod
 
 @defmethod Frame type
-Returns the type of the frame.  The value can be one of
-@code{gdb.NORMAL_FRAME}, @code{gdb.DUMMY_FRAME}, @code{gdb.SIGTRAMP_FRAME}
-or @code{gdb.SENTINEL_FRAME}.
+Returns the type of the frame.  The value can be one of:
+@table @code
+@item gdb.NORMAL_FRAME
+An ordinary stack frame.
+
+@item gdb.DUMMY_FRAME
+A fake stack frame that was created by @value{GDBN} when performing an
+inferior function call.
+
+@item gdb.INLINE_FRAME
+A frame representing an inlined function.  The function was inlined
+into a @code{gdb.NORMAL_FRAME} that is newer than this one.
+
+@item gdb.SIGTRAMP_FRAME
+A signal trampoline frame.  This is the frame created by the OS when
+it calls into a signal handler.
+
+@item gdb.ARCH_FRAME
+A fake stack frame representing a cross-architecture call.
+
+@item gdb.SENTINEL_FRAME
+This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
+newest frame.
+@end table
 @end defmethod
 
 @defmethod Frame unwind_stop_reason
Index: python/py-frame.c
===================================================================
RCS file: /cvs/src/src/gdb/python/py-frame.c,v
retrieving revision 1.10
diff -u -r1.10 py-frame.c
--- python/py-frame.c	1 Jan 2011 15:33:25 -0000	1.10
+++ python/py-frame.c	5 Jan 2011 21:03:32 -0000
@@ -574,7 +574,9 @@
      That seems too messy.  */
   PyModule_AddIntConstant (gdb_module, "NORMAL_FRAME", NORMAL_FRAME);
   PyModule_AddIntConstant (gdb_module, "DUMMY_FRAME", DUMMY_FRAME);
+  PyModule_AddIntConstant (gdb_module, "INLINE_FRAME", INLINE_FRAME);
   PyModule_AddIntConstant (gdb_module, "SIGTRAMP_FRAME", SIGTRAMP_FRAME);
+  PyModule_AddIntConstant (gdb_module, "ARCH_FRAME", ARCH_FRAME);
   PyModule_AddIntConstant (gdb_module, "SENTINEL_FRAME", SENTINEL_FRAME);
   PyModule_AddIntConstant (gdb_module,
 			   "FRAME_UNWIND_NO_REASON", UNWIND_NO_REASON);