gdb/frame.h

   1 /* Definitions for dealing with stack frames, for GDB, the GNU debugger.
   2
   3    Copyright (C) 1986-2022 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20 #if !defined (FRAME_H)
  21 #define FRAME_H 1
  22
  23 #include "frame-info.h"
  24
  25 /* The following is the intended naming schema for frame functions.
  26    It isn't 100% consistent, but it is approaching that.  Frame naming
  27    schema:
  28
  29    Prefixes:
  30
  31    get_frame_WHAT...(): Get WHAT from the THIS frame (functionally
  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    get_stack_frame_WHAT...(): Get WHAT for THIS frame, but if THIS is
  43    inlined, skip to the containing stack frame.
  44
  45    put_frame_WHAT...(): Put a value into this frame (unsafe, need to
  46    invalidate the frame / regcache afterwards) (better name more
  47    strongly hinting at its unsafeness)
  48
  49    safe_....(): Safer version of various functions, doesn't throw an
  50    error (leave this for later?).  Returns true / non-NULL if the request
  51    succeeds, false / NULL otherwise.
  52
  53    Suffixes:
  54
  55    void /frame/_WHAT(): Read WHAT's value into the buffer parameter.
  56
  57    ULONGEST /frame/_WHAT_unsigned(): Return an unsigned value (the
  58    alternative is *frame_unsigned_WHAT).
  59
  60    LONGEST /frame/_WHAT_signed(): Return WHAT signed value.
  61
  62    What:
  63
  64    /frame/_memory* (frame, coreaddr, len [, buf]): Extract/return
  65    *memory.
  66
  67    /frame/_register* (frame, regnum [, buf]): extract/return register.
  68
  69    CORE_ADDR /frame/_{pc,sp,...} (frame): Resume address, innner most
  70    stack *address, ...
  71
  72    */
  73
  74 #include "language.h"
  75 #include "cli/cli-option.h"
  76 #include "gdbsupport/common-debug.h"
  77
  78 struct symtab_and_line;
  79 struct frame_unwind;
  80 struct frame_base;
  81 struct block;
  82 struct gdbarch;
  83 struct ui_file;
  84 struct ui_out;
  85 struct frame_print_options;
  86
  87 /* The frame object.  */
  88
  89 class frame_info_ptr;
  90
  91 /* Save and restore the currently selected frame.  */
  92
  93 class scoped_restore_selected_frame
  94 {
  95 public:
  96   /* Save the currently selected frame.  */
  97   scoped_restore_selected_frame ();
  98
  99   /* Restore the currently selected frame.  */
 100   ~scoped_restore_selected_frame ();
 101
 102   DISABLE_COPY_AND_ASSIGN (scoped_restore_selected_frame);
 103
 104 private:
 105
 106   /* The ID and level of the previously selected frame.  */
 107   struct frame_id m_fid;
 108   int m_level;
 109
 110   /* Save/restore the language as well, because selecting a frame
 111      changes the current language to the frame's language if "set
 112      language auto".  */
 113   enum language m_lang;
 114 };
 115
 116 /* Flag to control debugging.  */
 117
 118 extern bool frame_debug;
 119
 120 /* Print a "frame" debug statement.  */
 121
 122 #define frame_debug_printf(fmt, ...) \
 123   debug_prefixed_printf_cond (frame_debug, "frame", fmt, ##__VA_ARGS__)
 124
 125 /* Print "frame" enter/exit debug statements.  */
 126
 127 #define FRAME_SCOPED_DEBUG_ENTER_EXIT \
 128   scoped_debug_enter_exit (frame_debug, "frame")
 129
 130 /* Construct a frame ID.  The first parameter is the frame's constant
 131    stack address (typically the outer-bound), and the second the
 132    frame's constant code address (typically the entry point).
 133    The special identifier address is set to indicate a wild card.  */
 134 extern struct frame_id frame_id_build (CORE_ADDR stack_addr,
 135                                        CORE_ADDR code_addr);
 136
 137 /* Construct a special frame ID.  The first parameter is the frame's constant
 138    stack address (typically the outer-bound), the second is the
 139    frame's constant code address (typically the entry point),
 140    and the third parameter is the frame's special identifier address.  */
 141 extern struct frame_id frame_id_build_special (CORE_ADDR stack_addr,
 142                                                CORE_ADDR code_addr,
 143                                                CORE_ADDR special_addr);
 144
 145 /* Construct a frame ID representing a frame where the stack address
 146    exists, but is unavailable.  CODE_ADDR is the frame's constant code
 147    address (typically the entry point).  The special identifier
 148    address is set to indicate a wild card.  */
 149 extern struct frame_id frame_id_build_unavailable_stack (CORE_ADDR code_addr);
 150
 151 /* Construct a frame ID representing a frame where the stack address
 152    exists, but is unavailable.  CODE_ADDR is the frame's constant code
 153    address (typically the entry point).  SPECIAL_ADDR is the special
 154    identifier address.  */
 155 extern struct frame_id
 156   frame_id_build_unavailable_stack_special (CORE_ADDR code_addr,
 157                                             CORE_ADDR special_addr);
 158
 159 /* Construct a wild card frame ID.  The parameter is the frame's constant
 160    stack address (typically the outer-bound).  The code address as well
 161    as the special identifier address are set to indicate wild cards.  */
 162 extern struct frame_id frame_id_build_wild (CORE_ADDR stack_addr);
 163
 164 /* Returns true when L is a valid frame.  */
 165 extern bool frame_id_p (frame_id l);
 166
 167 /* Returns true when L is a valid frame representing a frame made up by GDB
 168    without stack data representation in inferior, such as INLINE_FRAME or
 169    TAILCALL_FRAME.  */
 170 extern bool frame_id_artificial_p (frame_id l);
 171
 172 /* Frame types.  Some are real, some are signal trampolines, and some
 173    are completely artificial (dummy).  */
 174
 175 enum frame_type
 176 {
 177   /* A true stack frame, created by the target program during normal
 178      execution.  */
 179   NORMAL_FRAME,
 180   /* A fake frame, created by GDB when performing an inferior function
 181      call.  */
 182   DUMMY_FRAME,
 183   /* A frame representing an inlined function, associated with an
 184      upcoming (prev, outer, older) NORMAL_FRAME.  */
 185   INLINE_FRAME,
 186   /* A virtual frame of a tail call - see dwarf2_tailcall_frame_unwind.  */
 187   TAILCALL_FRAME,
 188   /* In a signal handler, various OSs handle this in various ways.
 189      The main thing is that the frame may be far from normal.  */
 190   SIGTRAMP_FRAME,
 191   /* Fake frame representing a cross-architecture call.  */
 192   ARCH_FRAME,
 193   /* Sentinel or registers frame.  This frame obtains register values
 194      direct from the inferior's registers.  */
 195   SENTINEL_FRAME
 196 };
 197
 198 /* For every stopped thread, GDB tracks two frames: current and
 199    selected.  Current frame is the inner most frame of the selected
 200    thread.  Selected frame is the one being examined by the GDB
 201    CLI (selected using `up', `down', ...).  The frames are created
 202    on-demand (via get_prev_frame()) and then held in a frame cache.  */
 203 /* FIXME: cagney/2002-11-28: Er, there is a lie here.  If you do the
 204    sequence: `thread 1; up; thread 2; thread 1' you lose thread 1's
 205    selected frame.  At present GDB only tracks the selected frame of
 206    the current thread.  But be warned, that might change.  */
 207 /* FIXME: cagney/2002-11-14: At any time, only one thread's selected
 208    and current frame can be active.  Switching threads causes gdb to
 209    discard all that cached frame information.  Ulgh!  Instead, current
 210    and selected frame should be bound to a thread.  */
 211
 212 /* On demand, create the inner most frame using information found in
 213    the inferior.  If the inner most frame can't be created, throw an
 214    error.  */
 215 extern frame_info_ptr get_current_frame (void);
 216
 217 /* Does the current target interface have enough state to be able to
 218    query the current inferior for frame info, and is the inferior in a
 219    state where that is possible?  */
 220 extern bool has_stack_frames ();
 221
 222 /* Invalidates the frame cache (this function should have been called
 223    invalidate_cached_frames).
 224
 225    FIXME: cagney/2002-11-28: There should be two methods: one that
 226    reverts the thread's selected frame back to current frame (for when
 227    the inferior resumes) and one that does not (for when the user
 228    modifies the target invalidating the frame cache).  */
 229 extern void reinit_frame_cache (void);
 230
 231 /* Return the selected frame.  Always returns non-NULL.  If there
 232    isn't an inferior sufficient for creating a frame, an error is
 233    thrown.  When MESSAGE is non-NULL, use it for the error message,
 234    otherwise use a generic error message.  */
 235 /* FIXME: cagney/2002-11-28: At present, when there is no selected
 236    frame, this function always returns the current (inner most) frame.
 237    It should instead, when a thread has previously had its frame
 238    selected (but not resumed) and the frame cache invalidated, find
 239    and then return that thread's previously selected frame.  */
 240 extern frame_info_ptr get_selected_frame (const char *message = nullptr);
 241
 242 /* Select a specific frame.  */
 243 extern void select_frame (frame_info_ptr);
 244
 245 /* Save the frame ID and frame level of the selected frame in FRAME_ID
 246    and FRAME_LEVEL, to be restored later with restore_selected_frame.
 247
 248    This is preferred over getting the same info out of
 249    get_selected_frame directly because this function does not create
 250    the selected-frame's frame_info object if it hasn't been created
 251    yet, and thus is more efficient and doesn't throw.  */
 252 extern void save_selected_frame (frame_id *frame_id, int *frame_level)
 253   noexcept;
 254
 255 /* Restore selected frame as saved with save_selected_frame.
 256
 257    Does not try to find the corresponding frame_info object.  Instead
 258    the next call to get_selected_frame will look it up and cache the
 259    result.
 260
 261    This function does not throw.  It is designed to be safe to called
 262    from the destructors of RAII types.  */
 263 extern void restore_selected_frame (frame_id frame_id, int frame_level)
 264   noexcept;
 265
 266 /* Given a FRAME, return the next (more inner, younger) or previous
 267    (more outer, older) frame.  */
 268 extern frame_info_ptr get_prev_frame (frame_info_ptr);
 269 extern frame_info_ptr get_next_frame (frame_info_ptr);
 270
 271 /* Like get_next_frame(), but allows return of the sentinel frame.  NULL
 272    is never returned.  */
 273 extern frame_info_ptr get_next_frame_sentinel_okay (frame_info_ptr);
 274
 275 /* Return a "struct frame_info" corresponding to the frame that called
 276    THIS_FRAME.  Returns NULL if there is no such frame.
 277
 278    Unlike get_prev_frame, this function always tries to unwind the
 279    frame.  */
 280 extern frame_info_ptr get_prev_frame_always (frame_info_ptr);
 281
 282 /* Given a frame's ID, relocate the frame.  Returns NULL if the frame
 283    is not found.  */
 284 extern frame_info_ptr frame_find_by_id (frame_id id);
 285
 286 /* Base attributes of a frame: */
 287
 288 /* The frame's `resume' address.  Where the program will resume in
 289    this frame.
 290
 291    This replaced: frame->pc; */
 292 extern CORE_ADDR get_frame_pc (frame_info_ptr);
 293
 294 /* Same as get_frame_pc, but return a boolean indication of whether
 295    the PC is actually available, instead of throwing an error.  */
 296
 297 extern bool get_frame_pc_if_available (frame_info_ptr frame, CORE_ADDR *pc);
 298
 299 /* An address (not necessarily aligned to an instruction boundary)
 300    that falls within THIS frame's code block.
 301
 302    When a function call is the last statement in a block, the return
 303    address for the call may land at the start of the next block.
 304    Similarly, if a no-return function call is the last statement in
 305    the function, the return address may end up pointing beyond the
 306    function, and possibly at the start of the next function.
 307
 308    These methods make an allowance for this.  For call frames, this
 309    function returns the frame's PC-1 which "should" be an address in
 310    the frame's block.  */
 311
 312 extern CORE_ADDR get_frame_address_in_block (frame_info_ptr this_frame);
 313
 314 /* Same as get_frame_address_in_block, but returns a boolean
 315    indication of whether the frame address is determinable (when the
 316    PC is unavailable, it will not be), instead of possibly throwing an
 317    error trying to read an unavailable PC.  */
 318
 319 extern bool get_frame_address_in_block_if_available (frame_info_ptr this_frame,
 320                                                      CORE_ADDR *pc);
 321
 322 /* The frame's inner-most bound.  AKA the stack-pointer.  Confusingly
 323    known as top-of-stack.  */
 324
 325 extern CORE_ADDR get_frame_sp (frame_info_ptr);
 326
 327 /* Following on from the `resume' address.  Return the entry point
 328    address of the function containing that resume address, or zero if
 329    that function isn't known.  */
 330 extern CORE_ADDR get_frame_func (frame_info_ptr fi);
 331
 332 /* Same as get_frame_func, but returns a boolean indication of whether
 333    the frame function is determinable (when the PC is unavailable, it
 334    will not be), instead of possibly throwing an error trying to read
 335    an unavailable PC.  */
 336
 337 extern bool get_frame_func_if_available (frame_info_ptr fi, CORE_ADDR *);
 338
 339 /* Closely related to the resume address, various symbol table
 340    attributes that are determined by the PC.  Note that for a normal
 341    frame, the PC refers to the resume address after the return, and
 342    not the call instruction.  In such a case, the address is adjusted
 343    so that it (approximately) identifies the call site (and not the
 344    return site).
 345
 346    NOTE: cagney/2002-11-28: The frame cache could be used to cache the
 347    computed value.  Working on the assumption that the bottle-neck is
 348    in the single step code, and that code causes the frame cache to be
 349    constantly flushed, caching things in a frame is probably of little
 350    benefit.  As they say `show us the numbers'.
 351
 352    NOTE: cagney/2002-11-28: Plenty more where this one came from:
 353    find_frame_block(), find_frame_partial_function(),
 354    find_frame_symtab(), find_frame_function().  Each will need to be
 355    carefully considered to determine if the real intent was for it to
 356    apply to the PC or the adjusted PC.  */
 357 extern symtab_and_line find_frame_sal (frame_info_ptr frame);
 358
 359 /* Set the current source and line to the location given by frame
 360    FRAME, if possible.  */
 361
 362 void set_current_sal_from_frame (frame_info_ptr);
 363
 364 /* Return the frame base (what ever that is) (DEPRECATED).
 365
 366    Old code was trying to use this single method for two conflicting
 367    purposes.  Such code needs to be updated to use either of:
 368
 369    get_frame_id: A low level frame unique identifier, that consists of
 370    both a stack and a function address, that can be used to uniquely
 371    identify a frame.  This value is determined by the frame's
 372    low-level unwinder, the stack part [typically] being the
 373    top-of-stack of the previous frame, and the function part being the
 374    function's start address.  Since the correct identification of a
 375    frameless function requires both a stack and function address,
 376    the old get_frame_base method was not sufficient.
 377
 378    get_frame_base_address: get_frame_locals_address:
 379    get_frame_args_address: A set of high-level debug-info dependant
 380    addresses that fall within the frame.  These addresses almost
 381    certainly will not match the stack address part of a frame ID (as
 382    returned by get_frame_base).
 383
 384    This replaced: frame->frame; */
 385
 386 extern CORE_ADDR get_frame_base (frame_info_ptr);
 387
 388 /* Return the per-frame unique identifer.  Can be used to relocate a
 389    frame after a frame cache flush (and other similar operations).  If
 390    FI is NULL, return the null_frame_id.  */
 391 extern struct frame_id get_frame_id (frame_info_ptr fi);
 392 extern struct frame_id get_stack_frame_id (frame_info_ptr fi);
 393 extern struct frame_id frame_unwind_caller_id (frame_info_ptr next_frame);
 394
 395 /* Assuming that a frame is `normal', return its base-address, or 0 if
 396    the information isn't available.  NOTE: This address is really only
 397    meaningful to the frame's high-level debug info.  */
 398 extern CORE_ADDR get_frame_base_address (frame_info_ptr);
 399
 400 /* Assuming that a frame is `normal', return the base-address of the
 401    local variables, or 0 if the information isn't available.  NOTE:
 402    This address is really only meaningful to the frame's high-level
 403    debug info.  Typically, the argument and locals share a single
 404    base-address.  */
 405 extern CORE_ADDR get_frame_locals_address (frame_info_ptr);
 406
 407 /* Assuming that a frame is `normal', return the base-address of the
 408    parameter list, or 0 if that information isn't available.  NOTE:
 409    This address is really only meaningful to the frame's high-level
 410    debug info.  Typically, the argument and locals share a single
 411    base-address.  */
 412 extern CORE_ADDR get_frame_args_address (frame_info_ptr);
 413
 414 /* The frame's level: 0 for innermost, 1 for its caller, ...; or -1
 415    for an invalid frame).  */
 416 extern int frame_relative_level (frame_info_ptr fi);
 417
 418 /* Return the frame's type.  */
 419
 420 extern enum frame_type get_frame_type (frame_info_ptr);
 421
 422 /* Return the frame's program space.  */
 423 extern struct program_space *get_frame_program_space (frame_info_ptr);
 424
 425 /* Unwind THIS frame's program space from the NEXT frame.  */
 426 extern struct program_space *frame_unwind_program_space (frame_info_ptr);
 427
 428 class address_space;
 429
 430 /* Return the frame's address space.  */
 431 extern const address_space *get_frame_address_space (frame_info_ptr);
 432
 433 /* For frames where we can not unwind further, describe why.  */
 434
 435 enum unwind_stop_reason
 436   {
 437 #define SET(name, description) name,
 438 #define FIRST_ENTRY(name) UNWIND_FIRST = name,
 439 #define LAST_ENTRY(name) UNWIND_LAST = name,
 440 #define FIRST_ERROR(name) UNWIND_FIRST_ERROR = name,
 441
 442 #include "unwind_stop_reasons.def"
 443 #undef SET
 444 #undef FIRST_ENTRY
 445 #undef LAST_ENTRY
 446 #undef FIRST_ERROR
 447   };
 448
 449 /* Return the reason why we can't unwind past this frame.  */
 450
 451 enum unwind_stop_reason get_frame_unwind_stop_reason (frame_info_ptr);
 452
 453 /* Translate a reason code to an informative string.  This converts the
 454    generic stop reason codes into a generic string describing the code.
 455    For a possibly frame specific string explaining the stop reason, use
 456    FRAME_STOP_REASON_STRING instead.  */
 457
 458 const char *unwind_stop_reason_to_string (enum unwind_stop_reason);
 459
 460 /* Return a possibly frame specific string explaining why the unwind
 461    stopped here.  E.g., if unwinding tripped on a memory error, this
 462    will return the error description string, which includes the address
 463    that we failed to access.  If there's no specific reason stored for
 464    a frame then a generic reason string will be returned.
 465
 466    Should only be called for frames that don't have a previous frame.  */
 467
 468 const char *frame_stop_reason_string (frame_info_ptr);
 469
 470 /* Unwind the stack frame so that the value of REGNUM, in the previous
 471    (up, older) frame is returned.  If VALUEP is NULL, don't
 472    fetch/compute the value.  Instead just return the location of the
 473    value.  */
 474 extern void frame_register_unwind (frame_info_ptr frame, int regnum,
 475                                    int *optimizedp, int *unavailablep,
 476                                    enum lval_type *lvalp,
 477                                    CORE_ADDR *addrp, int *realnump,
 478                                    gdb_byte *valuep);
 479
 480 /* Fetch a register from this, or unwind a register from the next
 481    frame.  Note that the get_frame methods are wrappers to
 482    frame->next->unwind.  They all [potentially] throw an error if the
 483    fetch fails.  The value methods never return NULL, but usually
 484    do return a lazy value.  */
 485
 486 extern void frame_unwind_register (frame_info_ptr next_frame,
 487                                    int regnum, gdb_byte *buf);
 488 extern void get_frame_register (frame_info_ptr frame,
 489                                 int regnum, gdb_byte *buf);
 490
 491 struct value *frame_unwind_register_value (frame_info_ptr next_frame,
 492                                            int regnum);
 493 struct value *get_frame_register_value (frame_info_ptr frame,
 494                                         int regnum);
 495
 496 extern LONGEST frame_unwind_register_signed (frame_info_ptr next_frame,
 497                                              int regnum);
 498 extern LONGEST get_frame_register_signed (frame_info_ptr frame,
 499                                           int regnum);
 500 extern ULONGEST frame_unwind_register_unsigned (frame_info_ptr frame,
 501                                                 int regnum);
 502 extern ULONGEST get_frame_register_unsigned (frame_info_ptr frame,
 503                                              int regnum);
 504
 505 /* Read a register from this, or unwind a register from the next
 506    frame.  Note that the read_frame methods are wrappers to
 507    get_frame_register_value, that do not throw if the result is
 508    optimized out or unavailable.  */
 509
 510 extern bool read_frame_register_unsigned (frame_info_ptr frame,
 511                                           int regnum, ULONGEST *val);
 512
 513 /* The reverse.  Store a register value relative to the specified
 514    frame.  Note: this call makes the frame's state undefined.  The
 515    register and frame caches must be flushed.  */
 516 extern void put_frame_register (frame_info_ptr frame, int regnum,
 517                                 const gdb_byte *buf);
 518
 519 /* Read LEN bytes from one or multiple registers starting with REGNUM
 520    in frame FRAME, starting at OFFSET, into BUF.  If the register
 521    contents are optimized out or unavailable, set *OPTIMIZEDP,
 522    *UNAVAILABLEP accordingly.  */
 523 extern bool get_frame_register_bytes (frame_info_ptr frame, int regnum,
 524                                       CORE_ADDR offset,
 525                                       gdb::array_view<gdb_byte> buffer,
 526                                       int *optimizedp, int *unavailablep);
 527
 528 /* Write bytes from BUFFER to one or multiple registers starting with REGNUM
 529    in frame FRAME, starting at OFFSET.  */
 530 extern void put_frame_register_bytes (frame_info_ptr frame, int regnum,
 531                                       CORE_ADDR offset,
 532                                       gdb::array_view<const gdb_byte> buffer);
 533
 534 /* Unwind the PC.  Strictly speaking return the resume address of the
 535    calling frame.  For GDB, `pc' is the resume address and not a
 536    specific register.  */
 537
 538 extern CORE_ADDR frame_unwind_caller_pc (frame_info_ptr frame);
 539
 540 /* Discard the specified frame.  Restoring the registers to the state
 541    of the caller.  */
 542 extern void frame_pop (frame_info_ptr frame);
 543
 544 /* Return memory from the specified frame.  A frame knows its thread /
 545    LWP and hence can find its way down to a target.  The assumption
 546    here is that the current and previous frame share a common address
 547    space.
 548
 549    If the memory read fails, these methods throw an error.
 550
 551    NOTE: cagney/2003-06-03: Should there be unwind versions of these
 552    methods?  That isn't clear.  Can code, for instance, assume that
 553    this and the previous frame's memory or architecture are identical?
 554    If architecture / memory changes are always separated by special
 555    adaptor frames this should be ok.  */
 556
 557 extern void get_frame_memory (frame_info_ptr this_frame, CORE_ADDR addr,
 558                               gdb::array_view<gdb_byte> buffer);
 559 extern LONGEST get_frame_memory_signed (frame_info_ptr this_frame,
 560                                         CORE_ADDR memaddr, int len);
 561 extern ULONGEST get_frame_memory_unsigned (frame_info_ptr this_frame,
 562                                            CORE_ADDR memaddr, int len);
 563
 564 /* Same as above, but return true zero when the entire memory read
 565    succeeds, false otherwise.  */
 566 extern bool safe_frame_unwind_memory (frame_info_ptr this_frame, CORE_ADDR addr,
 567                                       gdb::array_view<gdb_byte> buffer);
 568
 569 /* Return this frame's architecture.  */
 570 extern struct gdbarch *get_frame_arch (frame_info_ptr this_frame);
 571
 572 /* Return the previous frame's architecture.  */
 573 extern struct gdbarch *frame_unwind_arch (frame_info_ptr next_frame);
 574
 575 /* Return the previous frame's architecture, skipping inline functions.  */
 576 extern struct gdbarch *frame_unwind_caller_arch (frame_info_ptr frame);
 577
 578
 579 /* Values for the source flag to be used in print_frame_info ().
 580    For all the cases below, the address is never printed if
 581    'set print address' is off.  When 'set print address' is on,
 582    the address is printed if the program counter is not at the
 583    beginning of the source line of the frame
 584    and PRINT_WHAT is != LOC_AND_ADDRESS.  */
 585 enum print_what
 586   {
 587     /* Print only the address, source line, like in stepi.  */
 588     SRC_LINE = -1,
 589     /* Print only the location, i.e. level, address,
 590        function, args (as controlled by 'set print frame-arguments'),
 591        file, line, line num.  */
 592     LOCATION,
 593     /* Print both of the above.  */
 594     SRC_AND_LOC,
 595     /* Print location only, print the address even if the program counter
 596        is at the beginning of the source line.  */
 597     LOC_AND_ADDRESS,
 598     /* Print only level and function,
 599        i.e. location only, without address, file, line, line num.  */
 600     SHORT_LOCATION
 601   };
 602
 603 /* Allocate zero initialized memory from the frame cache obstack.
 604    Appendices to the frame info (such as the unwind cache) should
 605    allocate memory using this method.  */
 606
 607 extern void *frame_obstack_zalloc (unsigned long size);
 608 #define FRAME_OBSTACK_ZALLOC(TYPE) \
 609   ((TYPE *) frame_obstack_zalloc (sizeof (TYPE)))
 610 #define FRAME_OBSTACK_CALLOC(NUMBER,TYPE) \
 611   ((TYPE *) frame_obstack_zalloc ((NUMBER) * sizeof (TYPE)))
 612
 613 class readonly_detached_regcache;
 614 /* Create a regcache, and copy the frame's registers into it.  */
 615 std::unique_ptr<readonly_detached_regcache> frame_save_as_regcache
 616     (frame_info_ptr this_frame);
 617
 618 extern const struct block *get_frame_block (frame_info_ptr,
 619                                             CORE_ADDR *addr_in_block);
 620
 621 /* Return the `struct block' that belongs to the selected thread's
 622    selected frame.  If the inferior has no state, return NULL.
 623
 624    NOTE: cagney/2002-11-29:
 625
 626    No state?  Does the inferior have any execution state (a core file
 627    does, an executable does not).  At present the code tests
 628    `target_has_stack' but I'm left wondering if it should test
 629    `target_has_registers' or, even, a merged target_has_state.
 630
 631    Should it look at the most recently specified SAL?  If the target
 632    has no state, should this function try to extract a block from the
 633    most recently selected SAL?  That way `list foo' would give it some
 634    sort of reference point.  Then again, perhaps that would confuse
 635    things.
 636
 637    Calls to this function can be broken down into two categories: Code
 638    that uses the selected block as an additional, but optional, data
 639    point; Code that uses the selected block as a prop, when it should
 640    have the relevant frame/block/pc explicitly passed in.
 641
 642    The latter can be eliminated by correctly parameterizing the code,
 643    the former though is more interesting.  Per the "address" command,
 644    it occurs in the CLI code and makes it possible for commands to
 645    work, even when the inferior has no state.  */
 646
 647 extern const struct block *get_selected_block (CORE_ADDR *addr_in_block);
 648
 649 extern struct symbol *get_frame_function (frame_info_ptr);
 650
 651 extern CORE_ADDR get_pc_function_start (CORE_ADDR);
 652
 653 extern frame_info_ptr find_relative_frame (frame_info_ptr, int *);
 654
 655 /* Wrapper over print_stack_frame modifying current_uiout with UIOUT for
 656    the function call.  */
 657
 658 extern void print_stack_frame_to_uiout (struct ui_out *uiout,
 659                                         frame_info_ptr, int print_level,
 660                                         enum print_what print_what,
 661                                         int set_current_sal);
 662
 663 extern void print_stack_frame (frame_info_ptr, int print_level,
 664                                enum print_what print_what,
 665                                int set_current_sal);
 666
 667 extern void print_frame_info (const frame_print_options &fp_opts,
 668                               frame_info_ptr, int print_level,
 669                               enum print_what print_what, int args,
 670                               int set_current_sal);
 671
 672 extern frame_info_ptr block_innermost_frame (const struct block *);
 673
 674 extern bool deprecated_frame_register_read (frame_info_ptr frame, int regnum,
 675                                             gdb_byte *buf);
 676
 677 /* From stack.c.  */
 678
 679 /* The possible choices of "set print frame-arguments".  */
 680 extern const char print_frame_arguments_all[];
 681 extern const char print_frame_arguments_scalars[];
 682 extern const char print_frame_arguments_none[];
 683
 684 /* The possible choices of "set print frame-info".  */
 685 extern const char print_frame_info_auto[];
 686 extern const char print_frame_info_source_line[];
 687 extern const char print_frame_info_location[];
 688 extern const char print_frame_info_source_and_location[];
 689 extern const char print_frame_info_location_and_address[];
 690 extern const char print_frame_info_short_location[];
 691
 692 /* The possible choices of "set print entry-values".  */
 693 extern const char print_entry_values_no[];
 694 extern const char print_entry_values_only[];
 695 extern const char print_entry_values_preferred[];
 696 extern const char print_entry_values_if_needed[];
 697 extern const char print_entry_values_both[];
 698 extern const char print_entry_values_compact[];
 699 extern const char print_entry_values_default[];
 700
 701 /* Data for the frame-printing "set print" settings exposed as command
 702    options.  */
 703
 704 struct frame_print_options
 705 {
 706   const char *print_frame_arguments = print_frame_arguments_scalars;
 707   const char *print_frame_info = print_frame_info_auto;
 708   const char *print_entry_values = print_entry_values_default;
 709
 710   /* If true, don't invoke pretty-printers for frame
 711      arguments.  */
 712   bool print_raw_frame_arguments;
 713 };
 714
 715 /* The values behind the global "set print ..." settings.  */
 716 extern frame_print_options user_frame_print_options;
 717
 718 /* Inferior function parameter value read in from a frame.  */
 719
 720 struct frame_arg
 721 {
 722   /* Symbol for this parameter used for example for its name.  */
 723   struct symbol *sym = nullptr;
 724
 725   /* Value of the parameter.  It is NULL if ERROR is not NULL; if both VAL and
 726      ERROR are NULL this parameter's value should not be printed.  */
 727   struct value *val = nullptr;
 728
 729   /* String containing the error message, it is more usually NULL indicating no
 730      error occured reading this parameter.  */
 731   gdb::unique_xmalloc_ptr<char> error;
 732
 733   /* One of the print_entry_values_* entries as appropriate specifically for
 734      this frame_arg.  It will be different from print_entry_values.  With
 735      print_entry_values_no this frame_arg should be printed as a normal
 736      parameter.  print_entry_values_only says it should be printed as entry
 737      value parameter.  print_entry_values_compact says it should be printed as
 738      both as a normal parameter and entry values parameter having the same
 739      value - print_entry_values_compact is not permitted fi ui_out_is_mi_like_p
 740      (in such case print_entry_values_no and print_entry_values_only is used
 741      for each parameter kind specifically.  */
 742   const char *entry_kind = nullptr;
 743 };
 744
 745 extern void read_frame_arg (const frame_print_options &fp_opts,
 746                             symbol *sym, frame_info_ptr frame,
 747                             struct frame_arg *argp,
 748                             struct frame_arg *entryargp);
 749 extern void read_frame_local (struct symbol *sym, frame_info_ptr frame,
 750                               struct frame_arg *argp);
 751
 752 extern void info_args_command (const char *, int);
 753
 754 extern void info_locals_command (const char *, int);
 755
 756 extern void return_command (const char *, int);
 757
 758 /* Set FRAME's unwinder temporarily, so that we can call a sniffer.
 759    If sniffing fails, the caller should be sure to call
 760    frame_cleanup_after_sniffer.  */
 761
 762 extern void frame_prepare_for_sniffer (frame_info_ptr frame,
 763                                        const struct frame_unwind *unwind);
 764
 765 /* Clean up after a failed (wrong unwinder) attempt to unwind past
 766    FRAME.  */
 767
 768 extern void frame_cleanup_after_sniffer (frame_info_ptr frame);
 769
 770 /* Notes (cagney/2002-11-27, drow/2003-09-06):
 771
 772    You might think that calls to this function can simply be replaced by a
 773    call to get_selected_frame().
 774
 775    Unfortunately, it isn't that easy.
 776
 777    The relevant code needs to be audited to determine if it is
 778    possible (or practical) to instead pass the applicable frame in as a
 779    parameter.  For instance, DEPRECATED_DO_REGISTERS_INFO() relied on
 780    the deprecated_selected_frame global, while its replacement,
 781    PRINT_REGISTERS_INFO(), is parameterized with the selected frame.
 782    The only real exceptions occur at the edge (in the CLI code) where
 783    user commands need to pick up the selected frame before proceeding.
 784
 785    There are also some functions called with a NULL frame meaning either "the
 786    program is not running" or "use the selected frame".
 787
 788    This is important.  GDB is trying to stamp out the hack:
 789
 790    saved_frame = deprecated_safe_get_selected_frame ();
 791    select_frame (...);
 792    hack_using_global_selected_frame ();
 793    select_frame (saved_frame);
 794
 795    Take care!
 796
 797    This function calls get_selected_frame if the inferior should have a
 798    frame, or returns NULL otherwise.  */
 799
 800 extern frame_info_ptr deprecated_safe_get_selected_frame (void);
 801
 802 /* Create a frame using the specified BASE and PC.  */
 803
 804 extern frame_info_ptr create_new_frame (CORE_ADDR base, CORE_ADDR pc);
 805
 806 /* Return true if the frame unwinder for frame FI is UNWINDER; false
 807    otherwise.  */
 808
 809 extern bool frame_unwinder_is (frame_info_ptr fi, const frame_unwind *unwinder);
 810
 811 /* Return the language of FRAME.  */
 812
 813 extern enum language get_frame_language (frame_info_ptr frame);
 814
 815 /* Return the first non-tailcall frame above FRAME or FRAME if it is not a
 816    tailcall frame.  Return NULL if FRAME is the start of a tailcall-only
 817    chain.  */
 818
 819 extern frame_info_ptr skip_tailcall_frames (frame_info_ptr frame);
 820
 821 /* Return the first frame above FRAME or FRAME of which the code is
 822    writable.  */
 823
 824 extern frame_info_ptr skip_unwritable_frames (frame_info_ptr frame);
 825
 826 /* Data for the "set backtrace" settings.  */
 827
 828 struct set_backtrace_options
 829 {
 830   /* Flag to indicate whether backtraces should continue past
 831      main.  */
 832   bool backtrace_past_main = false;
 833
 834   /* Flag to indicate whether backtraces should continue past
 835      entry.  */
 836   bool backtrace_past_entry = false;
 837
 838   /* Upper bound on the number of backtrace levels.  Note this is not
 839      exposed as a command option, because "backtrace" and "frame
 840      apply" already have other means to set a frame count limit.  */
 841   unsigned int backtrace_limit = UINT_MAX;
 842 };
 843
 844 /* The corresponding option definitions.  */
 845 extern const gdb::option::option_def set_backtrace_option_defs[2];
 846
 847 /* The values behind the global "set backtrace ..." settings.  */
 848 extern set_backtrace_options user_set_backtrace_options;
 849
 850 /* Get the number of calls to reinit_frame_cache.  */
 851
 852 unsigned int get_frame_cache_generation ();
 853
 854 /* Mark that the PC value is masked for the previous frame.  */
 855
 856 extern void set_frame_previous_pc_masked (frame_info_ptr frame);
 857
 858 /* Get whether the PC value is masked for the given frame.  */
 859
 860 extern bool get_frame_pc_masked (frame_info_ptr frame);
 861
 862
 863 #endif /* !defined (FRAME_H)  */