gdb/dwarf2/frame.h

   1 /* Frame unwinder for frames with DWARF Call Frame Information.
   2
   3    Copyright (C) 2003-2024 Free Software Foundation, Inc.
   4
   5    Contributed by Mark Kettenis.
   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 #ifndef DWARF2_FRAME_H
  23 #define DWARF2_FRAME_H 1
  24
  25 struct gdbarch;
  26 class frame_info_ptr;
  27 struct dwarf2_per_cu_data;
  28 struct agent_expr;
  29 struct axs_value;
  30
  31 /* Register rule.  */
  32
  33 enum dwarf2_frame_reg_rule
  34 {
  35   /* Make certain that 0 maps onto the correct enum value; the
  36      corresponding structure is being initialized using memset zero.
  37      This indicates that CFI didn't provide any information at all
  38      about a register, leaving how to obtain its value totally
  39      unspecified.  */
  40   DWARF2_FRAME_REG_UNSPECIFIED = 0,
  41
  42   /* The term "undefined" comes from the DWARF2 CFI spec which this
  43      code is modeling; it indicates that the register's value is
  44      "undefined".  GCC uses the less formal term "unsaved".  Its
  45      definition is a combination of REG_UNDEFINED and REG_UNSPECIFIED.
  46      The failure to differentiate the two helps explain a few problems
  47      with the CFI generated by GCC.  */
  48   DWARF2_FRAME_REG_UNDEFINED,
  49   DWARF2_FRAME_REG_SAVED_OFFSET,
  50   DWARF2_FRAME_REG_SAVED_REG,
  51   DWARF2_FRAME_REG_SAVED_EXP,
  52   DWARF2_FRAME_REG_SAME_VALUE,
  53
  54   /* These are defined in Dwarf3.  */
  55   DWARF2_FRAME_REG_SAVED_VAL_OFFSET,
  56   DWARF2_FRAME_REG_SAVED_VAL_EXP,
  57
  58   /* These aren't defined by the DWARF2 CFI specification, but are
  59      used internally by GDB.  */
  60   DWARF2_FRAME_REG_FN,          /* Call a registered function.  */
  61   DWARF2_FRAME_REG_RA,          /* Return Address.  */
  62   DWARF2_FRAME_REG_RA_OFFSET,   /* Return Address with offset.  */
  63   DWARF2_FRAME_REG_CFA,         /* Call Frame Address.  */
  64   DWARF2_FRAME_REG_CFA_OFFSET   /* Call Frame Address with offset.  */
  65 };
  66
  67 /* Register state.  */
  68
  69 typedef struct value *(*fn_prev_register) (frame_info_ptr this_frame,
  70                                            void **this_cache, int regnum);
  71
  72 struct dwarf2_frame_state_reg
  73 {
  74   /* Each register save state can be described in terms of a CFA slot,
  75      another register, or a location expression.  */
  76   union {
  77     LONGEST offset;
  78     ULONGEST reg;
  79     struct
  80     {
  81       const gdb_byte *start;
  82       ULONGEST len;
  83     } exp;
  84     fn_prev_register fn;
  85   } loc;
  86   enum dwarf2_frame_reg_rule how;
  87 };
  88
  89 enum cfa_how_kind
  90 {
  91   CFA_UNSET,
  92   CFA_REG_OFFSET,
  93   CFA_EXP
  94 };
  95
  96 struct dwarf2_frame_state_reg_info
  97 {
  98   dwarf2_frame_state_reg_info () = default;
  99   ~dwarf2_frame_state_reg_info ()
 100   {
 101     delete prev;
 102   }
 103
 104   /* Copy constructor.  */
 105   dwarf2_frame_state_reg_info (const dwarf2_frame_state_reg_info &src)
 106     : reg (src.reg), cfa_offset (src.cfa_offset),
 107       cfa_reg (src.cfa_reg), cfa_how (src.cfa_how), cfa_exp (src.cfa_exp),
 108       prev (src.prev)
 109   {
 110   }
 111
 112   /* Assignment operator for both move-assignment and copy-assignment.  */
 113   dwarf2_frame_state_reg_info&
 114   operator= (dwarf2_frame_state_reg_info rhs)
 115   {
 116     swap (*this, rhs);
 117     return *this;
 118   }
 119
 120   /* Move constructor.  */
 121   dwarf2_frame_state_reg_info (dwarf2_frame_state_reg_info &&rhs) noexcept
 122     : reg (std::move (rhs.reg)), cfa_offset (rhs.cfa_offset),
 123       cfa_reg (rhs.cfa_reg), cfa_how (rhs.cfa_how), cfa_exp (rhs.cfa_exp),
 124       prev (rhs.prev)
 125   {
 126     rhs.prev = nullptr;
 127   }
 128
 129   /* If necessary, enlarge the register set to hold NUM_REGS_REQUESTED
 130      registers.  */
 131   void alloc_regs (int num_regs_requested)
 132   {
 133     gdb_assert (num_regs_requested > 0);
 134
 135     if (num_regs_requested <= reg.size ())
 136       return;
 137
 138     reg.resize (num_regs_requested);
 139   }
 140
 141   std::vector<struct dwarf2_frame_state_reg> reg;
 142
 143   LONGEST cfa_offset = 0;
 144   ULONGEST cfa_reg = 0;
 145   enum cfa_how_kind cfa_how = CFA_UNSET;
 146   const gdb_byte *cfa_exp = NULL;
 147
 148   /* Used to implement DW_CFA_remember_state.  */
 149   struct dwarf2_frame_state_reg_info *prev = NULL;
 150
 151 private:
 152   friend void swap (dwarf2_frame_state_reg_info& lhs,
 153                     dwarf2_frame_state_reg_info& rhs)
 154   {
 155     using std::swap;
 156
 157     swap (lhs.reg, rhs.reg);
 158     swap (lhs.cfa_offset, rhs.cfa_offset);
 159     swap (lhs.cfa_reg, rhs.cfa_reg);
 160     swap (lhs.cfa_how, rhs.cfa_how);
 161     swap (lhs.cfa_exp, rhs.cfa_exp);
 162     swap (lhs.prev, rhs.prev);
 163   }
 164 };
 165
 166 struct dwarf2_cie;
 167
 168 /* Structure describing a frame state.  */
 169
 170 struct dwarf2_frame_state
 171 {
 172   dwarf2_frame_state (CORE_ADDR pc, struct dwarf2_cie *cie);
 173
 174   /* Each register save state can be described in terms of a CFA slot,
 175      another register, or a location expression.  */
 176   struct dwarf2_frame_state_reg_info regs {};
 177
 178   /* The PC described by the current frame state.  */
 179   CORE_ADDR pc;
 180
 181   /* Initial register set from the CIE.
 182      Used to implement DW_CFA_restore.  */
 183   struct dwarf2_frame_state_reg_info initial {};
 184
 185   /* The information we care about from the CIE.  */
 186   const LONGEST data_align;
 187   const ULONGEST code_align;
 188   const ULONGEST retaddr_column;
 189
 190   /* Flags for known producer quirks.  */
 191
 192   /* The ARM compilers, in DWARF2 mode, assume that DW_CFA_def_cfa
 193      and DW_CFA_def_cfa_offset takes a factored offset.  */
 194   bool armcc_cfa_offsets_sf = false;
 195
 196   /* The ARM compilers, in DWARF2 or DWARF3 mode, may assume that
 197      the CFA is defined as REG - OFFSET rather than REG + OFFSET.  */
 198   bool armcc_cfa_offsets_reversed = false;
 199 };
 200
 201 /* When this is true the DWARF frame unwinders can be used if they are
 202    registered with the gdbarch.  Not all architectures can or do use the
 203    DWARF unwinders.  Setting this to true on a target that does not
 204    otherwise support the DWARF unwinders has no effect.  */
 205 extern bool dwarf2_frame_unwinders_enabled_p;
 206
 207 /* Set the architecture-specific register state initialization
 208    function for GDBARCH to INIT_REG.  */
 209
 210 extern void dwarf2_frame_set_init_reg (struct gdbarch *gdbarch,
 211                                        void (*init_reg) (struct gdbarch *, int,
 212                                              struct dwarf2_frame_state_reg *,
 213                                              frame_info_ptr));
 214
 215 /* Set the architecture-specific signal trampoline recognition
 216    function for GDBARCH to SIGNAL_FRAME_P.  */
 217
 218 extern void
 219   dwarf2_frame_set_signal_frame_p (struct gdbarch *gdbarch,
 220                                    int (*signal_frame_p) (struct gdbarch *,
 221                                                           frame_info_ptr));
 222
 223 /* Set the architecture-specific adjustment of .eh_frame and .debug_frame
 224    register numbers.  */
 225
 226 extern void
 227   dwarf2_frame_set_adjust_regnum (struct gdbarch *gdbarch,
 228                                   int (*adjust_regnum) (struct gdbarch *,
 229                                                         int, int));
 230
 231 /* Append the DWARF-2 frame unwinders to GDBARCH's list.  */
 232
 233 void dwarf2_append_unwinders (struct gdbarch *gdbarch);
 234
 235 /* Return the frame base methods for the function that contains PC, or
 236    NULL if it can't be handled by the DWARF CFI frame unwinder.  */
 237
 238 extern const struct frame_base *
 239   dwarf2_frame_base_sniffer (frame_info_ptr this_frame);
 240
 241 /* Compute the DWARF CFA for a frame.  */
 242
 243 CORE_ADDR dwarf2_frame_cfa (frame_info_ptr this_frame);
 244
 245 /* Find the CFA information for PC.
 246
 247    Return 1 if a register is used for the CFA, or 0 if another
 248    expression is used.  Throw an exception on error.
 249
 250    GDBARCH is the architecture to use.
 251    DATA is the per-CU data.
 252
 253    REGNUM_OUT is an out parameter that is set to the register number.
 254    OFFSET_OUT is the offset to use from this register.
 255    These are only filled in when 1 is returned.
 256
 257    TEXT_OFFSET_OUT, CFA_START_OUT, and CFA_END_OUT describe the CFA
 258    in other cases.  These are only used when 0 is returned.  */
 259
 260 extern int dwarf2_fetch_cfa_info (struct gdbarch *gdbarch, CORE_ADDR pc,
 261                                   struct dwarf2_per_cu_data *data,
 262                                   int *regnum_out, LONGEST *offset_out,
 263                                   CORE_ADDR *text_offset_out,
 264                                   const gdb_byte **cfa_start_out,
 265                                   const gdb_byte **cfa_end_out);
 266
 267
 268 /* Allocate a new instance of the function unique data.
 269
 270    The main purpose of this custom function data object is to allow caching the
 271    value of expensive lookups in the prev_register implementation.
 272
 273    THIS_FRAME is the frame that the custom data object should be associated
 274    with.
 275    THIS_CACHE is the dwarf2 cache object to store the pointer on.
 276    COOKIE is the key for the prev_function implementation.
 277    SIZE is the size of the custom data object to allocate.  */
 278
 279 extern void *dwarf2_frame_allocate_fn_data (frame_info_ptr this_frame,
 280                                             void **this_cache,
 281                                             fn_prev_register cookie,
 282                                             unsigned long size);
 283
 284 /* Retrieve the function unique data for this frame or NULL if none exists.
 285
 286    The main purpose of this custom function data object is to allow caching the
 287    value of expensive lookups in the prev_register implementation.
 288
 289    THIS_FRAME is the frame that the custom data object should be associated
 290    with.
 291    THIS_CACHE is the dwarf2 cache object to store the pointer on.
 292    COOKIE is the key for the prev_function implementation.  */
 293
 294 extern void *dwarf2_frame_get_fn_data (frame_info_ptr this_frame,
 295                                        void **this_cache,
 296                                        fn_prev_register cookie);
 297
 298 #endif /* dwarf2-frame.h */