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 3D7913857034 for ; Fri, 6 May 2022 18:11:18 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 3D7913857034 Received: from fencepost.gnu.org ([2001:470:142:3::e]:51116) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nn2Q9-0005hz-QL; Fri, 06 May 2022 14:11:17 -0400 Received: from [87.69.77.57] (port=3894 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 1nn2Q7-0002xA-04; Fri, 06 May 2022 14:11:17 -0400 Date: Fri, 06 May 2022 21:11:03 +0300 Message-Id: <83wneyzg3s.fsf@gnu.org> From: Eli Zaretskii To: Andrew Burgess Cc: gdb-patches@sourceware.org In-Reply-To: <6bb32e0a83539ac7d5b51e5aa306e683f4fedf1b.1651857000.git.aburgess@redhat.com> (message from Andrew Burgess via Gdb-patches on Fri, 6 May 2022 18:17:12 +0100) Subject: Re: [PATCHv5 3/5] gdb/python: implement the print_insn extension language hook References: <6bb32e0a83539ac7d5b51e5aa306e683f4fedf1b.1651857000.git.aburgess@redhat.com> X-Spam-Status: No, score=-7.6 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, 06 May 2022 18:11:19 -0000 > Date: Fri, 6 May 2022 18:17:12 +0100 > From: Andrew Burgess via Gdb-patches > Cc: Andrew Burgess > > diff --git a/gdb/NEWS b/gdb/NEWS > index 982f4a1a18c..ddbaff51f89 100644 > --- a/gdb/NEWS > +++ b/gdb/NEWS > @@ -38,6 +38,40 @@ maintenance info line-table > This is the same format that GDB uses when printing address, symbol, > and offset information from the disassembler. > > + ** New Python API for wrapping GDB's disassembler: > + > + - gdb.disassembler.register_disassembler(DISASSEMBLER, ARCH). > + DISASSEMBLER is a sub-class of gdb.disassembler.Disassembler. > + ARCH is either None or a string containing a bfd architecture > + name. DISASSEMBLER is registered as a disassembler for > + architecture ARCH, or for all architectures if ARCH is None. > + The previous disassembler registered for ARCH is returned, this > + can be None if no previous disassembler was registered. > + > + - gdb.disassembler.Disassembler is the class from which all > + disassemblers should inherit. Its constructor takes a string, > + a name for the disassembler, which is currently only used in > + some debug output. Sub-classes should override the __call__ > + method to perform disassembly, invoking __call__ on this base > + class will raise an exception. > + > + - gdb.disassembler.DisassembleInfo is the class used to describe > + a single disassembly request from GDB. An instance of this > + class is passed to the __call__ method of > + gdb.disassembler.Disassembler and has the following read-only > + attributes: 'address', and 'architecture', as well as the > + following method: 'read_memory'. > + > + - gdb.disassembler.builtin_disassemble(INFO, MEMORY_SOURCE), > + calls GDB's builtin disassembler on INFO, which is a > + gdb.disassembler.DisassembleInfo object. MEMORY_SOURCE is > + optional, its default value is None. If MEMORY_SOURCE is not > + None then it must be an object that has a 'read_memory' method. > + > + - gdb.disassembler.DisassemblerResult is a class that can be used > + to wrap the result of a call to a Disassembler. It has > + read-only attributes 'length' and 'string'. > + > *** Changes in GDB 12 This part is OK. > +@smallexample > +(@value{GDBP}) show architecture > +The target architecture is set to "auto" (currently "i386"). > +(@value{GDBP}) maint info python-disassemblers > +Architecture Disassember Name > +i386 Disassembler_1 (Matches current architecture) > +GLOBAL Disassembler_2 > +(@value{GDBP}) set architecture arm > +The target architecture is set to "arm". > +(@value{GDBP}) maint info python-disassemblers > +quit > +Architecture Disassember Name > +i386 Disassembler_1 > +GLOBAL Disassembler_2 (Matches current architecture) > +@end smallexample It is best to subdivide this long example into at least 2 groups using @group..@end group. This way, the example will not be broken between 2 pages in some arbitrary place. My suggestion is to do this: +@smallexample + group +(@value{GDBP}) show architecture +The target architecture is set to "auto" (currently "i386"). +(@value{GDBP}) maint info python-disassemblers +Architecture Disassember Name +i386 Disassembler_1 (Matches current architecture) +GLOBAL Disassembler_2 +@end group +@group +(@value{GDBP}) set architecture arm +The target architecture is set to "arm". +(@value{GDBP}) maint info python-disassemblers +quit +Architecture Disassember Name +i386 Disassembler_1 +GLOBAL Disassembler_2 (Matches current architecture) +@end group +@end smallexample > +Consider, for example, and architecture with 2-byte and 4-byte ^^^ I think you meant "an" there. > +order to establish if the instruction is 2 or 4 bytes long. If the > +instruction is 4-bytes long then the disassembler might then read the ^^^^ ^^^^ Two "then" in a row; one of them is redundant. > +@defun DisassemblerResult.__init__ (@var{length}, @var{string}) > +Initialise an instance of this class, @var{length} is the length of ^^^^^^^^^^ "Initialize". We use the US spelling. > +To see which disassemblers have been registered the @kbd{maint info > +python-disassemblers} command can be used (@pxref{maint info > +python-disassemblers}). It is better to use active tense: "you can use ... to see which disassemblers ...". Thanks.