[Patch][Python] PR python/13285 Document named constants for frame unwind stop reasons

[Kevin Pouget <kevin dot pouget at gmail dot com>]

On Wed, Oct 12, 2011 at 7:05 PM, Tom Tromey <tromey@redhat.com> wrote:
>>>>>> "Kevin" == Kevin Pouget <kevin.pouget@gmail.com> writes:
>
>>> Why not use the supplied gdb constants in this case? ?"2" does not map
>>> to any enum.
>>> IE gdb.FRAME_UNWIND_NO_REASON
>
> Kevin> it looks like these enums are not documented, are they? I can't grep
> Kevin> 'FRAME_UNWIND_NO_REASON' in gdb.texinfo
>
> Yeah, we should document those.
> I filed: http://sourceware.org/bugzilla/show_bug.cgi?id=13285
>
> Tom

Hello,

I've prepared a bit of documentation for these named constants, based
on their comments in the source code.
The concept of frame ID (struct frame_id) is not exposed in the Python
interface, but I'm not sure that the constants could be explained
without this idea.

Thanks,

Kevin

2011-10-13  Kevin Pouget  <kevin.pouget@st.com>

	PR python/13285 Document named constants for frame unwind stop reasons
	* gdb.texinfo (Frames In Python): Document gdb.FRAME_UNWIND_*
	constants.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index da04e2e..e4bc5a1 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23414,7 +23414,51 @@ newest frame.
 Return an integer representing the reason why it's not possible to find
 more frames toward the outermost frame.  Use
 @code{gdb.frame_stop_reason_string} to convert the value returned by this
-function to a string.
+function to a string. The value can be one of:
+
+@table @code
+@item gdb.FRAME_UNWIND_NO_REASON
+No particular reason.
+@end table
+
+@table @code
+@item gdb.FRAME_UNWIND_NULL_ID
+The previous frame's analyzer returns an invalid result.
+@end table
+
+@table @code
+@item gdb.FRAME_UNWIND_OUTERMOST
+This frame is the outermost.
+@end table
+
+@table @code
+@item gdb.FRAME_UNWIND_UNAVAILABLE
+Cannot unwind further, because that would require knowing the 
+values of registers or memory that have not been collected.
+@end table
+
+@table @code
+@item gdb.FRAME_UNWIND_INNER_ID
+This frame ID looks like it ought to belong to a NEXT frame,
+but we got it for a PREV frame.  Normally, this is a sign of
+unwinder failure.  It could also indicate stack corruption.
+@end table
+
+@table @code
+@item gdb.FRAME_UNWIND_SAME_ID
+This frame has the same ID as the previous one.  That means
+that unwinding further would almost certainly give us another
+frame with exactly the same ID, so break the chain.  Normally,
+this is a sign of unwinder failure.  It could also indicate
+stack corruption.
+@end table
+
+@table @code
+@item gdb.FRAME_UNWIND_NO_SAVED_PC
+The frame unwinder did not find any saved PC, but we needed
+one to unwind further.
+@end table
+
 @end defun
 
 @defun Frame.pc ()