1 /* Definitions for dealing with stack frames, for GDB, the GNU debugger.
3 Copyright 1986, 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1996,
4 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
6 This file is part of GDB.
8 This program is free software; you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation; either version 2 of the License, or
11 (at your option) any later version.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
18 You should have received a copy of the GNU General Public License
19 along with this program; if not, write to the Free Software
20 Foundation, Inc., 59 Temple Place - Suite 330,
21 Boston, MA 02111-1307, USA. */
23 #if !defined (FRAME_H)
26 struct symtab_and_line
;
28 /* The frame object. */
32 /* The frame object's ID. This provides a per-frame unique identifier
33 that can be used to relocate a `struct frame_info' after a target
34 resume or a frame cache destruct (assuming the target hasn't
35 unwound the stack past that frame - a problem handled elsewhere). */
39 /* The frame's address. This should be constant through out the
40 lifetime of a frame. */
41 /* NOTE: cagney/2002-11-16: The ia64 has two stacks and hence two
42 frame bases. This will need to be expanded to accomodate that. */
44 /* The frame's current PC. While the PC within the function may
45 change, the function that contains the PC does not. Should this
46 instead be the frame's function? */
50 /* For every stopped thread, GDB tracks two frames: current and
51 selected. Current frame is the inner most frame of the selected
52 thread. Selected frame is the one being examined by the the GDB
53 CLI (selected using `up', `down', ...). The frames are created
54 on-demand (via get_prev_frame()) and then held in a frame cache. */
55 /* FIXME: cagney/2002-11-28: Er, there is a lie here. If you do the
56 sequence: `thread 1; up; thread 2; thread 1' you loose thread 1's
57 selected frame. At present GDB only tracks the selected frame of
58 the current thread. But be warned, that might change. */
59 /* FIXME: cagney/2002-11-14: At any time, only one thread's selected
60 and current frame can be active. Switching threads causes gdb to
61 discard all that cached frame information. Ulgh! Instead, current
62 and selected frame should be bound to a thread. */
64 /* On demand, create the inner most frame using information found in
65 the inferior. If the inner most frame can't be created, throw an
67 extern struct frame_info
*get_current_frame (void);
69 /* Invalidates the frame cache (this function should have been called
70 invalidate_cached_frames).
72 FIXME: cagney/2002-11-28: The only difference between
73 flush_cached_frames() and reinit_frame_cache() is that the latter
74 explicitly sets the selected frame back to the current frame there
75 isn't any real difference (except that one delays the selection of
76 a new frame). Code can instead simply rely on get_selected_frame()
77 to reinit's the selected frame as needed. As for invalidating the
78 cache, there should be two methods one that reverts the thread's
79 selected frame back to current frame (for when the inferior
80 resumes) and one that does not (for when the user modifies the
81 target invalidating the frame cache). */
82 extern void flush_cached_frames (void);
83 extern void reinit_frame_cache (void);
85 /* On demand, create the selected frame and then return it. If the
86 selected frame can not be created, this function throws an error. */
87 /* FIXME: cagney/2002-11-28: At present, when there is no selected
88 frame, this function always returns the current (inner most) frame.
89 It should instead, when a thread has previously had its frame
90 selected (but not resumed) and the frame cache invalidated, find
91 and then return that thread's previously selected frame. */
92 extern struct frame_info
*get_selected_frame (void);
94 /* Select a specific frame. NULL, apparently implies re-select the
96 extern void select_frame (struct frame_info
*);
98 /* Given a FRAME, return the next (more inner, younger) or previous
99 (more outer, older) frame. */
100 extern struct frame_info
*get_prev_frame (struct frame_info
*);
101 extern struct frame_info
*get_next_frame (struct frame_info
*);
103 /* Given a frame's ID, relocate the frame. Returns NULL if the frame
105 extern struct frame_info
*frame_find_by_id (struct frame_id id
);
107 /* Base attributes of a frame: */
109 /* The frame's `resume' address. Where the program will resume in
111 extern CORE_ADDR
get_frame_pc (struct frame_info
*);
113 /* Closely related to the resume address, various symbol table
114 attributes that are determined by the PC. Note that for a normal
115 frame, the PC refers to the resume address after the return, and
116 not the call instruction. In such a case, the address is adjusted
117 so that it (approximatly) identifies the call site (and not return
120 NOTE: cagney/2002-11-28: The frame cache could be used to cache the
121 computed value. Working on the assumption that the bottle-neck is
122 in the single step code, and that code causes the frame cache to be
123 constantly flushed, caching things in a frame is probably of little
124 benefit. As they say `show us the numbers'.
126 NOTE: cagney/2002-11-28: Plenty more where this one came from:
127 find_frame_block(), find_frame_partial_function(),
128 find_frame_symtab(), find_frame_function(). Each will need to be
129 carefully considered to determine if the real intent was for it to
130 apply to the PC or the adjusted PC. */
131 extern void find_frame_sal (struct frame_info
*frame
,
132 struct symtab_and_line
*sal
);
134 /* Return the frame address from FI. Except in the machine-dependent
135 *FRAME* macros, a frame address has no defined meaning other than
136 as a magic cookie which identifies a frame over calls to the
137 inferior (um, SEE NOTE BELOW). The only known exception is
138 inferior.h (PC_IN_CALL_DUMMY) [ON_STACK]; see comments there. You
139 cannot assume that a frame address contains enough information to
140 reconstruct the frame; if you want more than just to identify the
141 frame (e.g. be able to fetch variables relative to that frame),
142 then save the whole struct frame_info (and the next struct
143 frame_info, since the latter is used for fetching variables on some
144 machines) (um, again SEE NOTE BELOW).
146 NOTE: cagney/2002-11-18: Actually, the frame address isn't
147 sufficient for identifying a frame, and the counter examples are
150 Code that needs to (re)identify a frame must use get_frame_id() and
151 frame_find_by_id() (and in the future, a frame_compare() function
152 instead of INNER_THAN()). Two reasons: an architecture (e.g.,
153 ia64) can have more than one frame address (due to multiple stack
154 pointers) (frame ID is going to be expanded to accomodate this);
155 successive frameless function calls can only be differientated by
156 comparing both the frame's base and the frame's enclosing function
157 (frame_find_by_id() is going to be modified to perform this test).
159 The generic dummy frame version of PC_IN_CALL_DUMMY() is able to
160 identify a dummy frame using only the PC value. So the frame
161 address is not needed. In fact, most PC_IN_CALL_DUMMY() calls now
162 pass zero as the frame/sp values as the caller knows that those
163 values won't be used. Once all architectures are using generic
164 dummy frames, PC_IN_CALL_DUMMY() can drop the sp/frame parameters.
165 When it comes to finding a dummy frame, the next frame's frame ID
166 (with out duing an unwind) can be used (ok, could if it wasn't for
167 the need to change the way the PPC defined frame base in a strange
170 Modern architectures should be using something like dwarf2's
171 location expression to describe where a variable lives. Such
172 expressions specify their own debug info centric frame address.
173 Consequently, a generic frame address is pretty meaningless. */
175 extern CORE_ADDR
get_frame_base (struct frame_info
*);
177 /* Return the per-frame unique identifer. Can be used to relocate a
178 frame after a frame cache flush (and other similar operations). */
179 extern void get_frame_id (struct frame_info
*fi
, struct frame_id
*id
);
181 /* The frame's level: 0 for innermost, 1 for its caller, ...; or -1
182 for an invalid frame). */
183 extern int frame_relative_level (struct frame_info
*fi
);
185 /* Return the frame's type. Some are real, some are signal
186 trampolines, and some are completly artificial (dummy). */
190 /* A true stack frame, created by the target program during normal
193 /* A fake frame, created by GDB when performing an inferior function
196 /* In a signal handler, various OSs handle this in various ways.
197 The main thing is that the frame may be far from normal. */
200 extern enum frame_type
get_frame_type (struct frame_info
*);
202 /* FIXME: cagney/2002-11-10: Some targets want to directly mark a
203 frame as being of a specific type. This shouldn't be necessary.
204 PC_IN_SIGTRAMP() indicates a SIGTRAMP_FRAME and PC_IN_CALL_DUMMY()
205 indicates a DUMMY_FRAME. I suspect the real problem here is that
206 get_prev_frame() only sets initialized after INIT_EXTRA_FRAME_INFO
207 as been called. Consequently, some targets found that the frame's
208 type was wrong and tried to fix it. The correct fix is to modify
209 get_prev_frame() so that it initializes the frame's type before
210 calling any other functions. */
211 extern void deprecated_set_frame_type (struct frame_info
*,
212 enum frame_type type
);
214 /* Unwind the stack frame so that the value of REGNUM, in the previous
215 (up, older) frame is returned. If VALUEP is NULL, don't
216 fetch/compute the value. Instead just return the location of the
218 extern void frame_register_unwind (struct frame_info
*frame
, int regnum
,
219 int *optimizedp
, enum lval_type
*lvalp
,
220 CORE_ADDR
*addrp
, int *realnump
,
223 /* More convenient interface to frame_register_unwind(). */
224 /* NOTE: cagney/2002-09-13: Return void as one day these functions may
225 be changed to return an indication that the read succeeded. */
227 extern void frame_unwind_signed_register (struct frame_info
*frame
,
228 int regnum
, LONGEST
*val
);
230 extern void frame_unwind_unsigned_register (struct frame_info
*frame
,
231 int regnum
, ULONGEST
*val
);
233 /* Get the value of the register that belongs to this FRAME. This
234 function is a wrapper to the call sequence ``frame_unwind_register
235 (get_next_frame (FRAME))''. As per frame_register_unwind(), if
236 VALUEP is NULL, the registers value is not fetched/computed. */
238 extern void frame_register (struct frame_info
*frame
, int regnum
,
239 int *optimizedp
, enum lval_type
*lvalp
,
240 CORE_ADDR
*addrp
, int *realnump
,
243 /* More convenient interface to frame_register(). */
244 /* NOTE: cagney/2002-09-13: Return void as one day these functions may
245 be changed to return an indication that the read succeeded. */
247 extern void frame_read_signed_register (struct frame_info
*frame
,
248 int regnum
, LONGEST
*val
);
250 extern void frame_read_unsigned_register (struct frame_info
*frame
,
251 int regnum
, ULONGEST
*val
);
253 /* Map between a frame register number and its name. A frame register
254 space is a superset of the cooked register space --- it also
255 includes builtin registers. */
257 extern int frame_map_name_to_regnum (const char *name
, int strlen
);
258 extern const char *frame_map_regnum_to_name (int regnum
);
260 /* Unwind the PC. Strictly speaking return the resume address of the
261 calling frame. For GDB, `pc' is the resume address and not a
262 specific register. */
264 extern CORE_ADDR
frame_pc_unwind (struct frame_info
*frame
);
267 /* Return the location (and possibly value) of REGNUM for the previous
268 (older, up) frame. All parameters except VALUEP can be assumed to
269 be non NULL. When VALUEP is NULL, just the location of the
270 register should be returned.
272 UNWIND_CACHE is provided as mechanism for implementing a per-frame
273 local cache. It's initial value being NULL. Memory for that cache
274 should be allocated using frame_obstack_alloc().
276 Register window architectures (eg SPARC) should note that REGNUM
277 identifies the register for the previous frame. For instance, a
278 request for the value of "o1" for the previous frame would be found
279 in the register "i1" in this FRAME. */
281 typedef void (frame_register_unwind_ftype
) (struct frame_info
*frame
,
285 enum lval_type
*lvalp
,
290 /* Same as for registers above, but return the address at which the
291 calling frame would resume. */
293 typedef CORE_ADDR (frame_pc_unwind_ftype
) (struct frame_info
*frame
,
294 void **unwind_cache
);
296 /* Describe the saved registers of a frame. */
298 #if defined (EXTRA_FRAME_INFO) || defined (FRAME_FIND_SAVED_REGS)
299 /* XXXX - deprecated */
300 struct frame_saved_regs
302 /* For each register R (except the SP), regs[R] is the address at
303 which it was saved on entry to the frame, or zero if it was not
304 saved on entry to this frame. This includes special registers
305 such as pc and fp saved in special ways in the stack frame.
307 regs[SP_REGNUM] is different. It holds the actual SP, not the
308 address at which it was saved. */
310 CORE_ADDR regs
[NUM_REGS
];
314 /* We keep a cache of stack frames, each of which is a "struct
315 frame_info". The innermost one gets allocated (in
316 wait_for_inferior) each time the inferior stops; current_frame
317 points to it. Additional frames get allocated (in
318 get_prev_frame) as needed, and are chained through the next
319 and prev fields. Any time that the frame cache becomes invalid
320 (most notably when we execute something, but also if we change how
321 we interpret the frames (e.g. "set heuristic-fence-post" in
322 mips-tdep.c, or anything which reads new symbols)), we should call
323 reinit_frame_cache. */
327 /* Nominal address of the frame described. See comments at
328 get_frame_base() about what this means outside the *FRAME*
329 macros; in the *FRAME* macros, it can mean whatever makes most
330 sense for this machine. */
333 /* Address at which execution is occurring in this frame.
334 For the innermost frame, it's the current pc.
335 For other frames, it is a pc saved in the next frame. */
338 /* Level of this frame. The inner-most (youngest) frame is at
339 level 0. As you move towards the outer-most (oldest) frame,
340 the level increases. This is a cached value. It could just as
341 easily be computed by counting back from the selected frame to
342 the inner most frame. */
343 /* NOTE: cagney/2002-04-05: Perhaphs a level of ``-1'' should be
344 reserved to indicate a bogus frame - one that has been created
345 just to keep GDB happy (GDB always needs a frame). For the
346 moment leave this as speculation. */
349 /* The frame's type. */
350 enum frame_type type
;
352 /* For each register, address of where it was saved on entry to
353 the frame, or zero if it was not saved on entry to this frame.
354 This includes special registers such as pc and fp saved in
355 special ways in the stack frame. The SP_REGNUM is even more
356 special, the address here is the sp for the previous frame, not
357 the address where the sp was saved. */
358 /* Allocated by frame_saved_regs_zalloc () which is called /
359 initialized by FRAME_INIT_SAVED_REGS(). */
360 CORE_ADDR
*saved_regs
; /*NUM_REGS + NUM_PSEUDO_REGS*/
362 #ifdef EXTRA_FRAME_INFO
363 /* XXXX - deprecated */
364 /* Anything extra for this structure that may have been defined
365 in the machine dependent files. */
369 /* Anything extra for this structure that may have been defined
370 in the machine dependent files. */
371 /* Allocated by frame_obstack_alloc () which is called /
372 initialized by INIT_EXTRA_FRAME_INFO */
373 struct frame_extra_info
*extra_info
;
375 /* If dwarf2 unwind frame informations is used, this structure holds all
376 related unwind data. */
377 struct context
*context
;
379 /* Unwind cache shared between the unwind functions - they had
380 better all agree as to the contents. */
383 /* See description above. The previous frame's registers. */
384 frame_register_unwind_ftype
*register_unwind
;
386 /* See description above. The previous frame's resume address.
387 Save the previous PC in a local cache. */
388 frame_pc_unwind_ftype
*pc_unwind
;
389 int pc_unwind_cache_p
;
390 CORE_ADDR pc_unwind_cache
;
392 /* Pointers to the next (down, inner, younger) and previous (up,
393 outer, older) frame_info's in the frame cache. */
394 struct frame_info
*next
; /* down, inner, younger */
396 struct frame_info
*prev
; /* up, outer, older */
399 /* Values for the source flag to be used in print_frame_info_base(). */
402 /* Print only the source line, like in stepi. */
404 /* Print only the location, i.e. level, address (sometimes)
405 function, args, file, line, line num. */
407 /* Print both of the above. */
409 /* Print location only, but always include the address. */
413 /* Allocate additional space for appendices to a struct frame_info.
414 NOTE: Much of GDB's code works on the assumption that the allocated
415 saved_regs[] array is the size specified below. If you try to make
416 that array smaller, GDB will happily walk off its end. */
418 #ifdef SIZEOF_FRAME_SAVED_REGS
419 #error "SIZEOF_FRAME_SAVED_REGS can not be re-defined"
421 #define SIZEOF_FRAME_SAVED_REGS \
422 (sizeof (CORE_ADDR) * (NUM_REGS+NUM_PSEUDO_REGS))
424 extern void *frame_obstack_alloc (unsigned long size
);
425 extern void frame_saved_regs_zalloc (struct frame_info
*);
427 /* Define a default FRAME_CHAIN_VALID, in the form that is suitable for most
428 targets. If FRAME_CHAIN_VALID returns zero it means that the given frame
429 is the outermost one and has no caller.
431 XXXX - both default and alternate frame_chain_valid functions are
432 deprecated. New code should use dummy frames and one of the
433 generic functions. */
435 extern int file_frame_chain_valid (CORE_ADDR
, struct frame_info
*);
436 extern int func_frame_chain_valid (CORE_ADDR
, struct frame_info
*);
437 extern int nonnull_frame_chain_valid (CORE_ADDR
, struct frame_info
*);
438 extern int generic_file_frame_chain_valid (CORE_ADDR
, struct frame_info
*);
439 extern int generic_func_frame_chain_valid (CORE_ADDR
, struct frame_info
*);
440 extern void generic_save_dummy_frame_tos (CORE_ADDR sp
);
444 #ifdef FRAME_FIND_SAVED_REGS
445 /* XXX - deprecated */
446 #define FRAME_INIT_SAVED_REGS(FI) get_frame_saved_regs (FI, NULL)
447 extern void get_frame_saved_regs (struct frame_info
*,
448 struct frame_saved_regs
*);
451 extern struct block
*get_frame_block (struct frame_info
*,
452 CORE_ADDR
*addr_in_block
);
454 /* Return the `struct block' that belongs to the selected thread's
455 selected frame. If the inferior has no state, return NULL.
457 NOTE: cagney/2002-11-29:
459 No state? Does the inferior have any execution state (a core file
460 does, an executable does not). At present the code tests
461 `target_has_stack' but I'm left wondering if it should test
462 `target_has_registers' or, even, a merged target_has_state.
464 Should it look at the most recently specified SAL? If the target
465 has no state, should this function try to extract a block from the
466 most recently selected SAL? That way `list foo' would give it some
467 sort of reference point. Then again, perhaphs that would confuse
470 Calls to this function can be broken down into two categories: Code
471 that uses the selected block as an additional, but optional, data
472 point; Code that uses the selected block as a prop, when it should
473 have the relevant frame/block/pc explicitly passed in.
475 The latter can be eliminated by correctly parameterizing the code,
476 the former though is more interesting. Per the "address" command,
477 it occures in the CLI code and makes it possible for commands to
478 work, even when the inferior has no state. */
480 extern struct block
*get_selected_block (CORE_ADDR
*addr_in_block
);
482 extern struct symbol
*get_frame_function (struct frame_info
*);
484 extern CORE_ADDR
frame_address_in_block (struct frame_info
*);
486 extern CORE_ADDR
get_pc_function_start (CORE_ADDR
);
488 extern struct block
*block_for_pc (CORE_ADDR
);
490 extern struct block
*block_for_pc_sect (CORE_ADDR
, asection
*);
492 extern int frameless_look_for_prologue (struct frame_info
*);
494 extern void print_frame_args (struct symbol
*, struct frame_info
*,
495 int, struct ui_file
*);
497 extern struct frame_info
*find_relative_frame (struct frame_info
*, int *);
499 extern void show_and_print_stack_frame (struct frame_info
*fi
, int level
,
502 extern void print_stack_frame (struct frame_info
*, int, int);
504 extern void print_only_stack_frame (struct frame_info
*, int, int);
506 extern void show_stack_frame (struct frame_info
*);
508 extern void print_frame_info (struct frame_info
*, int, int, int);
510 extern void show_frame_info (struct frame_info
*, int, int, int);
512 extern struct frame_info
*block_innermost_frame (struct block
*);
514 /* NOTE: cagney/2002-09-13: There is no need for this function.
515 Instead either of frame_unwind_signed_register() or
516 frame_unwind_unsigned_register() can be used. */
517 extern CORE_ADDR
deprecated_read_register_dummy (CORE_ADDR pc
,
519 extern void generic_push_dummy_frame (void);
520 extern void generic_pop_current_frame (void (*)(struct frame_info
*));
521 extern void generic_pop_dummy_frame (void);
523 extern int generic_pc_in_call_dummy (CORE_ADDR pc
,
524 CORE_ADDR sp
, CORE_ADDR fp
);
526 /* NOTE: cagney/2002-06-26: Targets should no longer use this
527 function. Instead, the contents of a dummy frames registers can be
528 obtained by applying: frame_register_unwind to the dummy frame; or
529 get_saved_register to the next outer frame. */
531 extern char *deprecated_generic_find_dummy_frame (CORE_ADDR pc
, CORE_ADDR fp
);
533 extern void generic_fix_call_dummy (char *dummy
, CORE_ADDR pc
, CORE_ADDR fun
,
534 int nargs
, struct value
**args
,
535 struct type
*type
, int gcc_p
);
537 /* The function generic_get_saved_register() has been made obsolete.
538 GET_SAVED_REGISTER now defaults to the recursive equivalent -
539 generic_unwind_get_saved_register() - so there is no need to even
540 set GET_SAVED_REGISTER. Architectures that need to override the
541 register unwind mechanism should modify frame->unwind(). */
542 extern void deprecated_generic_get_saved_register (char *, int *, CORE_ADDR
*,
543 struct frame_info
*, int,
546 extern void generic_save_call_dummy_addr (CORE_ADDR lo
, CORE_ADDR hi
);
548 extern void get_saved_register (char *raw_buffer
, int *optimized
,
550 struct frame_info
*frame
,
551 int regnum
, enum lval_type
*lval
);
553 extern int frame_register_read (struct frame_info
*frame
, int regnum
,
557 extern void args_info (char *, int);
559 extern void locals_info (char *, int);
561 extern void (*selected_frame_level_changed_hook
) (int);
563 extern void return_command (char *, int);
566 /* NOTE: cagney/2002-11-27:
568 You might think that the below global can simply be replaced by a
569 call to either get_selected_frame() or select_frame().
571 Unfortunatly, it isn't that easy.
573 The relevant code needs to be audited to determine if it is
574 possible (or pratical) to instead pass the applicable frame in as a
575 parameter. For instance, DEPRECATED_DO_REGISTERS_INFO() relied on
576 the deprecated_selected_frame global, while its replacement,
577 PRINT_REGISTERS_INFO(), is parameterized with the selected frame.
578 The only real exceptions occure at the edge (in the CLI code) where
579 user commands need to pick up the selected frame before proceeding.
581 This is important. GDB is trying to stamp out the hack:
583 saved_frame = deprecated_selected_frame;
584 deprecated_selected_frame = ...;
585 hack_using_global_selected_frame ();
586 deprecated_selected_frame = saved_frame;
590 extern struct frame_info
*deprecated_selected_frame
;
593 /* NOTE: cagney/2002-11-28:
595 These functions are used to explicitly create and set the inner
596 most (current) frame vis:
598 set_current_frame (create_new_frame (read_fp(), stop_pc)));
600 Such code should be removed. Instead that task can be left to
601 get_current_frame() which will update things on-demand.
603 The only vague exception is found in "infcmd.c" (and a few
604 architectures specific files) as part of the code implementing the
605 command ``(gdb) frame FRAME PC''. There, the frame should be
606 created/selected in a single shot. */
608 extern void set_current_frame (struct frame_info
*);
609 extern struct frame_info
*create_new_frame (CORE_ADDR
, CORE_ADDR
);
611 #endif /* !defined (FRAME_H) */