FreeChainXenon/binutils-gdb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

* agentexpr.texi (Tracing On Symmetrix): Delete section.

Browse source 
(Using Agent Expressions): Delete cross reference.
This commit is contained in:
Pedro Alves 2009-11-11 15:08:50 +00:00
parent c1e2689731
commit a5832c8fbd
2 changed files with 6 additions and 141 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
gdb/doc/ChangeLog
View file

@ -1,3 +1,8 @@
2009-11-11 Pedro Alves <pedro@codesourcery.com>
* agentexpr.texi (Tracing On Symmetrix): Delete section.
(Using Agent Expressions): Delete cross reference.
2009-11-07 Joel Brobecker <brobecker@adacore.com>
* gdbint.texinfo, stabs.texinfo: Move the @setchapternewpage

142
gdb/doc/agentexpr.texi
View file

@ -58,8 +58,6 @@ debugging agent in real-time applications.
* 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
@ -503,9 +501,7 @@ 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}.
The agent arranges to be notified when a trace point is hit.
@item
When execution on the target reaches a trace point, the agent evaluates
@ -559,142 +555,6 @@ 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}.
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