Commit | Line | Data |
---|---|---|
c906108c SS |
1 | \input texinfo |
2 | @c %**start of header | |
3 | @setfilename agentexpr.info | |
4 | @settitle GDB Agent Expressions | |
5 | @setchapternewpage off | |
6 | @c %**end of header | |
7 | ||
8 | Revision: $Id$ | |
9 | ||
10 | @node The GDB Agent Expression Mechanism | |
11 | @chapter The GDB Agent Expression Mechanism | |
12 | ||
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. | |
19 | ||
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 | |
25 | in memory --- structures or arrays, for example --- whose values GDB | |
26 | should record; while visiting a particular tracepoint, the user may | |
27 | inspect those objects as if they were in memory at that moment. | |
28 | However, because GDB records these values without interacting with the | |
29 | user, it can do so quickly and unobtrusively, hopefully not disturbing | |
30 | the program's behavior. | |
31 | ||
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. | |
38 | ||
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, | |
41 | shifts, and so on) and various sizes of literals and memory reference | |
42 | operations. The bytecode interpreter operates strictly on machine-level | |
43 | values --- various sizes of integers and floating point numbers --- and | |
44 | requires no information about types or symbols; thus, the interpreter's | |
45 | internal data structures are simple, and each bytecode requires only a | |
46 | few native machine instructions to implement it. The interpreter is | |
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 | |
49 | debugging agent in real-time applications. | |
50 | ||
51 | @menu | |
52 | * General Bytecode Design:: Overview of the interpreter. | |
53 | * Bytecode Descriptions:: What each one does. | |
54 | * Using Agent Expressions:: How agent expressions fit into the big picture. | |
55 | * Varying Target Capabilities:: How to discover what the target can do. | |
56 | * Tracing on Symmetrix:: Special info for implementation on EMC's | |
57 | boxes. | |
58 | * Rationale:: Why we did it this way. | |
59 | @end menu | |
60 | ||
61 | ||
62 | @c @node Rationale | |
63 | @c @section Rationale | |
64 | ||
65 | ||
66 | @node General Bytecode Design | |
67 | @section General Bytecode Design | |
68 | ||
69 | The agent represents bytecode expressions as an array of bytes. Each | |
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. | |
73 | ||
74 | The bytecode interpreter is a stack-based machine; most instructions pop | |
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 | |
80 | carry no record of their type; bytecode could push a value as an | |
81 | integer, then pop it as a floating point value. However, GDB will not | |
82 | generate code which does this. In C, one might define the type of a | |
83 | stack element as follows: | |
84 | @example | |
85 | union agent_val @{ | |
86 | LONGEST l; | |
87 | DOUBLEST d; | |
88 | @}; | |
89 | @end example | |
90 | @noindent | |
91 | where @code{LONGEST} and @code{DOUBLEST} are @code{typedef} names for | |
92 | the largest integer and floating point types on the machine. | |
93 | ||
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 | |
99 | value may be useful. | |
100 | ||
101 | Separate from the stack, the interpreter has two registers: | |
102 | @table @code | |
103 | @item pc | |
104 | The address of the next bytecode to execute. | |
105 | ||
106 | @item start | |
107 | The address of the start of the bytecode expression, necessary for | |
108 | interpreting the @code{goto} and @code{if_goto} instructions. | |
109 | ||
110 | @end table | |
111 | @noindent | |
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 | |
114 | operations. | |
115 | ||
116 | There are no instructions to perform side effects on the running | |
117 | program, or call the program's functions; we assume that these | |
118 | expressions are only used for unobtrusive debugging, not for patching | |
119 | the running code. | |
120 | ||
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 | |
123 | values are simply ignored, since they do not usually make a difference | |
124 | to the value computed. The exceptions to this rule are: | |
125 | @table @asis | |
126 | ||
127 | @item memory reference instructions (@code{ref}@var{n}) | |
128 | There are distinct instructions to fetch different word sizes from | |
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 | |
131 | exists for this purpose. | |
132 | ||
133 | @item the sign-extension instruction (@code{ext} @var{n}) | |
134 | These clearly need to know which portion of their operand is to be | |
135 | extended to occupy the full length of the word. | |
136 | ||
137 | @end table | |
138 | ||
139 | If the interpreter is unable to evaluate an expression completely for | |
140 | some reason (a memory location is inaccessible, or a divisor is zero, | |
141 | for example), we say that interpretation ``terminates with an error''. | |
142 | This means that the problem is reported back to the interpreter's caller | |
143 | in some helpful way. In general, code using agent expressions should | |
144 | assume that they may attempt to divide by zero, fetch arbitrary memory | |
145 | locations, and misbehave in other ways. | |
146 | ||
147 | Even complicated C expressions compile to a few bytecode instructions; | |
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 | |
150 | registers, and @code{z} is a global variable holding a 32-bit | |
151 | @code{int}: | |
152 | @example | |
153 | reg 1 | |
154 | reg 2 | |
155 | const32 @i{address of z} | |
156 | ref32 | |
157 | ext 32 | |
158 | mul | |
159 | add | |
160 | end | |
161 | @end example | |
162 | ||
163 | In detail, these mean: | |
164 | @table @code | |
165 | ||
166 | @item reg 1 | |
167 | Push the value of register 1 (presumably holding @code{x}) onto the | |
168 | stack. | |
169 | ||
170 | @item reg 2 | |
171 | Push the value of register 2 (holding @code{y}). | |
172 | ||
173 | @item const32 @i{address of z} | |
174 | Push the address of @code{z} onto the stack. | |
175 | ||
176 | @item ref32 | |
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 | |
179 | of @code{z} with @code{z}'s value. | |
180 | ||
181 | @item ext 32 | |
182 | Sign-extend the value on the top of the stack from 32 bits to full | |
183 | length. This is necessary because @code{z} is a signed integer. | |
184 | ||
185 | @item mul | |
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 | |
188 | @code{y * z}. | |
189 | ||
190 | @item add | |
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}. | |
193 | ||
194 | @item end | |
195 | Stop executing; the value left on the stack top is the value to be | |
196 | recorded. | |
197 | ||
198 | @end table | |
199 | ||
200 | ||
201 | @node Bytecode Descriptions | |
202 | @section Bytecode Descriptions | |
203 | ||
204 | Each bytecode description has the following form: | |
205 | ||
206 | @table @asis | |
207 | ||
208 | @item @code{add} (0x02): @var{a} @var{b} @result{} @var{a+b} | |
209 | ||
210 | Pop the top two stack items, @var{a} and @var{b}, as integers; push | |
211 | their sum, as an integer. | |
212 | ||
213 | @end table | |
214 | ||
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 | |
217 | hexidecimal. The phrase ``@var{a} @var{b} @result{} @var{a+b}'' shows | |
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. | |
225 | ||
226 | Here is another example: | |
227 | ||
228 | @table @asis | |
229 | ||
230 | @item @code{const8} (0x22) @var{n}: @result{} @var{n} | |
231 | Push the 8-bit integer constant @var{n} on the stack, without sign | |
232 | extension. | |
233 | ||
234 | @end table | |
235 | ||
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 | |
241 | description. | |
242 | ||
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. | |
247 | ||
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 | |
250 | bytecode treats it as an address. | |
251 | ||
252 | We do not fully describe the floating point operations here; although | |
253 | this design can be extended in a clean way to handle floating point | |
254 | values, they are not of immediate interest to the customer, so we avoid | |
255 | describing them, to save time. | |
256 | ||
257 | ||
258 | @table @asis | |
259 | ||
260 | @item @code{float} (0x01): @result{} | |
261 | ||
262 | Prefix for floating-point bytecodes. Not implemented yet. | |
263 | ||
264 | @item @code{add} (0x02): @var{a} @var{b} @result{} @var{a+b} | |
265 | Pop two integers from the stack, and push their sum, as an integer. | |
266 | ||
267 | @item @code{sub} (0x03): @var{a} @var{b} @result{} @var{a-b} | |
268 | Pop two integers from the stack, subtract the top value from the | |
269 | next-to-top value, and push the difference. | |
270 | ||
271 | @item @code{mul} (0x04): @var{a} @var{b} @result{} @var{a*b} | |
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. | |
276 | ||
277 | @item @code{div_signed} (0x05): @var{a} @var{b} @result{} @var{a/b} | |
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 | |
280 | with an error. | |
281 | ||
282 | @item @code{div_unsigned} (0x06): @var{a} @var{b} @result{} @var{a/b} | |
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, | |
285 | terminate with an error. | |
286 | ||
287 | @item @code{rem_signed} (0x07): @var{a} @var{b} @result{} @var{a modulo b} | |
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, | |
290 | terminate with an error. | |
291 | ||
292 | @item @code{rem_unsigned} (0x08): @var{a} @var{b} @result{} @var{a modulo b} | |
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, | |
295 | terminate with an error. | |
296 | ||
297 | @item @code{lsh} (0x09): @var{a} @var{b} @result{} @var{a<<b} | |
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. | |
301 | ||
302 | @item @code{rsh_signed} (0x0a): @var{a} @var{b} @result{} @var{@code{(signed)}a>>b} | |
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. | |
306 | ||
307 | @item @code{rsh_unsigned} (0x0b): @var{a} @var{b} @result{} @var{a>>b} | |
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. | |
311 | ||
312 | @item @code{log_not} (0x0e): @var{a} @result{} @var{!a} | |
313 | Pop an integer from the stack; if it is zero, push the value one; | |
314 | otherwise, push the value zero. | |
315 | ||
316 | @item @code{bit_and} (0x0f): @var{a} @var{b} @result{} @var{a&b} | |
317 | Pop two integers from the stack, and push their bitwise @code{and}. | |
318 | ||
319 | @item @code{bit_or} (0x10): @var{a} @var{b} @result{} @var{a|b} | |
320 | Pop two integers from the stack, and push their bitwise @code{or}. | |
321 | ||
322 | @item @code{bit_xor} (0x11): @var{a} @var{b} @result{} @var{a^b} | |
323 | Pop two integers from the stack, and push their bitwise | |
324 | exclusive-@code{or}. | |
325 | ||
326 | @item @code{bit_not} (0x12): @var{a} @result{} @var{~a} | |
327 | Pop an integer from the stack, and push its bitwise complement. | |
328 | ||
329 | @item @code{equal} (0x13): @var{a} @var{b} @result{} @var{a=b} | |
330 | Pop two integers from the stack; if they are equal, push the value one; | |
331 | otherwise, push the value zero. | |
332 | ||
333 | @item @code{less_signed} (0x14): @var{a} @var{b} @result{} @var{a<b} | |
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. | |
336 | ||
337 | @item @code{less_unsigned} (0x15): @var{a} @var{b} @result{} @var{a<b} | |
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. | |
340 | ||
341 | @item @code{ext} (0x16) @var{n}: @var{a} @result{} @var{a}, sign-extended from @var{n} bits | |
342 | Pop an unsigned value from the stack; treating it as an @var{n}-bit | |
343 | twos-complement value, extend it to full length. This means that all | |
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. | |
348 | ||
349 | The number of source bits to preserve, @var{n}, is encoded as a single | |
350 | byte unsigned integer following the @code{ext} bytecode. | |
351 | ||
352 | @item @code{zero_ext} (0x2a) @var{n}: @var{a} @result{} @var{a}, zero-extended from @var{n} bits | |
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}. | |
356 | ||
357 | The number of source bits to preserve, @var{n}, is encoded as a single | |
358 | byte unsigned integer following the @code{zero_ext} bytecode. | |
359 | ||
360 | @item @code{ref8} (0x17): @var{addr} @result{} @var{a} | |
361 | @itemx @code{ref16} (0x18): @var{addr} @result{} @var{a} | |
362 | @itemx @code{ref32} (0x19): @var{addr} @result{} @var{a} | |
363 | @itemx @code{ref64} (0x1a): @var{addr} @result{} @var{a} | |
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 | |
367 | integer. | |
368 | ||
369 | Note that @var{addr} may not be aligned in any particular way; the | |
370 | @code{ref@var{n}} bytecodes should operate correctly for any address. | |
371 | ||
372 | If attempting to access memory at @var{addr} would cause a processor | |
373 | exception of some sort, terminate with an error. | |
374 | ||
375 | @item @code{ref_float} (0x1b): @var{addr} @result{} @var{d} | |
376 | @itemx @code{ref_double} (0x1c): @var{addr} @result{} @var{d} | |
377 | @itemx @code{ref_long_double} (0x1d): @var{addr} @result{} @var{d} | |
378 | @itemx @code{l_to_d} (0x1e): @var{a} @result{} @var{d} | |
379 | @itemx @code{d_to_l} (0x1f): @var{d} @result{} @var{a} | |
380 | Not implemented yet. | |
381 | ||
382 | @item @code{dup} (0x28): @var{a} => @var{a} @var{a} | |
383 | Push another copy of the stack's top element. | |
384 | ||
385 | @item @code{swap} (0x2b): @var{a} @var{b} => @var{b} @var{a} | |
386 | Exchange the top two items on the stack. | |
387 | ||
388 | @item @code{pop} (0x29): @var{a} => | |
389 | Discard the top value on the stack. | |
390 | ||
391 | @item @code{if_goto} (0x20) @var{offset}: @var{a} @result{} | |
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. | |
397 | ||
398 | The @var{offset} is stored as a sixteen-bit unsigned value, stored | |
399 | immediately following the @code{if_goto} bytecode. It is always stored | |
400 | most signficant byte first, regardless of the target's normal | |
401 | endianness. The offset is not guaranteed to fall at any particular | |
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 | |
404 | offset one byte at a time. | |
405 | ||
406 | @item @code{goto} (0x21) @var{offset}: @result{} | |
407 | Branch unconditionally to @var{offset}; in other words, set the | |
408 | @code{pc} register to @code{start} + @var{offset}. | |
409 | ||
410 | The offset is stored in the same way as for the @code{if_goto} bytecode. | |
411 | ||
412 | @item @code{const8} (0x22) @var{n}: @result{} @var{n} | |
413 | @itemx @code{const16} (0x23) @var{n}: @result{} @var{n} | |
414 | @itemx @code{const32} (0x24) @var{n}: @result{} @var{n} | |
415 | @itemx @code{const64} (0x25) @var{n}: @result{} @var{n} | |
416 | Push the integer constant @var{n} on the stack, without sign extension. | |
417 | To produce a small negative value, push a small twos-complement value, | |
418 | and then sign-extend it using the @code{ext} bytecode. | |
419 | ||
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 | |
423 | normal endianness. The constant is not guaranteed to fall at any | |
424 | particular alignment within the bytecode stream; thus, on machines where | |
425 | fetching a 16-bit on an unaligned address raises an exception, you | |
426 | should fetch @var{n} one byte at a time. | |
427 | ||
428 | @item @code{reg} (0x26) @var{n}: @result{} @var{a} | |
429 | Push the value of register number @var{n}, without sign extension. The | |
430 | registers are numbered following GDB's conventions. | |
431 | ||
432 | The register number @var{n} is encoded as a 16-bit unsigned integer | |
433 | immediately following the @code{reg} bytecode. It is always stored most | |
434 | signficant byte first, regardless of the target's normal endianness. | |
435 | The register number is not guaranteed to fall at any particular | |
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 | |
438 | register number one byte at a time. | |
439 | ||
440 | @item @code{trace} (0x0c): @var{addr} @var{size} @result{} | |
441 | Record the contents of the @var{size} bytes at @var{addr} in a trace | |
442 | buffer, for later retrieval by GDB. | |
443 | ||
444 | @item @code{trace_quick} (0x0d) @var{size}: @var{addr} @result{} @var{addr} | |
445 | Record the contents of the @var{size} bytes at @var{addr} in a trace | |
446 | buffer, for later retrieval by GDB. @var{size} is a single byte | |
447 | unsigned integer following the @code{trace} opcode. | |
448 | ||
449 | This bytecode is equivalent to the sequence @code{dup const8 @var{size} | |
450 | trace}, but we provide it anyway to save space in bytecode strings. | |
451 | ||
452 | @item @code{trace16} (0x30) @var{size}: @var{addr} @result{} @var{addr} | |
453 | Identical to trace_quick, except that @var{size} is a 16-bit big-endian | |
454 | unsigned integer, not a single byte. This should probably have been | |
455 | named @code{trace_quick16}, for consistency. | |
456 | ||
457 | @item @code{end} (0x27): @result{} | |
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. | |
462 | ||
463 | @end table | |
464 | ||
465 | ||
466 | @node Using Agent Expressions | |
467 | @section Using Agent Expressions | |
468 | ||
469 | Here is a sketch of a full non-stop debugging cycle, showing how agent | |
470 | expressions fit into the process. | |
471 | ||
472 | @itemize @bullet | |
473 | ||
474 | @item | |
475 | The user selects trace points in the program's code at which GDB should | |
476 | collect data. | |
477 | ||
478 | @item | |
479 | The user specifies expressions to evaluate at each trace point. These | |
480 | expressions may denote objects in memory, in which case those objects' | |
481 | contents are recorded as the program runs, or computed values, in which | |
482 | case the values themselves are recorded. | |
483 | ||
484 | @item | |
485 | GDB transmits the tracepoints and their associated expressions to the | |
486 | GDB agent, running on the debugging target. | |
487 | ||
488 | @item | |
489 | The agent arranges to be notified when a trace point is hit. Note that, | |
490 | on some systems, the target operating system is completely responsible | |
491 | for collecting the data; see @ref{Tracing on Symmetrix}. | |
492 | ||
493 | @item | |
494 | When execution on the target reaches a trace point, the agent evaluates | |
495 | the expressions associated with that trace point, and records the | |
496 | resulting values and memory ranges. | |
497 | ||
498 | @item | |
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 | |
502 | user asks to see an object whose contents have not been recorded, GDB | |
503 | reports an error. | |
504 | ||
505 | @end itemize | |
506 | ||
507 | ||
508 | @node Varying Target Capabilities | |
509 | @section Varying Target Capabilities | |
510 | ||
511 | Some targets don't support floating-point, and some would rather not | |
512 | have to deal with @code{long long} operations. Also, different targets | |
513 | will have different stack sizes, and different bytecode buffer lengths. | |
514 | ||
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 | |
517 | target a packet asking it to describe itself. The reply should be a | |
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 | |
520 | of GDB, and it should contain a version number. It should contain at | |
521 | least the following information: | |
522 | ||
523 | @itemize @bullet | |
524 | ||
525 | @item | |
526 | whether floating point is supported | |
527 | ||
528 | @item | |
529 | whether @code{long long} is supported | |
530 | ||
531 | @item | |
532 | maximum acceptable size of bytecode stack | |
533 | ||
534 | @item | |
535 | maximum acceptable length of bytecode expressions | |
536 | ||
537 | @item | |
538 | which registers are actually available for collection | |
539 | ||
540 | @item | |
541 | whether the target supports disabled tracepoints | |
542 | ||
543 | @end itemize | |
544 | ||
545 | ||
546 | ||
547 | @node Tracing on Symmetrix | |
548 | @section Tracing on Symmetrix | |
549 | ||
550 | This section documents the API used by the GDB agent to collect data on | |
551 | Symmetrix systems. | |
552 | ||
553 | Cygnus originally implemented these tracing features to help EMC | |
554 | Corporation debug their Symmetrix high-availability disk drives. The | |
555 | Symmetrix application code already includes substantial tracing | |
556 | facilities; the GDB agent for the Symmetrix system uses those facilities | |
557 | for its own data collection, via the API described here. | |
558 | ||
559 | @deftypefn Function DTC_RESPONSE adbg_find_memory_in_frame (FRAME_DEF *@var{frame}, char *@var{address}, char **@var{buffer}, unsigned int *@var{size}) | |
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. | |
563 | ||
564 | @itemize @bullet | |
565 | ||
566 | @item | |
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} | |
570 | that are saved at @code{*@var{buffer}}, and return | |
571 | @code{OK_TARGET_RESPONSE}. (Clearly, in this case, the function will | |
572 | always set @code{*@var{size}} to a value greater than zero.) | |
573 | ||
574 | @item | |
575 | If @var{frame} does not record any memory at @var{address}, set | |
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 | |
578 | there is no memory saved from any higher address, set @code{*@var{size}} | |
579 | to zero. Return @code{NOT_FOUND_TARGET_RESPONSE}. | |
580 | @end itemize | |
581 | ||
582 | These two possibilities allow the caller to either retrieve the data, or | |
583 | walk the address space to the next saved area. | |
584 | @end deftypefn | |
585 | ||
586 | This function allows the GDB agent to map the regions of memory saved in | |
587 | a particular frame, and retrieve their contents efficiently. | |
588 | ||
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 | |
596 | mechanism, but as long as this function works properly, all collected | |
597 | memory is visible to GDB. | |
598 | ||
599 | The function itself is straightforward to implement. A single pass over | |
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. | |
604 | ||
605 | As an example, suppose the trace frame @code{f} has saved sixteen bytes | |
606 | from address @code{0x8000} in a buffer at @code{0x1000}, and thirty-two | |
607 | bytes from address @code{0xc000} in a buffer at @code{0x1010}. Here are | |
608 | some sample calls, and the effect each would have: | |
609 | ||
610 | @table @code | |
611 | ||
612 | @item adbg_find_memory_in_frame (f, (char*) 0x8000, &buffer, &size) | |
613 | This would set @code{buffer} to @code{0x1000}, set @code{size} to | |
614 | sixteen, and return @code{OK_TARGET_RESPONSE}, since @code{f} saves | |
615 | sixteen bytes from @code{0x8000} at @code{0x1000}. | |
616 | ||
617 | @item adbg_find_memory_in_frame (f, (char *) 0x8004, &buffer, &size) | |
618 | This would set @code{buffer} to @code{0x1004}, set @code{size} to | |
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. | |
624 | ||
625 | @item adbg_find_memory_in_frame (f, (char *) 0x8100, &buffer, &size) | |
626 | This would set @code{size} to @code{0x3f00} and return | |
627 | @code{NOT_FOUND_TARGET_RESPONSE}, since there is no memory saved in | |
628 | @code{f} from the address @code{0x8100}, and the next memory available | |
629 | is at @code{0x8100 + 0x3f00}, or @code{0xc000}. This shows that request | |
630 | addresses may fall outside of all saved memory ranges; the function | |
631 | should indicate the next saved area, if any. | |
632 | ||
633 | @item adbg_find_memory_in_frame (f, (char *) 0x7000, &buffer, &size) | |
634 | This would set @code{size} to @code{0x1000} and return | |
635 | @code{NOT_FOUND_TARGET_RESPONSE}, since the next saved memory is at | |
636 | @code{0x7000 + 0x1000}, or @code{0x8000}. | |
637 | ||
638 | @item adbg_find_memory_in_frame (f, (char *) 0xf000, &buffer, &size) | |
639 | This would set @code{size} to zero, and return | |
640 | @code{NOT_FOUND_TARGET_RESPONSE}. This shows how the function tells the | |
641 | caller that no further memory ranges have been saved. | |
642 | ||
643 | @end table | |
644 | ||
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 | |
647 | Symmetrix INLINES console: | |
648 | @example | |
649 | void | |
650 | print_frame_addresses (FRAME_DEF *frame) | |
651 | @{ | |
652 | char *addr; | |
653 | char *buffer; | |
654 | unsigned long size; | |
655 | ||
656 | addr = 0; | |
657 | for (;;) | |
658 | @{ | |
659 | /* Either find out how much memory we have here, or discover | |
660 | where the next saved region is. */ | |
661 | if (adbg_find_memory_in_frame (frame, addr, &buffer, &size) | |
662 | == OK_TARGET_RESPONSE) | |
663 | printp ("saved %x to %x\n", addr, addr + size); | |
664 | if (size == 0) | |
665 | break; | |
666 | addr += size; | |
667 | @} | |
668 | @} | |
669 | @end example | |
670 | ||
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 | |
673 | @code{adbg_find_memory_in_frame} will return those memory ranges. The | |
674 | code above will always print the saved memory regions in order of | |
675 | increasing address, while the underlying frame structure might store the | |
676 | data in a random order. | |
677 | ||
678 | [[This section should cover the rest of the Symmetrix functions the stub | |
679 | relies upon, too.]] | |
680 | ||
681 | @node Rationale | |
682 | @section Rationale | |
683 | ||
684 | Some of the design decisions apparent above are arguable. | |
685 | ||
686 | @table @b | |
687 | ||
688 | @item What about stack overflow/underflow? | |
689 | GDB should be able to query the target to discover its stack size. | |
690 | Given that information, GDB can determine at translation time whether a | |
691 | given expression will overflow the stack. But this spec isn't about | |
692 | what kinds of error-checking GDB ought to do. | |
693 | ||
694 | @item Why are you doing everything in LONGEST? | |
695 | ||
696 | Speed isn't important, but agent code size is; using LONGEST brings in a | |
697 | bunch of support code to do things like division, etc. So this is a | |
698 | serious concern. | |
699 | ||
700 | First, note that you don't need different bytecodes for different | |
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 | |
703 | 32-bit ints, and you don't send any 64-bit bytecodes, everything just | |
704 | works. The observation here is that the MIPS and the Alpha have only | |
705 | fixed-size registers, and you can still get C's semantics even though | |
706 | most instructions only operate on full-sized words. You just need to | |
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. | |
710 | ||
711 | GDB should certainly check to see what sizes the target supports, so the | |
712 | user can get an error earlier, rather than later. But this information | |
713 | is not necessary for correctness. | |
714 | ||
715 | ||
716 | @item Why don't you have @code{>} or @code{<=} operators? | |
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. | |
720 | For example, @code{(x <= y)} is @code{! (x > y)}, which is @code{! (y < | |
721 | x)}. | |
722 | ||
723 | @item Why do you have @code{log_not}? | |
724 | @itemx Why do you have @code{ext}? | |
725 | @itemx Why do you have @code{zero_ext}? | |
726 | These are all easily synthesized from other instructions, but I expect | |
727 | them to be used frequently, and they're simple, so I include them to | |
728 | keep bytecode strings short. | |
729 | ||
730 | @code{log_not} is equivalent to @code{const8 0 equal}; it's used in half | |
731 | the relational operators. | |
732 | ||
733 | @code{ext @var{n}} is equivalent to @code{const8 @var{s-n} lsh const8 | |
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. | |
737 | ||
738 | @code{zero_ext @var{n}} is equivalent to @code{const@var{m} @var{mask} | |
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. | |
741 | ||
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. | |
745 | ||
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 | |
748 | @code{const32 @var{address} ref32} is only one byte longer. | |
749 | ||
750 | @item Why do the @code{ref@var{n}} operators have to support unaligned fetches? | |
751 | GDB will generate bytecode that fetches multi-byte values at unaligned | |
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 | |
755 | fetch will be aligned or not. | |
756 | ||
757 | In particular, structure bitfields may be several bytes long, but follow | |
758 | no alignment rules; members of packed structures are not necessarily | |
759 | aligned either. | |
760 | ||
761 | In general, there are many cases where unaligned references occur in | |
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 | |
764 | bytecodes work correctly in all circumstances than to make GDB guess in | |
765 | each case whether the compiler did the usual thing. | |
766 | ||
767 | @item Why are there no side-effecting operators? | |
768 | Because our current client doesn't want them? That's a cheap answer. I | |
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 | |
771 | delivered. | |
772 | ||
773 | @item Why aren't the @code{goto} ops PC-relative? | |
774 | The interpreter has the base address around anyway for PC bounds | |
775 | checking, and it seemed simpler. | |
776 | ||
777 | @item Why is there only one offset size for the @code{goto} ops? | |
778 | Offsets are currently sixteen bits. I'm not happy with this situation | |
779 | either: | |
780 | ||
781 | Suppose we have multiple branch ops with different offset sizes. As I | |
782 | generate code left-to-right, all my jumps are forward jumps (there are | |
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 | |
786 | like a big waste of time. | |
787 | ||
788 | I can imagine a reasonable expression being longer than 256 bytes. I | |
789 | can't imagine one being longer than 64k. Thus, we need 16-bit offsets. | |
790 | This kind of reasoning is so bogus, but relaxation is pathetic. | |
791 | ||
792 | The other approach would be to generate code right-to-left. Then I'd | |
793 | always know my offset size. That might be fun. | |
794 | ||
795 | @item Where is the function call bytecode? | |
796 | ||
797 | When we add side-effects, we should add this. | |
798 | ||
799 | @item Why does the @code{reg} bytecode take a 16-bit register number? | |
800 | ||
801 | Intel's IA64-architecture, Merced, has 128 general-purpose registers, | |
802 | and 128 floating-point registers, and I'm sure it has some random | |
803 | control registers. | |
804 | ||
805 | @item Why do we need @code{trace} and @code{trace_quick}? | |
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}. | |
810 | ||
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 | |
815 | its way. | |
816 | ||
817 | @item Why doesn't @code{trace_quick} consume its arguments the way everything else does? | |
818 | In general, you do want your operators to consume their arguments; it's | |
819 | consistent, and generally reduces the amount of stack rearrangement | |
820 | necessary. However, @code{trace_quick} is a kludge to save space; it | |
821 | only exists so we needn't write @code{dup const8 @var{SIZE} trace} | |
822 | before every memory reference. Therefore, it's okay for it not to | |
823 | consume its arguments; it's meant for a specific context in which we | |
824 | know exactly what it should do with the stack. If we're going to have a | |
825 | kludge, it should be an effective kludge. | |
826 | ||
827 | @item Why does @code{trace16} exist? | |
828 | That opcode was added by the customer that contracted Cygnus for the | |
829 | data tracing work. I personally think it is unnecessary; objects that | |
830 | large will be quite rare, so it is okay to use @code{dup const16 | |
831 | @var{size} trace} in those cases. | |
832 | ||
833 | Whatever we decide to do with @code{trace16}, we should at least leave | |
834 | opcode 0x30 reserved, to remain compatible with the customer who added | |
835 | it. | |
836 | ||
837 | @end table | |
838 | ||
839 | @bye |