/* Definitions for dealing with stack frames, for GDB, the GNU debugger.
Copyright 1986, 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1996,
- 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
+ 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
This file is part of GDB.
#if !defined (FRAME_H)
#define FRAME_H 1
+/* The following is the intended naming schema for frame functions.
+ It isn't 100% consistent, but it is aproaching that. Frame naming
+ schema:
+
+ Prefixes:
+
+ get_frame_WHAT...(): Get WHAT from the THIS frame (functionaly
+ equivalent to THIS->next->unwind->what)
+
+ frame_unwind_WHAT...(): Unwind THIS frame's WHAT from the NEXT
+ frame.
+
+ put_frame_WHAT...(): Put a value into this frame (unsafe, need to
+ invalidate the frame / regcache afterwards) (better name more
+ strongly hinting at its unsafeness)
+
+ safe_....(): Safer version of various functions, doesn't throw an
+ error (leave this for later?). Returns non-zero if the fetch
+ succeeds. Return a freshly allocated error message?
+
+ Suffixes:
+
+ void /frame/_WHAT(): Read WHAT's value into the buffer parameter.
+
+ ULONGEST /frame/_WHAT_unsigned(): Return an unsigned value (the
+ alternative is *frame_unsigned_WHAT).
+
+ LONGEST /frame/_WHAT_signed(): Return WHAT signed value.
+
+ What:
+
+ /frame/_memory* (frame, coreaddr, len [, buf]): Extract/return
+ *memory.
+
+ /frame/_register* (frame, regnum [, buf]): extract/return register.
+
+ CORE_ADDR /frame/_{pc,sp,...} (frame): Resume address, innner most
+ stack *address, ...
+
+ */
+
struct symtab_and_line;
struct frame_unwind;
struct frame_base;
is used. Watch out for all the legacy targets that still use the
function pointer register or stack pointer register. They are
wrong. */
- /* NOTE: cagney/2002-11-16: The ia64 has two stacks and hence two
- frame bases. This will need to be expanded to accomodate that. */
CORE_ADDR stack_addr;
/* The frame's code address. This shall be constant through out the
lifetime of the frame. While the PC (a.k.a. resume address)
Typically, it is set to the address of the entry point of the
frame's function (as returned by frame_func_unwind(). */
CORE_ADDR code_addr;
+ /* The frame's special address. This shall be constant through out the
+ lifetime of the frame. This is used for architectures that may have
+ frames that do not change the stack but are still distinct and have
+ some form of distinct identifier (e.g. the ia64 which uses a 2nd
+ stack for registers). This field is treated as unordered - i.e. will
+ not be used in frame ordering comparisons such as frame_id_inner().
+ A zero in this field will be treated as a wild-card when comparing
+ frames for equality. */
+ CORE_ADDR special_addr;
};
/* Methods for constructing and comparing Frame IDs.
- NOTE: Given frameless functions A and B, where A calls B (and hence
+ NOTE: Given stackless functions A and B, where A calls B (and hence
B is inner-to A). The relationships: !eq(A,B); !eq(B,A);
- !inner(A,B); !inner(B,A); all hold. This is because, while B is
- inner to A, B is not strictly inner to A (being frameless, they
- have the same .base value). */
+ !inner(A,B); !inner(B,A); all hold.
+
+ This is because, while B is inner-to A, B is not strictly inner-to A.
+ Being stackless, they have an identical .stack_addr value, and differ
+ only by their unordered .code_addr and/or .special_addr values.
+
+ Because frame_id_inner is only used as a safety net (e.g.,
+ detect a corrupt stack) the lack of strictness is not a problem.
+ Code needing to determine an exact relationship between two frames
+ must instead use frame_id_eq and frame_id_unwind. For instance,
+ in the above, to determine that A stepped-into B, the equation
+ "A.id != B.id && A.id == id_unwind (B)" can be used. */
/* For convenience. All fields are zero. */
extern const struct frame_id null_frame_id;
/* Construct a frame ID. The first parameter is the frame's constant
stack address (typically the outer-bound), and the second the
frame's constant code address (typically the entry point) (or zero,
- to indicate a wild card). */
+ to indicate a wild card). The special identifier address is
+ defaulted to zero. */
extern struct frame_id frame_id_build (CORE_ADDR stack_addr,
CORE_ADDR code_addr);
+/* Construct a special frame ID. The first parameter is the frame's constant
+ stack address (typically the outer-bound), the second is the
+ frame's constant code address (typically the entry point) (or zero,
+ to indicate a wild card), and the third parameter is the frame's
+ special identifier address (or zero to indicate a wild card or
+ unused default). */
+extern struct frame_id frame_id_build_special (CORE_ADDR stack_addr,
+ CORE_ADDR code_addr,
+ CORE_ADDR special_addr);
+
/* Returns non-zero when L is a valid frame (a valid frame has a
non-zero .base). */
extern int frame_id_p (struct frame_id l);
This replaced: frame->pc; */
extern CORE_ADDR get_frame_pc (struct frame_info *);
+/* An address (not necessarily alligned to an instruction boundary)
+ that falls within THIS frame's code block.
+
+ When a function call is the last statement in a block, the return
+ address for the call may land at the start of the next block.
+ Similarly, if a no-return function call is the last statement in
+ the function, the return address may end up pointing beyond the
+ function, and possibly at the start of the next function.
+
+ These methods make an allowance for this. For call frames, this
+ function returns the frame's PC-1 which "should" be an address in
+ the frame's block. */
+
+extern CORE_ADDR get_frame_address_in_block (struct frame_info *this_frame);
+extern CORE_ADDR frame_unwind_address_in_block (struct frame_info *next_frame);
+
+/* The frame's inner-most bound. AKA the stack-pointer. Confusingly
+ known as top-of-stack. */
+
+extern CORE_ADDR get_frame_sp (struct frame_info *);
+extern CORE_ADDR frame_sp_unwind (struct frame_info *);
+
+
/* Following on from the `resume' address. Return the entry point
address of the function containing that resume address, or zero if
that function isn't known. */
extern int frame_relative_level (struct frame_info *fi);
/* Return the frame's type. Some are real, some are signal
- trampolines, and some are completly artificial (dummy). */
+ trampolines, and some are completely artificial (dummy). */
enum frame_type
{
/* FIXME: cagney/2002-11-10: Some targets want to directly mark a
frame as being of a specific type. This shouldn't be necessary.
- PC_IN_SIGTRAMP() indicates a SIGTRAMP_FRAME and
+ DEPRECATED_PC_IN_SIGTRAMP() indicates a SIGTRAMP_FRAME and
DEPRECATED_PC_IN_CALL_DUMMY() indicates a DUMMY_FRAME. I suspect
the real problem here is that get_prev_frame() only sets
initialized after DEPRECATED_INIT_EXTRA_FRAME_INFO as been called.
CORE_ADDR *addrp, int *realnump,
void *valuep);
-/* More convenient interface to frame_register_unwind(). */
-/* NOTE: cagney/2002-09-13: Return void as one day these functions may
- be changed to return an indication that the read succeeded. */
+/* Fetch a register from this, or unwind a register from the next
+ frame. Note that the get_frame methods are wrappers to
+ frame->next->unwind. They all [potentially] throw an error if the
+ fetch fails. */
extern void frame_unwind_register (struct frame_info *frame,
int regnum, void *buf);
+extern void get_frame_register (struct frame_info *frame,
+ int regnum, void *buf);
+
+extern LONGEST frame_unwind_register_signed (struct frame_info *frame,
+ int regnum);
+extern LONGEST get_frame_register_signed (struct frame_info *frame,
+ int regnum);
+extern ULONGEST frame_unwind_register_unsigned (struct frame_info *frame,
+ int regnum);
+extern ULONGEST get_frame_register_unsigned (struct frame_info *frame,
+ int regnum);
-extern void frame_unwind_signed_register (struct frame_info *frame,
- int regnum, LONGEST *val);
+/* Use frame_unwind_register_signed. */
extern void frame_unwind_unsigned_register (struct frame_info *frame,
int regnum, ULONGEST *val);
CORE_ADDR *addrp, int *realnump,
void *valuep);
-/* More convenient interface to frame_register(). */
-/* NOTE: cagney/2002-09-13: Return void as one day these functions may
- be changed to return an indication that the read succeeded. */
-
-extern void frame_read_register (struct frame_info *frame, int regnum,
- void *buf);
-
-extern void frame_read_signed_register (struct frame_info *frame,
- int regnum, LONGEST *val);
-
-extern void frame_read_unsigned_register (struct frame_info *frame,
- int regnum, ULONGEST *val);
+/* The reverse. Store a register value relative to the specified
+ frame. Note: this call makes the frame's state undefined. The
+ register and frame caches must be flushed. */
+extern void put_frame_register (struct frame_info *frame, int regnum,
+ const void *buf);
/* Map between a frame register number and its name. A frame register
space is a superset of the cooked register space --- it also
includes builtin registers. If NAMELEN is negative, use the NAME's
length when doing the comparison. */
-extern int frame_map_name_to_regnum (const char *name, int namelen);
-extern const char *frame_map_regnum_to_name (int regnum);
+extern int frame_map_name_to_regnum (struct frame_info *frame,
+ const char *name, int namelen);
+extern const char *frame_map_regnum_to_name (struct frame_info *frame,
+ int regnum);
/* Unwind the PC. Strictly speaking return the resume address of the
calling frame. For GDB, `pc' is the resume address and not a
extern struct symbol *get_frame_function (struct frame_info *);
-extern CORE_ADDR frame_address_in_block (struct frame_info *);
-
extern CORE_ADDR get_pc_function_start (CORE_ADDR);
-extern int frameless_look_for_prologue (struct frame_info *);
-
-extern void print_frame_args (struct symbol *, struct frame_info *,
- int, struct ui_file *);
+extern int legacy_frameless_look_for_prologue (struct frame_info *);
extern struct frame_info *find_relative_frame (struct frame_info *, int *);
extern struct frame_info *block_innermost_frame (struct block *);
-/* NOTE: cagney/2002-09-13: There is no need for this function.
- Instead either of frame_unwind_signed_register() or
- frame_unwind_unsigned_register() can be used. */
+/* NOTE: cagney/2002-09-13: There is no need for this function. */
extern CORE_ADDR deprecated_read_register_dummy (CORE_ADDR pc,
CORE_ADDR fp, int);
extern void generic_push_dummy_frame (void);
-extern void generic_pop_current_frame (void (*)(struct frame_info *));
-extern void generic_pop_dummy_frame (void);
+extern void deprecated_pop_dummy_frame (void);
-extern int generic_pc_in_call_dummy (CORE_ADDR pc,
- CORE_ADDR sp, CORE_ADDR fp);
+extern int deprecated_pc_in_call_dummy (CORE_ADDR pc, CORE_ADDR sp,
+ CORE_ADDR fp);
/* NOTE: cagney/2002-06-26: Targets should no longer use this
function. Instead, the contents of a dummy frames registers can be
extern char *deprecated_generic_find_dummy_frame (CORE_ADDR pc, CORE_ADDR fp);
-void generic_unwind_get_saved_register (char *raw_buffer,
- int *optimizedp,
- CORE_ADDR *addrp,
- struct frame_info *frame,
- int regnum,
- enum lval_type *lvalp);
-
-/* The function generic_get_saved_register() has been made obsolete.
- DEPRECATED_GET_SAVED_REGISTER now defaults to the recursive
- equivalent - generic_unwind_get_saved_register() - so there is no
- need to even set DEPRECATED_GET_SAVED_REGISTER. Architectures that
- need to override the register unwind mechanism should modify
- frame->unwind(). */
+
+/* The DEPRECATED_GET_SAVED_REGISTER architecture interface is
+ entirely redundant. New architectures should implement per-frame
+ unwinders (ref "frame-unwind.h"). */
extern void deprecated_generic_get_saved_register (char *, int *, CORE_ADDR *,
struct frame_info *, int,
enum lval_type *);
extern void generic_save_call_dummy_addr (CORE_ADDR lo, CORE_ADDR hi);
/* FIXME: cagney/2003-02-02: Should be deprecated or replaced with a
- function called frame_read_register_p(). This slightly weird (and
- older) variant of frame_read_register() returns zero (indicating
- the register is unavailable) if either: the register isn't cached;
- or the register has been optimized out. Problem is, neither check
- is exactly correct. A register can't be optimized out (it may not
+ function called get_frame_register_p(). This slightly weird (and
+ older) variant of get_frame_register() returns zero (indicating the
+ register is unavailable) if either: the register isn't cached; or
+ the register has been optimized out. Problem is, neither check is
+ exactly correct. A register can't be optimized out (it may not
have been saved as part of a function call); The fact that a
register isn't in the register cache doesn't mean that the register
isn't available (it could have been fetched from memory). */
You might think that the below global can simply be replaced by a
call to either get_selected_frame() or select_frame().
- Unfortunatly, it isn't that easy.
+ Unfortunately, it isn't that easy.
The relevant code needs to be audited to determine if it is
possible (or pratical) to instead pass the applicable frame in as a
extern struct frame_info *deprecated_selected_frame;
+/* NOTE: drow/2003-09-06:
+
+ This function is "a step sideways" for uses of deprecated_selected_frame.
+ They should be fixed as above, but meanwhile, we needed a solution for
+ cases where functions are called with a NULL frame meaning either "the
+ program is not running" or "use the selected frame". Lazy building of
+ deprecated_selected_frame confuses the situation, because now
+ deprecated_selected_frame can be NULL even when the inferior is running.
+
+ This function calls get_selected_frame if the inferior should have a
+ frame, or returns NULL otherwise. */
+
+extern struct frame_info *deprecated_safe_get_selected_frame (void);
/* Create a frame using the specified BASE and PC. */
SP_REGNUM where the value of the register in the previous frame is
stored). */
extern CORE_ADDR *frame_saved_regs_zalloc (struct frame_info *);
-extern CORE_ADDR *get_frame_saved_regs (struct frame_info *);
+extern CORE_ADDR *deprecated_get_frame_saved_regs (struct frame_info *);
/* FIXME: cagney/2002-12-06: Has the PC in the current frame changed?
"infrun.c", Thanks to DECR_PC_AFTER_BREAK, can change the PC after
CORE_ADDR pc);
/* FIXME: cagney/2002-12-18: Has the frame's base changed? Or to be
- more exact, whas that initial guess at the frame's base as returned
- by deprecated_read_fp() wrong. If it was, fix it. This shouldn't
+ more exact, was that initial guess at the frame's base as returned
+ by deprecated_read_fp() wrong? If it was, fix it. This shouldn't
be necessary since the code should be getting the frame's base
correct from the outset.
extern void deprecated_update_frame_base_hack (struct frame_info *frame,
CORE_ADDR base);
-/* FIXME: cagney/2003-01-04: Explicitly set the frame's saved_regs
- and/or extra_info. Target code is allocating a fake frame and than
- initializing that to get around the problem of, when creating the
- inner most frame, there is no where to cache information such as
- the prologue analysis. This is fixed by the new unwind mechanism -
- even the inner most frame has somewhere to store things like the
- prolog analysis (or at least will once the frame overhaul is
- finished). */
-extern void deprecated_set_frame_saved_regs_hack (struct frame_info *frame,
- CORE_ADDR *saved_regs);
-extern void deprecated_set_frame_extra_info_hack (struct frame_info *frame,
- struct frame_extra_info *extra_info);
-
-/* FIXME: cagney/2003-01-04: Allocate a frame from the heap (rather
- than the frame obstack). Targets do this as a way of saving the
- prologue analysis from the inner most frame before that frame has
- been created. By always creating a frame, this problem goes away. */
-extern struct frame_info *deprecated_frame_xmalloc (void);
-
/* FIXME: cagney/2003-01-05: Allocate a frame, along with the
saved_regs and extra_info. Set up cleanups for all three. Same as
for deprecated_frame_xmalloc, targets are calling this when
extern struct frame_info *deprecated_frame_xmalloc_with_cleanup (long sizeof_saved_regs,
long sizeof_extra_info);
-/* FIXME: cagney/2003-01-07: These are just nasty. Code shouldn't be
- doing this. I suspect it dates back to the days when every field
- of an allocated structure was explicitly initialized. */
-extern void deprecated_set_frame_next_hack (struct frame_info *fi,
- struct frame_info *next);
-extern void deprecated_set_frame_prev_hack (struct frame_info *fi,
- struct frame_info *prev);
-
-/* FIXME: cagney/2003-01-07: Instead of the dwarf2cfi having its own
- dedicated `struct frame_info . context' field, the code should use
- the per frame `unwind_cache' that is passed to the
- frame_pc_unwind(), frame_register_unwind() and frame_id_unwind()
- methods.
-
- See "dummy-frame.c" for an example of how a cfi-frame object can be
- implemented using this. */
-extern struct context *deprecated_get_frame_context (struct frame_info *fi);
-extern void deprecated_set_frame_context (struct frame_info *fi,
- struct context *context);
-
/* Return non-zero if the architecture is relying on legacy frame
code. */
extern int legacy_frame_p (struct gdbarch *gdbarch);
projects / binutils.git / blobdiff