gdb/frame.h

   1 /* Definitions for dealing with stack frames, for GDB, the GNU debugger.
   2
   3    Copyright 1986, 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1996,
   4    1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
   5
   6    This file is part of GDB.
   7
   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.
  12
  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.
  17
  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.  */
  22
  23 #if !defined (FRAME_H)
  24 #define FRAME_H 1
  25
  26 /* The frame object.  */
  27
  28 struct frame_info;
  29
  30 /* The frame object's ID.  This provides a per-frame unique identifier
  31    that can be used to relocate a `struct frame_info' after a target
  32    resume or a frame cache destruct (assuming the target hasn't
  33    unwound the stack past that frame - a problem handled elsewhere).  */
  34
  35 struct frame_id
  36 {
  37   /* The frame's address.  This should be constant through out the
  38      lifetime of a frame.  */
  39   /* NOTE: cagney/2002-11-16: The ia64 has two stacks and hence two
  40      frame bases.  This will need to be expanded to accomodate that.  */
  41   CORE_ADDR base;
  42   /* The frame's current PC.  While the PC within the function may
  43      change, the function that contains the PC does not.  Should this
  44      instead be the frame's function?  */
  45   CORE_ADDR pc;
  46 };
  47
  48 /* For every stopped thread, GDB tracks two frames: current and
  49    selected.  Current frame is the inner most frame of the selected
  50    thread.  Selected frame is the one being examined by the the GDB
  51    CLI (selected using `up', `down', ...).  The frames are created
  52    on-demand (via get_prev_frame()) and then held in a frame cache.  */
  53 /* FIXME: cagney/2002-11-28: Er, there is a lie here.  If you do the
  54    sequence: `thread 1; up; thread 2; thread 1' you loose thread 1's
  55    selected frame.  At present GDB only tracks the selected frame of
  56    the current thread.  But be warned, that might change.  */
  57 /* FIXME: cagney/2002-11-14: At any time, only one thread's selected
  58    and current frame can be active.  Switching threads causes gdb to
  59    discard all that cached frame information.  Ulgh!  Instead, current
  60    and selected frame should be bound to a thread.  */
  61
  62 /* On demand, create the inner most frame using information found in
  63    the inferior.  If the inner most frame can't be created, throw an
  64    error.  */
  65 extern struct frame_info *get_current_frame (void);
  66
  67 /* Invalidates the frame cache (this function should have been called
  68    invalidate_cached_frames).
  69
  70    FIXME: cagney/2002-11-28: The only difference between
  71    flush_cached_frames() and reinit_frame_cache() is that the latter
  72    explicitly sets the selected frame back to the current frame there
  73    isn't any real difference (except that one delays the selection of
  74    a new frame).  There should instead be a get_selected_frame()
  75    method that reinit's the frame cache on-demand.  As for
  76    invalidating the cache, there should be two methods one that
  77    reverts the thread's selected frame back to current frame (for when
  78    the inferior resumes) and one that does not (for when the user
  79    modifies the target invalidating the frame cache).  */
  80 extern void flush_cached_frames (void);
  81 extern void reinit_frame_cache (void);
  82
  83 /* Select a specific frame.  NULL, apparently implies re-select the
  84    inner most frame.  */
  85 extern void select_frame (struct frame_info *);
  86
  87 /* Given a FRAME, return the next (more inner, younger) or previous
  88    (more outer, older) frame.  */
  89 extern struct frame_info *get_prev_frame (struct frame_info *);
  90 extern struct frame_info *get_next_frame (struct frame_info *);
  91
  92 /* Given a frame's ID, relocate the frame.  Returns NULL if the frame
  93    is not found.  */
  94 extern struct frame_info *frame_find_by_id (struct frame_id id);
  95
  96 /* Base attributes of a frame: */
  97
  98 /* The frame's `resume' address.  Where the program will resume in
  99    this frame.  */
 100 extern CORE_ADDR get_frame_pc (struct frame_info *);
 101
 102 /* Return the frame address from FI.  Except in the machine-dependent
 103    *FRAME* macros, a frame address has no defined meaning other than
 104    as a magic cookie which identifies a frame over calls to the
 105    inferior (um, SEE NOTE BELOW).  The only known exception is
 106    inferior.h (PC_IN_CALL_DUMMY) [ON_STACK]; see comments there.  You
 107    cannot assume that a frame address contains enough information to
 108    reconstruct the frame; if you want more than just to identify the
 109    frame (e.g. be able to fetch variables relative to that frame),
 110    then save the whole struct frame_info (and the next struct
 111    frame_info, since the latter is used for fetching variables on some
 112    machines) (um, again SEE NOTE BELOW).
 113
 114    NOTE: cagney/2002-11-18: Actually, the frame address isn't
 115    sufficient for identifying a frame, and the counter examples are
 116    wrong!
 117
 118    Code that needs to (re)identify a frame must use get_frame_id() and
 119    frame_find_by_id() (and in the future, a frame_compare() function
 120    instead of INNER_THAN()).  Two reasons: an architecture (e.g.,
 121    ia64) can have more than one frame address (due to multiple stack
 122    pointers) (frame ID is going to be expanded to accomodate this);
 123    successive frameless function calls can only be differientated by
 124    comparing both the frame's base and the frame's enclosing function
 125    (frame_find_by_id() is going to be modified to perform this test).
 126
 127    The generic dummy frame version of PC_IN_CALL_DUMMY() is able to
 128    identify a dummy frame using only the PC value.  So the frame
 129    address is not needed.  In fact, most PC_IN_CALL_DUMMY() calls now
 130    pass zero as the frame/sp values as the caller knows that those
 131    values won't be used.  Once all architectures are using generic
 132    dummy frames, PC_IN_CALL_DUMMY() can drop the sp/frame parameters.
 133    When it comes to finding a dummy frame, the next frame's frame ID
 134    (with out duing an unwind) can be used (ok, could if it wasn't for
 135    the need to change the way the PPC defined frame base in a strange
 136    way).
 137
 138    Modern architectures should be using something like dwarf2's
 139    location expression to describe where a variable lives.  Such
 140    expressions specify their own debug info centric frame address.
 141    Consequently, a generic frame address is pretty meaningless.  */
 142
 143 extern CORE_ADDR get_frame_base (struct frame_info *);
 144
 145 /* Return the per-frame unique identifer.  Can be used to relocate a
 146    frame after a frame cache flush (and other similar operations).  */
 147 extern void get_frame_id (struct frame_info *fi, struct frame_id *id);
 148
 149 /* The frame's level: 0 for innermost, 1 for its caller, ...; or -1
 150    for an invalid frame).  */
 151 extern int frame_relative_level (struct frame_info *fi);
 152
 153 /* Return the frame's type.  Some are real, some are signal
 154    trampolines, and some are completly artificial (dummy).  */
 155
 156 enum frame_type
 157 {
 158   /* A true stack frame, created by the target program during normal
 159      execution.  */
 160   NORMAL_FRAME,
 161   /* A fake frame, created by GDB when performing an inferior function
 162      call.  */
 163   DUMMY_FRAME,
 164   /* In a signal handler, various OSs handle this in various ways.
 165      The main thing is that the frame may be far from normal.  */
 166   SIGTRAMP_FRAME
 167 };
 168 extern enum frame_type get_frame_type (struct frame_info *);
 169
 170 /* FIXME: cagney/2002-11-10: Some targets want to directly mark a
 171    frame as being of a specific type.  This shouldn't be necessary.
 172    PC_IN_SIGTRAMP() indicates a SIGTRAMP_FRAME and PC_IN_CALL_DUMMY()
 173    indicates a DUMMY_FRAME.  I suspect the real problem here is that
 174    get_prev_frame() only sets initialized after INIT_EXTRA_FRAME_INFO
 175    as been called.  Consequently, some targets found that the frame's
 176    type was wrong and tried to fix it.  The correct fix is to modify
 177    get_prev_frame() so that it initializes the frame's type before
 178    calling any other functions.  */
 179 extern void deprecated_set_frame_type (struct frame_info *,
 180                                        enum frame_type type);
 181
 182 /* Unwind the stack frame so that the value of REGNUM, in the previous
 183    (up, older) frame is returned.  If VALUEP is NULL, don't
 184    fetch/compute the value.  Instead just return the location of the
 185    value.  */
 186 extern void frame_register_unwind (struct frame_info *frame, int regnum,
 187                                    int *optimizedp, enum lval_type *lvalp,
 188                                    CORE_ADDR *addrp, int *realnump,
 189                                    void *valuep);
 190
 191 /* More convenient interface to frame_register_unwind().  */
 192 /* NOTE: cagney/2002-09-13: Return void as one day these functions may
 193    be changed to return an indication that the read succeeded.  */
 194
 195 extern void frame_unwind_signed_register (struct frame_info *frame,
 196                                           int regnum, LONGEST *val);
 197
 198 extern void frame_unwind_unsigned_register (struct frame_info *frame,
 199                                             int regnum, ULONGEST *val);
 200
 201 /* Get the value of the register that belongs to this FRAME.  This
 202    function is a wrapper to the call sequence ``frame_unwind_register
 203    (get_next_frame (FRAME))''.  As per frame_register_unwind(), if
 204    VALUEP is NULL, the registers value is not fetched/computed.  */
 205
 206 extern void frame_register (struct frame_info *frame, int regnum,
 207                             int *optimizedp, enum lval_type *lvalp,
 208                             CORE_ADDR *addrp, int *realnump,
 209                             void *valuep);
 210
 211 /* More convenient interface to frame_register().  */
 212 /* NOTE: cagney/2002-09-13: Return void as one day these functions may
 213    be changed to return an indication that the read succeeded.  */
 214
 215 extern void frame_read_signed_register (struct frame_info *frame,
 216                                         int regnum, LONGEST *val);
 217
 218 extern void frame_read_unsigned_register (struct frame_info *frame,
 219                                           int regnum, ULONGEST *val);
 220
 221 /* Map between a frame register number and its name.  A frame register
 222    space is a superset of the cooked register space --- it also
 223    includes builtin registers.  */
 224
 225 extern int frame_map_name_to_regnum (const char *name, int strlen);
 226 extern const char *frame_map_regnum_to_name (int regnum);
 227
 228 /* Unwind the PC.  Strictly speaking return the resume address of the
 229    calling frame.  For GDB, `pc' is the resume address and not a
 230    specific register.  */
 231
 232 extern CORE_ADDR frame_pc_unwind (struct frame_info *frame);
 233
 234 \f
 235 /* Return the location (and possibly value) of REGNUM for the previous
 236    (older, up) frame.  All parameters except VALUEP can be assumed to
 237    be non NULL.  When VALUEP is NULL, just the location of the
 238    register should be returned.
 239
 240    UNWIND_CACHE is provided as mechanism for implementing a per-frame
 241    local cache.  It's initial value being NULL.  Memory for that cache
 242    should be allocated using frame_obstack_alloc().
 243
 244    Register window architectures (eg SPARC) should note that REGNUM
 245    identifies the register for the previous frame.  For instance, a
 246    request for the value of "o1" for the previous frame would be found
 247    in the register "i1" in this FRAME.  */
 248
 249 typedef void (frame_register_unwind_ftype) (struct frame_info *frame,
 250                                             void **unwind_cache,
 251                                             int regnum,
 252                                             int *optimized,
 253                                             enum lval_type *lvalp,
 254                                             CORE_ADDR *addrp,
 255                                             int *realnump,
 256                                             void *valuep);
 257
 258 /* Same as for registers above, but return the address at which the
 259    calling frame would resume.  */
 260
 261 typedef CORE_ADDR (frame_pc_unwind_ftype) (struct frame_info *frame,
 262                                            void **unwind_cache);
 263
 264 /* Describe the saved registers of a frame.  */
 265
 266 #if defined (EXTRA_FRAME_INFO) || defined (FRAME_FIND_SAVED_REGS)
 267 /* XXXX - deprecated */
 268 struct frame_saved_regs
 269   {
 270     /* For each register R (except the SP), regs[R] is the address at
 271        which it was saved on entry to the frame, or zero if it was not
 272        saved on entry to this frame.  This includes special registers
 273        such as pc and fp saved in special ways in the stack frame.
 274
 275        regs[SP_REGNUM] is different.  It holds the actual SP, not the
 276        address at which it was saved.  */
 277
 278     CORE_ADDR regs[NUM_REGS];
 279   };
 280 #endif
 281
 282 /* We keep a cache of stack frames, each of which is a "struct
 283    frame_info".  The innermost one gets allocated (in
 284    wait_for_inferior) each time the inferior stops; current_frame
 285    points to it.  Additional frames get allocated (in
 286    get_prev_frame) as needed, and are chained through the next
 287    and prev fields.  Any time that the frame cache becomes invalid
 288    (most notably when we execute something, but also if we change how
 289    we interpret the frames (e.g. "set heuristic-fence-post" in
 290    mips-tdep.c, or anything which reads new symbols)), we should call
 291    reinit_frame_cache.  */
 292
 293 struct frame_info
 294   {
 295     /* Nominal address of the frame described.  See comments at
 296        get_frame_base() about what this means outside the *FRAME*
 297        macros; in the *FRAME* macros, it can mean whatever makes most
 298        sense for this machine.  */
 299     CORE_ADDR frame;
 300
 301     /* Address at which execution is occurring in this frame.
 302        For the innermost frame, it's the current pc.
 303        For other frames, it is a pc saved in the next frame.  */
 304     CORE_ADDR pc;
 305
 306     /* Level of this frame.  The inner-most (youngest) frame is at
 307        level 0.  As you move towards the outer-most (oldest) frame,
 308        the level increases.  This is a cached value.  It could just as
 309        easily be computed by counting back from the selected frame to
 310        the inner most frame.  */
 311     /* NOTE: cagney/2002-04-05: Perhaphs a level of ``-1'' should be
 312        reserved to indicate a bogus frame - one that has been created
 313        just to keep GDB happy (GDB always needs a frame).  For the
 314        moment leave this as speculation.  */
 315     int level;
 316
 317     /* The frame's type.  */
 318     enum frame_type type;
 319
 320     /* For each register, address of where it was saved on entry to
 321        the frame, or zero if it was not saved on entry to this frame.
 322        This includes special registers such as pc and fp saved in
 323        special ways in the stack frame.  The SP_REGNUM is even more
 324        special, the address here is the sp for the previous frame, not
 325        the address where the sp was saved.  */
 326     /* Allocated by frame_saved_regs_zalloc () which is called /
 327        initialized by FRAME_INIT_SAVED_REGS(). */
 328     CORE_ADDR *saved_regs;      /*NUM_REGS + NUM_PSEUDO_REGS*/
 329
 330 #ifdef EXTRA_FRAME_INFO
 331     /* XXXX - deprecated */
 332     /* Anything extra for this structure that may have been defined
 333        in the machine dependent files. */
 334       EXTRA_FRAME_INFO
 335 #endif
 336
 337     /* Anything extra for this structure that may have been defined
 338        in the machine dependent files. */
 339     /* Allocated by frame_obstack_alloc () which is called /
 340        initialized by INIT_EXTRA_FRAME_INFO */
 341     struct frame_extra_info *extra_info;
 342
 343     /* If dwarf2 unwind frame informations is used, this structure holds all
 344        related unwind data.  */
 345     struct context *context;
 346
 347     /* Unwind cache shared between the unwind functions - they had
 348        better all agree as to the contents.  */
 349     void *unwind_cache;
 350
 351     /* See description above.  The previous frame's registers.  */
 352     frame_register_unwind_ftype *register_unwind;
 353
 354     /* See description above.  The previous frame's resume address.
 355        Save the previous PC in a local cache.  */
 356     frame_pc_unwind_ftype *pc_unwind;
 357     int pc_unwind_cache_p;
 358     CORE_ADDR pc_unwind_cache;
 359
 360     /* Pointers to the next (down, inner, younger) and previous (up,
 361        outer, older) frame_info's in the frame cache.  */
 362     struct frame_info *next; /* down, inner, younger */
 363     int prev_p;
 364     struct frame_info *prev; /* up, outer, older */
 365   };
 366
 367 /* Values for the source flag to be used in print_frame_info_base(). */
 368 enum print_what
 369   {
 370     /* Print only the source line, like in stepi. */
 371     SRC_LINE = -1,
 372     /* Print only the location, i.e. level, address (sometimes)
 373        function, args, file, line, line num. */
 374     LOCATION,
 375     /* Print both of the above. */
 376     SRC_AND_LOC,
 377     /* Print location only, but always include the address. */
 378     LOC_AND_ADDRESS
 379   };
 380
 381 /* Allocate additional space for appendices to a struct frame_info.
 382    NOTE: Much of GDB's code works on the assumption that the allocated
 383    saved_regs[] array is the size specified below.  If you try to make
 384    that array smaller, GDB will happily walk off its end. */
 385
 386 #ifdef SIZEOF_FRAME_SAVED_REGS
 387 #error "SIZEOF_FRAME_SAVED_REGS can not be re-defined"
 388 #endif
 389 #define SIZEOF_FRAME_SAVED_REGS \
 390         (sizeof (CORE_ADDR) * (NUM_REGS+NUM_PSEUDO_REGS))
 391
 392 extern void *frame_obstack_alloc (unsigned long size);
 393 extern void frame_saved_regs_zalloc (struct frame_info *);
 394
 395 /* Define a default FRAME_CHAIN_VALID, in the form that is suitable for most
 396    targets.  If FRAME_CHAIN_VALID returns zero it means that the given frame
 397    is the outermost one and has no caller.
 398
 399    XXXX - both default and alternate frame_chain_valid functions are
 400    deprecated.  New code should use dummy frames and one of the
 401    generic functions. */
 402
 403 extern int file_frame_chain_valid (CORE_ADDR, struct frame_info *);
 404 extern int func_frame_chain_valid (CORE_ADDR, struct frame_info *);
 405 extern int nonnull_frame_chain_valid (CORE_ADDR, struct frame_info *);
 406 extern int generic_file_frame_chain_valid (CORE_ADDR, struct frame_info *);
 407 extern int generic_func_frame_chain_valid (CORE_ADDR, struct frame_info *);
 408 extern void generic_save_dummy_frame_tos (CORE_ADDR sp);
 409
 410
 411
 412 #ifdef FRAME_FIND_SAVED_REGS
 413 /* XXX - deprecated */
 414 #define FRAME_INIT_SAVED_REGS(FI) get_frame_saved_regs (FI, NULL)
 415 extern void get_frame_saved_regs (struct frame_info *,
 416                                   struct frame_saved_regs *);
 417 #endif
 418
 419 extern struct block *get_frame_block (struct frame_info *,
 420                                       CORE_ADDR *addr_in_block);
 421
 422 extern struct block *get_selected_block (CORE_ADDR *addr_in_block);
 423
 424 extern struct symbol *get_frame_function (struct frame_info *);
 425
 426 extern CORE_ADDR frame_address_in_block (struct frame_info *);
 427
 428 extern CORE_ADDR get_pc_function_start (CORE_ADDR);
 429
 430 extern struct block *block_for_pc (CORE_ADDR);
 431
 432 extern struct block *block_for_pc_sect (CORE_ADDR, asection *);
 433
 434 extern int frameless_look_for_prologue (struct frame_info *);
 435
 436 extern void print_frame_args (struct symbol *, struct frame_info *,
 437                               int, struct ui_file *);
 438
 439 extern struct frame_info *find_relative_frame (struct frame_info *, int *);
 440
 441 extern void show_and_print_stack_frame (struct frame_info *fi, int level,
 442                                         int source);
 443
 444 extern void print_stack_frame (struct frame_info *, int, int);
 445
 446 extern void print_only_stack_frame (struct frame_info *, int, int);
 447
 448 extern void show_stack_frame (struct frame_info *);
 449
 450 extern void print_frame_info (struct frame_info *, int, int, int);
 451
 452 extern void show_frame_info (struct frame_info *, int, int, int);
 453
 454 extern struct frame_info *block_innermost_frame (struct block *);
 455
 456 /* NOTE: cagney/2002-09-13: There is no need for this function.
 457    Instead either of frame_unwind_signed_register() or
 458    frame_unwind_unsigned_register() can be used.  */
 459 extern CORE_ADDR deprecated_read_register_dummy (CORE_ADDR pc,
 460                                                  CORE_ADDR fp, int);
 461 extern void generic_push_dummy_frame (void);
 462 extern void generic_pop_current_frame (void (*)(struct frame_info *));
 463 extern void generic_pop_dummy_frame (void);
 464
 465 extern int generic_pc_in_call_dummy (CORE_ADDR pc,
 466                                      CORE_ADDR sp, CORE_ADDR fp);
 467
 468 /* NOTE: cagney/2002-06-26: Targets should no longer use this
 469    function.  Instead, the contents of a dummy frames registers can be
 470    obtained by applying: frame_register_unwind to the dummy frame; or
 471    get_saved_register to the next outer frame.  */
 472
 473 extern char *deprecated_generic_find_dummy_frame (CORE_ADDR pc, CORE_ADDR fp);
 474
 475 extern void generic_fix_call_dummy (char *dummy, CORE_ADDR pc, CORE_ADDR fun,
 476                                     int nargs, struct value **args,
 477                                     struct type *type, int gcc_p);
 478
 479 /* The function generic_get_saved_register() has been made obsolete.
 480    GET_SAVED_REGISTER now defaults to the recursive equivalent -
 481    generic_unwind_get_saved_register() - so there is no need to even
 482    set GET_SAVED_REGISTER.  Architectures that need to override the
 483    register unwind mechanism should modify frame->unwind().  */
 484 extern void deprecated_generic_get_saved_register (char *, int *, CORE_ADDR *,
 485                                                    struct frame_info *, int,
 486                                                    enum lval_type *);
 487
 488 extern void generic_save_call_dummy_addr (CORE_ADDR lo, CORE_ADDR hi);
 489
 490 extern void get_saved_register (char *raw_buffer, int *optimized,
 491                                 CORE_ADDR * addrp,
 492                                 struct frame_info *frame,
 493                                 int regnum, enum lval_type *lval);
 494
 495 extern int frame_register_read (struct frame_info *frame, int regnum,
 496                                 void *buf);
 497
 498 /* From stack.c.  */
 499 extern void args_info (char *, int);
 500
 501 extern void locals_info (char *, int);
 502
 503 extern void (*selected_frame_level_changed_hook) (int);
 504
 505 extern void return_command (char *, int);
 506
 507
 508 /* NOTE: cagney/2002-11-27:
 509
 510    You might think that the below global can simply be replaced by a
 511    call to either get_selected_frame() or select_frame().
 512
 513    Unfortunatly, it isn't that easy.
 514
 515    The relevant code needs to be audited to determine if it is
 516    possible (or pratical) to instead pass the applicable frame in as a
 517    parameter.  For instance, DEPRECATED_DO_REGISTERS_INFO() relied on
 518    the selected_frame global, but its replacement,
 519    PRINT_REGISTERS_INFO(), is parameterized with the selected frame.
 520    The only real exceptions occure at the edge (in the CLI code) where
 521    user commands need to pick up the selected frame before proceeding.
 522
 523    This is important.  GDB is trying to stamp out the hack:
 524
 525    saved_frame = selected_frame;
 526    selected_frame = ...;
 527    hack_using_global_selected_frame ();
 528    selected_frame = saved_frame;
 529
 530    Take care!  */
 531
 532 extern struct frame_info *selected_frame;
 533
 534
 535 /* NOTE: cagney/2002-11-28:
 536
 537    These functions are used to explicitly create and set the inner
 538    most (current) frame vis:
 539
 540    set_current_frame (create_new_frame (read_fp(), stop_pc)));
 541
 542    Such code should be removed.  Instead that task can be left to
 543    get_current_frame() which will update things on-demand.
 544
 545    The only vague exception is found in "infcmd.c" (and a few
 546    architectures specific files) as part of the code implementing the
 547    command ``(gdb) frame FRAME PC''.  There, the frame should be
 548    created/selected in a single shot.  */
 549
 550 extern void set_current_frame (struct frame_info *);
 551 extern struct frame_info *create_new_frame (CORE_ADDR, CORE_ADDR);
 552
 553 #endif /* !defined (FRAME_H)  */