From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from eggs.gnu.org (eggs.gnu.org [IPv6:2001:470:142:3::10]) by sourceware.org (Postfix) with ESMTPS id 64F0E3834E41 for ; Thu, 26 May 2022 06:50:22 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 64F0E3834E41 Received: from fencepost.gnu.org ([2001:470:142:3::e]:56836) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nu7K9-0000oW-9c; Thu, 26 May 2022 02:50:21 -0400 Received: from [87.69.77.57] (port=1747 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 1nu7Jw-00078U-Ch; Thu, 26 May 2022 02:50:19 -0400 Date: Thu, 26 May 2022 09:50:01 +0300 Message-Id: <83bkvkpz3a.fsf@gnu.org> From: Eli Zaretskii To: Pedro Alves Cc: gdb-patches@sourceware.org In-Reply-To: <1a48f5fd-e545-00a7-e657-55dd4ec41c74@palves.net> (message from Pedro Alves on Wed, 25 May 2022 22:02:04 +0100) Subject: Re: [PATCH v2] gdb/manual: Introduce location specs References: <20220525193126.1613411-1-pedro@palves.net> <83mtf5perq.fsf@gnu.org> <1a48f5fd-e545-00a7-e657-55dd4ec41c74@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: Thu, 26 May 2022 06:50:24 -0000 > Date: Wed, 25 May 2022 22:02:04 +0100 > Cc: gdb-patches@sourceware.org > From: Pedro Alves > > On 2022-05-25 20:56, Eli Zaretskii wrote: > > > Sorry, but I don't think this is a good idea. It is IMO okay to > > introduce "location specification" into our terminology; it is even > > okay to use "location spec" as its shorthand. But "locspec" is too > > much: it's not a word, so it doesn't explain itself enough, and thus > > cannot be used very far from where it is defined, because the reader > > will likely not understand what it means. "Locspec" is fine to use in > > the likes of @var{locspec}, where we describe commands that take a > > location specification as an argument, > > Here's a version of the patch that does that. I went through all references > to "locspec" that weren't a case of "@var{locspec} describing a comment argument", > and replaced them with "location spec". I take it from your comments above > that you would be OK with this. Thanks. However, this new version does only part of the job: it still uses "location" in an additional meaning: to mean "the actual place in the program where the breakpoint will break". We must avoid the confusion from using "location" in two quite different senses. I will mostly use the term "address" in the rest of my comments below, but if that term is not optimal for some reason, we could later replace it with something else. > Thus, is this version OK to apply? Unfortunately, no. Please see the comments below. > +@item break @var{locspec} > +Set a breakpoint at all the locations the given @var{locspec} matches. This should say something like Set a breakpoint at all the program addresses that match the @dfn{location specification} @var{locspec}. We could also use "all the places in the program code" instead of "all the program addresses". Or maybe you or someone else will be able to propose other alternatives. But we should not use "location" to mean the actual resolved address where the breakpoint will break. > +@var{locspec} can specify a function name, a line number, an address > +of an instruction, and more. @xref{Location Specifications}, for the > +various forms of @var{locspec}. The breakpoint will stop your program > +just before it executes any of the code at any of the breakpoint's > +locations. ^^^^^^^^^ "addresses", not "locations". > +It is possible that a breakpoint corresponds to several locations in > +your program. @xref{Location Specifications}, for examples. I would rephrase: It is possible that a breakpoint's location spec corresponds to several places in your program. > @value{GDBN} provides some additional commands for controlling what > -happens when the @samp{break} command cannot resolve breakpoint > -address specification to an address: > +happens when the @samp{break} command cannot find any location that > +matches the location spec (@pxref{Location Specifications}): This should say "...cannot resolve the breakpoint's location spec to an address". IOW, the only problem in the original text was with using "address specification", where we now want to use "location specification" instead. > @kindex set breakpoint pending > @kindex show breakpoint pending > @table @code > @item set breakpoint pending auto > -This is the default behavior. When @value{GDBN} cannot find the breakpoint > -location, it queries you whether a pending breakpoint should be created. > +This is the default behavior. When @value{GDBN} cannot find any > +location that matches the location spec, it queries you whether a > +pending breakpoint should be created. "When @value{GDBN} cannot resolve the breakpoint's location spec to an address, it queries you whether..." > @item set breakpoint pending on > -This indicates that an unrecognized breakpoint location should automatically > -result in a pending breakpoint being created. > +This indicates that when @value{GDBN} cannot find any location that > +matches the location spec, it should create a pending breakpoint > +without asking for confirmation. "This indicates that when @value{GDBN} cannot resolve a location spec, it should create a @dfn{pending breakpoint} without asking for confirmation." > @item set breakpoint pending off > -This indicates that pending breakpoints are not to be created. Any > -unrecognized breakpoint location results in an error. This setting does > +This indicates that pending breakpoints are not to be created. If > +@value{GDBN} cannot find any location that matches the location spec, > +it aborts the breakpoint creation with an error. This setting does > not affect any pending breakpoints previously created. Similar rephrasing here. > The settings above only affect the @code{break} command and its > -variants. Once breakpoint is set, it will be automatically updated > -as shared libraries are loaded and unloaded. > +variants. Once a breakpoint is created, it will be automatically > +updated as shared libraries are loaded and unloaded. I don't necessarily object, but can you tell why "breakpoint is set" was not good enough? After all the description of the "break" command says "Set a breakpoint...", so the original text here was being consistent with that. > -@item clear @var{location} > -Delete any breakpoints set at the specified @var{location}. > -@xref{Specify Location}, for the various forms of @var{location}; the > -most useful ones are listed below: > +@item clear @var{locspec} > +Delete any breakpoints set at the locations that match @var{locspec}. "Delete any breakpoints set at addresses that match the location spec @var{locspec}." > +Whenever execution reaches a location that matches @var{locspec}, > +print the values of one or more @var{expressions} under the control of > +the string @var{template}. To print several values, separate them > +with commas. "Whenever execution reaches an address that matches @var{locspec}, ..." > +@item until @var{locspec} > +@itemx u @var{locspec} > +Continue running your program until either a location that matches @var{locspec} is > +reached, or the current stack frame returns. @var{locspec} is any of > +the forms described in @ref{Location Specifications}. "Continue running your program until it either reaches an address that matches the location specification @var{locspec}, or the current stack frame returns." > +@kindex advance @var{locspec} > +@item advance @var{locspec} > +Continue running the program up to the location that matches > +@var{locspec}. ^^^^^^^^^^^^ This should be "an address". > Functions may be skipped by providing either a function name, linespec ^^^^^^^^^^^^^^^^^^^^^^^ Does "skip" support only some of the location specification formats? If it supports all of them, we should just say "location specification" there instead of using these two terms. > +In general, the @code{list} command expects you to supply zero, one or > +two location specs. The location specs specify source lines; there > +are several ways of writing them (@pxref{Location Specifications}), > +but the effect is always to specify some source line. The last sentence should say "These location specs are interpreted to specify source code lines; there are several ways of writing them (@pxref{Location Specifications}), but the effect is always to specify some source lines to display." > +@item list @var{locspec} > +Print lines centered around the line or lines for the locations that > +match @var{locspec}. "Print lines centered around the line or lines for the addresses that match @var{linespec}." > @item list @var{first},@var{last} > Print lines from @var{first} to @var{last}. Both arguments are > -locations. When a @code{list} command has two locations, and the > -source file of the second location is omitted, this refers to > -the same source file as the first location. > +location specs. When a @code{list} command has two location specs, and the source > +file of the second location spec is omitted, this refers to the same source > +file as the first location spec. If either @var{first} or @var{last} match > +more than one location in the program, then the list command will > +print the list of ambiguous locations and does not print any source > +lines. The last sentence should say "If either @var{first} or @var{last} match more than one source line in the program, the @code{list} command will show the list of ambiguous source lines, and will not print any source lines." > +Likewise, if @var{last} matches more than one location in the program, > +then the list command will print the list of ambiguous locations and > +does not print any source lines. Likewise here. > +A location spec serves as a blueprint, and it may match more than one > +actual location in your program. Examples of this situation are: ^^^^^^^^ "address". > +@item edit @var{locspec} > +Edit the source file specified by @code{locspec}. Editing starts at > +the specified location, e.g., at the specified source line of the > +specified file. @xref{Location Specifications}, for all the possible > +forms of the @var{locspec} argument. > + > +If @code{locspec} matches more than one location in your program, then ^^^^^^^^ "source line" > +the command prints the list of locations and does not proceed with the ^^^^^^^^^ "source lines" > We can also inquire (using @code{*@var{addr}} as the form for > -@var{location}) what source line covers a particular address: > +@var{locspec}) what source line covers a particular address: "You can also inquire (using @code{*@var{addr}} as the form for @var{locspec}) what source line covers a particular address @var{addr}:" > +@item info macros @var{locspec} > +Show all macro definitions that are in effect at the first location in > +your program that matches @var{locspec}, and describe the source > +location or compiler command-line where those definitions were > +established. "Show all macro definitions that are in effect at the first address in your program that matches @var{locspec}, and describe the place in the source code or compiler command-line where those definitions were established." > The @code{strace} command sets a static tracepoint. For targets that > support it, setting a static tracepoint probes a static > -instrumentation point, or marker, found at @var{location}. It may not > -be possible to set a static tracepoint at the desired location, in > -which case the command will exit with an explanatory message. > +instrumentation point, or marker, found at the locations that match > +@var{locspec}. ^^^^^^^^^ "addresses" > It may not be possible to set a static tracepoint at > +the desired location, in which case the command will exit with an "It may not be possible to set a static tracepoint at any address that matches @var{locspec}, in which case..." > @value{GDBN} handles arguments to @code{strace} exactly as for > @code{trace}, with the addition that the user can also specify > -@code{-m @var{marker}} as @var{location}. This probes the marker > +@code{-m @var{marker}} as location. This probes the marker "...the user can also specify @code{-m @var{marker}} instead of a location spec." > -@item info scope @var{location} > +@item info scope @var{locspec} > List all the variables local to a particular scope. This command > -accepts a @var{location} argument---a function name, a source line, or > -an address preceded by a @samp{*}, and prints all the variables local > -to the scope defined by that location. (@xref{Specify Location}, for > -details about supported forms of @var{location}.) For example: > +accepts a location specification argument---a function name, a source > +line, or an address preceded by a @samp{*}, and prints all the > +variables local to the scope defined by the first location in your ^^^^^^^^ "address" or "place". > +@item jump @var{locspec} > +@itemx j @var{locspec} > +Resume execution at the location that matches @var{locspec}. ^^^^^^^^ "address" > +@xref{Location Specifications}, for a description of the different > +forms of @var{locspec}. If @var{locspec} matches more than one > +location, the command aborts before jumping to any location. ^^^^^^^^ "address". And "to any location" at the end can be simply removed. > The @code{jump} command does not change the current stack frame, or > the stack pointer, or the contents of any memory location or any > -register other than the program counter. If @var{location} is in > -a different function from the one currently executing, the results may > -be bizarre if the two functions expect different patterns of arguments or > -of local variables. For this reason, the @code{jump} command requests > -confirmation if the specified line is not in the function currently > -executing. However, even bizarre results are predictable if you are > -well acquainted with the machine-language code of your program. > +register other than the program counter. If @var{locspec} matches a > +location in a different function from the one currently executing, the ^^^^^^^^ "address" > +@item break-range @var{start-locspec}, @var{end-locspec} > Set a breakpoint for an address range given by > -@var{start-location} and @var{end-location}, which can specify a function name, > +@var{start-locspec} and @var{end-locspec}, which can specify a function name, > a line number, an offset of lines from the current line or from the start > -location, or an address of an instruction (see @ref{Specify Location}, > -for a list of all the possible ways to specify a @var{location}.) > +location, or an address of an instruction (see @ref{Location Specifications}, > +for a list of all the possible ways to specify a location spec). > +If either @var{start-locspec} or @var{end-locspec} match multiple > +locations in the program, then the command aborts with an error ^^^^^^^^^ "addresses" > @smallexample > - -exec-until [ @var{location} ] > + -exec-until [ @var{locspec} ] > @end smallexample > > -Executes the inferior until the @var{location} specified in the > -argument is reached. If there is no argument, the inferior executes > -until a source line greater than the current one is reached. The > -reason for stopping in this case will be @samp{location-reached}. > +Executes the inferior until a location that matches @var{locspec} is > +reached. "Executes the inferior until it reaches an address that matches @var{locspec}." > @item line > -Line specification is required as parameter. @xref{Specify Location}. > +Line specification is required as parameter. @xref{Location Specifications}. ^^^^^^^^^^^^^^^^^^ "Line specification" or "location specification"? > -If @code{-at} is given, generate remote agent bytecode for @var{location}. > +If @code{-at} is given, generate remote agent bytecode for all > +locations that match @var{linespec} (@pxref{Linespec Locations}). Same question here. Thanks.