Re: [PATCH 25/25] Document remote clone events, and QThreadOptions packet

[Eli Zaretskii <eliz@gnu.org>]

> From: Pedro Alves <pedro@palves.net>
> Date: Mon, 20 Jun 2022 23:54:19 +0100
> 
> This commit documents in both manual and NEWS:
> 
>  - the new remote clone event stop reply,
>  - the new QThreadOptions packet and its current defined options,
>  - the associated "set/show remote thread-events-packet" command,
>  - and the associated QThreadOptions qSupported feature.

Thanks.

>    ** GDBserver is now supported on LoongArch GNU/Linux.
>  
> +* New remote packets
> +
> +clone stop reason
> +  Indicates that a clone system call was executed.

I'm confused: what is the relation between the "stop reason" part and
the description saying that "a clone system call was executed"?  The
gdb.texinfo description only mentions "clone" as the packet name,
without the other 2 words.  What am I missing?

> +@cindex thread clone events, remote reply
> +@anchor{thread clone event}
> +@item clone
> +The packet indicates that @code{clone} was called, and @var{r} is the
> +thread ID of the new child thread.  Refer to @ref{thread-id syntax}
> +for the format of the @var{thread-id} field.  This packet is only
> +applicable to targets that support clone events.

The text refers to @var{r} and @var{thread-id}, but they are not
present on the @item line that describes the packet itself.  Where are
those parameters used in this case.

> +@item QThreadOptions@r{[};@var{options}@r{[}:@var{thread-id}@r{]]}@dots{}
> +@cindex thread options, remote request
> +@cindex @samp{QThreadOptions} packet
> +
> +For each inferior thread, the rightmost options with a matching
> +@var{thread-id} are applied.

"Rightmost" means here "the last in the list"?  If so, perhaps it's
worth saying that explicitly to avoid possible confusion.

> +@item
> +Without clone events (on systems where threads are spawned via a clone
> +system call), if the single-stepped thread spawns a new clone child
> +(i.e., it executes a clone system call), and:
> +
> +@itemize @minus
> +@item
> +the breakpoint is stepped-over in-line, the spawned thread incorrectly
> +runs free while the breakpoint being stepped over is not inserted,
> +thus the spawned thread may potentially run past the breakpoint
> +without stopping for it.  By enabling @code{GDB_TO_CLONE}, the new
> +cloned thread is halted before it executes any instruction;
> +
> +@item
> +if alternativelly displaced (out-of-line) stepping is used, the
> +spawned thread starts running at the out-of-line PC, leading to
> +undefined behavior, usually crashes or data corruption.  By enabling
> +@code{GDB_TO_CLONE}, the new cloned thread is halted before it
> +executes any instruction, and @value{GDBN} adjusts its PC before
> +resuming its execution.
> +@end itemize

This reads awkwardly, because you say "and:", and start each @item of
the following itemized list with a lower-case letter, but each @item
includes more than one sentence.  How about the following rephrasing:

    For example, @value{GDBN} enables the @code{GDB_TO_EXIT} and
    @code{GDB_TO_CLONE} options when single-stepping a thread past a
    breakpoint, for the following reasons:

    @itemize @bullet
    @item
    If the single-stepped thread exits (e.g., it executes a thread exit
    system call), enabling @code{GDB_TO_EXIT} prevents @value{GDBN} from
    waiting forever, not knowing that it should no longer expect a stop for
    that same thread, and blocking other threads from progressing.

    @item
    If the single-stepped thread spawns a new clone child (i.e., it
    executes a clone system call), enabling @code{GDB_TO_CLONE} halts the
    cloned thread before it executes any instructions, and thus prevents
    the following problematic situations:

    @itemize @minus
    @item
    if the breakpoint is stepped-over in-line, the spawned thread would
    incorrectly run free while the breakpoint being stepped over is not
    inserted, and thus the cloned thread may potentially run past the
    breakpoint without stopping for it;

    @item
    if displaced (out-of-line) stepping is used, the cloned thread starts
    running at the out-of-line PC, leading to undefined behavior, usually
    crashing or corrupting data.
    @end itemize

    @end itemize