@c This file is part of the GDB manual.
@c
-@c Copyright (C) 2003, 2004, 2005, 2006
-@c Free Software Foundation, Inc.
+@c Copyright (C) 2003-2018 Free Software Foundation, Inc.
@c
@c See the file gdb.texinfo for copying conditions.
-@c Revision: $Id$
-
@node Agent Expressions
@appendix The GDB Agent Expression Mechanism
* 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
@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}.
+bits.
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{pop} (0x29): @var{a} =>
Discard the top value on the stack.
+@item @code{pick} (0x32) @var{n}: @var{a} @dots{} @var{b} => @var{a} @dots{} @var{b} @var{a}
+Duplicate an item from the stack and push it on the top of the stack.
+@var{n}, a single byte, indicates the stack item to copy. If @var{n}
+is zero, this is the same as @code{dup}; if @var{n} is one, it copies
+the item under the top item, etc. If @var{n} exceeds the number of
+items on the stack, terminate with an error.
+
+@item @code{rot} (0x33): @var{a} @var{b} @var{c} => @var{c} @var{a} @var{b}
+Rotate the top three items on the stack. The top item (c) becomes the third
+item, the next-to-top item (b) becomes the top item and the third item (a) from
+the top becomes the next-to-top item.
+
@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
16-bit on an unaligned address raises an exception, you should fetch the
register number one byte at a time.
+@item @code{getv} (0x2c) @var{n}: @result{} @var{v}
+Push the value of trace state variable number @var{n}, without sign
+extension.
+
+The variable number @var{n} is encoded as a 16-bit unsigned integer
+immediately following the @code{getv} bytecode. It is always stored most
+significant byte first, regardless of the target's normal endianness.
+The variable 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{setv} (0x2d) @var{n}: @var{v} @result{} @var{v}
+Set trace state variable number @var{n} to the value found on the top
+of the stack. The stack is unchanged, so that the value is readily
+available if the assignment is part of a larger expression. The
+handling of @var{n} is as described for @code{getv}.
+
@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.
unsigned integer, not a single byte. This should probably have been
named @code{trace_quick16}, for consistency.
+@item @code{tracev} (0x2e) @var{n}: @result{} @var{a}
+Record the value of trace state variable number @var{n} in the trace
+buffer. The handling of @var{n} is as described for @code{getv}.
+
+@item @code{tracenz} (0x2f) @var{addr} @var{size} @result{}
+Record the bytes at @var{addr} in a trace buffer, for later retrieval
+by GDB. Stop at either the first zero byte, or when @var{size} bytes
+have been recorded, whichever occurs first.
+
+@item @code{printf} (0x34) @var{numargs} @var{string} @result{}
+Do a formatted print, in the style of the C function @code{printf}).
+The value of @var{numargs} is the number of arguments to expect on the
+stack, while @var{string} is the format string, prefixed with a
+two-byte length. The last byte of the string must be zero, and is
+included in the length. The format string includes escaped sequences
+just as it appears in C source, so for instance the format string
+@code{"\t%d\n"} is six characters long, and the output will consist of
+a tab character, a decimal number, and a newline. At the top of the
+stack, above the values to be printed, this bytecode will pop a
+``function'' and ``channel''. If the function is nonzero, then the
+target may treat it as a function and call it, passing the channel as
+a first argument, as with the C function @code{fprintf}. If the
+function is zero, then the target may simply call a standard formatted
+print function of its choice. In all, this bytecode pops 2 +
+@var{numargs} stack elements, and pushes nothing.
+
@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
@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.
+Agent expressions can be used in several different ways by @value{GDBN},
+and the debugger can generate different bytecode sequences as appropriate.
+
+One possibility is to do expression evaluation on the target rather
+than the host, such as for the conditional of a conditional
+tracepoint. In such a case, @value{GDBN} compiles the source
+expression into a bytecode sequence that simply gets values from
+registers or memory, does arithmetic, and returns a result.
+
+Another way to use agent expressions is for tracepoint data
+collection. @value{GDBN} generates a different bytecode sequence for
+collection; in addition to bytecodes that do the calculation,
+@value{GDBN} adds @code{trace} bytecodes to save the pieces of
+memory that were used.
@itemize @bullet
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
@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
projects / deliverable / binutils-gdb.git / blobdiff