agentexpr.texi

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

@item @code{div_unsigned} (0x06): @var{a} @var{b} @result{} @var{a/b}
Pop two unsigned 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.

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

@item @code{rem_unsigned} (0x08): @var{a} @var{b} @result{} @var{a modulo b}
Pop two unsigned integers from the stack; divide the next-to-top value
by the top value, and push the remainder.  If the divisor is zero,
terminate with an error.

@item @code{lsh} (0x09): @var{a} @var{b} @result{} @var{a<<b}
Pop two integers from the stack; let @var{a} be the next-to-top value,
and @var{b} be the top value.  Shift @var{a} left by @var{b} bits, and
push the result.

@item @code{rsh_signed} (0x0a): @var{a} @var{b} @result{} @code{(signed)}@var{a>>b}
Pop two integers from the stack; let @var{a} be the next-to-top value,
and @var{b} be the top value.  Shift @var{a} right by @var{b} bits,
inserting copies of the top bit at the high end, and push the result.

@item @code{rsh_unsigned} (0x0b): @var{a} @var{b} @result{} @var{a>>b}
Pop two integers from the stack; let @var{a} be the next-to-top value,
and @var{b} be the top value.  Shift @var{a} right by @var{b} bits,
inserting zero bits at the high end, and push the result.

@item @code{log_not} (0x0e): @var{a} @result{} @var{!a}
Pop an integer from the stack; if it is zero, push the value one;
otherwise, push the value zero.

@item @code{bit_and} (0x0f): @var{a} @var{b} @result{} @var{a&b}
Pop two integers from the stack, and push their bitwise @code{and}.

@item @code{bit_or} (0x10): @var{a} @var{b} @result{} @var{a|b}
Pop two integers from the stack, and push their bitwise @code{or}.

@item @code{bit_xor} (0x11): @var{a} @var{b} @result{} @var{a^b}
Pop two integers from the stack, and push their bitwise
exclusive-@code{or}.

@item @code{bit_not} (0x12): @var{a} @result{} @var{~a}
Pop an integer from the stack, and push its bitwise complement.

@item @code{equal} (0x13): @var{a} @var{b} @result{} @var{a=b}
Pop two integers from the stack; if they are equal, push the value one;
otherwise, push the value zero.

@item @code{less_signed} (0x14): @var{a} @var{b} @result{} @var{a<b}
Pop two signed integers from the stack; if the next-to-top value is less
than the top value, push the value one; otherwise, push the value zero.

@item @code{less_unsigned} (0x15): @var{a} @var{b} @result{} @var{a<b}
Pop two unsigned integers from the stack; if the next-to-top value is less
than the top value, push the value one; otherwise, push the value zero.

@item @code{ext} (0x16) @var{n}: @var{a} @result{} @var{a}, sign-extended from @var{n} bits
Pop an unsigned value from the stack; treating it as an @var{n}-bit
twos-complement value, extend it to full length.  This means that all
bits to the left of bit @var{n-1} (where the least significant bit is bit
0) are set to the value of bit @var{n-1}.  Note that @var{n} may be
larger than or equal to the width of the stack elements of the bytecode
engine; in this case, the bytecode should have no effect.

The number of source bits to preserve, @var{n}, is encoded as a single
byte unsigned integer following the @code{ext} bytecode.

@item @code{zero_ext} (0x2a) @var{n}: @var{a} @result{} @var{a}, zero-extended from @var{n} bits
Pop an unsigned value from the stack; zero all but the bottom @var{n}
bits.  This means that all bits to the left of bit @var{n-1} (where the
least significant bit is bit 0) are set to the value of bit @var{n-1}.

The number of source bits to preserve, @var{n}, is encoded as a single
byte unsigned integer following the @code{zero_ext} bytecode.

@item @code{ref8} (0x17): @var{addr} @result{} @var{a}
@itemx @code{ref16} (0x18): @var{addr} @result{} @var{a}
@itemx @code{ref32} (0x19): @var{addr} @result{} @var{a}
@itemx @code{ref64} (0x1a): @var{addr} @result{} @var{a}
Pop an address @var{addr} from the stack.  For bytecode
@code{ref}@var{n}, fetch an @var{n}-bit value from @var{addr}, using the
natural target endianness.  Push the fetched value as an unsigned
integer.

Note that @var{addr} may not be aligned in any particular way; the
@code{ref@var{n}} bytecodes should operate correctly for any address.

If attempting to access memory at @var{addr} would cause a processor
exception of some sort, terminate with an error.

@item @code{ref_float} (0x1b): @var{addr} @result{} @var{d}
@itemx @code{ref_double} (0x1c): @var{addr} @result{} @var{d}
@itemx @code{ref_long_double} (0x1d): @var{addr} @result{} @var{d}
@itemx @code{l_to_d} (0x1e): @var{a} @result{} @var{d}
@itemx @code{d_to_l} (0x1f): @var{d} @result{} @var{a}
Not implemented yet.

@item @code{dup} (0x28): @var{a} => @var{a} @var{a}
Push another copy of the stack's top element.

@item @code{swap} (0x2b): @var{a} @var{b} => @var{b} @var{a}
Exchange the top two items on the stack.

@item @code{pop} (0x29): @var{a} =>
Discard the top value on the stack.

@item @code{if_goto} (0x20) @var{offset}: @var{a} @result{}
Pop an integer off the stack; if it is non-zero, branch to the given
offset in the bytecode string.  Otherwise, continue to the next
instruction in the bytecode stream.  In other words, if @var{a} is
non-zero, set the @code{pc} register to @code{start} + @var{offset}.
Thus, an offset of zero denotes the beginning of the expression.

The @var{offset} is stored as a sixteen-bit unsigned value, stored
immediately following the @code{if_goto} bytecode.  It is always stored
most significant byte first, regardless of the target's normal
endianness.  The offset is not guaranteed to fall at any particular
alignment within the bytecode stream; thus, on machines where fetching a
16-bit on an unaligned address raises an exception, you should fetch the
offset one byte at a time.

@item @code{goto} (0x21) @var{offset}: @result{}
Branch unconditionally to @var{offset}; in other words, set the
@code{pc} register to @code{start} + @var{offset}.

The offset is stored in the same way as for the @code{if_goto} bytecode.

@item @code{const8} (0x22) @var{n}: @result{} @var{n}
@itemx @code{const16} (0x23) @var{n}: @result{} @var{n}
@itemx @code{const32} (0x24) @var{n}: @result{} @var{n}
@itemx @code{const64} (0x25) @var{n}: @result{} @var{n}
Push the integer constant @var{n} on the stack, without sign extension.
To produce a small negative value, push a small twos-complement value,
and then sign-extend it using the @code{ext} bytecode.

The constant @var{n} is stored in the appropriate number of bytes
following the @code{const}@var{b} bytecode.  The constant @var{n} is
always stored most significant byte first, regardless of the target's
normal endianness.  The constant is not guaranteed to fall at any
particular alignment within the bytecode stream; thus, on machines where
fetching a 16-bit on an unaligned address raises an exception, you
should fetch @var{n} one byte at a time.

@item @code{reg} (0x26) @var{n}: @result{} @var{a}
Push the value of register number @var{n}, without sign extension.  The
registers are numbered following GDB's conventions.

The register number @var{n} is encoded as a 16-bit unsigned integer
immediately following the @code{reg} bytecode.  It is always stored most
significant byte first, regardless of the target's normal endianness.
The register number is not guaranteed to fall at any particular
alignment within the bytecode stream; thus, on machines where fetching a
16-bit on an unaligned address raises an exception, you should fetch the
register number one byte at a time.

@item @code{trace} (0x0c): @var{addr} @var{size} @result{}
Record the contents of the @var{size} bytes at @var{addr} in a trace
buffer, for later retrieval by GDB.

@item @code{trace_quick} (0x0d) @var{size}: @var{addr} @result{} @var{addr}
Record the contents of the @var{size} bytes at @var{addr} in a trace
buffer, for later retrieval by GDB.  @var{size} is a single byte
unsigned integer following the @code{trace} opcode.

This bytecode is equivalent to the sequence @code{dup const8 @var{size}
trace}, but we provide it anyway to save space in bytecode strings.

@item @code{trace16} (0x30) @var{size}: @var{addr} @result{} @var{addr}
Identical to trace_quick, except that @var{size} is a 16-bit big-endian
unsigned integer, not a single byte.  This should probably have been
named @code{trace_quick16}, for consistency.

@item @code{end} (0x27): @result{}
Stop executing bytecode; the result should be the top element of the
stack.  If the purpose of the expression was to compute an lvalue or a
range of memory, then the next-to-top of the stack is the lvalue's
address, and the top of the stack is the lvalue's size, in bytes.

@end table


@node Using Agent Expressions
@section Using Agent Expressions

Here is a sketch of a full non-stop debugging cycle, showing how agent
expressions fit into the process.

@itemize @bullet

@item
The user selects trace points in the program's code at which GDB should
collect data.

@item
The user specifies expressions to evaluate at each trace point.  These
expressions may denote objects in memory, in which case those objects'
contents are recorded as the program runs, or computed values, in which
case the values themselves are recorded.

@item
GDB transmits the tracepoints and their associated expressions to the
GDB agent, running on the debugging target.

@item
The agent arranges to be notified when a trace point is hit.  Note that,
on some systems, the target operating system is completely responsible
for collecting the data; see @ref{Tracing on Symmetrix}.

@item
When execution on the target reaches a trace point, the agent evaluates
the expressions associated with that trace point, and records the
resulting values and memory ranges.

@item
Later, when the user selects a given trace event and inspects the
objects and expression values recorded, GDB talks to the agent to
retrieve recorded data as necessary to meet the user's requests.  If the
user asks to see an object whose contents have not been recorded, GDB
reports an error.

@end itemize


@node Varying Target Capabilities
@section Varying Target Capabilities

Some targets don't support floating-point, and some would rather not
have to deal with @code{long long} operations.  Also, different targets
will have different stack sizes, and different bytecode buffer lengths.

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:

@itemize @bullet

@item
whether floating point is supported

@item
whether @code{long long} is supported

@item
maximum acceptable size of bytecode stack

@item
maximum acceptable length of bytecode expressions

@item
which registers are actually available for collection

@item
whether the target supports disabled tracepoints

@end itemize



@node Tracing on Symmetrix
@section Tracing on Symmetrix

This section documents the API used by the GDB agent to collect data on
Symmetrix systems.

Cygnus originally implemented these tracing features to help EMC
Corporation debug their Symmetrix high-availability disk drives.  The
Symmetrix application code already includes substantial tracing
facilities; the GDB agent for the Symmetrix system uses those facilities
for its own data collection, via the API described here.

@deftypefn Function DTC_RESPONSE adbg_find_memory_in_frame (FRAME_DEF *@var{frame}, char *@var{address}, char **@var{buffer}, unsigned int *@var{size})
Search the trace frame @var{frame} for memory saved from @var{address}.