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.

Function: DTC_RESPONSE adbg_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.]]