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

[Tom Tromey <tromey@redhat.com>]

>>>>> "Mark" == Mark Kettenis <mark.kettenis@xs4all.nl> writes:

>> +@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.

Mark> It isn't quite clear to me what this last sentence means.

I looked deeper, and this sentence is also incorrect.

I was looking at the comments in enum frame_type when writing this, but
the comment for INLINE_FRAME seems backward to me.  Code in various
places seems to agree with this.

Tom> Doc review needed.
Tom> Ok?

Eli> Yes, thanks.

How about the appended?  It has all the updates in place.

Tom

ChangeLog:
2011-01-06  Tom Tromey  <tromey@redhat.com>

	* frame.h (enum frame_type) <INLINE_FRAME>: Fix comment.
	* python/py-frame.c (gdbpy_initialize_frames): Add INLINE_FRAME
	and ARCH_FRAME.

doc/ChangeLog:
2011-01-06  Tom Tromey  <tromey@redhat.com>

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

Index: frame.h
===================================================================
RCS file: /cvs/src/src/gdb/frame.h,v
retrieving revision 1.183
diff -u -r1.183 frame.h
--- frame.h	1 Jan 2011 15:33:04 -0000	1.183
+++ frame.h	6 Jan 2011 16:52:30 -0000
@@ -204,7 +204,7 @@
      call.  */
   DUMMY_FRAME,
   /* A frame representing an inlined function, associated with an
-     upcoming (next, inner, younger) NORMAL_FRAME.  */
+     upcoming (prev, outer, older) NORMAL_FRAME.  */
   INLINE_FRAME,
   /* In a signal handler, various OSs handle this in various ways.
      The main thing is that the frame may be far from normal.  */
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	6 Jan 2011 16:52:34 -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 older 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	6 Jan 2011 16:52:34 -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);