From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from eggs.gnu.org (eggs.gnu.org [209.51.188.92]) by sourceware.org (Postfix) with ESMTPS id 3F445385841B for ; Fri, 11 Feb 2022 18:55:05 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 3F445385841B Received: from [2001:470:142:3::e] (port=33366 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nIb4I-00075l-KT; Fri, 11 Feb 2022 13:55:04 -0500 Received: from [87.69.77.57] (port=2951 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 1nIb4G-00064O-IV; Fri, 11 Feb 2022 13:54:54 -0500 Date: Fri, 11 Feb 2022 20:54:44 +0200 Message-Id: <83leyhs07f.fsf@gnu.org> From: Eli Zaretskii To: Andrew Burgess Cc: gdb-patches@sourceware.org In-Reply-To: <20220211161721.3252422-1-aburgess@redhat.com> (message from Andrew Burgess via Gdb-patches on Fri, 11 Feb 2022 16:17:21 +0000) Subject: Re: [PATCH] gdb/python: add gdb.Architecture.format_address References: <20220211161721.3252422-1-aburgess@redhat.com> X-Spam-Status: No, score=-8.0 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_BARRACUDACENTRAL, SPF_HELO_PASS, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 11 Feb 2022 18:55:06 -0000 > Date: Fri, 11 Feb 2022 16:17:21 +0000 > From: Andrew Burgess via Gdb-patches > Cc: Andrew Burgess > > diff --git a/gdb/NEWS b/gdb/NEWS > index e173d38c3a1..4f4f0c2af6d 100644 > --- a/gdb/NEWS > +++ b/gdb/NEWS > @@ -187,6 +187,11 @@ GNU/Linux/LoongArch loongarch*-*-linux* > > GNU/Linux/OpenRISC or1k*-*-linux* > > + ** New function gdb.Architecture.format_address(ADDRESS), which > + takes an address in the currently selected inferior's address > + space, and returns a string representing the address. The format > + of the returned string is '0x.... '. > + > *** Changes in GDB 11 > > * The 'set disassembler-options' command now supports specifying options > diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi > index c1a3f5f2a7e..50443f7b704 100644 > --- a/gdb/doc/python.texi > +++ b/gdb/doc/python.texi > @@ -6016,6 +6016,25 @@ > @code{gdb.Architecture}. > @end defun > > +@defun Architecture.format_address (@var{address}) > +Returns @var{address}, an address within the currently selected Our style is to say "Return", not "Returns". Also, saying "return ADDRESS" basically misses the main rationale of this function, I think; see below. > +inferior's address space, formatted as a string. When a suitable > +symbol can be found to associate with @var{address} this will be > +included in the returned string, formatted like this: > + > +@smallexample > +0x00001042 > +@end smallexample > + > +If there is no symbol that @value{GDBN} can find to associate with > +@var{address} then the returned string will just contain > +@var{address}. > + > +If @var{address} is not accessible within the current inferior's > +address space, this function will still return a string containing > +@var{address}. > +@end defun More generally, I wonder whether the name "format_address" is the best one we could come up with. Isn't this the equivalent of "info symbol" CLI command? If so, why not call it "address_to_symbol" or somesuch? This goes back to the documentation: saying that a method takes its argument and returns it as a string makes the reader wonder why would we need such a trivial method. So the documentation should start by saying that the method returns SYMBOL+OFFSET that corresponds to ADDRESS, and only mention that it returns ADDRESS as a string as the fallback, when SYMBOL cannot be found. Thanks.