* python unwinder doc improvement @ 2022-05-28 11:55 Paulo Neves 2022-05-28 11:55 ` [PATCH 1/2] gdb/python doc: Add register_unwinder to code example Paulo Neves ` (3 more replies) 0 siblings, 4 replies; 34+ messages in thread From: Paulo Neves @ 2022-05-28 11:55 UTC (permalink / raw) To: gdb-patches [PATCH 1/2] gdb/python doc: Add register_unwinder to code example [PATCH 2/2] gdb/python doc: Add enable property to the unwinder Minor documentation changes to the unwinder example code with the goal of having all the features described in the prose also reflect on the code. ^ permalink raw reply [flat|nested] 34+ messages in thread
* [PATCH 1/2] gdb/python doc: Add register_unwinder to code example 2022-05-28 11:55 python unwinder doc improvement Paulo Neves @ 2022-05-28 11:55 ` Paulo Neves 2022-05-28 12:20 ` Eli Zaretskii 2022-05-28 11:55 ` [PATCH 2/2] gdb/python doc: Add enable property to the unwinder example Paulo Neves ` (2 subsequent siblings) 3 siblings, 1 reply; 34+ messages in thread From: Paulo Neves @ 2022-05-28 11:55 UTC (permalink / raw) To: gdb-patches; +Cc: Paulo Neves It is now clear in the example code that an unwinder needs to be registered to be used. --- gdb/doc/python.texi | 2 ++ 1 file changed, 2 insertions(+) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index cb5283e03c0..5b7fba798a9 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -2814,6 +2814,8 @@ class MyUnwinder(Unwinder): # Return the result: return unwind_info +# To use an unwinder it needs to be registered and enabled. +gdb.unwinder.register_unwinder (<locus>, MyUnwinder, replace=<True|False>) @end smallexample @subheading Registering a Unwinder -- 2.25.1 ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH 1/2] gdb/python doc: Add register_unwinder to code example 2022-05-28 11:55 ` [PATCH 1/2] gdb/python doc: Add register_unwinder to code example Paulo Neves @ 2022-05-28 12:20 ` Eli Zaretskii 2022-06-21 11:17 ` Paulo Neves 0 siblings, 1 reply; 34+ messages in thread From: Eli Zaretskii @ 2022-05-28 12:20 UTC (permalink / raw) To: ptsneves; +Cc: gdb-patches > Date: Sat, 28 May 2022 13:55:08 +0200 > From: Paulo Neves via Gdb-patches <gdb-patches@sourceware.org> > Cc: Paulo Neves <ptsneves@gmail.com> > > It is now clear in the example code that an unwinder needs to be > registered to be used. > --- > gdb/doc/python.texi | 2 ++ > 1 file changed, 2 insertions(+) > > diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi > index cb5283e03c0..5b7fba798a9 100644 > --- a/gdb/doc/python.texi > +++ b/gdb/doc/python.texi > @@ -2814,6 +2814,8 @@ class MyUnwinder(Unwinder): > # Return the result: > return unwind_info > > +# To use an unwinder it needs to be registered and enabled. > +gdb.unwinder.register_unwinder (<locus>, MyUnwinder, replace=<True|False>) > @end smallexample Thanks, I think this needs to be reviewed by someone who knows how to program the Python unwinders. As far as Texinfo is concerned, this is fine. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH 1/2] gdb/python doc: Add register_unwinder to code example 2022-05-28 12:20 ` Eli Zaretskii @ 2022-06-21 11:17 ` Paulo Neves 2022-06-21 12:19 ` Eli Zaretskii 0 siblings, 1 reply; 34+ messages in thread From: Paulo Neves @ 2022-06-21 11:17 UTC (permalink / raw) To: Eli Zaretskii; +Cc: gdb-patches Hello all, Any idea when this can be merged or if there anything missing? Paulo Neves On 5/28/22 14:20, Eli Zaretskii wrote: >> Date: Sat, 28 May 2022 13:55:08 +0200 >> From: Paulo Neves via Gdb-patches <gdb-patches@sourceware.org> >> Cc: Paulo Neves <ptsneves@gmail.com> >> >> It is now clear in the example code that an unwinder needs to be >> registered to be used. >> --- >> gdb/doc/python.texi | 2 ++ >> 1 file changed, 2 insertions(+) >> >> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi >> index cb5283e03c0..5b7fba798a9 100644 >> --- a/gdb/doc/python.texi >> +++ b/gdb/doc/python.texi >> @@ -2814,6 +2814,8 @@ class MyUnwinder(Unwinder): >> # Return the result: >> return unwind_info >> >> +# To use an unwinder it needs to be registered and enabled. >> +gdb.unwinder.register_unwinder (<locus>, MyUnwinder, replace=<True|False>) >> @end smallexample > Thanks, I think this needs to be reviewed by someone who knows how to > program the Python unwinders. As far as Texinfo is concerned, this is > fine. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH 1/2] gdb/python doc: Add register_unwinder to code example 2022-06-21 11:17 ` Paulo Neves @ 2022-06-21 12:19 ` Eli Zaretskii 2022-09-30 11:59 ` Paulo Neves 0 siblings, 1 reply; 34+ messages in thread From: Eli Zaretskii @ 2022-06-21 12:19 UTC (permalink / raw) To: Paulo Neves; +Cc: gdb-patches > Date: Tue, 21 Jun 2022 13:17:32 +0200 > Cc: gdb-patches@sourceware.org > From: Paulo Neves <ptsneves@gmail.com> > > Hello all, > > Any idea when this can be merged or if there anything missing? Like I said before: this needs to be approved by someone who knows about Python unwinder programming. If the text is correct, the Texinfo use was already approved by me. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH 1/2] gdb/python doc: Add register_unwinder to code example 2022-06-21 12:19 ` Eli Zaretskii @ 2022-09-30 11:59 ` Paulo Neves 2022-09-30 12:25 ` Eli Zaretskii 0 siblings, 1 reply; 34+ messages in thread From: Paulo Neves @ 2022-09-30 11:59 UTC (permalink / raw) To: Eli Zaretskii; +Cc: gdb-patches On 6/21/22 14:19, Eli Zaretskii wrote: >> Date: Tue, 21 Jun 2022 13:17:32 +0200 >> Cc: gdb-patches@sourceware.org >> From: Paulo Neves <ptsneves@gmail.com> >> >> Hello all, >> >> Any idea when this can be merged or if there anything missing? > Like I said before: this needs to be approved by someone who knows > about Python unwinder programming. If the text is correct, the > Texinfo use was already approved by me. Hello Eli, Could you point me out somebody who knows the python unwinder part that i can ping? Paulo Neves ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH 1/2] gdb/python doc: Add register_unwinder to code example 2022-09-30 11:59 ` Paulo Neves @ 2022-09-30 12:25 ` Eli Zaretskii 0 siblings, 0 replies; 34+ messages in thread From: Eli Zaretskii @ 2022-09-30 12:25 UTC (permalink / raw) To: Paulo Neves; +Cc: gdb-patches > Date: Fri, 30 Sep 2022 13:59:06 +0200 > Cc: gdb-patches@sourceware.org > From: Paulo Neves <ptsneves@gmail.com> > > On 6/21/22 14:19, Eli Zaretskii wrote: > >> Date: Tue, 21 Jun 2022 13:17:32 +0200 > >> Cc: gdb-patches@sourceware.org > >> From: Paulo Neves <ptsneves@gmail.com> > >> > >> Hello all, > >> > >> Any idea when this can be merged or if there anything missing? > > Like I said before: this needs to be approved by someone who knows > > about Python unwinder programming. If the text is correct, the > > Texinfo use was already approved by me. > Hello Eli, > Could you point me out somebody who knows the python unwinder part that > i can ping? Any other of the global maintainers, really: Joel, Pedro, Simon, and many others. ^ permalink raw reply [flat|nested] 34+ messages in thread
* [PATCH 2/2] gdb/python doc: Add enable property to the unwinder example 2022-05-28 11:55 python unwinder doc improvement Paulo Neves 2022-05-28 11:55 ` [PATCH 1/2] gdb/python doc: Add register_unwinder to code example Paulo Neves @ 2022-05-28 11:55 ` Paulo Neves 2022-05-28 12:22 ` Eli Zaretskii 2022-05-28 13:29 ` [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example Paulo Neves 2022-06-03 16:01 ` [PATCH v3 1/4] " Paulo Neves 3 siblings, 1 reply; 34+ messages in thread From: Paulo Neves @ 2022-05-28 11:55 UTC (permalink / raw) To: gdb-patches; +Cc: Paulo Neves The enable property is now also in the example code making it clear how it is used and how it influences the operation of an unwinder. --- gdb/doc/python.texi | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 5b7fba798a9..cb148d9b0ea 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -2796,6 +2796,10 @@ class FrameId(object): class MyUnwinder(Unwinder): def __init__(....): super(MyUnwinder, self).__init___(<expects unwinder name argument>) + # If set to True the unwinder will be enabled. + # If upon registration the enable property is True, the unwinder will be usable immediately. + # gdb or code may change value. + self.enabled = <True|False> def __call__(pending_frame): if not <we recognize frame>: -- 2.25.1 ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH 2/2] gdb/python doc: Add enable property to the unwinder example 2022-05-28 11:55 ` [PATCH 2/2] gdb/python doc: Add enable property to the unwinder example Paulo Neves @ 2022-05-28 12:22 ` Eli Zaretskii 2022-05-28 13:35 ` Paulo Neves 0 siblings, 1 reply; 34+ messages in thread From: Eli Zaretskii @ 2022-05-28 12:22 UTC (permalink / raw) To: ptsneves; +Cc: gdb-patches > Date: Sat, 28 May 2022 13:55:09 +0200 > From: Paulo Neves via Gdb-patches <gdb-patches@sourceware.org> > Cc: Paulo Neves <ptsneves@gmail.com> > > The enable property is now also in the example code making it clear how > it is used and how it influences the operation of an unwinder. > --- > gdb/doc/python.texi | 4 ++++ > 1 file changed, 4 insertions(+) > > diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi > index 5b7fba798a9..cb148d9b0ea 100644 > --- a/gdb/doc/python.texi > +++ b/gdb/doc/python.texi > @@ -2796,6 +2796,10 @@ class FrameId(object): > class MyUnwinder(Unwinder): > def __init__(....): > super(MyUnwinder, self).__init___(<expects unwinder name argument>) > + # If set to True the unwinder will be enabled. > + # If upon registration the enable property is True, the unwinder will be usable immediately. This last line is too long for an @example, please break it into two. > + # gdb or code may change value. > + self.enabled = <True|False> > > def __call__(pending_frame): > if not <we recognize frame>: Other than that, this needs to be reviewed by someone who knows about programming unwinders in Python. Thanks. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH 2/2] gdb/python doc: Add enable property to the unwinder example 2022-05-28 12:22 ` Eli Zaretskii @ 2022-05-28 13:35 ` Paulo Neves 0 siblings, 0 replies; 34+ messages in thread From: Paulo Neves @ 2022-05-28 13:35 UTC (permalink / raw) To: Eli Zaretskii; +Cc: gdb-patches On 5/28/22 14:22, Eli Zaretskii wrote: >> Date: Sat, 28 May 2022 13:55:09 +0200 >> From: Paulo Neves via Gdb-patches<gdb-patches@sourceware.org> >> Cc: Paulo Neves<ptsneves@gmail.com> >> >> The enable property is now also in the example code making it clear how >> it is used and how it influences the operation of an unwinder. >> --- >> gdb/doc/python.texi | 4 ++++ >> 1 file changed, 4 insertions(+) >> >> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi >> index 5b7fba798a9..cb148d9b0ea 100644 >> --- a/gdb/doc/python.texi >> +++ b/gdb/doc/python.texi >> @@ -2796,6 +2796,10 @@ class FrameId(object): >> class MyUnwinder(Unwinder): >> def __init__(....): >> super(MyUnwinder, self).__init___(<expects unwinder name argument>) >> + # If set to True the unwinder will be enabled. >> + # If upon registration the enable property is True, the unwinder will be usable immediately. > This last line is too long for an @example, please break it into two. Done > >> + # gdb or code may change value. >> + self.enabled = <True|False> >> >> def __call__(pending_frame): >> if not <we recognize frame>: > Other than that, this needs to be reviewed by someone who knows about > programming unwinders in Python. > > Thanks. Ok, I will be waiting then and ping according to the guidelines. I added a 3rd patch that also corrects a mistake in the module name mentioned in the example and doc. ^ permalink raw reply [flat|nested] 34+ messages in thread
* [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example 2022-05-28 11:55 python unwinder doc improvement Paulo Neves 2022-05-28 11:55 ` [PATCH 1/2] gdb/python doc: Add register_unwinder to code example Paulo Neves 2022-05-28 11:55 ` [PATCH 2/2] gdb/python doc: Add enable property to the unwinder example Paulo Neves @ 2022-05-28 13:29 ` Paulo Neves 2022-05-28 13:29 ` [PATCH v2 2/3] gdb/python doc: Add enable property to the unwinder example Paulo Neves ` (2 more replies) 2022-06-03 16:01 ` [PATCH v3 1/4] " Paulo Neves 3 siblings, 3 replies; 34+ messages in thread From: Paulo Neves @ 2022-05-28 13:29 UTC (permalink / raw) To: gdb-patches; +Cc: Paulo Neves It is now clear in the example code that an unwinder needs to be registered to be used. --- gdb/doc/python.texi | 2 ++ 1 file changed, 2 insertions(+) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index cb5283e03c0..5b7fba798a9 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -2814,6 +2814,8 @@ class MyUnwinder(Unwinder): # Return the result: return unwind_info +# To use an unwinder it needs to be registered and enabled. +gdb.unwinder.register_unwinder (<locus>, MyUnwinder, replace=<True|False>) @end smallexample @subheading Registering a Unwinder -- 2.25.1 ^ permalink raw reply [flat|nested] 34+ messages in thread
* [PATCH v2 2/3] gdb/python doc: Add enable property to the unwinder example 2022-05-28 13:29 ` [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example Paulo Neves @ 2022-05-28 13:29 ` Paulo Neves 2022-05-30 9:57 ` Andrew Burgess 2022-05-28 13:29 ` [PATCH v2 3/3] gdb/python doc: Fix confusion between gdb.unwinders and gdb.unwinder Paulo Neves 2022-05-30 9:55 ` [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example Andrew Burgess 2 siblings, 1 reply; 34+ messages in thread From: Paulo Neves @ 2022-05-28 13:29 UTC (permalink / raw) To: gdb-patches; +Cc: Paulo Neves The enable property is now also in the example code making it clear how it is used and how it influences the operation of an unwinder. --- gdb/doc/python.texi | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 5b7fba798a9..444e332d752 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -2796,6 +2796,11 @@ class FrameId(object): class MyUnwinder(Unwinder): def __init__(....): super(MyUnwinder, self).__init___(<expects unwinder name argument>) + # If set to True the unwinder will be enabled. + # If upon registration the enable property is True, the unwinder + # will be usable immediately. + # gdb or code may change value. + self.enabled = <True|False> def __call__(pending_frame): if not <we recognize frame>: -- 2.25.1 ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v2 2/3] gdb/python doc: Add enable property to the unwinder example 2022-05-28 13:29 ` [PATCH v2 2/3] gdb/python doc: Add enable property to the unwinder example Paulo Neves @ 2022-05-30 9:57 ` Andrew Burgess 2022-06-03 15:54 ` Paulo Neves 0 siblings, 1 reply; 34+ messages in thread From: Andrew Burgess @ 2022-05-30 9:57 UTC (permalink / raw) To: Paulo Neves via Gdb-patches, gdb-patches; +Cc: Paulo Neves Paulo Neves via Gdb-patches <gdb-patches@sourceware.org> writes: > The enable property is now also in the example code making it clear how > it is used and how it influences the operation of an unwinder. > --- > gdb/doc/python.texi | 5 +++++ > 1 file changed, 5 insertions(+) > > diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi > index 5b7fba798a9..444e332d752 100644 > --- a/gdb/doc/python.texi > +++ b/gdb/doc/python.texi > @@ -2796,6 +2796,11 @@ class FrameId(object): > class MyUnwinder(Unwinder): > def __init__(....): > super(MyUnwinder, self).__init___(<expects unwinder name argument>) > + # If set to True the unwinder will be enabled. > + # If upon registration the enable property is True, the unwinder > + # will be usable immediately. > + # gdb or code may change value. > + self.enabled = <True|False> Everything I said about patch #1 applies here too. I think your comment could be shortened to just: # If set to True the unwinder will be enabled and available for use. Given that text I think most users will assume that setting the field to `True` in the constructor will result in the unwinder being available upon registration. Thanks, Andrew > > def __call__(pending_frame): > if not <we recognize frame>: > -- > 2.25.1 ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v2 2/3] gdb/python doc: Add enable property to the unwinder example 2022-05-30 9:57 ` Andrew Burgess @ 2022-06-03 15:54 ` Paulo Neves 0 siblings, 0 replies; 34+ messages in thread From: Paulo Neves @ 2022-06-03 15:54 UTC (permalink / raw) To: Andrew Burgess, Paulo Neves via Gdb-patches On 5/30/22 11:57, Andrew Burgess wrote: > Paulo Neves via Gdb-patches <gdb-patches@sourceware.org> writes: > >> The enable property is now also in the example code making it clear how >> it is used and how it influences the operation of an unwinder. >> --- >> gdb/doc/python.texi | 5 +++++ >> 1 file changed, 5 insertions(+) >> >> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi >> index 5b7fba798a9..444e332d752 100644 >> --- a/gdb/doc/python.texi >> +++ b/gdb/doc/python.texi >> @@ -2796,6 +2796,11 @@ class FrameId(object): >> class MyUnwinder(Unwinder): >> def __init__(....): >> super(MyUnwinder, self).__init___(<expects unwinder name argument>) >> + # If set to True the unwinder will be enabled. >> + # If upon registration the enable property is True, the unwinder >> + # will be usable immediately. >> + # gdb or code may change value. >> + self.enabled = <True|False> > Everything I said about patch #1 applies here too. > > I think your comment could be shortened to just: > > # If set to True the unwinder will be enabled and available for use. > > Given that text I think most users will assume that setting the field to > `True` in the constructor will result in the unwinder being available > upon registration. I think that part can be indeed removed but I think the hint that gdb may change values of your unwinder is important. I wrote these changes though the eyes of the difficulties I had as an absolute GDB extension newbie. > Thanks, > Andrew > > >> >> def __call__(pending_frame): >> if not <we recognize frame>: >> -- >> 2.25.1 ^ permalink raw reply [flat|nested] 34+ messages in thread
* [PATCH v2 3/3] gdb/python doc: Fix confusion between gdb.unwinders and gdb.unwinder 2022-05-28 13:29 ` [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example Paulo Neves 2022-05-28 13:29 ` [PATCH v2 2/3] gdb/python doc: Add enable property to the unwinder example Paulo Neves @ 2022-05-28 13:29 ` Paulo Neves 2022-05-30 9:33 ` Andrew Burgess 2022-05-30 9:55 ` [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example Andrew Burgess 2 siblings, 1 reply; 34+ messages in thread From: Paulo Neves @ 2022-05-28 13:29 UTC (permalink / raw) To: gdb-patches; +Cc: Paulo Neves Replace gdb.unwinders with gdb.unwinder. The gdb.unwinders module does not and trying to import it leads to errors. Other instances of the manual correctly refer to gdb.unwinder. --- gdb/doc/python.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 444e332d752..59232750099 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -2785,7 +2785,7 @@ class. Derive your unwinder class from it and structure the code as follows: @smallexample -from gdb.unwinders import Unwinder +from gdb.unwinder import Unwinder class FrameId(object): def __init__(self, sp, pc): @@ -2828,7 +2828,7 @@ gdb.unwinder.register_unwinder (<locus>, MyUnwinder, replace=<True|False>) An object file, a program space, and the @value{GDBN} proper can have unwinders registered with it. -The @code{gdb.unwinders} module provides the function to register a +The @code{gdb.unwinder} module provides the function to register a unwinder: @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) -- 2.25.1 ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v2 3/3] gdb/python doc: Fix confusion between gdb.unwinders and gdb.unwinder 2022-05-28 13:29 ` [PATCH v2 3/3] gdb/python doc: Fix confusion between gdb.unwinders and gdb.unwinder Paulo Neves @ 2022-05-30 9:33 ` Andrew Burgess 0 siblings, 0 replies; 34+ messages in thread From: Andrew Burgess @ 2022-05-30 9:33 UTC (permalink / raw) To: Paulo Neves via Gdb-patches, gdb-patches; +Cc: Paulo Neves Paulo Neves via Gdb-patches <gdb-patches@sourceware.org> writes: > Replace gdb.unwinders with gdb.unwinder. The gdb.unwinders module does > not and trying to import it leads to errors. Other instances of the > manual correctly refer to gdb.unwinder. This patch is fine. Thanks, Andrew > --- > gdb/doc/python.texi | 4 ++-- > 1 file changed, 2 insertions(+), 2 deletions(-) > > diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi > index 444e332d752..59232750099 100644 > --- a/gdb/doc/python.texi > +++ b/gdb/doc/python.texi > @@ -2785,7 +2785,7 @@ class. Derive your unwinder class from it and structure the code as > follows: > > @smallexample > -from gdb.unwinders import Unwinder > +from gdb.unwinder import Unwinder > > class FrameId(object): > def __init__(self, sp, pc): > @@ -2828,7 +2828,7 @@ gdb.unwinder.register_unwinder (<locus>, MyUnwinder, replace=<True|False>) > An object file, a program space, and the @value{GDBN} proper can have > unwinders registered with it. > > -The @code{gdb.unwinders} module provides the function to register a > +The @code{gdb.unwinder} module provides the function to register a > unwinder: > > @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) > -- > 2.25.1 ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example 2022-05-28 13:29 ` [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example Paulo Neves 2022-05-28 13:29 ` [PATCH v2 2/3] gdb/python doc: Add enable property to the unwinder example Paulo Neves 2022-05-28 13:29 ` [PATCH v2 3/3] gdb/python doc: Fix confusion between gdb.unwinders and gdb.unwinder Paulo Neves @ 2022-05-30 9:55 ` Andrew Burgess 2022-05-30 10:12 ` Paulo Neves 2 siblings, 1 reply; 34+ messages in thread From: Andrew Burgess @ 2022-05-30 9:55 UTC (permalink / raw) To: Paulo Neves via Gdb-patches, gdb-patches; +Cc: Paulo Neves Paulo Neves via Gdb-patches <gdb-patches@sourceware.org> writes: > It is now clear in the example code that an unwinder needs to be > registered to be used. > --- > gdb/doc/python.texi | 2 ++ > 1 file changed, 2 insertions(+) > > diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi > index cb5283e03c0..5b7fba798a9 100644 > --- a/gdb/doc/python.texi > +++ b/gdb/doc/python.texi > @@ -2814,6 +2814,8 @@ class MyUnwinder(Unwinder): > # Return the result: > return unwind_info > > +# To use an unwinder it needs to be registered and enabled. > +gdb.unwinder.register_unwinder (<locus>, MyUnwinder, replace=<True|False>) > @end smallexample I've had reason to read the unwinder example before, and I think it's probably my most hated example in our manual. I absolutely hate that the example is not real, executable, EXAMPLE, code, it's just seems like documentation in another form. That said, I think its not fair for me to require that your additions to the existing example be executable, when the rest of the example is not. But, if you _did_ want to improve this whole example, then I'd certainly be in favour! I do however, this that with this addition, the example code is now in the wrong place. Notice your example now makes use of `register_unwinder`, but this method is not discussed in detail until after the example code. I think that the whole subsection titled `Unwinder Skeleton Code` should be moved later, probably to just before `@node Xmethods In Python`, that is, right at the end of the section on unwinders. Thanks, Andrew > > @subheading Registering a Unwinder > -- > 2.25.1 ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example 2022-05-30 9:55 ` [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example Andrew Burgess @ 2022-05-30 10:12 ` Paulo Neves 0 siblings, 0 replies; 34+ messages in thread From: Paulo Neves @ 2022-05-30 10:12 UTC (permalink / raw) To: Andrew Burgess, Paulo Neves via Gdb-patches Hello Andrew On 5/30/22 11:55, Andrew Burgess wrote: > Paulo Neves via Gdb-patches<gdb-patches@sourceware.org> writes: > >> It is now clear in the example code that an unwinder needs to be >> registered to be used. >> --- >> gdb/doc/python.texi | 2 ++ >> 1 file changed, 2 insertions(+) >> >> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi >> index cb5283e03c0..5b7fba798a9 100644 >> --- a/gdb/doc/python.texi >> +++ b/gdb/doc/python.texi >> @@ -2814,6 +2814,8 @@ class MyUnwinder(Unwinder): >> # Return the result: >> return unwind_info >> >> +# To use an unwinder it needs to be registered and enabled. >> +gdb.unwinder.register_unwinder (<locus>, MyUnwinder, replace=<True|False>) >> @end smallexample > I've had reason to read the unwinder example before, and I think it's > probably my most hated example in our manual. > > I absolutely hate that the example is not real, executable, EXAMPLE, > code, it's just seems like documentation in another form. I think the fact it was not executable was the reason that nobody noticed the import was wrong. > > That said, I think its not fair for me to require that your additions to > the existing example be executable, when the rest of the example is > not. But, if you _did_ want to improve this whole example, then I'd > certainly be in favour! When you mean you want it to be executable, does this mean i should to remove the meta-values like "<SP number>" sprinkled in the code and replace them with comments? Also by real example do you want it to be functional? I am concerned an example that does any meaningful thing would be confusing. Something i looked at when trying to get my unwinder working was the gdb/testsuite/gdb.python/py-unwind.py test. It could be used but adds unrelated logic. > > I do however, this that with this addition, the example code is now in > the wrong place. Notice your example now makes use of > `register_unwinder`, but this method is not discussed in detail until > after the example code. > > I think that the whole subsection titled `Unwinder Skeleton Code` should > be moved later, probably to just before `@node Xmethods In Python`, that > is, right at the end of the section on unwinders. I can move the example to the last subsection. > > Thanks, > Andrew > >> >> @subheading Registering a Unwinder >> -- >> 2.25.1 I am interested in getting this section improved. Just give me the guidelines to the questions above and I will prepare the patches. Paulo Neves ^ permalink raw reply [flat|nested] 34+ messages in thread
* [PATCH v3 1/4] gdb/python doc: Add register_unwinder to code example 2022-05-28 11:55 python unwinder doc improvement Paulo Neves ` (2 preceding siblings ...) 2022-05-28 13:29 ` [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example Paulo Neves @ 2022-06-03 16:01 ` Paulo Neves 2022-06-03 16:01 ` [PATCH v3 2/4] gdb/python doc: Add enable property to the unwinder example Paulo Neves ` (3 more replies) 3 siblings, 4 replies; 34+ messages in thread From: Paulo Neves @ 2022-06-03 16:01 UTC (permalink / raw) To: gdb-patches; +Cc: Paulo Neves It is now clear in the example code that an unwinder needs to be registered to be used. --- gdb/doc/python.texi | 2 ++ 1 file changed, 2 insertions(+) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index ba5a9b315e1..228d515a817 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -2823,6 +2823,8 @@ class MyUnwinder(Unwinder): # Return the result: return unwind_info +# To use an unwinder it needs to be registered and enabled. +gdb.unwinder.register_unwinder (<locus>, MyUnwinder, replace=<True|False>) @end smallexample @subheading Registering a Unwinder -- 2.25.1 ^ permalink raw reply [flat|nested] 34+ messages in thread
* [PATCH v3 2/4] gdb/python doc: Add enable property to the unwinder example 2022-06-03 16:01 ` [PATCH v3 1/4] " Paulo Neves @ 2022-06-03 16:01 ` Paulo Neves 2022-06-03 16:17 ` Eli Zaretskii 2022-06-03 16:01 ` [PATCH v3 3/4] gdb/python doc: Fix confusion between gdb.unwinders and gdb.unwinder Paulo Neves ` (2 subsequent siblings) 3 siblings, 1 reply; 34+ messages in thread From: Paulo Neves @ 2022-06-03 16:01 UTC (permalink / raw) To: gdb-patches; +Cc: Paulo Neves The enable property is now also in the example code making it clear how it is used and how it influences the operation of an unwinder. --- gdb/doc/python.texi | 3 +++ 1 file changed, 3 insertions(+) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 228d515a817..3e4833a4a41 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -2805,6 +2805,9 @@ class FrameId(object): class MyUnwinder(Unwinder): def __init__(....): super(MyUnwinder, self).__init___(<expects unwinder name argument>) + # If set to True the unwinder will be enabled. + # gdb or code may change this value. + self.enabled = <True|False> def __call__(pending_frame): if not <we recognize frame>: -- 2.25.1 ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v3 2/4] gdb/python doc: Add enable property to the unwinder example 2022-06-03 16:01 ` [PATCH v3 2/4] gdb/python doc: Add enable property to the unwinder example Paulo Neves @ 2022-06-03 16:17 ` Eli Zaretskii 0 siblings, 0 replies; 34+ messages in thread From: Eli Zaretskii @ 2022-06-03 16:17 UTC (permalink / raw) To: Paulo Neves; +Cc: gdb-patches > Date: Fri, 3 Jun 2022 18:01:37 +0200 > From: Paulo Neves via Gdb-patches <gdb-patches@sourceware.org> > Cc: Paulo Neves <ptsneves@gmail.com> > > The enable property is now also in the example code making it clear how > it is used and how it influences the operation of an unwinder. > --- > gdb/doc/python.texi | 3 +++ > 1 file changed, 3 insertions(+) This is okay, thanks. ^ permalink raw reply [flat|nested] 34+ messages in thread
* [PATCH v3 3/4] gdb/python doc: Fix confusion between gdb.unwinders and gdb.unwinder 2022-06-03 16:01 ` [PATCH v3 1/4] " Paulo Neves 2022-06-03 16:01 ` [PATCH v3 2/4] gdb/python doc: Add enable property to the unwinder example Paulo Neves @ 2022-06-03 16:01 ` Paulo Neves 2022-06-03 16:17 ` Eli Zaretskii 2022-06-03 16:01 ` [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code Paulo Neves 2022-06-03 16:17 ` [PATCH v3 1/4] gdb/python doc: Add register_unwinder to code example Eli Zaretskii 3 siblings, 1 reply; 34+ messages in thread From: Paulo Neves @ 2022-06-03 16:01 UTC (permalink / raw) To: gdb-patches; +Cc: Paulo Neves Replace gdb.unwinders with gdb.unwinder. The gdb.unwinders module does not and trying to import it leads to errors. Other instances of the manual correctly refer to gdb.unwinder. --- gdb/doc/python.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 3e4833a4a41..e2821755851 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -2794,7 +2794,7 @@ class. Derive your unwinder class from it and structure the code as follows: @smallexample -from gdb.unwinders import Unwinder +from gdb.unwinder import Unwinder class FrameId(object): def __init__(self, sp, pc): @@ -2835,7 +2835,7 @@ gdb.unwinder.register_unwinder (<locus>, MyUnwinder, replace=<True|False>) An object file, a program space, and the @value{GDBN} proper can have unwinders registered with it. -The @code{gdb.unwinders} module provides the function to register a +The @code{gdb.unwinder} module provides the function to register a unwinder: @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) -- 2.25.1 ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v3 3/4] gdb/python doc: Fix confusion between gdb.unwinders and gdb.unwinder 2022-06-03 16:01 ` [PATCH v3 3/4] gdb/python doc: Fix confusion between gdb.unwinders and gdb.unwinder Paulo Neves @ 2022-06-03 16:17 ` Eli Zaretskii 0 siblings, 0 replies; 34+ messages in thread From: Eli Zaretskii @ 2022-06-03 16:17 UTC (permalink / raw) To: Paulo Neves; +Cc: gdb-patches > Date: Fri, 3 Jun 2022 18:01:38 +0200 > From: Paulo Neves via Gdb-patches <gdb-patches@sourceware.org> > Cc: Paulo Neves <ptsneves@gmail.com> > > Replace gdb.unwinders with gdb.unwinder. The gdb.unwinders module does > not and trying to import it leads to errors. Other instances of the > manual correctly refer to gdb.unwinder. > --- > gdb/doc/python.texi | 4 ++-- > 1 file changed, 2 insertions(+), 2 deletions(-) OK, thanks. ^ permalink raw reply [flat|nested] 34+ messages in thread
* [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code 2022-06-03 16:01 ` [PATCH v3 1/4] " Paulo Neves 2022-06-03 16:01 ` [PATCH v3 2/4] gdb/python doc: Add enable property to the unwinder example Paulo Neves 2022-06-03 16:01 ` [PATCH v3 3/4] gdb/python doc: Fix confusion between gdb.unwinders and gdb.unwinder Paulo Neves @ 2022-06-03 16:01 ` Paulo Neves 2022-06-03 16:20 ` Eli Zaretskii 2022-06-03 16:17 ` [PATCH v3 1/4] gdb/python doc: Add register_unwinder to code example Eli Zaretskii 3 siblings, 1 reply; 34+ messages in thread From: Paulo Neves @ 2022-06-03 16:01 UTC (permalink / raw) To: gdb-patches; +Cc: Paulo Neves This way all the concepts mentioned in the skeleton code are previously detailed. --- gdb/doc/python.texi | 50 ++++++++++++++++++++++----------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index e2821755851..1deeae82b9b 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -2787,6 +2787,31 @@ values see @ref{gdbpy_frame_read_register,,Frame.read_register}. @var{value} is a register value (a @code{gdb.Value} object). @end defun +@subheading Registering a Unwinder + +An object file, a program space, and the @value{GDBN} proper can have +unwinders registered with it. + +The @code{gdb.unwinder} module provides the function to register a +unwinder: + +@defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) +@var{locus} is specifies an object file or a program space to which +@var{unwinder} is added. Passing @code{None} or @code{gdb} adds +@var{unwinder} to the @value{GDBN}'s global unwinder list. The newly +added @var{unwinder} will be called before any other unwinder from the +same locus. Two unwinders in the same locus cannot have the same +name. An attempt to add a unwinder with already existing name raises +an exception unless @var{replace} is @code{True}, in which case the +old unwinder is deleted. +@end defun + +@subheading Unwinder Precedence + +@value{GDBN} first calls the unwinders from all the object files in no +particular order, then the unwinders from the current program space, +and finally the unwinders from @value{GDBN}. + @subheading Unwinder Skeleton Code @value{GDBN} comes with the module containing the base @code{Unwinder} @@ -2830,31 +2855,6 @@ class MyUnwinder(Unwinder): gdb.unwinder.register_unwinder (<locus>, MyUnwinder, replace=<True|False>) @end smallexample -@subheading Registering a Unwinder - -An object file, a program space, and the @value{GDBN} proper can have -unwinders registered with it. - -The @code{gdb.unwinder} module provides the function to register a -unwinder: - -@defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) -@var{locus} is specifies an object file or a program space to which -@var{unwinder} is added. Passing @code{None} or @code{gdb} adds -@var{unwinder} to the @value{GDBN}'s global unwinder list. The newly -added @var{unwinder} will be called before any other unwinder from the -same locus. Two unwinders in the same locus cannot have the same -name. An attempt to add a unwinder with already existing name raises -an exception unless @var{replace} is @code{True}, in which case the -old unwinder is deleted. -@end defun - -@subheading Unwinder Precedence - -@value{GDBN} first calls the unwinders from all the object files in no -particular order, then the unwinders from the current program space, -and finally the unwinders from @value{GDBN}. - @node Xmethods In Python @subsubsection Xmethods In Python @cindex xmethods in Python -- 2.25.1 ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code 2022-06-03 16:01 ` [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code Paulo Neves @ 2022-06-03 16:20 ` Eli Zaretskii 2022-06-03 16:38 ` Paulo Neves 2022-09-30 14:50 ` Pedro Alves 0 siblings, 2 replies; 34+ messages in thread From: Eli Zaretskii @ 2022-06-03 16:20 UTC (permalink / raw) To: Paulo Neves; +Cc: gdb-patches > Date: Fri, 3 Jun 2022 18:01:39 +0200 > From: Paulo Neves via Gdb-patches <gdb-patches@sourceware.org> > Cc: Paulo Neves <ptsneves@gmail.com> > > +@subheading Registering a Unwinder > + > +An object file, a program space, and the @value{GDBN} proper can have > +unwinders registered with it. > + > +The @code{gdb.unwinder} module provides the function to register a > +unwinder: > + > +@defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) > +@var{locus} is specifies an object file or a program space to which ^^ The "is" part should be deleted. > +@var{unwinder} is added. Passing @code{None} or @code{gdb} adds > +@var{unwinder} to the @value{GDBN}'s global unwinder list. First, @value{GDBN}, not @code{gdb}. And also, this sentence doesn't read well ("passing None or gdb adds..."), I guess it's some typo or missing or redundant word. Thanks. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code 2022-06-03 16:20 ` Eli Zaretskii @ 2022-06-03 16:38 ` Paulo Neves 2022-09-30 14:50 ` Pedro Alves 1 sibling, 0 replies; 34+ messages in thread From: Paulo Neves @ 2022-06-03 16:38 UTC (permalink / raw) To: Eli Zaretskii; +Cc: gdb-patches On 6/3/22 18:20, Eli Zaretskii wrote: >> Date: Fri, 3 Jun 2022 18:01:39 +0200 >> From: Paulo Neves via Gdb-patches<gdb-patches@sourceware.org> >> Cc: Paulo Neves<ptsneves@gmail.com> >> >> +@subheading Registering a Unwinder >> + >> +An object file, a program space, and the @value{GDBN} proper can have >> +unwinders registered with it. >> + >> +The @code{gdb.unwinder} module provides the function to register a >> +unwinder: >> + >> +@defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) >> +@var{locus} is specifies an object file or a program space to which > ^^ > The "is" part should be deleted. > >> +@var{unwinder} is added. Passing @code{None} or @code{gdb} adds >> +@var{unwinder} to the @value{GDBN}'s global unwinder list. > First, @value{GDBN}, not @code{gdb}. > > And also, this sentence doesn't read well ("passing None or gdb > adds..."), I guess it's some typo or missing or redundant word. > > Thanks. This patch is purely a move from one place to another, as suggested by Andrew. The issues you mention are not introduced in this patch, but i will try to fix the issues you mention on another commit and then rebase this patch on top of it. Paulo Neves ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code 2022-06-03 16:20 ` Eli Zaretskii 2022-06-03 16:38 ` Paulo Neves @ 2022-09-30 14:50 ` Pedro Alves 2022-09-30 15:53 ` Eli Zaretskii 1 sibling, 1 reply; 34+ messages in thread From: Pedro Alves @ 2022-09-30 14:50 UTC (permalink / raw) To: Eli Zaretskii, Paulo Neves; +Cc: gdb-patches On 2022-06-03 5:20 p.m., Eli Zaretskii via Gdb-patches wrote: >> Date: Fri, 3 Jun 2022 18:01:39 +0200 >> From: Paulo Neves via Gdb-patches <gdb-patches@sourceware.org> >> Cc: Paulo Neves <ptsneves@gmail.com> >> >> +@subheading Registering a Unwinder >> + >> +An object file, a program space, and the @value{GDBN} proper can have >> +unwinders registered with it. >> + >> +The @code{gdb.unwinder} module provides the function to register a >> +unwinder: >> + >> +@defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) >> +@var{locus} is specifies an object file or a program space to which > ^^ > The "is" part should be deleted. > >> +@var{unwinder} is added. Passing @code{None} or @code{gdb} adds >> +@var{unwinder} to the @value{GDBN}'s global unwinder list. > > First, @value{GDBN}, not @code{gdb}. > > And also, this sentence doesn't read well ("passing None or gdb > adds..."), I guess it's some typo or missing or redundant word. > I think the intent is to say that you can pass literal "None" or "gdb" to gdb.unwinder.register_unwinder, for "locus" argument. Reading like that, it makes sense to me, and replacing with @value{GDBN} would be incorrect. However, looking at the code itself, I don't see "gdb" being accepted as input: From gdb/python/lib/gdb/unwinder.py : def register_unwinder(locus, unwinder, replace=False): """Register unwinder in given locus. The unwinder is prepended to the locus's unwinders list. Unwinder name should be unique. Arguments: locus: Either an objfile, progspace, or None (in which case the unwinder is registered globally). unwinder: An object of a gdb.Unwinder subclass replace: If True, replaces existing unwinder with the same name. Otherwise, raises exception if unwinder with the same name already exists. Returns: Nothing. Raises: RuntimeError: Unwinder name is not unique TypeError: Bad locus type """ if locus is None: if gdb.parameter("verbose"): gdb.write("Registering global %s unwinder ...\n" % unwinder.name) locus = gdb elif isinstance(locus, gdb.Objfile) or isinstance(locus, gdb.Progspace): if gdb.parameter("verbose"): gdb.write( "Registering %s unwinder for %s ...\n" % (unwinder.name, locus.filename) ) else: raise TypeError("locus should be gdb.Objfile or gdb.Progspace or None") i = 0 for needle in locus.frame_unwinders: if needle.name == unwinder.name: if replace: del locus.frame_unwinders[i] else: raise RuntimeError("Unwinder %s already exists." % unwinder.name) i += 1 locus.frame_unwinders.insert(0, unwinder) gdb.invalidate_cached_frames() Above, when you pass "None", locus does end up being "gdb", if locus is None: if gdb.parameter("verbose"): gdb.write("Registering global %s unwinder ...\n" % unwinder.name) locus = gdb ^^^^^^^^^^^ but, if you pass locus=gdb as argument, seems to me you'll reach the else branch: else: raise TypeError("locus should be gdb.Objfile or gdb.Progspace or None") And note that error string does not mention the "gdb" possibility. So I think the manual should be fixed by dropping the "or @code{gdb}", resulting in: Passing @code{None} adds @var{unwinder} to the @value{GDBN}'s global unwinder list. Actually, the "the" in "to the @value{GDBN}'s" looks wrong to me. So I think we should really say: Passing @code{None} adds @var{unwinder} to @value{GDBN}'s global unwinder list. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code 2022-09-30 14:50 ` Pedro Alves @ 2022-09-30 15:53 ` Eli Zaretskii 2022-09-30 16:41 ` Pedro Alves 0 siblings, 1 reply; 34+ messages in thread From: Eli Zaretskii @ 2022-09-30 15:53 UTC (permalink / raw) To: Pedro Alves; +Cc: ptsneves, gdb-patches > Cc: gdb-patches@sourceware.org > From: Pedro Alves <pedro@palves.net> > Date: Fri, 30 Sep 2022 15:50:20 +0100 > > So I think the manual should be fixed by dropping the "or @code{gdb}", resulting in: > > Passing @code{None} adds @var{unwinder} to the @value{GDBN}'s global unwinder list. > > Actually, the "the" in "to the @value{GDBN}'s" looks wrong to me. So I think we > should really say: > > Passing @code{None} adds @var{unwinder} to @value{GDBN}'s global unwinder list. How about If @var{locus} is @code{None}, that stands for @value{GDBN}'s global unwinder list. I think this is clearer and less likely to cause misinterpretation. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code 2022-09-30 15:53 ` Eli Zaretskii @ 2022-09-30 16:41 ` Pedro Alves 2022-09-30 17:37 ` Eli Zaretskii 0 siblings, 1 reply; 34+ messages in thread From: Pedro Alves @ 2022-09-30 16:41 UTC (permalink / raw) To: Eli Zaretskii; +Cc: ptsneves, gdb-patches On 2022-09-30 4:53 p.m., Eli Zaretskii wrote: >> Cc: gdb-patches@sourceware.org >> From: Pedro Alves <pedro@palves.net> >> Date: Fri, 30 Sep 2022 15:50:20 +0100 >> >> So I think the manual should be fixed by dropping the "or @code{gdb}", resulting in: >> >> Passing @code{None} adds @var{unwinder} to the @value{GDBN}'s global unwinder list. >> >> Actually, the "the" in "to the @value{GDBN}'s" looks wrong to me. So I think we >> should really say: >> >> Passing @code{None} adds @var{unwinder} to @value{GDBN}'s global unwinder list. > > How about > > If @var{locus} is @code{None}, that stands for @value{GDBN}'s global > unwinder list. > > I think this is clearer and less likely to cause misinterpretation. > Seems fine in isolation, but looking at the whole paragraph, how about similar text to what's in gdb/python/lib/gdb/unwinder.py? Seems clear enough to me. I also noticed a couple instances of "a unwinder", also fixed. While at it, "GDB proper" seems like a weird conception. How about this? From 7c5e7875bed7f4316823db67d95821c88c679daf Mon Sep 17 00:00:00 2001 From: Pedro Alves <pedro@palves.net> Date: Fri, 30 Sep 2022 17:23:03 +0100 Subject: [PATCH] Python Change-Id: I98c1b1000e1063815238e945ca71ec6f37b5702e --- gdb/doc/python.texi | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 2692211f388..4a7b047c3e0 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -2861,21 +2861,21 @@ class MyUnwinder(Unwinder): @end smallexample -@subheading Registering a Unwinder +@subheading Registering an Unwinder -An object file, a program space, and the @value{GDBN} proper can have -unwinders registered with it. +Object files and program spaces can have unwinders registered with +them. In addition, you can also register unwinders globally. -The @code{gdb.unwinders} module provides the function to register a +The @code{gdb.unwinders} module provides the function to register an unwinder: @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) -@var{locus} is specifies an object file or a program space to which -@var{unwinder} is added. Passing @code{None} or @code{gdb} adds -@var{unwinder} to the @value{GDBN}'s global unwinder list. The newly -added @var{unwinder} will be called before any other unwinder from the +@var{locus} specifies which unwinder list the @var{unwinder} is +prepended to. It can be either an object file, a program space, or +@code{None}, in which case the unwinder is registered globally. The +newly added @var{unwinder} will be called before any other unwinder from the same locus. Two unwinders in the same locus cannot have the same -name. An attempt to add a unwinder with already existing name raises +name. An attempt to add an unwinder with an already existing name raises an exception unless @var{replace} is @code{True}, in which case the old unwinder is deleted. @end defun base-commit: cfc0ffd31e90972296b81d362a7d83eb60eb21c0 -- 2.36.0 ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code 2022-09-30 16:41 ` Pedro Alves @ 2022-09-30 17:37 ` Eli Zaretskii 2022-10-21 21:07 ` Pedro Alves 0 siblings, 1 reply; 34+ messages in thread From: Eli Zaretskii @ 2022-09-30 17:37 UTC (permalink / raw) To: Pedro Alves; +Cc: ptsneves, gdb-patches > Cc: ptsneves@gmail.com, gdb-patches@sourceware.org > From: Pedro Alves <pedro@palves.net> > Date: Fri, 30 Sep 2022 17:41:50 +0100 > > diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi > index 2692211f388..4a7b047c3e0 100644 > --- a/gdb/doc/python.texi > +++ b/gdb/doc/python.texi > @@ -2861,21 +2861,21 @@ class MyUnwinder(Unwinder): > > @end smallexample > > -@subheading Registering a Unwinder > +@subheading Registering an Unwinder > > -An object file, a program space, and the @value{GDBN} proper can have > -unwinders registered with it. > +Object files and program spaces can have unwinders registered with > +them. In addition, you can also register unwinders globally. > > -The @code{gdb.unwinders} module provides the function to register a > +The @code{gdb.unwinders} module provides the function to register an > unwinder: > > @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) > -@var{locus} is specifies an object file or a program space to which > -@var{unwinder} is added. Passing @code{None} or @code{gdb} adds > -@var{unwinder} to the @value{GDBN}'s global unwinder list. The newly > -added @var{unwinder} will be called before any other unwinder from the > +@var{locus} specifies which unwinder list the @var{unwinder} is > +prepended to. It can be either an object file, a program space, or > +@code{None}, in which case the unwinder is registered globally. The > +newly added @var{unwinder} will be called before any other unwinder from the > same locus. Two unwinders in the same locus cannot have the same > -name. An attempt to add a unwinder with already existing name raises > +name. An attempt to add an unwinder with an already existing name raises > an exception unless @var{replace} is @code{True}, in which case the > old unwinder is deleted. > @end defun That's fine, but let's avoid passive tense where we can (and make the sentence easier to grasp while at that). So: @var{locus} specifies to which unwinder list to prepend the @var{unwinder}. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code 2022-09-30 17:37 ` Eli Zaretskii @ 2022-10-21 21:07 ` Pedro Alves 2022-10-22 6:41 ` Paulo Neves 0 siblings, 1 reply; 34+ messages in thread From: Pedro Alves @ 2022-10-21 21:07 UTC (permalink / raw) To: Eli Zaretskii; +Cc: ptsneves, gdb-patches Hi, On 2022-09-30 6:37 p.m., Eli Zaretskii wrote: >> Cc: ptsneves@gmail.com, gdb-patches@sourceware.org >> From: Pedro Alves <pedro@palves.net> >> Date: Fri, 30 Sep 2022 17:41:50 +0100 >> >> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi >> index 2692211f388..4a7b047c3e0 100644 >> --- a/gdb/doc/python.texi >> +++ b/gdb/doc/python.texi >> @@ -2861,21 +2861,21 @@ class MyUnwinder(Unwinder): >> >> @end smallexample >> >> -@subheading Registering a Unwinder >> +@subheading Registering an Unwinder >> >> -An object file, a program space, and the @value{GDBN} proper can have >> -unwinders registered with it. >> +Object files and program spaces can have unwinders registered with >> +them. In addition, you can also register unwinders globally. >> >> -The @code{gdb.unwinders} module provides the function to register a >> +The @code{gdb.unwinders} module provides the function to register an >> unwinder: >> >> @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) >> -@var{locus} is specifies an object file or a program space to which >> -@var{unwinder} is added. Passing @code{None} or @code{gdb} adds >> -@var{unwinder} to the @value{GDBN}'s global unwinder list. The newly >> -added @var{unwinder} will be called before any other unwinder from the >> +@var{locus} specifies which unwinder list the @var{unwinder} is >> +prepended to. It can be either an object file, a program space, or >> +@code{None}, in which case the unwinder is registered globally. The >> +newly added @var{unwinder} will be called before any other unwinder from the >> same locus. Two unwinders in the same locus cannot have the same >> -name. An attempt to add a unwinder with already existing name raises >> +name. An attempt to add an unwinder with an already existing name raises >> an exception unless @var{replace} is @code{True}, in which case the >> old unwinder is deleted. >> @end defun > > That's fine, but let's avoid passive tense where we can (and make the > sentence easier to grasp while at that). So: > > @var{locus} specifies to which unwinder list to prepend the > @var{unwinder}. > Finally done, and merged. Thanks, Pedro Alves ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code 2022-10-21 21:07 ` Pedro Alves @ 2022-10-22 6:41 ` Paulo Neves 2022-10-22 6:41 ` Paulo Neves 0 siblings, 1 reply; 34+ messages in thread From: Paulo Neves @ 2022-10-22 6:41 UTC (permalink / raw) To: Pedro Alves; +Cc: Eli Zaretskii, gdb-patches Thank you very much Paulo Neves On Fri, 21 Oct 2022 at 23:07, Pedro Alves <pedro@palves.net> wrote: > Hi, > > On 2022-09-30 6:37 p.m., Eli Zaretskii wrote: > >> Cc: ptsneves@gmail.com, gdb-patches@sourceware.org > >> From: Pedro Alves <pedro@palves.net> > >> Date: Fri, 30 Sep 2022 17:41:50 +0100 > >> > >> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi > >> index 2692211f388..4a7b047c3e0 100644 > >> --- a/gdb/doc/python.texi > >> +++ b/gdb/doc/python.texi > >> @@ -2861,21 +2861,21 @@ class MyUnwinder(Unwinder): > >> > >> @end smallexample > >> > >> -@subheading Registering a Unwinder > >> +@subheading Registering an Unwinder > >> > >> -An object file, a program space, and the @value{GDBN} proper can have > >> -unwinders registered with it. > >> +Object files and program spaces can have unwinders registered with > >> +them. In addition, you can also register unwinders globally. > >> > >> -The @code{gdb.unwinders} module provides the function to register a > >> +The @code{gdb.unwinders} module provides the function to register an > >> unwinder: > >> > >> @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) > >> -@var{locus} is specifies an object file or a program space to which > >> -@var{unwinder} is added. Passing @code{None} or @code{gdb} adds > >> -@var{unwinder} to the @value{GDBN}'s global unwinder list. The newly > >> -added @var{unwinder} will be called before any other unwinder from the > >> +@var{locus} specifies which unwinder list the @var{unwinder} is > >> +prepended to. It can be either an object file, a program space, or > >> +@code{None}, in which case the unwinder is registered globally. The > >> +newly added @var{unwinder} will be called before any other unwinder > from the > >> same locus. Two unwinders in the same locus cannot have the same > >> -name. An attempt to add a unwinder with already existing name raises > >> +name. An attempt to add an unwinder with an already existing name > raises > >> an exception unless @var{replace} is @code{True}, in which case the > >> old unwinder is deleted. > >> @end defun > > > > That's fine, but let's avoid passive tense where we can (and make the > > sentence easier to grasp while at that). So: > > > > @var{locus} specifies to which unwinder list to prepend the > > @var{unwinder}. > > > > Finally done, and merged. > > Thanks, > Pedro Alves > > ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code 2022-10-22 6:41 ` Paulo Neves @ 2022-10-22 6:41 ` Paulo Neves 0 siblings, 0 replies; 34+ messages in thread From: Paulo Neves @ 2022-10-22 6:41 UTC (permalink / raw) To: Pedro Alves; +Cc: Eli Zaretskii, gdb-patches [-- Attachment #1: Type: text/plain, Size: 2390 bytes --] Thank you very much Paulo Neves On Fri, 21 Oct 2022 at 23:07, Pedro Alves <pedro@palves.net> wrote: > Hi, > > On 2022-09-30 6:37 p.m., Eli Zaretskii wrote: > >> Cc: ptsneves@gmail.com, gdb-patches@sourceware.org > >> From: Pedro Alves <pedro@palves.net> > >> Date: Fri, 30 Sep 2022 17:41:50 +0100 > >> > >> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi > >> index 2692211f388..4a7b047c3e0 100644 > >> --- a/gdb/doc/python.texi > >> +++ b/gdb/doc/python.texi > >> @@ -2861,21 +2861,21 @@ class MyUnwinder(Unwinder): > >> > >> @end smallexample > >> > >> -@subheading Registering a Unwinder > >> +@subheading Registering an Unwinder > >> > >> -An object file, a program space, and the @value{GDBN} proper can have > >> -unwinders registered with it. > >> +Object files and program spaces can have unwinders registered with > >> +them. In addition, you can also register unwinders globally. > >> > >> -The @code{gdb.unwinders} module provides the function to register a > >> +The @code{gdb.unwinders} module provides the function to register an > >> unwinder: > >> > >> @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) > >> -@var{locus} is specifies an object file or a program space to which > >> -@var{unwinder} is added. Passing @code{None} or @code{gdb} adds > >> -@var{unwinder} to the @value{GDBN}'s global unwinder list. The newly > >> -added @var{unwinder} will be called before any other unwinder from the > >> +@var{locus} specifies which unwinder list the @var{unwinder} is > >> +prepended to. It can be either an object file, a program space, or > >> +@code{None}, in which case the unwinder is registered globally. The > >> +newly added @var{unwinder} will be called before any other unwinder > from the > >> same locus. Two unwinders in the same locus cannot have the same > >> -name. An attempt to add a unwinder with already existing name raises > >> +name. An attempt to add an unwinder with an already existing name > raises > >> an exception unless @var{replace} is @code{True}, in which case the > >> old unwinder is deleted. > >> @end defun > > > > That's fine, but let's avoid passive tense where we can (and make the > > sentence easier to grasp while at that). So: > > > > @var{locus} specifies to which unwinder list to prepend the > > @var{unwinder}. > > > > Finally done, and merged. > > Thanks, > Pedro Alves > > ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: [PATCH v3 1/4] gdb/python doc: Add register_unwinder to code example 2022-06-03 16:01 ` [PATCH v3 1/4] " Paulo Neves ` (2 preceding siblings ...) 2022-06-03 16:01 ` [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code Paulo Neves @ 2022-06-03 16:17 ` Eli Zaretskii 3 siblings, 0 replies; 34+ messages in thread From: Eli Zaretskii @ 2022-06-03 16:17 UTC (permalink / raw) To: Paulo Neves; +Cc: gdb-patches > Date: Fri, 3 Jun 2022 18:01:36 +0200 > From: Paulo Neves via Gdb-patches <gdb-patches@sourceware.org> > Cc: Paulo Neves <ptsneves@gmail.com> > > It is now clear in the example code that an unwinder needs to be > registered to be used. > --- > gdb/doc/python.texi | 2 ++ > 1 file changed, 2 insertions(+) OK, thanks. ^ permalink raw reply [flat|nested] 34+ messages in thread
end of thread, other threads:[~2022-10-22 6:41 UTC | newest] Thread overview: 34+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2022-05-28 11:55 python unwinder doc improvement Paulo Neves 2022-05-28 11:55 ` [PATCH 1/2] gdb/python doc: Add register_unwinder to code example Paulo Neves 2022-05-28 12:20 ` Eli Zaretskii 2022-06-21 11:17 ` Paulo Neves 2022-06-21 12:19 ` Eli Zaretskii 2022-09-30 11:59 ` Paulo Neves 2022-09-30 12:25 ` Eli Zaretskii 2022-05-28 11:55 ` [PATCH 2/2] gdb/python doc: Add enable property to the unwinder example Paulo Neves 2022-05-28 12:22 ` Eli Zaretskii 2022-05-28 13:35 ` Paulo Neves 2022-05-28 13:29 ` [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example Paulo Neves 2022-05-28 13:29 ` [PATCH v2 2/3] gdb/python doc: Add enable property to the unwinder example Paulo Neves 2022-05-30 9:57 ` Andrew Burgess 2022-06-03 15:54 ` Paulo Neves 2022-05-28 13:29 ` [PATCH v2 3/3] gdb/python doc: Fix confusion between gdb.unwinders and gdb.unwinder Paulo Neves 2022-05-30 9:33 ` Andrew Burgess 2022-05-30 9:55 ` [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example Andrew Burgess 2022-05-30 10:12 ` Paulo Neves 2022-06-03 16:01 ` [PATCH v3 1/4] " Paulo Neves 2022-06-03 16:01 ` [PATCH v3 2/4] gdb/python doc: Add enable property to the unwinder example Paulo Neves 2022-06-03 16:17 ` Eli Zaretskii 2022-06-03 16:01 ` [PATCH v3 3/4] gdb/python doc: Fix confusion between gdb.unwinders and gdb.unwinder Paulo Neves 2022-06-03 16:17 ` Eli Zaretskii 2022-06-03 16:01 ` [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code Paulo Neves 2022-06-03 16:20 ` Eli Zaretskii 2022-06-03 16:38 ` Paulo Neves 2022-09-30 14:50 ` Pedro Alves 2022-09-30 15:53 ` Eli Zaretskii 2022-09-30 16:41 ` Pedro Alves 2022-09-30 17:37 ` Eli Zaretskii 2022-10-21 21:07 ` Pedro Alves 2022-10-22 6:41 ` Paulo Neves 2022-10-22 6:41 ` Paulo Neves 2022-06-03 16:17 ` [PATCH v3 1/4] gdb/python doc: Add register_unwinder to code example Eli Zaretskii
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).