gdb/
[deliverable/binutils-gdb.git] / gdb / doc / agentexpr.texi
CommitLineData
f418dd93 1@c \input texinfo
c906108c 2@c %**start of header
f418dd93
DJ
3@c @setfilename agentexpr.info
4@c @settitle GDB Agent Expressions
5@c @setchapternewpage off
c906108c
SS
6@c %**end of header
7
16d1a084
DJ
8@c This file is part of the GDB manual.
9@c
782b2b07 10@c Copyright (C) 2003, 2004, 2005, 2006, 2009
16d1a084
DJ
11@c Free Software Foundation, Inc.
12@c
13@c See the file gdb.texinfo for copying conditions.
14
f418dd93
DJ
15@node Agent Expressions
16@appendix The GDB Agent Expression Mechanism
c906108c 17
d3e8051b 18In some applications, it is not feasible for the debugger to interrupt
c906108c
SS
19the program's execution long enough for the developer to learn anything
20helpful about its behavior. If the program's correctness depends on its
21real-time behavior, delays introduced by a debugger might cause the
22program to fail, even when the code itself is correct. It is useful to
23be able to observe the program's behavior without interrupting it.
24
25Using GDB's @code{trace} and @code{collect} commands, the user can
26specify locations in the program, and arbitrary expressions to evaluate
27when those locations are reached. Later, using the @code{tfind}
28command, she can examine the values those expressions had when the
29program hit the trace points. The expressions may also denote objects
30in memory --- structures or arrays, for example --- whose values GDB
31should record; while visiting a particular tracepoint, the user may
32inspect those objects as if they were in memory at that moment.
33However, because GDB records these values without interacting with the
34user, it can do so quickly and unobtrusively, hopefully not disturbing
35the program's behavior.
36
37When GDB is debugging a remote target, the GDB @dfn{agent} code running
38on the target computes the values of the expressions itself. To avoid
39having a full symbolic expression evaluator on the agent, GDB translates
40expressions in the source language into a simpler bytecode language, and
41then sends the bytecode to the agent; the agent then executes the
42bytecode, and records the values for GDB to retrieve later.
43
44The bytecode language is simple; there are forty-odd opcodes, the bulk
45of which are the usual vocabulary of C operands (addition, subtraction,
46shifts, and so on) and various sizes of literals and memory reference
47operations. The bytecode interpreter operates strictly on machine-level
48values --- various sizes of integers and floating point numbers --- and
49requires no information about types or symbols; thus, the interpreter's
50internal data structures are simple, and each bytecode requires only a
51few native machine instructions to implement it. The interpreter is
52small, and strict limits on the memory and time required to evaluate an
53expression are easy to determine, making it suitable for use by the
54debugging agent in real-time applications.
55
56@menu
57* General Bytecode Design:: Overview of the interpreter.
58* Bytecode Descriptions:: What each one does.
59* Using Agent Expressions:: How agent expressions fit into the big picture.
60* Varying Target Capabilities:: How to discover what the target can do.
61* Tracing on Symmetrix:: Special info for implementation on EMC's
62 boxes.
63* Rationale:: Why we did it this way.
64@end menu
65
66
67@c @node Rationale
68@c @section Rationale
69
70
71@node General Bytecode Design
72@section General Bytecode Design
73
74The agent represents bytecode expressions as an array of bytes. Each
75instruction is one byte long (thus the term @dfn{bytecode}). Some
76instructions are followed by operand bytes; for example, the @code{goto}
77instruction is followed by a destination for the jump.
78
79The bytecode interpreter is a stack-based machine; most instructions pop
80their operands off the stack, perform some operation, and push the
81result back on the stack for the next instruction to consume. Each
82element of the stack may contain either a integer or a floating point
83value; these values are as many bits wide as the largest integer that
84can be directly manipulated in the source language. Stack elements
85carry no record of their type; bytecode could push a value as an
86integer, then pop it as a floating point value. However, GDB will not
87generate code which does this. In C, one might define the type of a
88stack element as follows:
89@example
90union agent_val @{
91 LONGEST l;
92 DOUBLEST d;
93@};
94@end example
95@noindent
96where @code{LONGEST} and @code{DOUBLEST} are @code{typedef} names for
97the largest integer and floating point types on the machine.
98
99By the time the bytecode interpreter reaches the end of the expression,
100the value of the expression should be the only value left on the stack.
101For tracing applications, @code{trace} bytecodes in the expression will
102have recorded the necessary data, and the value on the stack may be
103discarded. For other applications, like conditional breakpoints, the
104value may be useful.
105
106Separate from the stack, the interpreter has two registers:
107@table @code
108@item pc
109The address of the next bytecode to execute.
110
111@item start
112The address of the start of the bytecode expression, necessary for
113interpreting the @code{goto} and @code{if_goto} instructions.
114
115@end table
116@noindent
117Neither of these registers is directly visible to the bytecode language
118itself, but they are useful for defining the meanings of the bytecode
119operations.
120
121There are no instructions to perform side effects on the running
122program, or call the program's functions; we assume that these
123expressions are only used for unobtrusive debugging, not for patching
124the running code.
125
126Most bytecode instructions do not distinguish between the various sizes
127of values, and operate on full-width values; the upper bits of the
128values are simply ignored, since they do not usually make a difference
129to the value computed. The exceptions to this rule are:
130@table @asis
131
132@item memory reference instructions (@code{ref}@var{n})
133There are distinct instructions to fetch different word sizes from
134memory. Once on the stack, however, the values are treated as full-size
135integers. They may need to be sign-extended; the @code{ext} instruction
136exists for this purpose.
137
138@item the sign-extension instruction (@code{ext} @var{n})
139These clearly need to know which portion of their operand is to be
140extended to occupy the full length of the word.
141
142@end table
143
144If the interpreter is unable to evaluate an expression completely for
145some reason (a memory location is inaccessible, or a divisor is zero,
146for example), we say that interpretation ``terminates with an error''.
147This means that the problem is reported back to the interpreter's caller
148in some helpful way. In general, code using agent expressions should
149assume that they may attempt to divide by zero, fetch arbitrary memory
150locations, and misbehave in other ways.
151
152Even complicated C expressions compile to a few bytecode instructions;
153for example, the expression @code{x + y * z} would typically produce
154code like the following, assuming that @code{x} and @code{y} live in
155registers, and @code{z} is a global variable holding a 32-bit
156@code{int}:
157@example
158reg 1
159reg 2
160const32 @i{address of z}
161ref32
162ext 32
163mul
164add
165end
166@end example
167
168In detail, these mean:
169@table @code
170
171@item reg 1
172Push the value of register 1 (presumably holding @code{x}) onto the
173stack.
174
175@item reg 2
176Push the value of register 2 (holding @code{y}).
177
178@item const32 @i{address of z}
179Push the address of @code{z} onto the stack.
180
181@item ref32
182Fetch a 32-bit word from the address at the top of the stack; replace
183the address on the stack with the value. Thus, we replace the address
184of @code{z} with @code{z}'s value.
185
186@item ext 32
187Sign-extend the value on the top of the stack from 32 bits to full
188length. This is necessary because @code{z} is a signed integer.
189
190@item mul
191Pop the top two numbers on the stack, multiply them, and push their
192product. Now the top of the stack contains the value of the expression
193@code{y * z}.
194
195@item add
196Pop the top two numbers, add them, and push the sum. Now the top of the
197stack contains the value of @code{x + y * z}.
198
199@item end
200Stop executing; the value left on the stack top is the value to be
201recorded.
202
203@end table
204
205
206@node Bytecode Descriptions
207@section Bytecode Descriptions
208
209Each bytecode description has the following form:
210
211@table @asis
212
213@item @code{add} (0x02): @var{a} @var{b} @result{} @var{a+b}
214
215Pop the top two stack items, @var{a} and @var{b}, as integers; push
216their sum, as an integer.
217
218@end table
219
220In this example, @code{add} is the name of the bytecode, and
221@code{(0x02)} is the one-byte value used to encode the bytecode, in
d3e8051b 222hexadecimal. The phrase ``@var{a} @var{b} @result{} @var{a+b}'' shows
c906108c
SS
223the stack before and after the bytecode executes. Beforehand, the stack
224must contain at least two values, @var{a} and @var{b}; since the top of
225the stack is to the right, @var{b} is on the top of the stack, and
226@var{a} is underneath it. After execution, the bytecode will have
227popped @var{a} and @var{b} from the stack, and replaced them with a
228single value, @var{a+b}. There may be other values on the stack below
229those shown, but the bytecode affects only those shown.
230
231Here is another example:
232
233@table @asis
234
235@item @code{const8} (0x22) @var{n}: @result{} @var{n}
236Push the 8-bit integer constant @var{n} on the stack, without sign
237extension.
238
239@end table
240
241In this example, the bytecode @code{const8} takes an operand @var{n}
242directly from the bytecode stream; the operand follows the @code{const8}
243bytecode itself. We write any such operands immediately after the name
244of the bytecode, before the colon, and describe the exact encoding of
245the operand in the bytecode stream in the body of the bytecode
246description.
247
248For the @code{const8} bytecode, there are no stack items given before
249the @result{}; this simply means that the bytecode consumes no values
250from the stack. If a bytecode consumes no values, or produces no
251values, the list on either side of the @result{} may be empty.
252
253If a value is written as @var{a}, @var{b}, or @var{n}, then the bytecode
254treats it as an integer. If a value is written is @var{addr}, then the
255bytecode treats it as an address.
256
257We do not fully describe the floating point operations here; although
258this design can be extended in a clean way to handle floating point
259values, they are not of immediate interest to the customer, so we avoid
260describing them, to save time.
261
262
263@table @asis
264
265@item @code{float} (0x01): @result{}
266
267Prefix for floating-point bytecodes. Not implemented yet.
268
269@item @code{add} (0x02): @var{a} @var{b} @result{} @var{a+b}
270Pop two integers from the stack, and push their sum, as an integer.
271
272@item @code{sub} (0x03): @var{a} @var{b} @result{} @var{a-b}
273Pop two integers from the stack, subtract the top value from the
274next-to-top value, and push the difference.
275
276@item @code{mul} (0x04): @var{a} @var{b} @result{} @var{a*b}
277Pop two integers from the stack, multiply them, and push the product on
278the stack. Note that, when one multiplies two @var{n}-bit numbers
279yielding another @var{n}-bit number, it is irrelevant whether the
280numbers are signed or not; the results are the same.
281
282@item @code{div_signed} (0x05): @var{a} @var{b} @result{} @var{a/b}
283Pop two signed integers from the stack; divide the next-to-top value by
284the top value, and push the quotient. If the divisor is zero, terminate
285with an error.
286
287@item @code{div_unsigned} (0x06): @var{a} @var{b} @result{} @var{a/b}
288Pop two unsigned integers from the stack; divide the next-to-top value
289by the top value, and push the quotient. If the divisor is zero,
290terminate with an error.
291
292@item @code{rem_signed} (0x07): @var{a} @var{b} @result{} @var{a modulo b}
293Pop two signed integers from the stack; divide the next-to-top value by
294the top value, and push the remainder. If the divisor is zero,
295terminate with an error.
296
297@item @code{rem_unsigned} (0x08): @var{a} @var{b} @result{} @var{a modulo b}
298Pop two unsigned integers from the stack; divide the next-to-top value
299by the top value, and push the remainder. If the divisor is zero,
300terminate with an error.
301
302@item @code{lsh} (0x09): @var{a} @var{b} @result{} @var{a<<b}
303Pop two integers from the stack; let @var{a} be the next-to-top value,
304and @var{b} be the top value. Shift @var{a} left by @var{b} bits, and
305push the result.
306
f418dd93 307@item @code{rsh_signed} (0x0a): @var{a} @var{b} @result{} @code{(signed)}@var{a>>b}
c906108c
SS
308Pop two integers from the stack; let @var{a} be the next-to-top value,
309and @var{b} be the top value. Shift @var{a} right by @var{b} bits,
310inserting copies of the top bit at the high end, and push the result.
311
312@item @code{rsh_unsigned} (0x0b): @var{a} @var{b} @result{} @var{a>>b}
313Pop two integers from the stack; let @var{a} be the next-to-top value,
314and @var{b} be the top value. Shift @var{a} right by @var{b} bits,
315inserting zero bits at the high end, and push the result.
316
317@item @code{log_not} (0x0e): @var{a} @result{} @var{!a}
318Pop an integer from the stack; if it is zero, push the value one;
319otherwise, push the value zero.
320
321@item @code{bit_and} (0x0f): @var{a} @var{b} @result{} @var{a&b}
322Pop two integers from the stack, and push their bitwise @code{and}.
323
324@item @code{bit_or} (0x10): @var{a} @var{b} @result{} @var{a|b}
325Pop two integers from the stack, and push their bitwise @code{or}.
326
327@item @code{bit_xor} (0x11): @var{a} @var{b} @result{} @var{a^b}
328Pop two integers from the stack, and push their bitwise
329exclusive-@code{or}.
330
331@item @code{bit_not} (0x12): @var{a} @result{} @var{~a}
332Pop an integer from the stack, and push its bitwise complement.
333
334@item @code{equal} (0x13): @var{a} @var{b} @result{} @var{a=b}
335Pop two integers from the stack; if they are equal, push the value one;
336otherwise, push the value zero.
337
338@item @code{less_signed} (0x14): @var{a} @var{b} @result{} @var{a<b}
339Pop two signed integers from the stack; if the next-to-top value is less
340than the top value, push the value one; otherwise, push the value zero.
341
342@item @code{less_unsigned} (0x15): @var{a} @var{b} @result{} @var{a<b}
343Pop two unsigned integers from the stack; if the next-to-top value is less
344than the top value, push the value one; otherwise, push the value zero.
345
346@item @code{ext} (0x16) @var{n}: @var{a} @result{} @var{a}, sign-extended from @var{n} bits
347Pop an unsigned value from the stack; treating it as an @var{n}-bit
348twos-complement value, extend it to full length. This means that all
349bits to the left of bit @var{n-1} (where the least significant bit is bit
3500) are set to the value of bit @var{n-1}. Note that @var{n} may be
351larger than or equal to the width of the stack elements of the bytecode
352engine; in this case, the bytecode should have no effect.
353
354The number of source bits to preserve, @var{n}, is encoded as a single
355byte unsigned integer following the @code{ext} bytecode.
356
357@item @code{zero_ext} (0x2a) @var{n}: @var{a} @result{} @var{a}, zero-extended from @var{n} bits
358Pop an unsigned value from the stack; zero all but the bottom @var{n}
359bits. This means that all bits to the left of bit @var{n-1} (where the
360least significant bit is bit 0) are set to the value of bit @var{n-1}.
361
362The number of source bits to preserve, @var{n}, is encoded as a single
363byte unsigned integer following the @code{zero_ext} bytecode.
364
365@item @code{ref8} (0x17): @var{addr} @result{} @var{a}
366@itemx @code{ref16} (0x18): @var{addr} @result{} @var{a}
367@itemx @code{ref32} (0x19): @var{addr} @result{} @var{a}
368@itemx @code{ref64} (0x1a): @var{addr} @result{} @var{a}
369Pop an address @var{addr} from the stack. For bytecode
370@code{ref}@var{n}, fetch an @var{n}-bit value from @var{addr}, using the
371natural target endianness. Push the fetched value as an unsigned
372integer.
373
374Note that @var{addr} may not be aligned in any particular way; the
375@code{ref@var{n}} bytecodes should operate correctly for any address.
376
377If attempting to access memory at @var{addr} would cause a processor
378exception of some sort, terminate with an error.
379
380@item @code{ref_float} (0x1b): @var{addr} @result{} @var{d}
381@itemx @code{ref_double} (0x1c): @var{addr} @result{} @var{d}
382@itemx @code{ref_long_double} (0x1d): @var{addr} @result{} @var{d}
383@itemx @code{l_to_d} (0x1e): @var{a} @result{} @var{d}
384@itemx @code{d_to_l} (0x1f): @var{d} @result{} @var{a}
385Not implemented yet.
386
387@item @code{dup} (0x28): @var{a} => @var{a} @var{a}
388Push another copy of the stack's top element.
389
390@item @code{swap} (0x2b): @var{a} @var{b} => @var{b} @var{a}
391Exchange the top two items on the stack.
392
393@item @code{pop} (0x29): @var{a} =>
394Discard the top value on the stack.
395
396@item @code{if_goto} (0x20) @var{offset}: @var{a} @result{}
397Pop an integer off the stack; if it is non-zero, branch to the given
398offset in the bytecode string. Otherwise, continue to the next
399instruction in the bytecode stream. In other words, if @var{a} is
400non-zero, set the @code{pc} register to @code{start} + @var{offset}.
401Thus, an offset of zero denotes the beginning of the expression.
402
403The @var{offset} is stored as a sixteen-bit unsigned value, stored
404immediately following the @code{if_goto} bytecode. It is always stored
f821f325 405most significant byte first, regardless of the target's normal
c906108c
SS
406endianness. The offset is not guaranteed to fall at any particular
407alignment within the bytecode stream; thus, on machines where fetching a
40816-bit on an unaligned address raises an exception, you should fetch the
409offset one byte at a time.
410
411@item @code{goto} (0x21) @var{offset}: @result{}
412Branch unconditionally to @var{offset}; in other words, set the
413@code{pc} register to @code{start} + @var{offset}.
414
415The offset is stored in the same way as for the @code{if_goto} bytecode.
416
417@item @code{const8} (0x22) @var{n}: @result{} @var{n}
418@itemx @code{const16} (0x23) @var{n}: @result{} @var{n}
419@itemx @code{const32} (0x24) @var{n}: @result{} @var{n}
420@itemx @code{const64} (0x25) @var{n}: @result{} @var{n}
421Push the integer constant @var{n} on the stack, without sign extension.
422To produce a small negative value, push a small twos-complement value,
423and then sign-extend it using the @code{ext} bytecode.
424
425The constant @var{n} is stored in the appropriate number of bytes
426following the @code{const}@var{b} bytecode. The constant @var{n} is
427always stored most significant byte first, regardless of the target's
428normal endianness. The constant is not guaranteed to fall at any
429particular alignment within the bytecode stream; thus, on machines where
430fetching a 16-bit on an unaligned address raises an exception, you
431should fetch @var{n} one byte at a time.
432
433@item @code{reg} (0x26) @var{n}: @result{} @var{a}
434Push the value of register number @var{n}, without sign extension. The
435registers are numbered following GDB's conventions.
436
437The register number @var{n} is encoded as a 16-bit unsigned integer
438immediately following the @code{reg} bytecode. It is always stored most
f821f325 439significant byte first, regardless of the target's normal endianness.
c906108c
SS
440The register number is not guaranteed to fall at any particular
441alignment within the bytecode stream; thus, on machines where fetching a
44216-bit on an unaligned address raises an exception, you should fetch the
443register number one byte at a time.
444
445@item @code{trace} (0x0c): @var{addr} @var{size} @result{}
446Record the contents of the @var{size} bytes at @var{addr} in a trace
447buffer, for later retrieval by GDB.
448
449@item @code{trace_quick} (0x0d) @var{size}: @var{addr} @result{} @var{addr}
450Record the contents of the @var{size} bytes at @var{addr} in a trace
451buffer, for later retrieval by GDB. @var{size} is a single byte
452unsigned integer following the @code{trace} opcode.
453
454This bytecode is equivalent to the sequence @code{dup const8 @var{size}
455trace}, but we provide it anyway to save space in bytecode strings.
456
457@item @code{trace16} (0x30) @var{size}: @var{addr} @result{} @var{addr}
458Identical to trace_quick, except that @var{size} is a 16-bit big-endian
459unsigned integer, not a single byte. This should probably have been
460named @code{trace_quick16}, for consistency.
461
462@item @code{end} (0x27): @result{}
463Stop executing bytecode; the result should be the top element of the
464stack. If the purpose of the expression was to compute an lvalue or a
465range of memory, then the next-to-top of the stack is the lvalue's
466address, and the top of the stack is the lvalue's size, in bytes.
467
468@end table
469
470
471@node Using Agent Expressions
472@section Using Agent Expressions
473
782b2b07
SS
474Agent expressions can be used in several different ways by @value{GDBN},
475and the debugger can generate different bytecode sequences as appropriate.
476
477One possibility is to do expression evaluation on the target rather
478than the host, such as for the conditional of a conditional
479tracepoint. In such a case, @value{GDBN} compiles the source
480expression into a bytecode sequence that simply gets values from
481registers or memory, does arithmetic, and returns a result.
482
483Another way to use agent expressions is for tracepoint data
484collection. @value{GDBN} generates a different bytecode sequence for
485collection; in addition to bytecodes that do the calculation,
486@value{GDBN} adds @code{trace} bytecodes to save the pieces of
487memory that were used.
c906108c
SS
488
489@itemize @bullet
490
491@item
492The user selects trace points in the program's code at which GDB should
493collect data.
494
495@item
496The user specifies expressions to evaluate at each trace point. These
497expressions may denote objects in memory, in which case those objects'
498contents are recorded as the program runs, or computed values, in which
499case the values themselves are recorded.
500
501@item
502GDB transmits the tracepoints and their associated expressions to the
503GDB agent, running on the debugging target.
504
505@item
506The agent arranges to be notified when a trace point is hit. Note that,
507on some systems, the target operating system is completely responsible
508for collecting the data; see @ref{Tracing on Symmetrix}.
509
510@item
511When execution on the target reaches a trace point, the agent evaluates
512the expressions associated with that trace point, and records the
513resulting values and memory ranges.
514
515@item
516Later, when the user selects a given trace event and inspects the
517objects and expression values recorded, GDB talks to the agent to
518retrieve recorded data as necessary to meet the user's requests. If the
519user asks to see an object whose contents have not been recorded, GDB
520reports an error.
521
522@end itemize
523
524
525@node Varying Target Capabilities
526@section Varying Target Capabilities
527
528Some targets don't support floating-point, and some would rather not
529have to deal with @code{long long} operations. Also, different targets
530will have different stack sizes, and different bytecode buffer lengths.
531
532Thus, GDB needs a way to ask the target about itself. We haven't worked
533out the details yet, but in general, GDB should be able to send the
534target a packet asking it to describe itself. The reply should be a
535packet whose length is explicit, so we can add new information to the
536packet in future revisions of the agent, without confusing old versions
537of GDB, and it should contain a version number. It should contain at
538least the following information:
539
540@itemize @bullet
541
542@item
543whether floating point is supported
544
545@item
546whether @code{long long} is supported
547
548@item
549maximum acceptable size of bytecode stack
550
551@item
552maximum acceptable length of bytecode expressions
553
554@item
555which registers are actually available for collection
556
557@item
558whether the target supports disabled tracepoints
559
560@end itemize
561
562
563
564@node Tracing on Symmetrix
565@section Tracing on Symmetrix
566
567This section documents the API used by the GDB agent to collect data on
568Symmetrix systems.
569
570Cygnus originally implemented these tracing features to help EMC
571Corporation debug their Symmetrix high-availability disk drives. The
572Symmetrix application code already includes substantial tracing
573facilities; the GDB agent for the Symmetrix system uses those facilities
574for its own data collection, via the API described here.
575
576@deftypefn Function DTC_RESPONSE adbg_find_memory_in_frame (FRAME_DEF *@var{frame}, char *@var{address}, char **@var{buffer}, unsigned int *@var{size})
577Search the trace frame @var{frame} for memory saved from @var{address}.
578If the memory is available, provide the address of the buffer holding
579it; otherwise, provide the address of the next saved area.
580
581@itemize @bullet
582
583@item
584If the memory at @var{address} was saved in @var{frame}, set
585@code{*@var{buffer}} to point to the buffer in which that memory was
586saved, set @code{*@var{size}} to the number of bytes from @var{address}
587that are saved at @code{*@var{buffer}}, and return
588@code{OK_TARGET_RESPONSE}. (Clearly, in this case, the function will
589always set @code{*@var{size}} to a value greater than zero.)
590
591@item
592If @var{frame} does not record any memory at @var{address}, set
593@code{*@var{size}} to the distance from @var{address} to the start of
594the saved region with the lowest address higher than @var{address}. If
595there is no memory saved from any higher address, set @code{*@var{size}}
596to zero. Return @code{NOT_FOUND_TARGET_RESPONSE}.
597@end itemize
598
599These two possibilities allow the caller to either retrieve the data, or
600walk the address space to the next saved area.
601@end deftypefn
602
603This function allows the GDB agent to map the regions of memory saved in
604a particular frame, and retrieve their contents efficiently.
605
606This function also provides a clean interface between the GDB agent and
607the Symmetrix tracing structures, making it easier to adapt the GDB
608agent to future versions of the Symmetrix system, and vice versa. This
609function searches all data saved in @var{frame}, whether the data is
610there at the request of a bytecode expression, or because it falls in
611one of the format's memory ranges, or because it was saved from the top
612of the stack. EMC can arbitrarily change and enhance the tracing
613mechanism, but as long as this function works properly, all collected
614memory is visible to GDB.
615
616The function itself is straightforward to implement. A single pass over
617the trace frame's stack area, memory ranges, and expression blocks can
618yield the address of the buffer (if the requested address was saved),
619and also note the address of the next higher range of memory, to be
620returned when the search fails.
621
622As an example, suppose the trace frame @code{f} has saved sixteen bytes
623from address @code{0x8000} in a buffer at @code{0x1000}, and thirty-two
624bytes from address @code{0xc000} in a buffer at @code{0x1010}. Here are
625some sample calls, and the effect each would have:
626
627@table @code
628
629@item adbg_find_memory_in_frame (f, (char*) 0x8000, &buffer, &size)
630This would set @code{buffer} to @code{0x1000}, set @code{size} to
631sixteen, and return @code{OK_TARGET_RESPONSE}, since @code{f} saves
632sixteen bytes from @code{0x8000} at @code{0x1000}.
633
634@item adbg_find_memory_in_frame (f, (char *) 0x8004, &buffer, &size)
635This would set @code{buffer} to @code{0x1004}, set @code{size} to
636twelve, and return @code{OK_TARGET_RESPONSE}, since @file{f} saves the
637twelve bytes from @code{0x8004} starting four bytes into the buffer at
638@code{0x1000}. This shows that request addresses may fall in the middle
639of saved areas; the function should return the address and size of the
640remainder of the buffer.
641
642@item adbg_find_memory_in_frame (f, (char *) 0x8100, &buffer, &size)
643This would set @code{size} to @code{0x3f00} and return
644@code{NOT_FOUND_TARGET_RESPONSE}, since there is no memory saved in
645@code{f} from the address @code{0x8100}, and the next memory available
646is at @code{0x8100 + 0x3f00}, or @code{0xc000}. This shows that request
647addresses may fall outside of all saved memory ranges; the function
648should indicate the next saved area, if any.
649
650@item adbg_find_memory_in_frame (f, (char *) 0x7000, &buffer, &size)
651This would set @code{size} to @code{0x1000} and return
652@code{NOT_FOUND_TARGET_RESPONSE}, since the next saved memory is at
653@code{0x7000 + 0x1000}, or @code{0x8000}.
654
655@item adbg_find_memory_in_frame (f, (char *) 0xf000, &buffer, &size)
656This would set @code{size} to zero, and return
657@code{NOT_FOUND_TARGET_RESPONSE}. This shows how the function tells the
658caller that no further memory ranges have been saved.
659
660@end table
661
662As another example, here is a function which will print out the
663addresses of all memory saved in the trace frame @code{frame} on the
664Symmetrix INLINES console:
665@example
666void
667print_frame_addresses (FRAME_DEF *frame)
668@{
669 char *addr;
670 char *buffer;
671 unsigned long size;
672
673 addr = 0;
674 for (;;)
675 @{
676 /* Either find out how much memory we have here, or discover
677 where the next saved region is. */
678 if (adbg_find_memory_in_frame (frame, addr, &buffer, &size)
679 == OK_TARGET_RESPONSE)
680 printp ("saved %x to %x\n", addr, addr + size);
681 if (size == 0)
682 break;
683 addr += size;
684 @}
685@}
686@end example
687
688Note that there is not necessarily any connection between the order in
689which the data is saved in the trace frame, and the order in which
690@code{adbg_find_memory_in_frame} will return those memory ranges. The
691code above will always print the saved memory regions in order of
692increasing address, while the underlying frame structure might store the
693data in a random order.
694
695[[This section should cover the rest of the Symmetrix functions the stub
696relies upon, too.]]
697
698@node Rationale
699@section Rationale
700
701Some of the design decisions apparent above are arguable.
702
703@table @b
704
705@item What about stack overflow/underflow?
706GDB should be able to query the target to discover its stack size.
707Given that information, GDB can determine at translation time whether a
708given expression will overflow the stack. But this spec isn't about
709what kinds of error-checking GDB ought to do.
710
711@item Why are you doing everything in LONGEST?
712
713Speed isn't important, but agent code size is; using LONGEST brings in a
714bunch of support code to do things like division, etc. So this is a
715serious concern.
716
717First, note that you don't need different bytecodes for different
718operand sizes. You can generate code without @emph{knowing} how big the
719stack elements actually are on the target. If the target only supports
72032-bit ints, and you don't send any 64-bit bytecodes, everything just
721works. The observation here is that the MIPS and the Alpha have only
722fixed-size registers, and you can still get C's semantics even though
723most instructions only operate on full-sized words. You just need to
724make sure everything is properly sign-extended at the right times. So
725there is no need for 32- and 64-bit variants of the bytecodes. Just
726implement everything using the largest size you support.
727
728GDB should certainly check to see what sizes the target supports, so the
729user can get an error earlier, rather than later. But this information
730is not necessary for correctness.
731
732
733@item Why don't you have @code{>} or @code{<=} operators?
734I want to keep the interpreter small, and we don't need them. We can
735combine the @code{less_} opcodes with @code{log_not}, and swap the order
736of the operands, yielding all four asymmetrical comparison operators.
737For example, @code{(x <= y)} is @code{! (x > y)}, which is @code{! (y <
738x)}.
739
740@item Why do you have @code{log_not}?
741@itemx Why do you have @code{ext}?
742@itemx Why do you have @code{zero_ext}?
743These are all easily synthesized from other instructions, but I expect
744them to be used frequently, and they're simple, so I include them to
745keep bytecode strings short.
746
747@code{log_not} is equivalent to @code{const8 0 equal}; it's used in half
748the relational operators.
749
750@code{ext @var{n}} is equivalent to @code{const8 @var{s-n} lsh const8
751@var{s-n} rsh_signed}, where @var{s} is the size of the stack elements;
752it follows @code{ref@var{m}} and @var{reg} bytecodes when the value
753should be signed. See the next bulleted item.
754
755@code{zero_ext @var{n}} is equivalent to @code{const@var{m} @var{mask}
756log_and}; it's used whenever we push the value of a register, because we
757can't assume the upper bits of the register aren't garbage.
758
759@item Why not have sign-extending variants of the @code{ref} operators?
760Because that would double the number of @code{ref} operators, and we
761need the @code{ext} bytecode anyway for accessing bitfields.
762
763@item Why not have constant-address variants of the @code{ref} operators?
764Because that would double the number of @code{ref} operators again, and
765@code{const32 @var{address} ref32} is only one byte longer.
766
767@item Why do the @code{ref@var{n}} operators have to support unaligned fetches?
768GDB will generate bytecode that fetches multi-byte values at unaligned
769addresses whenever the executable's debugging information tells it to.
770Furthermore, GDB does not know the value the pointer will have when GDB
771generates the bytecode, so it cannot determine whether a particular
772fetch will be aligned or not.
773
774In particular, structure bitfields may be several bytes long, but follow
775no alignment rules; members of packed structures are not necessarily
776aligned either.
777
778In general, there are many cases where unaligned references occur in
779correct C code, either at the programmer's explicit request, or at the
780compiler's discretion. Thus, it is simpler to make the GDB agent
781bytecodes work correctly in all circumstances than to make GDB guess in
782each case whether the compiler did the usual thing.
783
784@item Why are there no side-effecting operators?
785Because our current client doesn't want them? That's a cheap answer. I
786think the real answer is that I'm afraid of implementing function
787calls. We should re-visit this issue after the present contract is
788delivered.
789
790@item Why aren't the @code{goto} ops PC-relative?
791The interpreter has the base address around anyway for PC bounds
792checking, and it seemed simpler.
793
794@item Why is there only one offset size for the @code{goto} ops?
795Offsets are currently sixteen bits. I'm not happy with this situation
796either:
797
798Suppose we have multiple branch ops with different offset sizes. As I
799generate code left-to-right, all my jumps are forward jumps (there are
800no loops in expressions), so I never know the target when I emit the
801jump opcode. Thus, I have to either always assume the largest offset
802size, or do jump relaxation on the code after I generate it, which seems
803like a big waste of time.
804
805I can imagine a reasonable expression being longer than 256 bytes. I
806can't imagine one being longer than 64k. Thus, we need 16-bit offsets.
807This kind of reasoning is so bogus, but relaxation is pathetic.
808
809The other approach would be to generate code right-to-left. Then I'd
810always know my offset size. That might be fun.
811
812@item Where is the function call bytecode?
813
814When we add side-effects, we should add this.
815
816@item Why does the @code{reg} bytecode take a 16-bit register number?
817
5e35df8e 818Intel's IA-64 architecture has 128 general-purpose registers,
c906108c
SS
819and 128 floating-point registers, and I'm sure it has some random
820control registers.
821
822@item Why do we need @code{trace} and @code{trace_quick}?
823Because GDB needs to record all the memory contents and registers an
824expression touches. If the user wants to evaluate an expression
825@code{x->y->z}, the agent must record the values of @code{x} and
826@code{x->y} as well as the value of @code{x->y->z}.
827
828@item Don't the @code{trace} bytecodes make the interpreter less general?
829They do mean that the interpreter contains special-purpose code, but
830that doesn't mean the interpreter can only be used for that purpose. If
831an expression doesn't use the @code{trace} bytecodes, they don't get in
832its way.
833
834@item Why doesn't @code{trace_quick} consume its arguments the way everything else does?
835In general, you do want your operators to consume their arguments; it's
836consistent, and generally reduces the amount of stack rearrangement
837necessary. However, @code{trace_quick} is a kludge to save space; it
838only exists so we needn't write @code{dup const8 @var{SIZE} trace}
839before every memory reference. Therefore, it's okay for it not to
840consume its arguments; it's meant for a specific context in which we
841know exactly what it should do with the stack. If we're going to have a
842kludge, it should be an effective kludge.
843
844@item Why does @code{trace16} exist?
845That opcode was added by the customer that contracted Cygnus for the
846data tracing work. I personally think it is unnecessary; objects that
847large will be quite rare, so it is okay to use @code{dup const16
848@var{size} trace} in those cases.
849
850Whatever we decide to do with @code{trace16}, we should at least leave
851opcode 0x30 reserved, to remain compatible with the customer who added
852it.
853
854@end table
This page took 0.620783 seconds and 4 git commands to generate.