E.5. 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.
DTC_RESPONSEadbg_find_memory_in_frame (FRAME_DEF *frame, char *address, char **buffer, unsigned int *size)
Search the trace frame frame for memory saved from address.
If the memory is available, provide the address of the buffer holding
it; otherwise, provide the address of the next saved area.
If the memory at address was saved in frame, set
*buffer to point to the buffer in which that memory was
saved, set *size to the number of bytes from address
that are saved at *buffer, and return
OK_TARGET_RESPONSE. (Clearly, in this case, the function will
always set *size to a value greater than zero.)
If frame does not record any memory at address, set
*size to the distance from address to the start of
the saved region with the lowest address higher than address. If
there is no memory saved from any higher address, set *size
to zero. Return NOT_FOUND_TARGET_RESPONSE.
These two possibilities allow the caller to either retrieve the data, or
walk the address space to the next saved area.
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 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 f has saved sixteen bytes
from address 0x8000 in a buffer at 0x1000, and thirty-two
bytes from address 0xc000 in a buffer at 0x1010. Here are
some sample calls, and the effect each would have:
- adbg_find_memory_in_frame (f, (char*) 0x8000, &buffer, &size)
This would set buffer to 0x1000, set size to
sixteen, and return OK_TARGET_RESPONSE, since f saves
sixteen bytes from 0x8000 at 0x1000.
- adbg_find_memory_in_frame (f, (char *) 0x8004, &buffer, &size)
This would set buffer to 0x1004, set size to
twelve, and return OK_TARGET_RESPONSE, since f saves the
twelve bytes from 0x8004 starting four bytes into the buffer at
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.
- adbg_find_memory_in_frame (f, (char *) 0x8100, &buffer, &size)
This would set size to 0x3f00 and return
NOT_FOUND_TARGET_RESPONSE, since there is no memory saved in
f from the address 0x8100, and the next memory available
is at 0x8100 + 0x3f00, or 0xc000. This shows that request
addresses may fall outside of all saved memory ranges; the function
should indicate the next saved area, if any.
- adbg_find_memory_in_frame (f, (char *) 0x7000, &buffer, &size)
This would set size to 0x1000 and return
NOT_FOUND_TARGET_RESPONSE, since the next saved memory is at
0x7000 + 0x1000, or 0x8000.
- adbg_find_memory_in_frame (f, (char *) 0xf000, &buffer, &size)
This would set size to zero, and return
NOT_FOUND_TARGET_RESPONSE. This shows how the function tells the
caller that no further memory ranges have been saved.
As another example, here is a function which will print out the
addresses of all memory saved in the trace frame frame on the
Symmetrix INLINES console:
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;
}
} |
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
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.]]
