Re: [patch 5/8] Doc for agent

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Mon, 23 Jan 2012 21:58:35 +0800
> From: Yao Qi <yao@codesourcery.com>
> 
> In this patch, we create a new chapter for agent, and put "Agent
> Expression" under this chapter.  One section "Control Agent" is added to
> document command in patch 3/8, and the rest of them is from original
> "Agent Expression".

Thanks.

> +@node Agent
> +@chapter Debugging Agent

Please add here

  @cindex debugging agent

> +The traditional debugging model is conceptually low-speed, but works fine,
> +because most of bugs can be reproduced in low-speed execution.  However,
           ^^^^^^^^^^^^
"most bugs", without "of".

> +as multi-core or many-core processor is becoming mainstream, and
                              ^^^^^^^^^^^^
"processors are"

> +multi-threaded program becomes more and more popular, there should be more
                  ^^^^^^^^^^^^^^^
"programs become"

> +and more bugs that only manifest themselves at full speed, for example, thread
> +races.

I don't really agree that the issue here is "low speed" vs "full
speed".  Rather, the issue is that the timeline of the running program
is modified by the debugger, when it stops some or all of the threads,
single-steps some of them, etc.  Disrupting the original timeline can
completely modify the behavior and conceal bugs that depend on timing.

> +the bug.  In order to overcome the interference, we should reduce the number of
> +operations debugger performed.
              ^^^^^^^^^^^^^^^^^^
"preformed by the debugger".

Again, I think the issue is not the number of operations, but
interference with the program's timing.

>                             @dfn{Agent}, a shared library, is running within
> +the same process with inferior, and is able to perform some debugging operations
> +itself.  As a result, debugger is only involved when necessary, and performance
> +of debugging can be improved accordingly.

But this is a half-measure, isn't it?  The agent will still stop or
slow down the program's threads, and so still influences its timeline,
right?

> +@menu
> +* Agent Expressions::	The GDB Agent Expression Mechanism
> +* Control Agent::       Turn agent on and off
> +* Varying Target Capabilities:: How to discover what the target can do

Please don't use TAB characters in Texinfo sources.  (If you use
Emacs, it will take care of that for you; if not, please untabify the
Texinfo sources after editing.)  Using TABs in Texinfo can produce
misaligned text in the manual.

> -In some applications, it is not feasible for the debugger to interrupt
> -the program's execution long enough for the developer to learn anything
> -helpful about its behavior.  If the program's correctness depends on its
> -real-time behavior, delays introduced by a debugger might cause the
> -program to fail, even when the code itself is correct.  It is useful to
> -be able to observe the program's behavior without interrupting it.

See, this text describes the issue more correctly, IMO, but it looks
like you deleted it and not moved it to the new chapter.

> +When using agent with @value{GDBN}, expression in agent will be used in many cases,
              ^^^^^                    ^^^^^^^^^^
"the agent", and "expressions", in plural.

> +such as the expressions used in tracepoint for data collection, and expressions used
                                   ^^^^^^^^^^
"tracepoints", in plural.

> +in breakpoint condition evaluation.  The expressions may also denote registers and
> +objects in memory --- structures or arrays, for example --- whose values @value{GDBN}

No blanks around "---", please.

> +When GDB is debugging a target, the GDB @dfn{agent} code running
>  on the target computes the values of the expressions itself.  To avoid
>  having a full symbolic expression evaluator on the agent, GDB translates
>  expressions in the source language into a simpler bytecode language, and
>  then sends the bytecode to the agent; the agent then executes the
> -bytecode, and records the values for GDB to retrieve later.
> +bytecode, and records the values for GDB to retrieve later.  We call these bytecode
> +@dfn{Agent Expression}.

@value{GDBN} instead of "GDB".

> +@node Control Agent
> +@section Turn agent on and off

@cindex here.  And please capitalize the words in the section name.

> +As a helper of debugging, agent should be turned on and off by user, which
> +can be done with the following commands:

Suggest to reword:

  You can control whether the agent is used as an aid for debugging
  with the following commands:

> +@table @code
> +@item set agent on
> +Causes agent may execute some debugging operations, which is determined by
> +actual debugging request from users and by the capability of agent.  For
> +example, if user request to evaluate breakpoint conditions in agent, and
> +agent has such capability as well, then breakpoint conditions will be
> +evaluated in agent.

  Causes the agent to perform some operations on behalf of the
  debugger.  Just which operations requested by the user will be done
  by the agent depends on the agent's capabilities.

> +@item set agent off
> +Causes agent not execute any debugging operations.  All of them should be
> +performed in @value{GDBN}.

  Disables execution of debugging operations by the agent.  All of the
  operations will be performed by @value{GDBN}.

> +Thus, GDB needs a way to ask the target about itself.  We haven't worked
> +out the details yet, but in general, GDB should be able to send the
> +target a packet asking it to describe itself.  The reply should be a
> +packet whose length is explicit, so we can add new information to the
> +packet in future revisions of the agent, without confusing old versions
> +of GDB, and it should contain a version number.  It should contain at
> +least the following information:

@value{GDBN}, please.

OK with these changes.

Thanks.