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