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

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

[Kevin Pouget]

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

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.

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

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 ()

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

[Eli Zaretskii]

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

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

OK with those changes.

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

[Kevin Pouget]

[-- 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 ()

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

[Kevin Pouget]

On Thu, Oct 13, 2011 at 4:05 PM, Kevin Pouget <kevin.pouget@gmail.com> wrote:
> 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.
>

commited: http://sourceware.org/ml/gdb-cvs/2011-10/msg00112.html

thanks