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). There should instead be a get_selected_frame()
77 method that reinit's the frame cache on-demand. As for
78 invalidating the cache, there should be two methods one that
79 reverts the thread's selected frame back to current frame (for when
80 the inferior resumes) and one that does not (for when the user
81 modifies the target invalidating the frame cache). */
82 extern void flush_cached_frames (void);
83 extern void reinit_frame_cache (void);
85 /* Select a specific frame. NULL, apparently implies re-select the
87 extern void select_frame (struct frame_info *);
89 /* Given a FRAME, return the next (more inner, younger) or previous
90 (more outer, older) frame. */
91 extern struct frame_info *get_prev_frame (struct frame_info *);
92 extern struct frame_info *get_next_frame (struct frame_info *);
94 /* Given a frame's ID, relocate the frame. Returns NULL if the frame
96 extern struct frame_info *frame_find_by_id (struct frame_id id);
98 /* Base attributes of a frame: */
100 /* The frame's `resume' address. Where the program will resume in
102 extern CORE_ADDR get_frame_pc (struct frame_info *);
104 /* Closely related to the resume address, various symbol table
105 attributes that are determined by the PC. Note that for a normal
106 frame, the PC refers to the resume address after the return, and
107 not the call instruction. In such a case, the address is adjusted
108 so that it (approximatly) identifies the call site (and not return
111 NOTE: cagney/2002-11-28: The frame cache could be used to cache the
112 computed value. Working on the assumption that the bottle-neck is
113 in the single step code, and that code causes the frame cache to be
114 constantly flushed, caching things in a frame is probably of little
115 benefit. As they say `show us the numbers'.
117 NOTE: cagney/2002-11-28: Plenty more where this one came from:
118 find_frame_block(), find_frame_partial_function(),
119 find_frame_symtab(), find_frame_function(). Each will need to be
120 carefully considered to determine if the real intent was for it to
121 apply to the PC or the adjusted PC. */
122 extern void find_frame_sal (struct frame_info *frame,
123 struct symtab_and_line *sal);
125 /* Return the frame address from FI. Except in the machine-dependent
126 *FRAME* macros, a frame address has no defined meaning other than
127 as a magic cookie which identifies a frame over calls to the
128 inferior (um, SEE NOTE BELOW). The only known exception is
129 inferior.h (PC_IN_CALL_DUMMY) [ON_STACK]; see comments there. You
130 cannot assume that a frame address contains enough information to
131 reconstruct the frame; if you want more than just to identify the
132 frame (e.g. be able to fetch variables relative to that frame),
133 then save the whole struct frame_info (and the next struct
134 frame_info, since the latter is used for fetching variables on some
135 machines) (um, again SEE NOTE BELOW).
137 NOTE: cagney/2002-11-18: Actually, the frame address isn't
138 sufficient for identifying a frame, and the counter examples are
141 Code that needs to (re)identify a frame must use get_frame_id() and
142 frame_find_by_id() (and in the future, a frame_compare() function
143 instead of INNER_THAN()). Two reasons: an architecture (e.g.,
144 ia64) can have more than one frame address (due to multiple stack
145 pointers) (frame ID is going to be expanded to accomodate this);
146 successive frameless function calls can only be differientated by
147 comparing both the frame's base and the frame's enclosing function
148 (frame_find_by_id() is going to be modified to perform this test).
150 The generic dummy frame version of PC_IN_CALL_DUMMY() is able to
151 identify a dummy frame using only the PC value. So the frame
152 address is not needed. In fact, most PC_IN_CALL_DUMMY() calls now
153 pass zero as the frame/sp values as the caller knows that those
154 values won't be used. Once all architectures are using generic
155 dummy frames, PC_IN_CALL_DUMMY() can drop the sp/frame parameters.
156 When it comes to finding a dummy frame, the next frame's frame ID
157 (with out duing an unwind) can be used (ok, could if it wasn't for
158 the need to change the way the PPC defined frame base in a strange
161 Modern architectures should be using something like dwarf2's
162 location expression to describe where a variable lives. Such
163 expressions specify their own debug info centric frame address.
164 Consequently, a generic frame address is pretty meaningless. */
166 extern CORE_ADDR get_frame_base (struct frame_info *);
168 /* Return the per-frame unique identifer. Can be used to relocate a
169 frame after a frame cache flush (and other similar operations). */
170 extern void get_frame_id (struct frame_info *fi, struct frame_id *id);
172 /* The frame's level: 0 for innermost, 1 for its caller, ...; or -1
173 for an invalid frame). */
174 extern int frame_relative_level (struct frame_info *fi);
176 /* Return the frame's type. Some are real, some are signal
177 trampolines, and some are completly artificial (dummy). */
181 /* A true stack frame, created by the target program during normal
184 /* A fake frame, created by GDB when performing an inferior function
187 /* In a signal handler, various OSs handle this in various ways.
188 The main thing is that the frame may be far from normal. */
191 extern enum frame_type get_frame_type (struct frame_info *);
193 /* FIXME: cagney/2002-11-10: Some targets want to directly mark a
194 frame as being of a specific type. This shouldn't be necessary.
195 PC_IN_SIGTRAMP() indicates a SIGTRAMP_FRAME and PC_IN_CALL_DUMMY()
196 indicates a DUMMY_FRAME. I suspect the real problem here is that
197 get_prev_frame() only sets initialized after INIT_EXTRA_FRAME_INFO
198 as been called. Consequently, some targets found that the frame's
199 type was wrong and tried to fix it. The correct fix is to modify
200 get_prev_frame() so that it initializes the frame's type before
201 calling any other functions. */
202 extern void deprecated_set_frame_type (struct frame_info *,
203 enum frame_type type);
205 /* Unwind the stack frame so that the value of REGNUM, in the previous
206 (up, older) frame is returned. If VALUEP is NULL, don't
207 fetch/compute the value. Instead just return the location of the
209 extern void frame_register_unwind (struct frame_info *frame, int regnum,
210 int *optimizedp, enum lval_type *lvalp,
211 CORE_ADDR *addrp, int *realnump,
214 /* More convenient interface to frame_register_unwind(). */
215 /* NOTE: cagney/2002-09-13: Return void as one day these functions may
216 be changed to return an indication that the read succeeded. */
218 extern void frame_unwind_signed_register (struct frame_info *frame,
219 int regnum, LONGEST *val);
221 extern void frame_unwind_unsigned_register (struct frame_info *frame,
222 int regnum, ULONGEST *val);
224 /* Get the value of the register that belongs to this FRAME. This
225 function is a wrapper to the call sequence ``frame_unwind_register
226 (get_next_frame (FRAME))''. As per frame_register_unwind(), if
227 VALUEP is NULL, the registers value is not fetched/computed. */
229 extern void frame_register (struct frame_info *frame, int regnum,
230 int *optimizedp, enum lval_type *lvalp,
231 CORE_ADDR *addrp, int *realnump,
234 /* More convenient interface to frame_register(). */
235 /* NOTE: cagney/2002-09-13: Return void as one day these functions may
236 be changed to return an indication that the read succeeded. */
238 extern void frame_read_signed_register (struct frame_info *frame,
239 int regnum, LONGEST *val);
241 extern void frame_read_unsigned_register (struct frame_info *frame,
242 int regnum, ULONGEST *val);
244 /* Map between a frame register number and its name. A frame register
245 space is a superset of the cooked register space --- it also
246 includes builtin registers. */
248 extern int frame_map_name_to_regnum (const char *name, int strlen);
249 extern const char *frame_map_regnum_to_name (int regnum);
251 /* Unwind the PC. Strictly speaking return the resume address of the
252 calling frame. For GDB, `pc' is the resume address and not a
253 specific register. */
255 extern CORE_ADDR frame_pc_unwind (struct frame_info *frame);
258 /* Return the location (and possibly value) of REGNUM for the previous
259 (older, up) frame. All parameters except VALUEP can be assumed to
260 be non NULL. When VALUEP is NULL, just the location of the
261 register should be returned.
263 UNWIND_CACHE is provided as mechanism for implementing a per-frame
264 local cache. It's initial value being NULL. Memory for that cache
265 should be allocated using frame_obstack_alloc().
267 Register window architectures (eg SPARC) should note that REGNUM
268 identifies the register for the previous frame. For instance, a
269 request for the value of "o1" for the previous frame would be found
270 in the register "i1" in this FRAME. */
272 typedef void (frame_register_unwind_ftype) (struct frame_info *frame,
276 enum lval_type *lvalp,
281 /* Same as for registers above, but return the address at which the
282 calling frame would resume. */
284 typedef CORE_ADDR (frame_pc_unwind_ftype) (struct frame_info *frame,
285 void **unwind_cache);
287 /* Describe the saved registers of a frame. */
289 #if defined (EXTRA_FRAME_INFO) || defined (FRAME_FIND_SAVED_REGS)
290 /* XXXX - deprecated */
291 struct frame_saved_regs
293 /* For each register R (except the SP), regs[R] is the address at
294 which it was saved on entry to the frame, or zero if it was not
295 saved on entry to this frame. This includes special registers
296 such as pc and fp saved in special ways in the stack frame.
298 regs[SP_REGNUM] is different. It holds the actual SP, not the
299 address at which it was saved. */
301 CORE_ADDR regs[NUM_REGS];
305 /* We keep a cache of stack frames, each of which is a "struct
306 frame_info". The innermost one gets allocated (in
307 wait_for_inferior) each time the inferior stops; current_frame
308 points to it. Additional frames get allocated (in
309 get_prev_frame) as needed, and are chained through the next
310 and prev fields. Any time that the frame cache becomes invalid
311 (most notably when we execute something, but also if we change how
312 we interpret the frames (e.g. "set heuristic-fence-post" in
313 mips-tdep.c, or anything which reads new symbols)), we should call
314 reinit_frame_cache. */
318 /* Nominal address of the frame described. See comments at
319 get_frame_base() about what this means outside the *FRAME*
320 macros; in the *FRAME* macros, it can mean whatever makes most
321 sense for this machine. */
324 /* Address at which execution is occurring in this frame.
325 For the innermost frame, it's the current pc.
326 For other frames, it is a pc saved in the next frame. */
329 /* Level of this frame. The inner-most (youngest) frame is at
330 level 0. As you move towards the outer-most (oldest) frame,
331 the level increases. This is a cached value. It could just as
332 easily be computed by counting back from the selected frame to
333 the inner most frame. */
334 /* NOTE: cagney/2002-04-05: Perhaphs a level of ``-1'' should be
335 reserved to indicate a bogus frame - one that has been created
336 just to keep GDB happy (GDB always needs a frame). For the
337 moment leave this as speculation. */
340 /* The frame's type. */
341 enum frame_type type;
343 /* For each register, address of where it was saved on entry to
344 the frame, or zero if it was not saved on entry to this frame.
345 This includes special registers such as pc and fp saved in
346 special ways in the stack frame. The SP_REGNUM is even more
347 special, the address here is the sp for the previous frame, not
348 the address where the sp was saved. */
349 /* Allocated by frame_saved_regs_zalloc () which is called /
350 initialized by FRAME_INIT_SAVED_REGS(). */
351 CORE_ADDR *saved_regs; /*NUM_REGS + NUM_PSEUDO_REGS*/
353 #ifdef EXTRA_FRAME_INFO
354 /* XXXX - deprecated */
355 /* Anything extra for this structure that may have been defined
356 in the machine dependent files. */
360 /* Anything extra for this structure that may have been defined
361 in the machine dependent files. */
362 /* Allocated by frame_obstack_alloc () which is called /
363 initialized by INIT_EXTRA_FRAME_INFO */
364 struct frame_extra_info *extra_info;
366 /* If dwarf2 unwind frame informations is used, this structure holds all
367 related unwind data. */
368 struct context *context;
370 /* Unwind cache shared between the unwind functions - they had
371 better all agree as to the contents. */
374 /* See description above. The previous frame's registers. */
375 frame_register_unwind_ftype *register_unwind;
377 /* See description above. The previous frame's resume address.
378 Save the previous PC in a local cache. */
379 frame_pc_unwind_ftype *pc_unwind;
380 int pc_unwind_cache_p;
381 CORE_ADDR pc_unwind_cache;
383 /* Pointers to the next (down, inner, younger) and previous (up,
384 outer, older) frame_info's in the frame cache. */
385 struct frame_info *next; /* down, inner, younger */
387 struct frame_info *prev; /* up, outer, older */
390 /* Values for the source flag to be used in print_frame_info_base(). */
393 /* Print only the source line, like in stepi. */
395 /* Print only the location, i.e. level, address (sometimes)
396 function, args, file, line, line num. */
398 /* Print both of the above. */
400 /* Print location only, but always include the address. */
404 /* Allocate additional space for appendices to a struct frame_info.
405 NOTE: Much of GDB's code works on the assumption that the allocated
406 saved_regs[] array is the size specified below. If you try to make
407 that array smaller, GDB will happily walk off its end. */
409 #ifdef SIZEOF_FRAME_SAVED_REGS
410 #error "SIZEOF_FRAME_SAVED_REGS can not be re-defined"
412 #define SIZEOF_FRAME_SAVED_REGS \
413 (sizeof (CORE_ADDR) * (NUM_REGS+NUM_PSEUDO_REGS))
415 extern void *frame_obstack_alloc (unsigned long size);
416 extern void frame_saved_regs_zalloc (struct frame_info *);
418 /* Define a default FRAME_CHAIN_VALID, in the form that is suitable for most
419 targets. If FRAME_CHAIN_VALID returns zero it means that the given frame
420 is the outermost one and has no caller.
422 XXXX - both default and alternate frame_chain_valid functions are
423 deprecated. New code should use dummy frames and one of the
424 generic functions. */
426 extern int file_frame_chain_valid (CORE_ADDR, struct frame_info *);
427 extern int func_frame_chain_valid (CORE_ADDR, struct frame_info *);
428 extern int nonnull_frame_chain_valid (CORE_ADDR, struct frame_info *);
429 extern int generic_file_frame_chain_valid (CORE_ADDR, struct frame_info *);
430 extern int generic_func_frame_chain_valid (CORE_ADDR, struct frame_info *);
431 extern void generic_save_dummy_frame_tos (CORE_ADDR sp);
435 #ifdef FRAME_FIND_SAVED_REGS
436 /* XXX - deprecated */
437 #define FRAME_INIT_SAVED_REGS(FI) get_frame_saved_regs (FI, NULL)
438 extern void get_frame_saved_regs (struct frame_info *,
439 struct frame_saved_regs *);
442 extern struct block *get_frame_block (struct frame_info *,
443 CORE_ADDR *addr_in_block);
445 /* Return the `struct block' that belongs to the selected thread's
446 selected frame. If the inferior has no state, return NULL.
448 NOTE: cagney/2002-11-29:
450 No state? Does the inferior have any execution state (a core file
451 does, an executable does not). At present the code tests
452 `target_has_stack' but I'm left wondering if it should test
453 `target_has_registers' or, even, a merged target_has_state.
455 Should it look at the most recently specified SAL? If the target
456 has no state, should this function try to extract a block from the
457 most recently selected SAL? That way `list foo' would give it some
458 sort of reference point. Then again, perhaphs that would confuse
461 Calls to this function can be broken down into two categories: Code
462 that uses the selected block as an additional, but optional, data
463 point; Code that uses the selected block as a prop, when it should
464 have the relevant frame/block/pc explicitly passed in.
466 The latter can be eliminated by correctly parameterizing the code,
467 the former though is more interesting. Per the "address" command,
468 it occures in the CLI code and makes it possible for commands to
469 work, even when the inferior has no state. */
471 extern struct block *get_selected_block (CORE_ADDR *addr_in_block);
473 extern struct symbol *get_frame_function (struct frame_info *);
475 extern CORE_ADDR frame_address_in_block (struct frame_info *);
477 extern CORE_ADDR get_pc_function_start (CORE_ADDR);
479 extern struct block *block_for_pc (CORE_ADDR);
481 extern struct block *block_for_pc_sect (CORE_ADDR, asection *);
483 extern int frameless_look_for_prologue (struct frame_info *);
485 extern void print_frame_args (struct symbol *, struct frame_info *,
486 int, struct ui_file *);
488 extern struct frame_info *find_relative_frame (struct frame_info *, int *);
490 extern void show_and_print_stack_frame (struct frame_info *fi, int level,
493 extern void print_stack_frame (struct frame_info *, int, int);
495 extern void print_only_stack_frame (struct frame_info *, int, int);
497 extern void show_stack_frame (struct frame_info *);
499 extern void print_frame_info (struct frame_info *, int, int, int);
501 extern void show_frame_info (struct frame_info *, int, int, int);
503 extern struct frame_info *block_innermost_frame (struct block *);
505 /* NOTE: cagney/2002-09-13: There is no need for this function.
506 Instead either of frame_unwind_signed_register() or
507 frame_unwind_unsigned_register() can be used. */
508 extern CORE_ADDR deprecated_read_register_dummy (CORE_ADDR pc,
510 extern void generic_push_dummy_frame (void);
511 extern void generic_pop_current_frame (void (*)(struct frame_info *));
512 extern void generic_pop_dummy_frame (void);
514 extern int generic_pc_in_call_dummy (CORE_ADDR pc,
515 CORE_ADDR sp, CORE_ADDR fp);
517 /* NOTE: cagney/2002-06-26: Targets should no longer use this
518 function. Instead, the contents of a dummy frames registers can be
519 obtained by applying: frame_register_unwind to the dummy frame; or
520 get_saved_register to the next outer frame. */
522 extern char *deprecated_generic_find_dummy_frame (CORE_ADDR pc, CORE_ADDR fp);
524 extern void generic_fix_call_dummy (char *dummy, CORE_ADDR pc, CORE_ADDR fun,
525 int nargs, struct value **args,
526 struct type *type, int gcc_p);
528 /* The function generic_get_saved_register() has been made obsolete.
529 GET_SAVED_REGISTER now defaults to the recursive equivalent -
530 generic_unwind_get_saved_register() - so there is no need to even
531 set GET_SAVED_REGISTER. Architectures that need to override the
532 register unwind mechanism should modify frame->unwind(). */
533 extern void deprecated_generic_get_saved_register (char *, int *, CORE_ADDR *,
534 struct frame_info *, int,
537 extern void generic_save_call_dummy_addr (CORE_ADDR lo, CORE_ADDR hi);
539 extern void get_saved_register (char *raw_buffer, int *optimized,
541 struct frame_info *frame,
542 int regnum, enum lval_type *lval);
544 extern int frame_register_read (struct frame_info *frame, int regnum,
548 extern void args_info (char *, int);
550 extern void locals_info (char *, int);
552 extern void (*selected_frame_level_changed_hook) (int);
554 extern void return_command (char *, int);
557 /* NOTE: cagney/2002-11-27:
559 You might think that the below global can simply be replaced by a
560 call to either get_selected_frame() or select_frame().
562 Unfortunatly, it isn't that easy.
564 The relevant code needs to be audited to determine if it is
565 possible (or pratical) to instead pass the applicable frame in as a
566 parameter. For instance, DEPRECATED_DO_REGISTERS_INFO() relied on
567 the selected_frame global, but its replacement,
568 PRINT_REGISTERS_INFO(), is parameterized with the selected frame.
569 The only real exceptions occure at the edge (in the CLI code) where
570 user commands need to pick up the selected frame before proceeding.
572 This is important. GDB is trying to stamp out the hack:
574 saved_frame = selected_frame;
575 selected_frame = ...;
576 hack_using_global_selected_frame ();
577 selected_frame = saved_frame;
581 extern struct frame_info *selected_frame;
584 /* NOTE: cagney/2002-11-28:
586 These functions are used to explicitly create and set the inner
587 most (current) frame vis:
589 set_current_frame (create_new_frame (read_fp(), stop_pc)));
591 Such code should be removed. Instead that task can be left to
592 get_current_frame() which will update things on-demand.
594 The only vague exception is found in "infcmd.c" (and a few
595 architectures specific files) as part of the code implementing the
596 command ``(gdb) frame FRAME PC''. There, the frame should be
597 created/selected in a single shot. */
599 extern void set_current_frame (struct frame_info *);
600 extern struct frame_info *create_new_frame (CORE_ADDR, CORE_ADDR);
602 #endif /* !defined (FRAME_H) */