public inbox for gdb-patches@sourceware.org
 help / color / mirror / Atom feed
From: Pedro Alves <pedro@palves.net>
To: Tom Tromey <tromey@adacore.com>, gdb-patches@sourceware.org
Subject: Re: [PATCH] Update the 'g' packet documentation
Date: Fri, 13 Jan 2023 12:09:21 +0000	[thread overview]
Message-ID: <533a8893-c0b2-ec5a-fa11-f83bf98f4429@palves.net> (raw)
In-Reply-To: <20230111183725.2902496-1-tromey@adacore.com>

Hi Tom,

On 2023-01-11 6:37 p.m., Tom Tromey via Gdb-patches wrote:
> The 'g' packet documentation references a macro that no longer exists,
> and it also claims that the 'x' response for an unavailable register
> is limited to trace frames.  This patch updates the documentation to
> reflect what I think is currently correct.
> ---
>  gdb/doc/gdb.texinfo | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 9c0018ea5c1..80584241870 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -41318,11 +41318,12 @@ Reply:
>  Each byte of register data is described by two hex digits.  The bytes
>  with the register are transmitted in target byte order.  The size of
>  each register and their position within the @samp{g} packet are
> -determined by the @value{GDBN} internal gdbarch functions
> -@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}.
> +determined by the target description (@pxref{Target Descriptions}); in
> +the absence of a target description, this is done using code internal
> +to @value{GDBN}; typically this is some customary register layout for
> +the architecture in question.
>  

This part seems fine.

> -When reading registers from a trace frame (@pxref{Analyze Collected
> -Data,,Using the Collected Data}), the stub may also return a string of
> +When reading registers, the stub may also return a string of
>  literal @samp{x}'s in place of the register data digits, to indicate
>  that the corresponding register has not been collected, thus its value
>  is unavailable.  For example, for an architecture with 4 registers of
> 

Here, the new text still uses "collected", but lost the reference to trace frames.
It seems to me that that will result in people not knowing what "collected"
means in this context.  I suggest flipping things around a little, like:

 When reading registers, the stub may also return a string of
 literal @samp{x}'s in place of the register data digits, to indicate
 that the corresponding register's value is unavailable.  For example,
 when reading registers from a trace frame (@pxref{Analyze Collected
 Data,,Using the Collected Data}), this means that the register has
 not been collected.

and then the following sentence, where it reads

 For example, for an architecture with 4 registers of
 4 bytes each, the following reply indicates to @value{GDBN} that
 registers 0 and 2 have not been collected, while registers 1 and 3
 have been collected, and both have zero value:

it may be better to tweak it to say something like:

 For example, for an architecture with 4 registers of
 4 bytes each, the following reply indicates to @value{GDBN} that
 registers 0 and 2 are unavailable, while registers 1 and 3
 are available, and both have zero value:

  parent reply	other threads:[~2023-01-13 12:09 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-01-11 18:37 Tom Tromey
2023-01-11 19:56 ` Eli Zaretskii
2023-01-13 12:09 ` Pedro Alves [this message]
2023-01-13 18:58   ` Tom Tromey
2023-01-27 15:25     ` [PATCH v2] " Pedro Alves
2023-01-27 16:15       ` Eli Zaretskii
2023-01-30 21:15       ` Tom Tromey
2023-02-16 17:10         ` Pedro Alves
2023-02-16 18:16           ` Tom Tromey

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=533a8893-c0b2-ec5a-fa11-f83bf98f4429@palves.net \
    --to=pedro@palves.net \
    --cc=gdb-patches@sourceware.org \
    --cc=tromey@adacore.com \
    /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).