From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id F2C693858D39 for ; Tue, 14 Mar 2023 09:27:39 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org F2C693858D39 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1678786059; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=EEGQI1WqS/S3qjFYHHhUjitmwCBB+6fVtor/IcGCsrU=; b=M7Z7jcvXT+pEYu41/bI93yzVkNS4hChbYJqDYNUJm9evxgSQzBJLqPlTNtOIu23tbCKPpA TvWg/SN+leyUeToNSdMniQG7YVvM5Xp0BKIBgHvOeI1bceacwBfb3RrJ+doX3A7aFxARFp O4kyM3OIILTBX/hAv9uHXEfzn3E3Vbw= Received: from mail-ed1-f72.google.com (mail-ed1-f72.google.com [209.85.208.72]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-650-hGpBvg1ZPpmXHqrhfsWG5Q-1; Tue, 14 Mar 2023 05:27:38 -0400 X-MC-Unique: hGpBvg1ZPpmXHqrhfsWG5Q-1 Received: by mail-ed1-f72.google.com with SMTP id r9-20020a05640251c900b004d4257341c2so20979508edd.19 for ; Tue, 14 Mar 2023 02:27:38 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1678786057; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=EEGQI1WqS/S3qjFYHHhUjitmwCBB+6fVtor/IcGCsrU=; b=TgX3zQR7lcjLISq384JbBJUBAq0FvTBR6d8JH4qApCLFMvaYeTyTDy0GwepaWMk6WB pvsq2UfjsgrWKn2IQYWGGY8hI/fpL7iL0Mk5AKtY8vLwcEqel7XWtN1ALFLt86BsbIJ+ 59I5J5rgiLtEl6t+YCBsKFcD0vxz+N2oQrMBehD85fo/SLtnHPFH4osZ7TfRyRNSFaO/ DU+QzTUToZW27BvnbydOuWBdyAlSIafn7rs9t0Ds7fQ6nkDn0sIFz6jGEWltxcKZr0YO ej08IdysHHbZa4YyFVSWeGnqsP17WS5QzuOjjDaF/TtDvyEFefCkRN7F2UqkmIpS196a RdvA== X-Gm-Message-State: AO0yUKULP5YW7If3n1jlmRtbP4gj9wMG+vJIDjozkO2jFnXfUwfySoOX g4tbptX/7IwtmIjczE2OxRZD2olannQd5lduZvGFrTYcAmaq2iWHuD7h2mGcwOUu6qi8QvPXV5h 3SX6GPt3TPV+u6sVVpcVCXQDeyikRFg== X-Received: by 2002:a17:906:702:b0:913:ff28:59bd with SMTP id y2-20020a170906070200b00913ff2859bdmr1684687ejb.52.1678786057009; Tue, 14 Mar 2023 02:27:37 -0700 (PDT) X-Google-Smtp-Source: AK7set/NrRRjs/OUQDCahb7Ci54uenq/g1DFOnx3fNHGFO7y8YyFwIgXzexGZQvaF3nf/zk6QQKRgg== X-Received: by 2002:a17:906:702:b0:913:ff28:59bd with SMTP id y2-20020a170906070200b00913ff2859bdmr1684671ejb.52.1678786056646; Tue, 14 Mar 2023 02:27:36 -0700 (PDT) Received: from localhost (95.72.115.87.dyn.plus.net. [87.115.72.95]) by smtp.gmail.com with ESMTPSA id hp2-20020a1709073e0200b008b175c46867sm866090ejc.116.2023.03.14.02.27.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 14 Mar 2023 02:27:36 -0700 (PDT) From: Andrew Burgess To: Eli Zaretskii Cc: gdb-patches@sourceware.org Subject: Re: [PATCH 01/10] gdb/doc: spring clean the Python unwinders documentation In-Reply-To: <834jqszl1c.fsf@gnu.org> References: <3bad3bab1077f38d3f508e0cb4a071663e745b06.1678460067.git.aburgess@redhat.com> <834jqszl1c.fsf@gnu.org> Date: Tue, 14 Mar 2023 09:27:29 +0000 Message-ID: <87mt4ffzsu.fsf@redhat.com> MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain X-Spam-Status: No, score=-11.7 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_NONE,TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: Eli Zaretskii writes: >> Cc: Andrew Burgess >> Date: Fri, 10 Mar 2023 14:55:18 +0000 >> From: Andrew Burgess via Gdb-patches >> >> The documentation for the Python Unwinders API could do with some >> improvement. The 'Unwinder Skeleton Code' has an error: it says >> 'unwinders' when it should say 'unwinder' in one case. >> >> Additionally, by placing the 'Unwinder Skeleton Code' before the >> section 'Registering an Unwinder' we have skipping including the >> registration line in the skeleton code. But this is confusion for >> users (I think) as the skeleton code is almost complete, except for >> one missing line which the user has to figure out for themselves. By >> reordering the sections, it is now obvious that the registration >> should be included in the skeleton code, and the example is therefore >> almost complete. >> >> Additionally, in the example skeleton code the way in which the >> frame-id was being built (using the current stack point and program >> counter is (a) not correct, and (b) counter to what is laid out in the >> 'Unwinder Input' section when describing building a frame-id. >> >> I've removed the incorrect code and replaced it with more generic >> comments indicating what needs to be done. As the actual actions that >> need to be performed are both architecture specific, and dependent on >> the function being unwound, it's almost impossible to include more >> exact code here, but I think what I'm proposing is less misleading >> than what we had before. >> >> I've also added more cross references. >> --- >> gdb/doc/python.texi | 82 ++++++++++++++++++++++++--------------------- >> 1 file changed, 44 insertions(+), 38 deletions(-) > > Thanks. > >> @defun PendingFrame.create_unwind_info (frame_id) >> Returns a new @code{gdb.UnwindInfo} instance identified by given >> -@var{frame_id}. The argument is used to build @value{GDBN}'s frame ID >> -using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes >> -determine which function will be used, as follows: >> +@var{frame_id}. The @var{frame_id} is used internally by @value{GDBN} >> +to identify the frames within the current thread's stack. The >> +attributes of @var{frame_id} determine what type of frame ID is >> +created within @value{GDBN}: ^^^^^^^^ > > I think the "ID" part there should be dropped (you are talking about > creating frames, not IDs, right?). Good spot. I dropped the 'ID'. > >> +Object files and program spaces can have unwinders registered with >> +them. In addition, you can also register unwinders globally. > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > Either "in addition" or "also", but not both. This sentence has become: In addition, you can register unwinders globally. > >> +same 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 and the new unwinder is registered in >> +its place. ^^ > ^^^^^^^^^ > I believe "in its stead" is better English-wise. Changed to '... this command installed in its stead.' > >> +@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, >> +then the globally registered unwinders, and finally the unwinders >> +builtin to @value{GDBN}. > > This text is too short to justify a separate @subheading, IMO. I folded this section into the previous function description. The previous function is how to register unwinders, so adding information about the order in which registered unwinders are called feels like a good fit. > > Reviewed-By: Eli Zaretskii I added your tag, but the updated patch is below if you want to take another pass. Thank, Andrew --- commit 861c24ec4d306d7604818cff0cd5c6063292376f Author: Andrew Burgess Date: Wed Mar 8 15:26:32 2023 +0000 gdb/doc: spring clean the Python unwinders documentation The documentation for the Python Unwinders API could do with some improvement. The 'Unwinder Skeleton Code' has an error: it says 'unwinders' when it should say 'unwinder' in one case. Additionally, by placing the 'Unwinder Skeleton Code' before the section 'Registering an Unwinder' we have skipping including the registration line in the skeleton code. But this is confusion for users (I think) as the skeleton code is almost complete, except for one missing line which the user has to figure out for themselves. By reordering the sections, it is now obvious that the registration should be included in the skeleton code, and the example is therefore almost complete. Additionally, in the example skeleton code the way in which the frame-id was being built (using the current stack point and program counter is (a) not correct, and (b) counter to what is laid out in the 'Unwinder Input' section when describing building a frame-id. I've removed the incorrect code and replaced it with more generic comments indicating what needs to be done. As the actual actions that need to be performed are both architecture specific, and dependent on the function being unwound, it's almost impossible to include more exact code here, but I think what I'm proposing is less misleading than what we had before. I've also added more cross references. Reviewed-By: Eli Zaretskii diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index b04f1de2ddf..54d5660543a 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -2784,9 +2784,10 @@ @defun PendingFrame.create_unwind_info (frame_id) Returns a new @code{gdb.UnwindInfo} instance identified by given -@var{frame_id}. The argument is used to build @value{GDBN}'s frame ID -using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes -determine which function will be used, as follows: +@var{frame_id}. The @var{frame_id} is used internally by @value{GDBN} +to identify the frames within the current thread's stack. The +attributes of @var{frame_id} determine what type of frame is +created within @value{GDBN}: @table @code @item sp, pc @@ -2841,6 +2842,32 @@ @var{value} is a register value (a @code{gdb.Value} object). @end defun +@subheading Registering an Unwinder + +Object files and program spaces can have unwinders registered with +them. In addition, you can register unwinders globally. + +The @code{gdb.unwinders} module provides the function to register an +unwinder: + +@defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) +@var{locus} specifies to which unwinder list to prepend the +@var{unwinder}. It can be either an object file (@pxref{Objfiles In +Python}), a program space (@pxref{Progspaces In Python}), 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 an unwinder with an already existing +name raises an exception unless @var{replace} is @code{True}, in which +case the old unwinder is deleted and the new unwinder is registered in +its place. + +@value{GDBN} first calls the unwinders from all the object files in no +particular order, then the unwinders from the current program space, +then the globally registered unwinders, and finally the unwinders +builtin to @value{GDBN}. +@end defun + @subheading Unwinder Skeleton Code @value{GDBN} comes with the module containing the base @code{Unwinder} @@ -2848,7 +2875,7 @@ follows: @smallexample -from gdb.unwinders import Unwinder +from gdb.unwinder import Unwinder class FrameId(object): def __init__(self, sp, pc): @@ -2857,53 +2884,30 @@ class MyUnwinder(Unwinder): - def __init__(....): - super(MyUnwinder, self).__init___() + def __init__(self): + super().__init___("MyUnwinder_Name") - def __call__(pending_frame): + def __call__(self, pending_frame): if not : return None - # Create UnwindInfo. Usually the frame is identified by the stack - # pointer and the program counter. - sp = pending_frame.read_register() - pc = pending_frame.read_register() + + # Create a FrameID. Usually the frame is identified by a + # stack pointer and the function address. + sp = ... compute a stack address ... + pc = ... compute function address ... unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc)) - # Find the values of the registers in the caller's frame and + # Find the values of the registers in the caller's frame and # save them in the result: - unwind_info.add_saved_register(, ) + unwind_info.add_saved_register(, ) .... # Return the result: return unwind_info +gdb.unwinder.register_unwinder(, MyUnwinder(), ) @end smallexample -@subheading Registering an Unwinder - -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 an -unwinder: - -@defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) -@var{locus} specifies to which unwinder list to prepend the -@var{unwinder}. 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 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 - -@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 @@ -4398,7 +4402,7 @@ commands. Setting this attribute to @code{True} will install the command for use. If there is already a Python command with this name installed, the currently installed command will be uninstalled, and -this command installed in its place. +this command installed in its stead. @end defvar The following code snippet shows how a two trivial MI command can be