Re: [PATCH] [gdb/doc] aarch64: Expand documentation of XML features

[Eli Zaretskii <eliz@gnu.org>]

> From: Luis Machado <luis.machado@arm.com>
> CC: <eliz@gnu.org>
> Date: Thu, 23 Feb 2023 09:52:44 +0000
> 
> Similar to the arm target documentation situation, the documentation of the
> XML features for AArch64 targets is rather brief.  I have received the same
> feedback that what gdb carries in the documentation is quite unclear from the
> perspective of what debugging servers should define in the XML features, how and
> what the outcome is in gdb.
> 
> This patch attempts to clarify a bit more what all the possible features are.

Thanks.

>  The @samp{org.gnu.gdb.aarch64.core} feature is required for AArch64
> -targets.  It should contain registers @samp{x0} through @samp{x30},
> -@samp{sp}, @samp{pc}, and @samp{cpsr}.
> +targets.  It must contain the following:
> +
> +@itemize @minus
> +@item
> +@samp{x0} through @samp{x30}, with size of 64-bit.  Register @samp{x30} is

This doesn't say these are registers, please add that.

> +also known as the link register @samp{lr}.

The "link register" part should probably be in @dfn, and "@samp{lr}"
should probably be ", or @samp{lr}", as it's an alternative name AFAIU.

> +@item
> +@samp{pc}, the program counter register. It is 64-bit in size and has a type
> +of @samp{code_ptr}.                    ^^

Two spaces there, please.

> +The @samp{cpsr} flags type gets updated based on new architectural
> +features.

"flags type gets updated" sounds awkward and confusing.  What did you
mean by that? what is updated?

> +@item
> +@samp{v0} through @samp{v31}, the vector registers with size of 128-bit.  The
                                                                   ^^^^^^^
The dash is redundant there and should be dropped.

> +@samp{z0} through @samp{z31}, the scalable vector registers.  Their sizes are
> +variable and a multiple of 128-bit up to a maximum of 2048-bit.  Their type is

Same here.

> +@samp{p0} through @samp{p15}, the predicate registers.  Their sizes are
> +variable, based on the current vector length, and a multiple of 16-bit.  Their

And here.

> +@item
> +@samp{ffr}, the First Fault register.  It has a variable size based on the
> +current vector length and is a multiple of 16-bit.  The type is the same as

And here.  Also, "and is" is ambiguous: you mean the size is a
multiple, but the text can be interpreted as alluding to the register,
not its size.

Reviewed-By: Eli Zaretskii <eliz@gnu.org>