Re: [PATCH 12/12] gdb: initial support for ROCm platform (AMDGPU) debugging

[Eli Zaretskii <eliz@gnu.org>]

> Cc: Simon Marchi <simon.marchi@efficios.com>,
>  Zoran Zaric <zoran.zaric@amd.com>,
>  Laurent Morichetti <laurent.morichetti@amd.com>,
>  Tony Tye <Tony.Tye@amd.com>, Lancelot SIX <lancelot.six@amd.com>,
>  Pedro Alves <pedro@palves.net>
> Date: Tue,  6 Dec 2022 08:57:29 -0500
> From: Simon Marchi via Gdb-patches <gdb-patches@sourceware.org>
> 
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -7021,6 +7021,8 @@ signal happened.  @value{GDBN} alerts you to the context switch with a
>  message such as @samp{[Switching to Thread @var{n}]} to identify the
>  thread.  
>  
> +@node set scheduler-locking

This @node is without any @chapter/@section, and does not appear in any
@menu.  That doesn't look right; did you actually succeed in building the
manual with these changes?

> +The following @acronym{AMD GPU} architectures are supported:
> +
> +@table @emph
> +
> +@item @samp{gfx900}
> +AMD Vega 10 devices, displayed as @samp{vega10} by @value{GDBN}.
> +
> +@item @samp{gfx906}
> +AMD Vega 7nm devices, displayed as @samp{vega20} by @value{GDBN}.

Do we really need this long list of architectures in the GDB manual?  It
sounds like an ad for AMD...

> +@smallexample
> +hipcc -O0 -g --offload-arch=gfx900 --offload-arch=gfx906 bit_extract.cpp -o bit_extract
> +@end smallexample

This and other @smallexamples in the patch have too long lines; please break
them into two or more, to avoid problems with the printed format of the
manual.

> +@subsubsection @acronym{AMD GPU} Wavefronts

I think a @cindex about wavefronts would be useful here.

> +@item file_path
> +The file's path specified as a URI encoded UTF-8 string.  In URI
> +encoding, every character that is not:
> +
> +@itemize
> +@item In the @samp{a-z}, @samp{A-Z}, @samp{0-9} ranges
> +@item @samp{/}, @samp{_}, @samp{.}, @samp{~} or @samp{-}
> +@end itemize
> +
> +is encoded as two uppercase hexadecimal digits proceeded by @samp{%}.

You want @noindent before the last line.

> +Directories in the path are separated by @samp{/}.

GNU coding standards frown on using "path" for anything that is not
PATH-style lists of directories.  Please use "file name" instead.

> +The @acronym{AMD GPU} entities have the following target identifier formats:
> +
> +@table @var

@var is wrong here, since the @item text is not a meta-syntactic variable:
it doesn't stand for something else.  I'd use @asis instead.

> +Make sure the container user is a member of the @var{render} group for
> +Ubuntu 20.04 onward and the @var{video} group for all other

??? Why are we talking about specific Linux distros in the manual?

Finally: maybe it's just me, but isn't this documentation way too detailed?
It weighs in at 800 lines, and includes many details that seem to be more
related to AMD, GPU, and HIP than to GDB.  Would it be reasonable to make
this section shorter by omitting too low-level and unrelated details?

Thanks.