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

[Kevin Pouget <kevin.pouget@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1352 bytes --]

On Thu, Oct 13, 2011 at 3:48 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>
> > From: Kevin Pouget <kevin.pouget@gmail.com>
> > Date: Thu, 13 Oct 2011 14:39:16 +0200
> > Cc: pmuldoon@redhat.com, gdb-patches@sourceware.org
> >
> > I've prepared a bit of documentation for these named constants, based
> > on their comments in the source code.
>
> Thanks.
>
> > +@table @code
> > +@item gdb.FRAME_UNWIND_NO_REASON
> > +No particular reason.
>
> This begs for some explanation of when this "no-reason" reason will be
> seen.  Is it true that this value is used when it's NOT impossible to
> find more frames?  If so, we should say that explicitly.

Yes, that's my understanding too. I've changed the sentence to
> No particular reason (older frames should be available).

I'll commit the patch in an hour, if no one contradicts

> > +@end table
>
> There's no need to make each value a separate @table.  You can just
> make them all be a single table, like this:
>
>  @table @code
>  @item foo
>  Description of foo.
>  @item bar
>  Description of bar.
>  ...
>  @end @table.

sorry, I don't know where I got it from !

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.

[-- Attachment #2: gdb.texinfo.patch --]
[-- Type: text/x-patch, Size: 1563 bytes --]

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index da04e2e..0aa90eb 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23414,7 +23414,39 @@ 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 (older frames should be available).
+
+@item gdb.FRAME_UNWIND_NULL_ID
+The previous frame's analyzer returns an invalid result.
+
+@item gdb.FRAME_UNWIND_OUTERMOST
+This frame is the outermost.
+
+@item gdb.FRAME_UNWIND_UNAVAILABLE
+Cannot unwind further, because that would require knowing the 
+values of registers or memory that have not been collected.
+
+@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.
+
+@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.
+
+@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 ()