From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from eggs.gnu.org (eggs.gnu.org [209.51.188.92]) by sourceware.org (Postfix) with ESMTPS id 376B43858407 for ; Mon, 11 Jul 2022 16:10:15 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 376B43858407 Received: from fencepost.gnu.org ([2001:470:142:3::e]:55588) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oAvzC-0004tO-Np; Mon, 11 Jul 2022 12:10:14 -0400 Received: from [87.69.77.57] (port=4859 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oAvz5-0007GW-0u; Mon, 11 Jul 2022 12:10:14 -0400 Date: Mon, 11 Jul 2022 19:09:54 +0300 Message-Id: <83k08jzl4d.fsf@gnu.org> From: Eli Zaretskii To: Pedro Alves Cc: gdb-patches@sourceware.org In-Reply-To: <8ca45d20-55f3-f3b0-82c3-971d54f2e0a3@palves.net> (message from Pedro Alves on Mon, 11 Jul 2022 16:19:57 +0100) Subject: Re: [PATCH 25/25] Document remote clone events, and QThreadOptions packet References: <20220620225419.382221-1-pedro@palves.net> <20220620225419.382221-26-pedro@palves.net> <838rpqkyof.fsf@gnu.org> <8ca45d20-55f3-f3b0-82c3-971d54f2e0a3@palves.net> X-Spam-Status: No, score=1.5 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, RCVD_IN_BARRACUDACENTRAL, SPF_HELO_PASS, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=no autolearn_force=no version=3.4.6 X-Spam-Level: * X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 11 Jul 2022 16:10:16 -0000 > Cc: gdb-patches@sourceware.org > From: Pedro Alves > Date: Mon, 11 Jul 2022 16:19:57 +0100 > > >> +* 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? > > A "stop reason" is a remote-protocol defined term, which should be familiar > to remote stub maintainers. See here: I see. It's highly confusing, IMO, although we use it elsewhere in NEWS. I would suggest at least 'clone', a stop reason or 'clone' (a stop reason) or even new stop reason: 'clone' (Yes, for the rest of similar entries as well. No, I don't insist.) > fork stop reason > Indicates that a fork system call was executed. > > vfork stop reason > Indicates that a vfork system call was executed. Just for the record: you do realize that using 3 nouns, 2 of which can also be verbs, in a row, without any context creates very ambiguous text? "clone stop reason" could be interpreted as "clone the stop reason" (i.e. the stop reason should be cloned) or "reason for stopping the clone" or "stop reason of the clone" and probably a few others. > @cindex fork events, remote reply > @item fork > The packet indicates that @code{fork} was called, and @var{r} > is the thread ID of the new child process. Refer to > @ref{thread-id syntax} for the format of the @var{thread-id} > field. (...) > > A bit further above, we say: > > @item > If @var{n} is @samp{thread}, then @var{r} is the @var{thread-id} of > the stopped thread, as specified in @ref{thread-id syntax}. "thread-id" should not be in @var here, since it is not referenced anywhere. The text about fork events that you cite above gets that right, and the new text should so the same. > >> +@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. > > I can change it, but I'm curious what the confusion could be? I used > rightmost here to contrast with the vCont description, which uses "leftmost". I don't think "left" and "right" are well defined in this context, so they sound strange (especially to someone who reads RTL text every day). Why not "first" and "last"? > > 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 > > > > Thank you, that is perfect, I'll take it. But please capitalize the text of each @item (I forgot to do that in the last two). Thanks.