From: Eli Zaretskii <eliz@gnu.org>
To: Andrew Burgess <aburgess@redhat.com>
Cc: gdb-patches@sourceware.org
Subject: Re: [PATCH 5/5] gdb/python: extend the Python Disassembler API to allow for styling
Date: Tue, 04 Apr 2023 15:01:17 +0300 [thread overview]
Message-ID: <83v8ibua9e.fsf@gnu.org> (raw)
In-Reply-To: <62700c9aaddb83cc05e1b5e51e115d4eea8281e4.1680596378.git.aburgess@redhat.com> (message from Andrew Burgess via Gdb-patches on Tue, 4 Apr 2023 09:21:07 +0100)
> Cc: Andrew Burgess <aburgess@redhat.com>
> Date: Tue, 4 Apr 2023 09:21:07 +0100
> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
>
> gdb/NEWS | 19 +
> gdb/doc/python.texi | 313 +++++++++-
> gdb/python/py-disasm.c | 818 +++++++++++++++++++++++--
> gdb/testsuite/gdb.python/py-disasm.exp | 94 ++-
> gdb/testsuite/gdb.python/py-disasm.py | 158 ++++-
> 5 files changed, 1309 insertions(+), 93 deletions(-)
Thanks.
> diff --git a/gdb/NEWS b/gdb/NEWS
> index d1726842299..dceccf09c6d 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -155,6 +155,25 @@ info main
> ** It is now no longer possible to sub-class the
> gdb.disassembler.DisassemblerResult type.
>
> + ** The Disassembler API from the gdb.disassembler module has been
> + extended to include styling support:
> +
> + - The DisassemblerResult class can now be initialized with a list
> + of parts. Each part represents part of the disassembled
> + instruction along with the associated style information. This
> + list of parts can be accessed with the new
> + DisassemblerResult.parts property.
> +
> + - New constants gdb.disassembler.STYLE_* representing all the
> + different styles part of an instruction might have.
> +
> + - New methods DisassembleInfo.text_part and
> + DisassembleInfo.address_part which are used to create the new
> + styled parts of a disassembled instruction.
> +
> + - Changes are backwards compatible, the older API can still be
> + used to disassemble instructions without styling.
> +
> *** Changes in GDB 13
This part is OK.
> +@defun DisassembleInfo.text_part (@var{style}, @var{string})
Same question about @var inside @defun.
> +@defun DisassembleInfo.address_part (@var{address})
> +Create a new @code{DisassemblerAddressPart}. @var{address} is the
> +value of the absolute address this part represents. When @value{GDBN}
> +displays an address part it display the absolute address, and also an
> +associated symbol.
The last sentence is problematic ("When GDB dipslays [...] it
display...") Suggest to rephrase.
> +Only one of @var{string} or @var{parts} should be used to initialize a
> +new @code{DisassemblerResult}, whichever is not used should be passed
> +the value @code{None}, or the arguments can be passed by name, and the
> +unused argument can be ignored.
This sentence is hard to parse. Suggest to reword:
Only one of @var{string} or @var{parts} should be used to initialize
a new @code{DisassemblerResult}; the other one should be passed the
value @code{None}. Alternatively, the arguments can be passed by
name, and the unused argument can be ignored.
> +The @var{string} argument, if not @code{None}, is a non-empty string
> +that represents the entire disassembled instruction. Building a result
^^
Two spaces there.
> +If this instance was initialized using a single string rather than a
^
That "a" should be deleted.
> +The following table lists all of the disassembler styles that are
> +available. @value{GDBN} maps these style constants onto its style
> +settings (@pxref{Output Styling}). In some cases multiple of these
> +style constants map to the same style setting.
Suggest to reword the last sentence above:
In some cases, several style constants produce the same style
settings, and thus will produce the same visual effect on the
screen.
> This could change in
> +future releases of @value{GDBN}, so care should be taken to select the
> +correct style constant to ensure correct output styling on future
> +releases of @value{GDBN}. ^^
"in", not "on".
> +@vindex STYLE_IMMEDIATE
> +@item gdb.disassembler.STYLE_IMMEDIATE
> +This style is used for styling numerical values within a disassembled
> +instruction when those values are not addresses, address offsets, or
> +register numbers, use @code{STYLE_ADDRESS},
> +@code{STYLE_ADDRESS_OFFSET}, or @code{STYLE_REGISTER} in those cases.
This should be rewritten as 2 separate sentences: one describing which
values use STYLE_IMMEDIATE, the other (perhaps in parentheses)
describing the alternative style constants for other kinds of values.
> +For any other numerical value within a disassembled instruction,
> +@code{STYLE_IMMEDIATE} should be used.
This reads awkward, both because it uses passive voice, and because
the verb is at the end. Reword:
Use the @code{STYLE_IMMEDIATE} for any other values within a
disassembled instruction.
Also, it sounds like this just repeats the first of the two sentences
above, so perhaps it should be removed?
It might be a good idea to describe the "other" styles for values
first, and then the "immediate" style, as the catchall for the other
values.
> +referring too. For example, this x86-64 instruction:
> +
> +@smallexample
> +call 0x401136 <foo>
> +@end smallexample
> +
> +@noindent
> +Here @code{foo} is the name of a symbol, and should be given the
> +@code{STYLE_SYMBOL} style.
Since you start a new sentence after @noindent, the "For example" part
should be reworded, perhaps leaving just "For example:".
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
next prev parent reply other threads:[~2023-04-04 12:00 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-04-04 8:21 [PATCH 0/5] Disassembler Styling And The Python API Andrew Burgess
2023-04-04 8:21 ` [PATCH 1/5] gdb/doc: improve Python Disassembler API documentation Andrew Burgess
2023-04-04 11:36 ` Eli Zaretskii
2023-04-28 22:49 ` Andrew Burgess
2023-05-12 17:42 ` Andrew Burgess
2023-04-04 8:21 ` [PATCH 2/5] gdb/python: implement __repr__ methods for py-disasm.c types Andrew Burgess
2023-05-12 17:43 ` Andrew Burgess
2023-04-04 8:21 ` [PATCH 3/5] gdb/python: implement DisassemblerResult.__str__ method Andrew Burgess
2023-05-12 17:43 ` Andrew Burgess
2023-04-04 8:21 ` [PATCH 4/5] gdb/python: rework how the disassembler API reads the result object Andrew Burgess
2023-04-04 11:38 ` Eli Zaretskii
2023-04-04 8:21 ` [PATCH 5/5] gdb/python: extend the Python Disassembler API to allow for styling Andrew Burgess
2023-04-04 12:01 ` Eli Zaretskii [this message]
2023-04-28 23:11 ` Andrew Burgess
2023-04-17 16:25 ` Tom Tromey
2023-04-28 23:09 ` [PATCHv2 " Andrew Burgess
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83v8ibua9e.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=aburgess@redhat.com \
--cc=gdb-patches@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).