gdb/frame-id.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 #ifndef GDB_FRAME_ID_H
  21 #define GDB_FRAME_ID_H 1
  22
  23 /* Status of a given frame's stack.  */
  24
  25 enum frame_id_stack_status
  26 {
  27   /* Stack address is invalid.  */
  28   FID_STACK_INVALID = 0,
  29
  30   /* Stack address is valid, and is found in the stack_addr field.  */
  31   FID_STACK_VALID = 1,
  32
  33   /* Sentinel frame.  */
  34   FID_STACK_SENTINEL = 2,
  35
  36   /* Outer frame.  Since a frame's stack address is typically defined as the
  37      value the stack pointer had prior to the activation of the frame, an outer
  38      frame doesn't have a stack address.  The frame ids of frames inlined in the
  39      outer frame are also of this type.  */
  40   FID_STACK_OUTER = 3,
  41
  42   /* Stack address is unavailable.  I.e., there's a valid stack, but
  43      we don't know where it is (because memory or registers we'd
  44      compute it from were not collected).  */
  45   FID_STACK_UNAVAILABLE = -1
  46 };
  47
  48 /* The frame object's ID.  This provides a per-frame unique identifier
  49    that can be used to relocate a `struct frame_info' after a target
  50    resume or a frame cache destruct.  It of course assumes that the
  51    inferior hasn't unwound the stack past that frame.  */
  52
  53 struct frame_id
  54 {
  55   /* The frame's stack address.  This shall be constant through out
  56      the lifetime of a frame.  Note that this requirement applies to
  57      not just the function body, but also the prologue and (in theory
  58      at least) the epilogue.  Since that value needs to fall either on
  59      the boundary, or within the frame's address range, the frame's
  60      outer-most address (the inner-most address of the previous frame)
  61      is used.  Watch out for all the legacy targets that still use the
  62      function pointer register or stack pointer register.  They are
  63      wrong.
  64
  65      This field is valid only if frame_id.stack_status is
  66      FID_STACK_VALID.  It will be 0 for other
  67      FID_STACK_... statuses.  */
  68   CORE_ADDR stack_addr;
  69
  70   /* The frame's code address.  This shall be constant through out the
  71      lifetime of the frame.  While the PC (a.k.a. resume address)
  72      changes as the function is executed, this code address cannot.
  73      Typically, it is set to the address of the entry point of the
  74      frame's function (as returned by get_frame_func).
  75
  76      For inlined functions (INLINE_DEPTH != 0), this is the address of
  77      the first executed instruction in the block corresponding to the
  78      inlined function.
  79
  80      This field is valid only if code_addr_p is true.  Otherwise, this
  81      frame is considered to have a wildcard code address, i.e. one that
  82      matches every address value in frame comparisons.  */
  83   CORE_ADDR code_addr;
  84
  85   /* The frame's special address.  This shall be constant through out the
  86      lifetime of the frame.  This is used for architectures that may have
  87      frames that do not change the stack but are still distinct and have
  88      some form of distinct identifier (e.g. the ia64 which uses a 2nd
  89      stack for registers).  This field is treated as unordered - i.e. will
  90      not be used in frame ordering comparisons.
  91
  92      This field is valid only if special_addr_p is true.  Otherwise, this
  93      frame is considered to have a wildcard special address, i.e. one that
  94      matches every address value in frame comparisons.  */
  95   CORE_ADDR special_addr;
  96
  97   /* Flags to indicate the above fields have valid contents.  */
  98   ENUM_BITFIELD(frame_id_stack_status) stack_status : 3;
  99   unsigned int code_addr_p : 1;
 100   unsigned int special_addr_p : 1;
 101
 102   /* It is non-zero for a frame made up by GDB without stack data
 103      representation in inferior, such as INLINE_FRAME or TAILCALL_FRAME.
 104      Caller of inlined function will have it zero, each more inner called frame
 105      will have it increasingly one, two etc.  Similarly for TAILCALL_FRAME.  */
 106   int artificial_depth;
 107
 108   /* Return a string representation of this frame id.  */
 109   std::string to_string () const;
 110
 111   /* Returns true when this frame_id and R identify the same
 112      frame.  */
 113   bool operator== (const frame_id &r) const;
 114
 115   /* Inverse of ==.  */
 116   bool operator!= (const frame_id &r) const
 117   {
 118     return !(*this == r);
 119   }
 120 };
 121
 122 /* Methods for constructing and comparing Frame IDs.  */
 123
 124 /* For convenience.  All fields are zero.  This means "there is no frame".  */
 125 extern const struct frame_id null_frame_id;
 126
 127 /* Sentinel frame.  */
 128 extern const struct frame_id sentinel_frame_id;
 129
 130 /* This means "there is no frame ID, but there is a frame".  It should be
 131    replaced by best-effort frame IDs for the outermost frame, somehow.
 132    The implementation is only special_addr_p set.  */
 133 extern const struct frame_id outer_frame_id;
 134
 135 #endif /* ifdef GDB_FRAME_ID_H  */