agentexpr.texi

这个是LINUX下的GDB调度工具的源码

@c \input texinfo
@c %**start of header
@c @setfilename agentexpr.info
@c @settitle GDB Agent Expressions
@c @setchapternewpage off
@c %**end of header

@c Revision: $Id: agentexpr.texi,v 1.2 1998/12/09 21:23:46 jimb Exp $

@node Agent Expressions
@appendix The GDB Agent Expression Mechanism

In some applications, it is not feasable 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.

Using GDB's @code{trace} and @code{collect} commands, the user can
specify locations in the program, and arbitrary expressions to evaluate
when those locations are reached.  Later, using the @code{tfind}
command, she can examine the values those expressions had when the
program hit the trace points.  The expressions may also denote objects
in memory --- structures or arrays, for example --- whose values GDB
should record; while visiting a particular tracepoint, the user may
inspect those objects as if they were in memory at that moment.
However, because GDB records these values without interacting with the
user, it can do so quickly and unobtrusively, hopefully not disturbing
the program's behavior.

When GDB is debugging a remote 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.

The bytecode language is simple; there are forty-odd opcodes, the bulk
of which are the usual vocabulary of C operands (addition, subtraction,
shifts, and so on) and various sizes of literals and memory reference
operations.  The bytecode interpreter operates strictly on machine-level
values --- various sizes of integers and floating point numbers --- and
requires no information about types or symbols; thus, the interpreter's
internal data structures are simple, and each bytecode requires only a
few native machine instructions to implement it.  The interpreter is
small, and strict limits on the memory and time required to evaluate an
expression are easy to determine, making it suitable for use by the
debugging agent in real-time applications.

@menu
* General Bytecode Design::     Overview of the interpreter.
* Bytecode Descriptions::       What each one does.
* Using Agent Expressions::     How agent expressions fit into the big picture.
* Varying Target Capabilities:: How to discover what the target can do.
* Tracing on Symmetrix::        Special info for implementation on EMC's
                                boxes.
* Rationale::                   Why we did it this way.
@end menu


@c @node Rationale
@c @section Rationale


@node General Bytecode Design
@section General Bytecode Design

The agent represents bytecode expressions as an array of bytes.  Each
instruction is one byte long (thus the term @dfn{bytecode}).  Some
instructions are followed by operand bytes; for example, the @code{goto}
instruction is followed by a destination for the jump.

The bytecode interpreter is a stack-based machine; most instructions pop
their operands off the stack, perform some operation, and push the
result back on the stack for the next instruction to consume.  Each
element of the stack may contain either a integer or a floating point
value; these values are as many bits wide as the largest integer that
can be directly manipulated in the source language.  Stack elements
carry no record of their type; bytecode could push a value as an
integer, then pop it as a floating point value.  However, GDB will not
generate code which does this.  In C, one might define the type of a
stack element as follows:
@example
union agent_val @{
  LONGEST l;
  DOUBLEST d;
@};
@end example
@noindent
where @code{LONGEST} and @code{DOUBLEST} are @code{typedef} names for
the largest integer and floating point types on the machine.

By the time the bytecode interpreter reaches the end of the expression,
the value of the expression should be the only value left on the stack.
For tracing applications, @code{trace} bytecodes in the expression will
have recorded the necessary data, and the value on the stack may be
discarded.  For other applications, like conditional breakpoints, the
value may be useful.

Separate from the stack, the interpreter has two registers:
@table @code
@item pc
The address of the next bytecode to execute.

@item start
The address of the start of the bytecode expression, necessary for
interpreting the @code{goto} and @code{if_goto} instructions.

@end table
@noindent
Neither of these registers is directly visible to the bytecode language
itself, but they are useful for defining the meanings of the bytecode
operations.

There are no instructions to perform side effects on the running
program, or call the program's functions; we assume that these
expressions are only used for unobtrusive debugging, not for patching
the running code.  

Most bytecode instructions do not distinguish between the various sizes
of values, and operate on full-width values; the upper bits of the
values are simply ignored, since they do not usually make a difference
to the value computed.  The exceptions to this rule are:
@table @asis

@item memory reference instructions (@code{ref}@var{n})
There are distinct instructions to fetch different word sizes from
memory.  Once on the stack, however, the values are treated as full-size
integers.  They may need to be sign-extended; the @code{ext} instruction
exists for this purpose.

@item the sign-extension instruction (@code{ext} @var{n})
These clearly need to know which portion of their operand is to be
extended to occupy the full length of the word.

@end table

If the interpreter is unable to evaluate an expression completely for
some reason (a memory location is inaccessible, or a divisor is zero,
for example), we say that interpretation ``terminates with an error''.
This means that the problem is reported back to the interpreter's caller
in some helpful way.  In general, code using agent expressions should
assume that they may attempt to divide by zero, fetch arbitrary memory
locations, and misbehave in other ways.

Even complicated C expressions compile to a few bytecode instructions;
for example, the expression @code{x + y * z} would typically produce
code like the following, assuming that @code{x} and @code{y} live in
registers, and @code{z} is a global variable holding a 32-bit
@code{int}:
@example
reg 1
reg 2
const32 @i{address of z}
ref32
ext 32
mul
add
end
@end example

In detail, these mean:
@table @code

@item reg 1
Push the value of register 1 (presumably holding @code{x}) onto the
stack.

@item reg 2
Push the value of register 2 (holding @code{y}).

@item const32 @i{address of z}
Push the address of @code{z} onto the stack.

@item ref32
Fetch a 32-bit word from the address at the top of the stack; replace
the address on the stack with the value.  Thus, we replace the address
of @code{z} with @code{z}'s value.

@item ext 32
Sign-extend the value on the top of the stack from 32 bits to full
length.  This is necessary because @code{z} is a signed integer.

@item mul
Pop the top two numbers on the stack, multiply them, and push their
product.  Now the top of the stack contains the value of the expression
@code{y * z}.

@item add
Pop the top two numbers, add them, and push the sum.  Now the top of the
stack contains the value of @code{x + y * z}.

@item end
Stop executing; the value left on the stack top is the value to be
recorded.

@end table


@node Bytecode Descriptions
@section Bytecode Descriptions

Each bytecode description has the following form:

@table @asis

@item @code{add} (0x02): @var{a} @var{b} @result{} @var{a+b}

Pop the top two stack items, @var{a} and @var{b}, as integers; push
their sum, as an integer.

@end table

In this example, @code{add} is the name of the bytecode, and
@code{(0x02)} is the one-byte value used to encode the bytecode, in
hexidecimal.  The phrase ``@var{a} @var{b} @result{} @var{a+b}'' shows
the stack before and after the bytecode executes.  Beforehand, the stack
must contain at least two values, @var{a} and @var{b}; since the top of
the stack is to the right, @var{b} is on the top of the stack, and
@var{a} is underneath it.  After execution, the bytecode will have
popped @var{a} and @var{b} from the stack, and replaced them with a
single value, @var{a+b}.  There may be other values on the stack below
those shown, but the bytecode affects only those shown.

Here is another example:

@table @asis

@item @code{const8} (0x22) @var{n}: @result{} @var{n}
Push the 8-bit integer constant @var{n} on the stack, without sign
extension.

@end table

In this example, the bytecode @code{const8} takes an operand @var{n}
directly from the bytecode stream; the operand follows the @code{const8}
bytecode itself.  We write any such operands immediately after the name
of the bytecode, before the colon, and describe the exact encoding of
the operand in the bytecode stream in the body of the bytecode
description.

For the @code{const8} bytecode, there are no stack items given before
the @result{}; this simply means that the bytecode consumes no values
from the stack.  If a bytecode consumes no values, or produces no
values, the list on either side of the @result{} may be empty.

If a value is written as @var{a}, @var{b}, or @var{n}, then the bytecode
treats it as an integer.  If a value is written is @var{addr}, then the
bytecode treats it as an address.

We do not fully describe the floating point operations here; although
this design can be extended in a clean way to handle floating point
values, they are not of immediate interest to the customer, so we avoid
describing them, to save time.


@table @asis

@item @code{float} (0x01): @result{}

Prefix for floating-point bytecodes.  Not implemented yet.

@item @code{add} (0x02): @var{a} @var{b} @result{} @var{a+b}
Pop two integers from the stack, and push their sum, as an integer.

@item @code{sub} (0x03): @var{a} @var{b} @result{} @var{a-b}
Pop two integers from the stack, subtract the top value from the
next-to-top value, and push the difference.

@item @code{mul} (0x04): @var{a} @var{b} @result{} @var{a*b}
Pop two integers from the stack, multiply them, and push the product on
the stack.  Note that, when one multiplies two @var{n}-bit numbers
yielding another @var{n}-bit number, it is irrelevant whether the
numbers are signed or not; the results are the same.

@item @code{div_signed} (0x05): @var{a} @var{b} @result{} @var{a/b}
Pop two signed integers from the stack; divide the next-to-top value by
the top value, and push the quotient.  If the divisor is zero, terminate
with an error.