gdb/frame.h

   1 /* Definitions for dealing with stack frames, for GDB, the GNU debugger.
   2
   3    Copyright (C) 1986, 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1996, 1997,
   4    1998, 1999, 2000, 2001, 2002, 2003, 2004, 2007, 2008
   5    Free Software Foundation, Inc.
   6
   7    This file is part of GDB.
   8
   9    This program is free software; you can redistribute it and/or modify
  10    it under the terms of the GNU General Public License as published by
  11    the Free Software Foundation; either version 3 of the License, or
  12    (at your option) any later version.
  13
  14    This program is distributed in the hope that it will be useful,
  15    but WITHOUT ANY WARRANTY; without even the implied warranty of
  16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17    GNU General Public License for more details.
  18
  19    You should have received a copy of the GNU General Public License
  20    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  21
  22 #if !defined (FRAME_H)
  23 #define FRAME_H 1
  24
  25 /* The following is the intended naming schema for frame functions.
  26    It isn't 100% consistent, but it is aproaching that.  Frame naming
  27    schema:
  28
  29    Prefixes:
  30
  31    get_frame_WHAT...(): Get WHAT from the THIS frame (functionaly
  32    equivalent to THIS->next->unwind->what)
  33
  34    frame_unwind_WHAT...(): Unwind THIS frame's WHAT from the NEXT
  35    frame.
  36
  37    frame_unwind_caller_WHAT...(): Unwind WHAT for NEXT stack frame's
  38    real caller.  Any inlined functions in NEXT's stack frame are
  39    skipped.  Use these to ignore any potentially inlined functions,
  40    e.g. inlined into the first instruction of a library trampoline.
  41
  42    put_frame_WHAT...(): Put a value into this frame (unsafe, need to
  43    invalidate the frame / regcache afterwards) (better name more
  44    strongly hinting at its unsafeness)
  45
  46    safe_....(): Safer version of various functions, doesn't throw an
  47    error (leave this for later?).  Returns non-zero / non-NULL if the
  48    request succeeds, zero / NULL otherwize.
  49
  50    Suffixes:
  51
  52    void /frame/_WHAT(): Read WHAT's value into the buffer parameter.
  53
  54    ULONGEST /frame/_WHAT_unsigned(): Return an unsigned value (the
  55    alternative is *frame_unsigned_WHAT).
  56
  57    LONGEST /frame/_WHAT_signed(): Return WHAT signed value.
  58
  59    What:
  60
  61    /frame/_memory* (frame, coreaddr, len [, buf]): Extract/return
  62    *memory.
  63
  64    /frame/_register* (frame, regnum [, buf]): extract/return register.
  65
  66    CORE_ADDR /frame/_{pc,sp,...} (frame): Resume address, innner most
  67    stack *address, ...
  68
  69    */
  70
  71 struct symtab_and_line;
  72 struct frame_unwind;
  73 struct frame_base;
  74 struct block;
  75 struct gdbarch;
  76 struct ui_file;
  77
  78 /* The frame object.  */
  79
  80 struct frame_info;
  81
  82 /* The frame object's ID.  This provides a per-frame unique identifier
  83    that can be used to relocate a `struct frame_info' after a target
  84    resume or a frame cache destruct.  It of course assumes that the
  85    inferior hasn't unwound the stack past that frame.  */
  86
  87 struct frame_id
  88 {
  89   /* The frame's stack address.  This shall be constant through out
  90      the lifetime of a frame.  Note that this requirement applies to
  91      not just the function body, but also the prologue and (in theory
  92      at least) the epilogue.  Since that value needs to fall either on
  93      the boundary, or within the frame's address range, the frame's
  94      outer-most address (the inner-most address of the previous frame)
  95      is used.  Watch out for all the legacy targets that still use the
  96      function pointer register or stack pointer register.  They are
  97      wrong.
  98
  99      This field is valid only if stack_addr_p is true.  Otherwise, this
 100      frame represents the null frame.  */
 101   CORE_ADDR stack_addr;
 102
 103   /* The frame's code address.  This shall be constant through out the
 104      lifetime of the frame.  While the PC (a.k.a. resume address)
 105      changes as the function is executed, this code address cannot.
 106      Typically, it is set to the address of the entry point of the
 107      frame's function (as returned by get_frame_func).
 108
 109      This field is valid only if code_addr_p is true.  Otherwise, this
 110      frame is considered to have a wildcard code address, i.e. one that
 111      matches every address value in frame comparisons.  */
 112   CORE_ADDR code_addr;
 113
 114   /* The frame's special address.  This shall be constant through out the
 115      lifetime of the frame.  This is used for architectures that may have
 116      frames that do not change the stack but are still distinct and have
 117      some form of distinct identifier (e.g. the ia64 which uses a 2nd
 118      stack for registers).  This field is treated as unordered - i.e. will
 119      not be used in frame ordering comparisons such as frame_id_inner().
 120
 121      This field is valid only if special_addr_p is true.  Otherwise, this
 122      frame is considered to have a wildcard special address, i.e. one that
 123      matches every address value in frame comparisons.  */
 124   CORE_ADDR special_addr;
 125
 126   /* Flags to indicate the above fields have valid contents.  */
 127   unsigned int stack_addr_p : 1;
 128   unsigned int code_addr_p : 1;
 129   unsigned int special_addr_p : 1;
 130 };
 131
 132 /* Methods for constructing and comparing Frame IDs.
 133
 134    NOTE: Given stackless functions A and B, where A calls B (and hence
 135    B is inner-to A).  The relationships: !eq(A,B); !eq(B,A);
 136    !inner(A,B); !inner(B,A); all hold.
 137
 138    This is because, while B is inner-to A, B is not strictly inner-to A.
 139    Being stackless, they have an identical .stack_addr value, and differ
 140    only by their unordered .code_addr and/or .special_addr values.
 141
 142    Because frame_id_inner is only used as a safety net (e.g.,
 143    detect a corrupt stack) the lack of strictness is not a problem.
 144    Code needing to determine an exact relationship between two frames
 145    must instead use frame_id_eq and frame_id_unwind.  For instance,
 146    in the above, to determine that A stepped-into B, the equation
 147    "A.id != B.id && A.id == id_unwind (B)" can be used.  */
 148
 149 /* For convenience.  All fields are zero.  */
 150 extern const struct frame_id null_frame_id;
 151
 152 /* Flag to control debugging.  */
 153
 154 extern int frame_debug;
 155
 156 /* Construct a frame ID.  The first parameter is the frame's constant
 157    stack address (typically the outer-bound), and the second the
 158    frame's constant code address (typically the entry point).
 159    The special identifier address is set to indicate a wild card.  */
 160 extern struct frame_id frame_id_build (CORE_ADDR stack_addr,
 161                                        CORE_ADDR code_addr);
 162
 163 /* Construct a special frame ID.  The first parameter is the frame's constant
 164    stack address (typically the outer-bound), the second is the
 165    frame's constant code address (typically the entry point),
 166    and the third parameter is the frame's special identifier address. */
 167 extern struct frame_id frame_id_build_special (CORE_ADDR stack_addr,
 168                                                CORE_ADDR code_addr,
 169                                                CORE_ADDR special_addr);
 170
 171 /* Construct a wild card frame ID.  The parameter is the frame's constant
 172    stack address (typically the outer-bound).  The code address as well
 173    as the special identifier address are set to indicate wild cards.  */
 174 extern struct frame_id frame_id_build_wild (CORE_ADDR stack_addr);
 175
 176 /* Returns non-zero when L is a valid frame (a valid frame has a
 177    non-zero .base).  */
 178 extern int frame_id_p (struct frame_id l);
 179
 180 /* Returns non-zero when L and R identify the same frame, or, if
 181    either L or R have a zero .func, then the same frame base.  */
 182 extern int frame_id_eq (struct frame_id l, struct frame_id r);
 183
 184 /* Returns non-zero when L is strictly inner-than R (they have
 185    different frame .bases).  Neither L, nor R can be `null'.  See note
 186    above about frameless functions.  */
 187 extern int frame_id_inner (struct gdbarch *gdbarch, struct frame_id l,
 188                            struct frame_id r);
 189
 190 /* Write the internal representation of a frame ID on the specified
 191    stream.  */
 192 extern void fprint_frame_id (struct ui_file *file, struct frame_id id);
 193
 194
 195 /* Frame types.  Some are real, some are signal trampolines, and some
 196    are completely artificial (dummy).  */
 197
 198 enum frame_type
 199 {
 200   /* A true stack frame, created by the target program during normal
 201      execution.  */
 202   NORMAL_FRAME,
 203   /* A fake frame, created by GDB when performing an inferior function
 204      call.  */
 205   DUMMY_FRAME,
 206   /* In a signal handler, various OSs handle this in various ways.
 207      The main thing is that the frame may be far from normal.  */
 208   SIGTRAMP_FRAME,
 209   /* Sentinel or registers frame.  This frame obtains register values
 210      direct from the inferior's registers.  */
 211   SENTINEL_FRAME
 212 };
 213
 214 /* For every stopped thread, GDB tracks two frames: current and
 215    selected.  Current frame is the inner most frame of the selected
 216    thread.  Selected frame is the one being examined by the the GDB
 217    CLI (selected using `up', `down', ...).  The frames are created
 218    on-demand (via get_prev_frame()) and then held in a frame cache.  */
 219 /* FIXME: cagney/2002-11-28: Er, there is a lie here.  If you do the
 220    sequence: `thread 1; up; thread 2; thread 1' you lose thread 1's
 221    selected frame.  At present GDB only tracks the selected frame of
 222    the current thread.  But be warned, that might change.  */
 223 /* FIXME: cagney/2002-11-14: At any time, only one thread's selected
 224    and current frame can be active.  Switching threads causes gdb to
 225    discard all that cached frame information.  Ulgh!  Instead, current
 226    and selected frame should be bound to a thread.  */
 227
 228 /* On demand, create the inner most frame using information found in
 229    the inferior.  If the inner most frame can't be created, throw an
 230    error.  */
 231 extern struct frame_info *get_current_frame (void);
 232
 233 /* Invalidates the frame cache (this function should have been called
 234    invalidate_cached_frames).
 235
 236    FIXME: cagney/2002-11-28: There should be two methods: one that
 237    reverts the thread's selected frame back to current frame (for when
 238    the inferior resumes) and one that does not (for when the user
 239    modifies the target invalidating the frame cache).  */
 240 extern void reinit_frame_cache (void);
 241
 242 /* On demand, create the selected frame and then return it.  If the
 243    selected frame can not be created, this function prints then throws
 244    an error.  When MESSAGE is non-NULL, use it for the error message,
 245    otherwize use a generic error message.  */
 246 /* FIXME: cagney/2002-11-28: At present, when there is no selected
 247    frame, this function always returns the current (inner most) frame.
 248    It should instead, when a thread has previously had its frame
 249    selected (but not resumed) and the frame cache invalidated, find
 250    and then return that thread's previously selected frame.  */
 251 extern struct frame_info *get_selected_frame (const char *message);
 252
 253 /* Select a specific frame.  NULL, apparently implies re-select the
 254    inner most frame.  */
 255 extern void select_frame (struct frame_info *);
 256
 257 /* Given a FRAME, return the next (more inner, younger) or previous
 258    (more outer, older) frame.  */
 259 extern struct frame_info *get_prev_frame (struct frame_info *);
 260 extern struct frame_info *get_next_frame (struct frame_info *);
 261
 262 /* Given a frame's ID, relocate the frame.  Returns NULL if the frame
 263    is not found.  */
 264 extern struct frame_info *frame_find_by_id (struct frame_id id);
 265
 266 /* Base attributes of a frame: */
 267
 268 /* The frame's `resume' address.  Where the program will resume in
 269    this frame.
 270
 271    This replaced: frame->pc; */
 272 extern CORE_ADDR get_frame_pc (struct frame_info *);
 273
 274 /* An address (not necessarily aligned to an instruction boundary)
 275    that falls within THIS frame's code block.
 276
 277    When a function call is the last statement in a block, the return
 278    address for the call may land at the start of the next block.
 279    Similarly, if a no-return function call is the last statement in
 280    the function, the return address may end up pointing beyond the
 281    function, and possibly at the start of the next function.
 282
 283    These methods make an allowance for this.  For call frames, this
 284    function returns the frame's PC-1 which "should" be an address in
 285    the frame's block.  */
 286
 287 extern CORE_ADDR get_frame_address_in_block (struct frame_info *this_frame);
 288
 289 /* The frame's inner-most bound.  AKA the stack-pointer.  Confusingly
 290    known as top-of-stack.  */
 291
 292 extern CORE_ADDR get_frame_sp (struct frame_info *);
 293
 294 /* Following on from the `resume' address.  Return the entry point
 295    address of the function containing that resume address, or zero if
 296    that function isn't known.  */
 297 extern CORE_ADDR get_frame_func (struct frame_info *fi);
 298
 299 /* Closely related to the resume address, various symbol table
 300    attributes that are determined by the PC.  Note that for a normal
 301    frame, the PC refers to the resume address after the return, and
 302    not the call instruction.  In such a case, the address is adjusted
 303    so that it (approximately) identifies the call site (and not the
 304    return site).
 305
 306    NOTE: cagney/2002-11-28: The frame cache could be used to cache the
 307    computed value.  Working on the assumption that the bottle-neck is
 308    in the single step code, and that code causes the frame cache to be
 309    constantly flushed, caching things in a frame is probably of little
 310    benefit.  As they say `show us the numbers'.
 311
 312    NOTE: cagney/2002-11-28: Plenty more where this one came from:
 313    find_frame_block(), find_frame_partial_function(),
 314    find_frame_symtab(), find_frame_function().  Each will need to be
 315    carefully considered to determine if the real intent was for it to
 316    apply to the PC or the adjusted PC.  */
 317 extern void find_frame_sal (struct frame_info *frame,
 318                             struct symtab_and_line *sal);
 319
 320 /* Set the current source and line to the location given by frame
 321    FRAME, if possible.  When CENTER is true, adjust so the relevant
 322    line is in the center of the next 'list'.  */
 323
 324 void set_current_sal_from_frame (struct frame_info *, int);
 325
 326 /* Return the frame base (what ever that is) (DEPRECATED).
 327
 328    Old code was trying to use this single method for two conflicting
 329    purposes.  Such code needs to be updated to use either of:
 330
 331    get_frame_id: A low level frame unique identifier, that consists of
 332    both a stack and a function address, that can be used to uniquely
 333    identify a frame.  This value is determined by the frame's
 334    low-level unwinder, the stack part [typically] being the
 335    top-of-stack of the previous frame, and the function part being the
 336    function's start address.  Since the correct identification of a
 337    frameless function requires both the a stack and function address,
 338    the old get_frame_base method was not sufficient.
 339
 340    get_frame_base_address: get_frame_locals_address:
 341    get_frame_args_address: A set of high-level debug-info dependant
 342    addresses that fall within the frame.  These addresses almost
 343    certainly will not match the stack address part of a frame ID (as
 344    returned by get_frame_base).
 345
 346    This replaced: frame->frame; */
 347
 348 extern CORE_ADDR get_frame_base (struct frame_info *);
 349
 350 /* Return the per-frame unique identifer.  Can be used to relocate a
 351    frame after a frame cache flush (and other similar operations).  If
 352    FI is NULL, return the null_frame_id.
 353
 354    NOTE: kettenis/20040508: These functions return a structure.  On
 355    platforms where structures are returned in static storage (vax,
 356    m68k), this may trigger compiler bugs in code like:
 357
 358    if (frame_id_eq (get_frame_id (l), get_frame_id (r)))
 359
 360    where the return value from the first get_frame_id (l) gets
 361    overwritten by the second get_frame_id (r).  Please avoid writing
 362    code like this.  Use code like:
 363
 364    struct frame_id id = get_frame_id (l);
 365    if (frame_id_eq (id, get_frame_id (r)))
 366
 367    instead, since that avoids the bug.  */
 368 extern struct frame_id get_frame_id (struct frame_info *fi);
 369 extern struct frame_id frame_unwind_caller_id (struct frame_info *next_frame);
 370
 371 /* Assuming that a frame is `normal', return its base-address, or 0 if
 372    the information isn't available.  NOTE: This address is really only
 373    meaningful to the frame's high-level debug info.  */
 374 extern CORE_ADDR get_frame_base_address (struct frame_info *);
 375
 376 /* Assuming that a frame is `normal', return the base-address of the
 377    local variables, or 0 if the information isn't available.  NOTE:
 378    This address is really only meaningful to the frame's high-level
 379    debug info.  Typically, the argument and locals share a single
 380    base-address.  */
 381 extern CORE_ADDR get_frame_locals_address (struct frame_info *);
 382
 383 /* Assuming that a frame is `normal', return the base-address of the
 384    parameter list, or 0 if that information isn't available.  NOTE:
 385    This address is really only meaningful to the frame's high-level
 386    debug info.  Typically, the argument and locals share a single
 387    base-address.  */
 388 extern CORE_ADDR get_frame_args_address (struct frame_info *);
 389
 390 /* The frame's level: 0 for innermost, 1 for its caller, ...; or -1
 391    for an invalid frame).  */
 392 extern int frame_relative_level (struct frame_info *fi);
 393
 394 /* Return the frame's type.  */
 395
 396 extern enum frame_type get_frame_type (struct frame_info *);
 397
 398 /* For frames where we can not unwind further, describe why.  */
 399
 400 enum unwind_stop_reason
 401   {
 402     /* No particular reason; either we haven't tried unwinding yet,
 403        or we didn't fail.  */
 404     UNWIND_NO_REASON,
 405
 406     /* The previous frame's analyzer returns an invalid result
 407        from this_id.
 408
 409        FIXME drow/2006-08-16: This is how GDB used to indicate end of
 410        stack.  We should migrate to a model where frames always have a
 411        valid ID, and this becomes not just an error but an internal
 412        error.  But that's a project for another day.  */
 413     UNWIND_NULL_ID,
 414
 415     /* All the conditions after this point are considered errors;
 416        abnormal stack termination.  If a backtrace stops for one
 417        of these reasons, we'll let the user know.  This marker
 418        is not a valid stop reason.  */
 419     UNWIND_FIRST_ERROR,
 420
 421     /* This frame ID looks like it ought to belong to a NEXT frame,
 422        but we got it for a PREV frame.  Normally, this is a sign of
 423        unwinder failure.  It could also indicate stack corruption.  */
 424     UNWIND_INNER_ID,
 425
 426     /* This frame has the same ID as the previous one.  That means
 427        that unwinding further would almost certainly give us another
 428        frame with exactly the same ID, so break the chain.  Normally,
 429        this is a sign of unwinder failure.  It could also indicate
 430        stack corruption.  */
 431     UNWIND_SAME_ID,
 432
 433     /* The frame unwinder didn't find any saved PC, but we needed
 434        one to unwind further.  */
 435     UNWIND_NO_SAVED_PC,
 436   };
 437
 438 /* Return the reason why we can't unwind past this frame.  */
 439
 440 enum unwind_stop_reason get_frame_unwind_stop_reason (struct frame_info *);
 441
 442 /* Translate a reason code to an informative string.  */
 443
 444 const char *frame_stop_reason_string (enum unwind_stop_reason);
 445
 446 /* Unwind the stack frame so that the value of REGNUM, in the previous
 447    (up, older) frame is returned.  If VALUEP is NULL, don't
 448    fetch/compute the value.  Instead just return the location of the
 449    value.  */
 450 extern void frame_register_unwind (struct frame_info *frame, int regnum,
 451                                    int *optimizedp, enum lval_type *lvalp,
 452                                    CORE_ADDR *addrp, int *realnump,
 453                                    gdb_byte *valuep);
 454
 455 /* Fetch a register from this, or unwind a register from the next
 456    frame.  Note that the get_frame methods are wrappers to
 457    frame->next->unwind.  They all [potentially] throw an error if the
 458    fetch fails.  The value methods never return NULL, but usually
 459    do return a lazy value.  */
 460
 461 extern void frame_unwind_register (struct frame_info *frame,
 462                                    int regnum, gdb_byte *buf);
 463 extern void get_frame_register (struct frame_info *frame,
 464                                 int regnum, gdb_byte *buf);
 465
 466 struct value *frame_unwind_register_value (struct frame_info *frame,
 467                                            int regnum);
 468 struct value *get_frame_register_value (struct frame_info *frame,
 469                                         int regnum);
 470
 471 extern LONGEST frame_unwind_register_signed (struct frame_info *frame,
 472                                              int regnum);
 473 extern LONGEST get_frame_register_signed (struct frame_info *frame,
 474                                           int regnum);
 475 extern ULONGEST frame_unwind_register_unsigned (struct frame_info *frame,
 476                                                int regnum);
 477 extern ULONGEST get_frame_register_unsigned (struct frame_info *frame,
 478                                              int regnum);
 479
 480
 481 /* Get the value of the register that belongs to this FRAME.  This
 482    function is a wrapper to the call sequence ``frame_register_unwind
 483    (get_next_frame (FRAME))''.  As per frame_register_unwind(), if
 484    VALUEP is NULL, the registers value is not fetched/computed.  */
 485
 486 extern void frame_register (struct frame_info *frame, int regnum,
 487                             int *optimizedp, enum lval_type *lvalp,
 488                             CORE_ADDR *addrp, int *realnump,
 489                             gdb_byte *valuep);
 490
 491 /* The reverse.  Store a register value relative to the specified
 492    frame.  Note: this call makes the frame's state undefined.  The
 493    register and frame caches must be flushed.  */
 494 extern void put_frame_register (struct frame_info *frame, int regnum,
 495                                 const gdb_byte *buf);
 496
 497 /* Read LEN bytes from one or multiple registers starting with REGNUM
 498    in frame FRAME, starting at OFFSET, into BUF.  */
 499 extern int get_frame_register_bytes (struct frame_info *frame, int regnum,
 500                                      CORE_ADDR offset, int len,
 501                                      gdb_byte *myaddr);
 502
 503 /* Write LEN bytes to one or multiple registers starting with REGNUM
 504    in frame FRAME, starting at OFFSET, into BUF.  */
 505 extern void put_frame_register_bytes (struct frame_info *frame, int regnum,
 506                                       CORE_ADDR offset, int len,
 507                                       const gdb_byte *myaddr);
 508
 509 /* Map between a frame register number and its name.  A frame register
 510    space is a superset of the cooked register space --- it also
 511    includes builtin registers.  If NAMELEN is negative, use the NAME's
 512    length when doing the comparison.  */
 513
 514 extern int frame_map_name_to_regnum (struct frame_info *frame,
 515                                      const char *name, int namelen);
 516 extern const char *frame_map_regnum_to_name (struct frame_info *frame,
 517                                              int regnum);
 518
 519 /* Unwind the PC.  Strictly speaking return the resume address of the
 520    calling frame.  For GDB, `pc' is the resume address and not a
 521    specific register.  */
 522
 523 extern CORE_ADDR frame_unwind_caller_pc (struct frame_info *frame);
 524
 525 /* Discard the specified frame.  Restoring the registers to the state
 526    of the caller.  */
 527 extern void frame_pop (struct frame_info *frame);
 528
 529 /* Return memory from the specified frame.  A frame knows its thread /
 530    LWP and hence can find its way down to a target.  The assumption
 531    here is that the current and previous frame share a common address
 532    space.
 533
 534    If the memory read fails, these methods throw an error.
 535
 536    NOTE: cagney/2003-06-03: Should there be unwind versions of these
 537    methods?  That isn't clear.  Can code, for instance, assume that
 538    this and the previous frame's memory or architecture are identical?
 539    If architecture / memory changes are always separated by special
 540    adaptor frames this should be ok.  */
 541
 542 extern void get_frame_memory (struct frame_info *this_frame, CORE_ADDR addr,
 543                               gdb_byte *buf, int len);
 544 extern LONGEST get_frame_memory_signed (struct frame_info *this_frame,
 545                                         CORE_ADDR memaddr, int len);
 546 extern ULONGEST get_frame_memory_unsigned (struct frame_info *this_frame,
 547                                            CORE_ADDR memaddr, int len);
 548
 549 /* Same as above, but return non-zero when the entire memory read
 550    succeeds, zero otherwize.  */
 551 extern int safe_frame_unwind_memory (struct frame_info *this_frame,
 552                                      CORE_ADDR addr, gdb_byte *buf, int len);
 553
 554 /* Return this frame's architecture.  */
 555
 556 extern struct gdbarch *get_frame_arch (struct frame_info *this_frame);
 557
 558
 559 /* Values for the source flag to be used in print_frame_info_base().  */
 560 enum print_what
 561   {
 562     /* Print only the source line, like in stepi. */
 563     SRC_LINE = -1,
 564     /* Print only the location, i.e. level, address (sometimes)
 565        function, args, file, line, line num. */
 566     LOCATION,
 567     /* Print both of the above. */
 568     SRC_AND_LOC,
 569     /* Print location only, but always include the address. */
 570     LOC_AND_ADDRESS
 571   };
 572
 573 /* Allocate zero initialized memory from the frame cache obstack.
 574    Appendices to the frame info (such as the unwind cache) should
 575    allocate memory using this method.  */
 576
 577 extern void *frame_obstack_zalloc (unsigned long size);
 578 #define FRAME_OBSTACK_ZALLOC(TYPE) ((TYPE *) frame_obstack_zalloc (sizeof (TYPE)))
 579 #define FRAME_OBSTACK_CALLOC(NUMBER,TYPE) ((TYPE *) frame_obstack_zalloc ((NUMBER) * sizeof (TYPE)))
 580
 581 /* Create a regcache, and copy the frame's registers into it.  */
 582 struct regcache *frame_save_as_regcache (struct frame_info *this_frame);
 583
 584 extern struct block *get_frame_block (struct frame_info *,
 585                                       CORE_ADDR *addr_in_block);
 586
 587 /* Return the `struct block' that belongs to the selected thread's
 588    selected frame.  If the inferior has no state, return NULL.
 589
 590    NOTE: cagney/2002-11-29:
 591
 592    No state?  Does the inferior have any execution state (a core file
 593    does, an executable does not).  At present the code tests
 594    `target_has_stack' but I'm left wondering if it should test
 595    `target_has_registers' or, even, a merged target_has_state.
 596
 597    Should it look at the most recently specified SAL?  If the target
 598    has no state, should this function try to extract a block from the
 599    most recently selected SAL?  That way `list foo' would give it some
 600    sort of reference point.  Then again, perhaps that would confuse
 601    things.
 602
 603    Calls to this function can be broken down into two categories: Code
 604    that uses the selected block as an additional, but optional, data
 605    point; Code that uses the selected block as a prop, when it should
 606    have the relevant frame/block/pc explicitly passed in.
 607
 608    The latter can be eliminated by correctly parameterizing the code,
 609    the former though is more interesting.  Per the "address" command,
 610    it occurs in the CLI code and makes it possible for commands to
 611    work, even when the inferior has no state.  */
 612
 613 extern struct block *get_selected_block (CORE_ADDR *addr_in_block);
 614
 615 extern struct symbol *get_frame_function (struct frame_info *);
 616
 617 extern CORE_ADDR get_pc_function_start (CORE_ADDR);
 618
 619 extern struct frame_info *find_relative_frame (struct frame_info *, int *);
 620
 621 extern void show_and_print_stack_frame (struct frame_info *fi, int print_level,
 622                                         enum print_what print_what);
 623
 624 extern void print_stack_frame (struct frame_info *, int print_level,
 625                                enum print_what print_what);
 626
 627 extern void print_frame_info (struct frame_info *, int print_level,
 628                               enum print_what print_what, int args);
 629
 630 extern struct frame_info *block_innermost_frame (struct block *);
 631
 632 extern int deprecated_pc_in_call_dummy (CORE_ADDR pc);
 633
 634 /* FIXME: cagney/2003-02-02: Should be deprecated or replaced with a
 635    function called get_frame_register_p().  This slightly weird (and
 636    older) variant of get_frame_register() returns zero (indicating the
 637    register is unavailable) if either: the register isn't cached; or
 638    the register has been optimized out.  Problem is, neither check is
 639    exactly correct.  A register can't be optimized out (it may not
 640    have been saved as part of a function call); The fact that a
 641    register isn't in the register cache doesn't mean that the register
 642    isn't available (it could have been fetched from memory).  */
 643
 644 extern int frame_register_read (struct frame_info *frame, int regnum,
 645                                 gdb_byte *buf);
 646
 647 /* From stack.c.  */
 648 extern void args_info (char *, int);
 649
 650 extern void locals_info (char *, int);
 651
 652 extern void (*deprecated_selected_frame_level_changed_hook) (int);
 653
 654 extern void return_command (char *, int);
 655
 656 /* Set FRAME's unwinder temporarily, so that we can call a sniffer.
 657    Return a cleanup which should be called if unwinding fails, and
 658    discarded if it succeeds.  */
 659
 660 struct cleanup *frame_prepare_for_sniffer (struct frame_info *frame,
 661                                            const struct frame_unwind *unwind);
 662
 663 /* Notes (cagney/2002-11-27, drow/2003-09-06):
 664
 665    You might think that calls to this function can simply be replaced by a
 666    call to get_selected_frame().
 667
 668    Unfortunately, it isn't that easy.
 669
 670    The relevant code needs to be audited to determine if it is
 671    possible (or practical) to instead pass the applicable frame in as a
 672    parameter.  For instance, DEPRECATED_DO_REGISTERS_INFO() relied on
 673    the deprecated_selected_frame global, while its replacement,
 674    PRINT_REGISTERS_INFO(), is parameterized with the selected frame.
 675    The only real exceptions occur at the edge (in the CLI code) where
 676    user commands need to pick up the selected frame before proceeding.
 677
 678    There are also some functions called with a NULL frame meaning either "the
 679    program is not running" or "use the selected frame".
 680
 681    This is important.  GDB is trying to stamp out the hack:
 682
 683    saved_frame = deprecated_safe_get_selected_frame ();
 684    select_frame (...);
 685    hack_using_global_selected_frame ();
 686    select_frame (saved_frame);
 687
 688    Take care!
 689
 690    This function calls get_selected_frame if the inferior should have a
 691    frame, or returns NULL otherwise.  */
 692
 693 extern struct frame_info *deprecated_safe_get_selected_frame (void);
 694
 695 /* Create a frame using the specified BASE and PC.  */
 696
 697 extern struct frame_info *create_new_frame (CORE_ADDR base, CORE_ADDR pc);
 698
 699 /* FIXME: cagney/2002-12-06: Has the PC in the current frame changed?
 700    "infrun.c", Thanks to gdbarch_decr_pc_after_break, can change the PC after
 701    the initial frame create.  This puts things back in sync.
 702
 703    This replaced: frame->pc = ....; */
 704 extern void deprecated_update_frame_pc_hack (struct frame_info *frame,
 705                                              CORE_ADDR pc);
 706
 707 /* FIXME: cagney/2002-12-18: Has the frame's base changed?  Or to be
 708    more exact, was that initial guess at the frame's base as returned
 709    by the deleted read_fp() wrong?  If it was, fix it.  This shouldn't
 710    be necessary since the code should be getting the frame's base
 711    correct from the outset.
 712
 713    This replaced: frame->frame = ....; */
 714 extern void deprecated_update_frame_base_hack (struct frame_info *frame,
 715                                                CORE_ADDR base);
 716
 717 #endif /* !defined (FRAME_H)  */