agentexpr.texi

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

If the memory is available, provide the address of the buffer holding
it; otherwise, provide the address of the next saved area.

@itemize @bullet

@item
If the memory at @var{address} was saved in @var{frame}, set
@code{*@var{buffer}} to point to the buffer in which that memory was
saved, set @code{*@var{size}} to the number of bytes from @var{address}
that are saved at @code{*@var{buffer}}, and return
@code{OK_TARGET_RESPONSE}.  (Clearly, in this case, the function will
always set @code{*@var{size}} to a value greater than zero.)

@item
If @var{frame} does not record any memory at @var{address}, set
@code{*@var{size}} to the distance from @var{address} to the start of
the saved region with the lowest address higher than @var{address}.  If
there is no memory saved from any higher address, set @code{*@var{size}}
to zero.  Return @code{NOT_FOUND_TARGET_RESPONSE}.
@end itemize

These two possibilities allow the caller to either retrieve the data, or
walk the address space to the next saved area.
@end deftypefn

This function allows the GDB agent to map the regions of memory saved in
a particular frame, and retrieve their contents efficiently.

This function also provides a clean interface between the GDB agent and
the Symmetrix tracing structures, making it easier to adapt the GDB
agent to future versions of the Symmetrix system, and vice versa.  This
function searches all data saved in @var{frame}, whether the data is
there at the request of a bytecode expression, or because it falls in
one of the format's memory ranges, or because it was saved from the top
of the stack.  EMC can arbitrarily change and enhance the tracing
mechanism, but as long as this function works properly, all collected
memory is visible to GDB.

The function itself is straightforward to implement.  A single pass over
the trace frame's stack area, memory ranges, and expression blocks can
yield the address of the buffer (if the requested address was saved),
and also note the address of the next higher range of memory, to be
returned when the search fails.

As an example, suppose the trace frame @code{f} has saved sixteen bytes
from address @code{0x8000} in a buffer at @code{0x1000}, and thirty-two
bytes from address @code{0xc000} in a buffer at @code{0x1010}.  Here are
some sample calls, and the effect each would have:

@table @code

@item adbg_find_memory_in_frame (f, (char*) 0x8000, &buffer, &size)
This would set @code{buffer} to @code{0x1000}, set @code{size} to
sixteen, and return @code{OK_TARGET_RESPONSE}, since @code{f} saves
sixteen bytes from @code{0x8000} at @code{0x1000}.

@item adbg_find_memory_in_frame (f, (char *) 0x8004, &buffer, &size)
This would set @code{buffer} to @code{0x1004}, set @code{size} to
twelve, and return @code{OK_TARGET_RESPONSE}, since @file{f} saves the
twelve bytes from @code{0x8004} starting four bytes into the buffer at
@code{0x1000}.  This shows that request addresses may fall in the middle
of saved areas; the function should return the address and size of the
remainder of the buffer.

@item adbg_find_memory_in_frame (f, (char *) 0x8100, &buffer, &size)
This would set @code{size} to @code{0x3f00} and return
@code{NOT_FOUND_TARGET_RESPONSE}, since there is no memory saved in
@code{f} from the address @code{0x8100}, and the next memory available
is at @code{0x8100 + 0x3f00}, or @code{0xc000}.  This shows that request
addresses may fall outside of all saved memory ranges; the function
should indicate the next saved area, if any.

@item adbg_find_memory_in_frame (f, (char *) 0x7000, &buffer, &size)
This would set @code{size} to @code{0x1000} and return
@code{NOT_FOUND_TARGET_RESPONSE}, since the next saved memory is at
@code{0x7000 + 0x1000}, or @code{0x8000}.

@item adbg_find_memory_in_frame (f, (char *) 0xf000, &buffer, &size)
This would set @code{size} to zero, and return
@code{NOT_FOUND_TARGET_RESPONSE}.  This shows how the function tells the
caller that no further memory ranges have been saved.

@end table

As another example, here is a function which will print out the
addresses of all memory saved in the trace frame @code{frame} on the
Symmetrix INLINES console:
@example
void
print_frame_addresses (FRAME_DEF *frame)
@{
  char *addr;
  char *buffer;
  unsigned long size;

  addr = 0;
  for (;;)
    @{
      /* Either find out how much memory we have here, or discover
         where the next saved region is.  */
      if (adbg_find_memory_in_frame (frame, addr, &buffer, &size)
          == OK_TARGET_RESPONSE)
        printp ("saved %x to %x\n", addr, addr + size);
      if (size == 0)
        break;
      addr += size;
    @}
@}
@end example

Note that there is not necessarily any connection between the order in
which the data is saved in the trace frame, and the order in which
@code{adbg_find_memory_in_frame} will return those memory ranges.  The
code above will always print the saved memory regions in order of
increasing address, while the underlying frame structure might store the
data in a random order.

[[This section should cover the rest of the Symmetrix functions the stub
relies upon, too.]]

@node Rationale
@section Rationale

Some of the design decisions apparent above are arguable.

@table @b

@item What about stack overflow/underflow?
GDB should be able to query the target to discover its stack size.
Given that information, GDB can determine at translation time whether a
given expression will overflow the stack.  But this spec isn't about
what kinds of error-checking GDB ought to do.

@item Why are you doing everything in LONGEST?

Speed isn't important, but agent code size is; using LONGEST brings in a
bunch of support code to do things like division, etc.  So this is a
serious concern.

First, note that you don't need different bytecodes for different
operand sizes.  You can generate code without @emph{knowing} how big the
stack elements actually are on the target.  If the target only supports
32-bit ints, and you don't send any 64-bit bytecodes, everything just
works.  The observation here is that the MIPS and the Alpha have only
fixed-size registers, and you can still get C's semantics even though
most instructions only operate on full-sized words.  You just need to
make sure everything is properly sign-extended at the right times.  So
there is no need for 32- and 64-bit variants of the bytecodes.  Just
implement everything using the largest size you support.

GDB should certainly check to see what sizes the target supports, so the
user can get an error earlier, rather than later.  But this information
is not necessary for correctness.


@item Why don't you have @code{>} or @code{<=} operators?
I want to keep the interpreter small, and we don't need them.  We can
combine the @code{less_} opcodes with @code{log_not}, and swap the order
of the operands, yielding all four asymmetrical comparison operators.
For example, @code{(x <= y)} is @code{! (x > y)}, which is @code{! (y <
x)}.

@item Why do you have @code{log_not}?
@itemx Why do you have @code{ext}?
@itemx Why do you have @code{zero_ext}?
These are all easily synthesized from other instructions, but I expect
them to be used frequently, and they're simple, so I include them to
keep bytecode strings short.

@code{log_not} is equivalent to @code{const8 0 equal}; it's used in half
the relational operators.

@code{ext @var{n}} is equivalent to @code{const8 @var{s-n} lsh const8
@var{s-n} rsh_signed}, where @var{s} is the size of the stack elements;
it follows @code{ref@var{m}} and @var{reg} bytecodes when the value
should be signed.  See the next bulleted item.

@code{zero_ext @var{n}} is equivalent to @code{const@var{m} @var{mask}
log_and}; it's used whenever we push the value of a register, because we
can't assume the upper bits of the register aren't garbage.

@item Why not have sign-extending variants of the @code{ref} operators?
Because that would double the number of @code{ref} operators, and we
need the @code{ext} bytecode anyway for accessing bitfields.

@item Why not have constant-address variants of the @code{ref} operators?
Because that would double the number of @code{ref} operators again, and
@code{const32 @var{address} ref32} is only one byte longer.

@item Why do the @code{ref@var{n}} operators have to support unaligned fetches?
GDB will generate bytecode that fetches multi-byte values at unaligned
addresses whenever the executable's debugging information tells it to.
Furthermore, GDB does not know the value the pointer will have when GDB
generates the bytecode, so it cannot determine whether a particular
fetch will be aligned or not.

In particular, structure bitfields may be several bytes long, but follow
no alignment rules; members of packed structures are not necessarily
aligned either.

In general, there are many cases where unaligned references occur in
correct C code, either at the programmer's explicit request, or at the
compiler's discretion.  Thus, it is simpler to make the GDB agent
bytecodes work correctly in all circumstances than to make GDB guess in
each case whether the compiler did the usual thing.

@item Why are there no side-effecting operators?
Because our current client doesn't want them?  That's a cheap answer.  I
think the real answer is that I'm afraid of implementing function
calls.  We should re-visit this issue after the present contract is
delivered.

@item Why aren't the @code{goto} ops PC-relative?
The interpreter has the base address around anyway for PC bounds
checking, and it seemed simpler.

@item Why is there only one offset size for the @code{goto} ops?
Offsets are currently sixteen bits.  I'm not happy with this situation
either:

Suppose we have multiple branch ops with different offset sizes.  As I
generate code left-to-right, all my jumps are forward jumps (there are
no loops in expressions), so I never know the target when I emit the
jump opcode.  Thus, I have to either always assume the largest offset
size, or do jump relaxation on the code after I generate it, which seems
like a big waste of time.

I can imagine a reasonable expression being longer than 256 bytes.  I
can't imagine one being longer than 64k.  Thus, we need 16-bit offsets.
This kind of reasoning is so bogus, but relaxation is pathetic.

The other approach would be to generate code right-to-left.  Then I'd
always know my offset size.  That might be fun.

@item Where is the function call bytecode?

When we add side-effects, we should add this.

@item Why does the @code{reg} bytecode take a 16-bit register number?

Intel's IA-64 architecture has 128 general-purpose registers,
and 128 floating-point registers, and I'm sure it has some random
control registers.

@item Why do we need @code{trace} and @code{trace_quick}?
Because GDB needs to record all the memory contents and registers an
expression touches.  If the user wants to evaluate an expression
@code{x->y->z}, the agent must record the values of @code{x} and
@code{x->y} as well as the value of @code{x->y->z}.

@item Don't the @code{trace} bytecodes make the interpreter less general?
They do mean that the interpreter contains special-purpose code, but
that doesn't mean the interpreter can only be used for that purpose.  If
an expression doesn't use the @code{trace} bytecodes, they don't get in
its way.

@item Why doesn't @code{trace_quick} consume its arguments the way everything else does?
In general, you do want your operators to consume their arguments; it's
consistent, and generally reduces the amount of stack rearrangement
necessary.  However, @code{trace_quick} is a kludge to save space; it
only exists so we needn't write @code{dup const8 @var{SIZE} trace}
before every memory reference.  Therefore, it's okay for it not to
consume its arguments; it's meant for a specific context in which we
know exactly what it should do with the stack.  If we're going to have a
kludge, it should be an effective kludge.

@item Why does @code{trace16} exist?
That opcode was added by the customer that contracted Cygnus for the
data tracing work.  I personally think it is unnecessary; objects that
large will be quite rare, so it is okay to use @code{dup const16
@var{size} trace} in those cases.

Whatever we decide to do with @code{trace16}, we should at least leave
opcode 0x30 reserved, to remain compatible with the customer who added
it.

@end table