From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from eggs.gnu.org (eggs.gnu.org [IPv6:2001:470:142:3::10]) by sourceware.org (Postfix) with ESMTPS id BC3A33858D32 for ; Fri, 10 Mar 2023 15:25:08 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org BC3A33858D32 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=gnu.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gnu.org Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1paecE-0003mL-5K; Fri, 10 Mar 2023 10:25:06 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=ncwmr+lHabiV9oosNOU1GPNOlip0GHO6hBZCWNBz57E=; b=rJ6vsiCBm5zg gQmFwLZHbBoA/uyROcfx+cWjkGlG/VvOCSDckTbzzd0LZwWehKC9W2gCK6kslD8zU8L0kN/wkbpiu r//eiOKTAUUQc9xa13NIiHdvUPWxcbQvX8F2y9azL3OVkkWABSPau/DoK42RS4gaH/fGbI1YxZe6k Dc95QmMT2o+1JZLMDUjGjDUHcfl+O7jM6JNmm9kHS3YCUFnQAqI/jF7z9Ak7xvvM35/sLK1nt+2+d PhLl+Ox1nN8bq3iB17Fte4IkJkvOMKX+soka/cA++Wj92H/oVdGzpUGWbZcLM/L/+eFQEN8iQ8azI JfPlT1uScOKOSMF7W0NgcA==; Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1paecC-00020t-A3; Fri, 10 Mar 2023 10:25:05 -0500 Date: Fri, 10 Mar 2023 17:24:47 +0200 Message-Id: <834jqszl1c.fsf@gnu.org> From: Eli Zaretskii To: Andrew Burgess Cc: gdb-patches@sourceware.org In-Reply-To: <3bad3bab1077f38d3f508e0cb4a071663e745b06.1678460067.git.aburgess@redhat.com> (message from Andrew Burgess via Gdb-patches on Fri, 10 Mar 2023 14:55:18 +0000) Subject: Re: [PATCH 01/10] gdb/doc: spring clean the Python unwinders documentation References: <3bad3bab1077f38d3f508e0cb4a071663e745b06.1678460067.git.aburgess@redhat.com> X-Spam-Status: No, score=1.8 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_BARRACUDACENTRAL,SPF_HELO_PASS,SPF_PASS,TXREP autolearn=no autolearn_force=no version=3.4.6 X-Spam-Level: * X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: > 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?). > +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. > +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. > +@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. Reviewed-By: Eli Zaretskii