Lines Matching refs:the
13 In some applications, it is not feasable for the debugger to interrupt
14 the program's execution long enough for the developer to learn anything
15 helpful about its behavior. If the program's correctness depends on its
16 real-time behavior, delays introduced by a debugger might cause the
17 program to fail, even when the code itself is correct. It is useful to
18 be able to observe the program's behavior without interrupting it.
20 Using GDB's @code{trace} and @code{collect} commands, the user can
21 specify locations in the program, and arbitrary expressions to evaluate
22 when those locations are reached. Later, using the @code{tfind}
23 command, she can examine the values those expressions had when the
24 program hit the trace points. The expressions may also denote objects
26 should record; while visiting a particular tracepoint, the user may
28 However, because GDB records these values without interacting with the
30 the program's behavior.
32 When GDB is debugging a remote target, the GDB @dfn{agent} code running
33 on the target computes the values of the expressions itself. To avoid
34 having a full symbolic expression evaluator on the agent, GDB translates
35 expressions in the source language into a simpler bytecode language, and
36 then sends the bytecode to the agent; the agent then executes the
37 bytecode, and records the values for GDB to retrieve later.
39 The bytecode language is simple; there are forty-odd opcodes, the bulk
40 of which are the usual vocabulary of C operands (addition, subtraction,
44 requires no information about types or symbols; thus, the interpreter's
47 small, and strict limits on the memory and time required to evaluate an
48 expression are easy to determine, making it suitable for use by the
52 * General Bytecode Design:: Overview of the interpreter.
54 * Using Agent Expressions:: How agent expressions fit into the big picture.
55 * Varying Target Capabilities:: How to discover what the target can do.
70 instruction is one byte long (thus the term @dfn{bytecode}). Some
71 instructions are followed by operand bytes; for example, the @code{goto}
72 instruction is followed by a destination for the jump.
75 their operands off the stack, perform some operation, and push the
76 result back on the stack for the next instruction to consume. Each
77 element of the stack may contain either a integer or a floating point
78 value; these values are as many bits wide as the largest integer that
79 can be directly manipulated in the source language. Stack elements
82 generate code which does this. In C, one might define the type of a
92 the largest integer and floating point types on the machine.
94 By the time the bytecode interpreter reaches the end of the expression,
95 the value of the expression should be the only value left on the stack.
96 For tracing applications, @code{trace} bytecodes in the expression will
97 have recorded the necessary data, and the value on the stack may be
98 discarded. For other applications, like conditional breakpoints, the
101 Separate from the stack, the interpreter has two registers:
104 The address of the next bytecode to execute.
107 The address of the start of the bytecode expression, necessary for
108 interpreting the @code{goto} and @code{if_goto} instructions.
112 Neither of these registers is directly visible to the bytecode language
113 itself, but they are useful for defining the meanings of the bytecode
116 There are no instructions to perform side effects on the running
117 program, or call the program's functions; we assume that these
119 the running code.
121 Most bytecode instructions do not distinguish between the various sizes
122 of values, and operate on full-width values; the upper bits of the
124 to the value computed. The exceptions to this rule are:
129 memory. Once on the stack, however, the values are treated as full-size
130 integers. They may need to be sign-extended; the @code{ext} instruction
133 @item the sign-extension instruction (@code{ext} @var{n})
135 extended to occupy the full length of the word.
139 If the interpreter is unable to evaluate an expression completely for
142 This means that the problem is reported back to the interpreter's caller
148 for example, the expression @code{x + y * z} would typically produce
149 code like the following, assuming that @code{x} and @code{y} live in
167 Push the value of register 1 (presumably holding @code{x}) onto the
171 Push the value of register 2 (holding @code{y}).
174 Push the address of @code{z} onto the stack.
177 Fetch a 32-bit word from the address at the top of the stack; replace
178 the address on the stack with the value. Thus, we replace the address
182 Sign-extend the value on the top of the stack from 32 bits to full
186 Pop the top two numbers on the stack, multiply them, and push their
187 product. Now the top of the stack contains the value of the expression
191 Pop the top two numbers, add them, and push the sum. Now the top of the
192 stack contains the value of @code{x + y * z}.
195 Stop executing; the value left on the stack top is the value to be
204 Each bytecode description has the following form:
210 Pop the top two stack items, @var{a} and @var{b}, as integers; push
215 In this example, @code{add} is the name of the bytecode, and
216 @code{(0x02)} is the one-byte value used to encode the bytecode, in
218 the stack before and after the bytecode executes. Beforehand, the stack
219 must contain at least two values, @var{a} and @var{b}; since the top of
220 the stack is to the right, @var{b} is on the top of the stack, and
221 @var{a} is underneath it. After execution, the bytecode will have
222 popped @var{a} and @var{b} from the stack, and replaced them with a
223 single value, @var{a+b}. There may be other values on the stack below
224 those shown, but the bytecode affects only those shown.
231 Push the 8-bit integer constant @var{n} on the stack, without sign
236 In this example, the bytecode @code{const8} takes an operand @var{n}
237 directly from the bytecode stream; the operand follows the @code{const8}
238 bytecode itself. We write any such operands immediately after the name
239 of the bytecode, before the colon, and describe the exact encoding of
240 the operand in the bytecode stream in the body of the bytecode
243 For the @code{const8} bytecode, there are no stack items given before
244 the @result{}; this simply means that the bytecode consumes no values
245 from the stack. If a bytecode consumes no values, or produces no
246 values, the list on either side of the @result{} may be empty.
248 If a value is written as @var{a}, @var{b}, or @var{n}, then the bytecode
249 treats it as an integer. If a value is written is @var{addr}, then the
252 We do not fully describe the floating point operations here; although
254 values, they are not of immediate interest to the customer, so we avoid
265 Pop two integers from the stack, and push their sum, as an integer.
268 Pop two integers from the stack, subtract the top value from the
269 next-to-top value, and push the difference.
272 Pop two integers from the stack, multiply them, and push the product on
273 the stack. Note that, when one multiplies two @var{n}-bit numbers
274 yielding another @var{n}-bit number, it is irrelevant whether the
275 numbers are signed or not; the results are the same.
278 Pop two signed integers from the stack; divide the next-to-top value by
279 the top value, and push the quotient. If the divisor is zero, terminate
283 Pop two unsigned integers from the stack; divide the next-to-top value
284 by the top value, and push the quotient. If the divisor is zero,
288 Pop two signed integers from the stack; divide the next-to-top value by
289 the top value, and push the remainder. If the divisor is zero,
293 Pop two unsigned integers from the stack; divide the next-to-top value
294 by the top value, and push the remainder. If the divisor is zero,
298 Pop two integers from the stack; let @var{a} be the next-to-top value,
299 and @var{b} be the top value. Shift @var{a} left by @var{b} bits, and
300 push the result.
303 Pop two integers from the stack; let @var{a} be the next-to-top value,
304 and @var{b} be the top value. Shift @var{a} right by @var{b} bits,
305 inserting copies of the top bit at the high end, and push the result.
308 Pop two integers from the stack; let @var{a} be the next-to-top value,
309 and @var{b} be the top value. Shift @var{a} right by @var{b} bits,
310 inserting zero bits at the high end, and push the result.
313 Pop an integer from the stack; if it is zero, push the value one;
314 otherwise, push the value zero.
317 Pop two integers from the stack, and push their bitwise @code{and}.
320 Pop two integers from the stack, and push their bitwise @code{or}.
323 Pop two integers from the stack, and push their bitwise
327 Pop an integer from the stack, and push its bitwise complement.
330 Pop two integers from the stack; if they are equal, push the value one;
331 otherwise, push the value zero.
334 Pop two signed integers from the stack; if the next-to-top value is less
335 than the top value, push the value one; otherwise, push the value zero.
338 Pop two unsigned integers from the stack; if the next-to-top value is less
339 than the top value, push the value one; otherwise, push the value zero.
342 Pop an unsigned value from the stack; treating it as an @var{n}-bit
344 bits to the left of bit @var{n-1} (where the least significant bit is bit
345 0) are set to the value of bit @var{n-1}. Note that @var{n} may be
346 larger than or equal to the width of the stack elements of the bytecode
347 engine; in this case, the bytecode should have no effect.
350 byte unsigned integer following the @code{ext} bytecode.
353 Pop an unsigned value from the stack; zero all but the bottom @var{n}
354 bits. This means that all bits to the left of bit @var{n-1} (where the
355 least significant bit is bit 0) are set to the value of bit @var{n-1}.
358 byte unsigned integer following the @code{zero_ext} bytecode.
364 Pop an address @var{addr} from the stack. For bytecode
365 @code{ref}@var{n}, fetch an @var{n}-bit value from @var{addr}, using the
366 natural target endianness. Push the fetched value as an unsigned
369 Note that @var{addr} may not be aligned in any particular way; the
383 Push another copy of the stack's top element.
386 Exchange the top two items on the stack.
389 Discard the top value on the stack.
392 Pop an integer off the stack; if it is non-zero, branch to the given
393 offset in the bytecode string. Otherwise, continue to the next
394 instruction in the bytecode stream. In other words, if @var{a} is
395 non-zero, set the @code{pc} register to @code{start} + @var{offset}.
396 Thus, an offset of zero denotes the beginning of the expression.
399 immediately following the @code{if_goto} bytecode. It is always stored
400 most significant byte first, regardless of the target's normal
402 alignment within the bytecode stream; thus, on machines where fetching a
403 16-bit on an unaligned address raises an exception, you should fetch the
407 Branch unconditionally to @var{offset}; in other words, set the
410 The offset is stored in the same way as for the @code{if_goto} bytecode.
416 Push the integer constant @var{n} on the stack, without sign extension.
418 and then sign-extend it using the @code{ext} bytecode.
420 The constant @var{n} is stored in the appropriate number of bytes
421 following the @code{const}@var{b} bytecode. The constant @var{n} is
422 always stored most significant byte first, regardless of the target's
424 particular alignment within the bytecode stream; thus, on machines where
429 Push the value of register number @var{n}, without sign extension. The
433 immediately following the @code{reg} bytecode. It is always stored most
434 significant byte first, regardless of the target's normal endianness.
436 alignment within the bytecode stream; thus, on machines where fetching a
437 16-bit on an unaligned address raises an exception, you should fetch the
441 Record the contents of the @var{size} bytes at @var{addr} in a trace
445 Record the contents of the @var{size} bytes at @var{addr} in a trace
447 unsigned integer following the @code{trace} opcode.
449 This bytecode is equivalent to the sequence @code{dup const8 @var{size}
458 Stop executing bytecode; the result should be the top element of the
459 stack. If the purpose of the expression was to compute an lvalue or a
460 range of memory, then the next-to-top of the stack is the lvalue's
461 address, and the top of the stack is the lvalue's size, in bytes.
470 expressions fit into the process.
475 The user selects trace points in the program's code at which GDB should
481 contents are recorded as the program runs, or computed values, in which
482 case the values themselves are recorded.
485 GDB transmits the tracepoints and their associated expressions to the
486 GDB agent, running on the debugging target.
490 on some systems, the target operating system is completely responsible
491 for collecting the data; see @ref{Tracing on Symmetrix}.
494 When execution on the target reaches a trace point, the agent evaluates
495 the expressions associated with that trace point, and records the
499 Later, when the user selects a given trace event and inspects the
500 objects and expression values recorded, GDB talks to the agent to
501 retrieve recorded data as necessary to meet the user's requests. If the
515 Thus, GDB needs a way to ask the target about itself. We haven't worked
516 out the details yet, but in general, GDB should be able to send the
518 packet whose length is explicit, so we can add new information to the
519 packet in future revisions of the agent, without confusing old versions
521 least the following information:
541 whether the target supports disabled tracepoints
550 This section documents the API used by the GDB agent to collect data on
556 facilities; the GDB agent for the Symmetrix system uses those facilities
557 for its own data collection, via the API described here.
560 Search the trace frame @var{frame} for memory saved from @var{address}.
561 If the memory is available, provide the address of the buffer holding
562 it; otherwise, provide the address of the next saved area.
567 If the memory at @var{address} was saved in @var{frame}, set
568 @code{*@var{buffer}} to point to the buffer in which that memory was
569 saved, set @code{*@var{size}} to the number of bytes from @var{address}
571 @code{OK_TARGET_RESPONSE}. (Clearly, in this case, the function will
576 @code{*@var{size}} to the distance from @var{address} to the start of
577 the saved region with the lowest address higher than @var{address}. If
582 These two possibilities allow the caller to either retrieve the data, or
583 walk the address space to the next saved area.
586 This function allows the GDB agent to map the regions of memory saved in
589 This function also provides a clean interface between the GDB agent and
590 the Symmetrix tracing structures, making it easier to adapt the GDB
591 agent to future versions of the Symmetrix system, and vice versa. This
592 function searches all data saved in @var{frame}, whether the data is
593 there at the request of a bytecode expression, or because it falls in
594 one of the format's memory ranges, or because it was saved from the top
595 of the stack. EMC can arbitrarily change and enhance the tracing
600 the trace frame's stack area, memory ranges, and expression blocks can
601 yield the address of the buffer (if the requested address was saved),
602 and also note the address of the next higher range of memory, to be
603 returned when the search fails.
605 As an example, suppose the trace frame @code{f} has saved sixteen bytes
608 some sample calls, and the effect each would have:
619 twelve, and return @code{OK_TARGET_RESPONSE}, since @file{f} saves the
620 twelve bytes from @code{0x8004} starting four bytes into the buffer at
621 @code{0x1000}. This shows that request addresses may fall in the middle
622 of saved areas; the function should return the address and size of the
623 remainder of the buffer.
628 @code{f} from the address @code{0x8100}, and the next memory available
630 addresses may fall outside of all saved memory ranges; the function
631 should indicate the next saved area, if any.
635 @code{NOT_FOUND_TARGET_RESPONSE}, since the next saved memory is at
640 @code{NOT_FOUND_TARGET_RESPONSE}. This shows how the function tells the
645 As another example, here is a function which will print out the
646 addresses of all memory saved in the trace frame @code{frame} on the
660 where the next saved region is. */
671 Note that there is not necessarily any connection between the order in
672 which the data is saved in the trace frame, and the order in which
674 code above will always print the saved memory regions in order of
675 increasing address, while the underlying frame structure might store the
678 [[This section should cover the rest of the Symmetrix functions the stub
684 Some of the design decisions apparent above are arguable.
689 GDB should be able to query the target to discover its stack size.
691 given expression will overflow the stack. But this spec isn't about
701 operand sizes. You can generate code without @emph{knowing} how big the
702 stack elements actually are on the target. If the target only supports
704 works. The observation here is that the MIPS and the Alpha have only
707 make sure everything is properly sign-extended at the right times. So
708 there is no need for 32- and 64-bit variants of the bytecodes. Just
709 implement everything using the largest size you support.
711 GDB should certainly check to see what sizes the target supports, so the
717 I want to keep the interpreter small, and we don't need them. We can
718 combine the @code{less_} opcodes with @code{log_not}, and swap the order
719 of the operands, yielding all four asymmetrical comparison operators.
731 the relational operators.
734 @var{s-n} rsh_signed}, where @var{s} is the size of the stack elements;
735 it follows @code{ref@var{m}} and @var{reg} bytecodes when the value
736 should be signed. See the next bulleted item.
739 log_and}; it's used whenever we push the value of a register, because we
740 can't assume the upper bits of the register aren't garbage.
742 @item Why not have sign-extending variants of the @code{ref} operators?
743 Because that would double the number of @code{ref} operators, and we
744 need the @code{ext} bytecode anyway for accessing bitfields.
746 @item Why not have constant-address variants of the @code{ref} operators?
747 Because that would double the number of @code{ref} operators again, and
750 @item Why do the @code{ref@var{n}} operators have to support unaligned fetches?
752 addresses whenever the executable's debugging information tells it to.
753 Furthermore, GDB does not know the value the pointer will have when GDB
754 generates the bytecode, so it cannot determine whether a particular
762 correct C code, either at the programmer's explicit request, or at the
763 compiler's discretion. Thus, it is simpler to make the GDB agent
765 each case whether the compiler did the usual thing.
769 think the real answer is that I'm afraid of implementing function
770 calls. We should re-visit this issue after the present contract is
773 @item Why aren't the @code{goto} ops PC-relative?
774 The interpreter has the base address around anyway for PC bounds
777 @item Why is there only one offset size for the @code{goto} ops?
783 no loops in expressions), so I never know the target when I emit the
784 jump opcode. Thus, I have to either always assume the largest offset
785 size, or do jump relaxation on the code after I generate it, which seems
795 @item Where is the function call bytecode?
799 @item Why does the @code{reg} bytecode take a 16-bit register number?
806 Because GDB needs to record all the memory contents and registers an
807 expression touches. If the user wants to evaluate an expression
808 @code{x->y->z}, the agent must record the values of @code{x} and
809 @code{x->y} as well as the value of @code{x->y->z}.
811 @item Don't the @code{trace} bytecodes make the interpreter less general?
812 They do mean that the interpreter contains special-purpose code, but
813 that doesn't mean the interpreter can only be used for that purpose. If
814 an expression doesn't use the @code{trace} bytecodes, they don't get in
817 @item Why doesn't @code{trace_quick} consume its arguments the way everything else does?
819 consistent, and generally reduces the amount of stack rearrangement
824 know exactly what it should do with the stack. If we're going to have a
828 That opcode was added by the customer that contracted Cygnus for the
834 opcode 0x30 reserved, to remain compatible with the customer who added