gdb/frame-unwind.h

   1 /* Definitions for a frame unwinder, for GDB, the GNU debugger.
   2
   3    Copyright (C) 2003-2016 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_UNWIND_H)
  21 #define FRAME_UNWIND_H 1
  22
  23 struct frame_data;
  24 struct frame_info;
  25 struct frame_id;
  26 struct frame_unwind;
  27 struct gdbarch;
  28 struct regcache;
  29 struct value;
  30
  31 #include "frame.h"              /* For enum frame_type.  */
  32
  33 /* The following unwind functions assume a chain of frames forming the
  34    sequence: (outer) prev <-> this <-> next (inner).  All the
  35    functions are called with this frame's `struct frame_info' and
  36    prologue cache.
  37
  38    THIS frame's register values can be obtained by unwinding NEXT
  39    frame's registers (a recursive operation).
  40
  41    THIS frame's prologue cache can be used to cache information such
  42    as where this frame's prologue stores the previous frame's
  43    registers.  */
  44
  45 /* Given THIS frame, take a whiff of its registers (namely
  46    the PC and attributes) and if SELF is the applicable unwinder,
  47    return non-zero.  Possibly also initialize THIS_PROLOGUE_CACHE; but
  48    only if returning 1.  Initializing THIS_PROLOGUE_CACHE in other
  49    cases (0 return, or exception) is invalid.  */
  50
  51 typedef int (frame_sniffer_ftype) (const struct frame_unwind *self,
  52                                    struct frame_info *this_frame,
  53                                    void **this_prologue_cache);
  54
  55 typedef enum unwind_stop_reason (frame_unwind_stop_reason_ftype)
  56   (struct frame_info *this_frame, void **this_prologue_cache);
  57
  58 /* A default frame sniffer which always accepts the frame.  Used by
  59    fallback prologue unwinders.  */
  60
  61 int default_frame_sniffer (const struct frame_unwind *self,
  62                            struct frame_info *this_frame,
  63                            void **this_prologue_cache);
  64
  65 /* A default stop_reason callback which always claims the frame is
  66    unwindable.  */
  67
  68 enum unwind_stop_reason
  69   default_frame_unwind_stop_reason (struct frame_info *this_frame,
  70                                     void **this_cache);
  71
  72 /* Assuming the frame chain: (outer) prev <-> this <-> next (inner);
  73    use THIS frame, and through it the NEXT frame's register unwind
  74    method, to determine the frame ID of THIS frame.
  75
  76    A frame ID provides an invariant that can be used to re-identify an
  77    instance of a frame.  It is a combination of the frame's `base' and
  78    the frame's function's code address.
  79
  80    Traditionally, THIS frame's ID was determined by examining THIS
  81    frame's function's prologue, and identifying the register/offset
  82    used as THIS frame's base.
  83
  84    Example: An examination of THIS frame's prologue reveals that, on
  85    entry, it saves the PC(+12), SP(+8), and R1(+4) registers
  86    (decrementing the SP by 12).  Consequently, the frame ID's base can
  87    be determined by adding 12 to the THIS frame's stack-pointer, and
  88    the value of THIS frame's SP can be obtained by unwinding the NEXT
  89    frame's SP.
  90
  91    THIS_PROLOGUE_CACHE can be used to share any prolog analysis data
  92    with the other unwind methods.  Memory for that cache should be
  93    allocated using FRAME_OBSTACK_ZALLOC().  */
  94
  95 typedef void (frame_this_id_ftype) (struct frame_info *this_frame,
  96                                     void **this_prologue_cache,
  97                                     struct frame_id *this_id);
  98
  99 /* Assuming the frame chain: (outer) prev <-> this <-> next (inner);
 100    use THIS frame, and implicitly the NEXT frame's register unwind
 101    method, to unwind THIS frame's registers (returning the value of
 102    the specified register REGNUM in the previous frame).
 103
 104    Traditionally, THIS frame's registers were unwound by examining
 105    THIS frame's function's prologue and identifying which registers
 106    that prolog code saved on the stack.
 107
 108    Example: An examination of THIS frame's prologue reveals that, on
 109    entry, it saves the PC(+12), SP(+8), and R1(+4) registers
 110    (decrementing the SP by 12).  Consequently, the value of the PC
 111    register in the previous frame is found in memory at SP+12, and
 112    THIS frame's SP can be obtained by unwinding the NEXT frame's SP.
 113
 114    This function takes THIS_FRAME as an argument.  It can find the
 115    values of registers in THIS frame by calling get_frame_register
 116    (THIS_FRAME), and reinvoke itself to find other registers in the
 117    PREVIOUS frame by calling frame_unwind_register (THIS_FRAME).
 118
 119    The result is a GDB value object describing the register value.  It
 120    may be a lazy reference to memory, a lazy reference to the value of
 121    a register in THIS frame, or a non-lvalue.
 122
 123    THIS_PROLOGUE_CACHE can be used to share any prolog analysis data
 124    with the other unwind methods.  Memory for that cache should be
 125    allocated using FRAME_OBSTACK_ZALLOC().  */
 126
 127 typedef struct value * (frame_prev_register_ftype)
 128   (struct frame_info *this_frame, void **this_prologue_cache,
 129    int regnum);
 130
 131 /* Deallocate extra memory associated with the frame cache if any.  */
 132
 133 typedef void (frame_dealloc_cache_ftype) (struct frame_info *self,
 134                                           void *this_cache);
 135
 136 /* Assuming the frame chain: (outer) prev <-> this <-> next (inner);
 137    use THIS frame, and implicitly the NEXT frame's register unwind
 138    method, return PREV frame's architecture.  */
 139
 140 typedef struct gdbarch *(frame_prev_arch_ftype) (struct frame_info *this_frame,
 141                                                  void **this_prologue_cache);
 142
 143 struct frame_unwind
 144 {
 145   /* The frame's type.  Should this instead be a collection of
 146      predicates that test the frame for various attributes?  */
 147   enum frame_type type;
 148   /* Should an attribute indicating the frame's address-in-block go
 149      here?  */
 150   frame_unwind_stop_reason_ftype *stop_reason;
 151   frame_this_id_ftype *this_id;
 152   frame_prev_register_ftype *prev_register;
 153   const struct frame_data *unwind_data;
 154   frame_sniffer_ftype *sniffer;
 155   frame_dealloc_cache_ftype *dealloc_cache;
 156   frame_prev_arch_ftype *prev_arch;
 157 };
 158
 159 /* Register a frame unwinder, _prepending_ it to the front of the
 160    search list (so it is sniffed before previously registered
 161    unwinders).  By using a prepend, later calls can install unwinders
 162    that override earlier calls.  This allows, for instance, an OSABI
 163    to install a more specific sigtramp unwinder that overrides the
 164    traditional brute-force unwinder.  */
 165 extern void frame_unwind_prepend_unwinder (struct gdbarch *,
 166                                            const struct frame_unwind *);
 167
 168 /* Add a frame sniffer to the list.  The predicates are polled in the
 169    order that they are appended.  The initial list contains the dummy
 170    frame sniffer.  */
 171
 172 extern void frame_unwind_append_unwinder (struct gdbarch *gdbarch,
 173                                           const struct frame_unwind *unwinder);
 174
 175 /* Iterate through sniffers for THIS_FRAME frame until one returns with an
 176    unwinder implementation.  THIS_FRAME->UNWIND must be NULL, it will get set
 177    by this function.  Possibly initialize THIS_CACHE.  */
 178
 179 extern void frame_unwind_find_by_frame (struct frame_info *this_frame,
 180                                         void **this_cache);
 181
 182 /* Helper functions for value-based register unwinding.  These return
 183    a (possibly lazy) value of the appropriate type.  */
 184
 185 /* Return a value which indicates that FRAME did not save REGNUM.  */
 186
 187 struct value *frame_unwind_got_optimized (struct frame_info *frame,
 188                                           int regnum);
 189
 190 /* Return a value which indicates that FRAME copied REGNUM into
 191    register NEW_REGNUM.  */
 192
 193 struct value *frame_unwind_got_register (struct frame_info *frame, int regnum,
 194                                          int new_regnum);
 195
 196 /* Return a value which indicates that FRAME saved REGNUM in memory at
 197    ADDR.  */
 198
 199 struct value *frame_unwind_got_memory (struct frame_info *frame, int regnum,
 200                                        CORE_ADDR addr);
 201
 202 /* Return a value which indicates that FRAME's saved version of
 203    REGNUM has a known constant (computed) value of VAL.  */
 204
 205 struct value *frame_unwind_got_constant (struct frame_info *frame, int regnum,
 206                                          ULONGEST val);
 207
 208 /* Return a value which indicates that FRAME's saved version of
 209    REGNUM has a known constant (computed) value which is stored
 210    inside BUF.  */
 211
 212 struct value *frame_unwind_got_bytes (struct frame_info *frame, int regnum,
 213                                       gdb_byte *buf);
 214
 215 /* Return a value which indicates that FRAME's saved version of REGNUM
 216    has a known constant (computed) value of ADDR.  Convert the
 217    CORE_ADDR to a target address if necessary.  */
 218
 219 struct value *frame_unwind_got_address (struct frame_info *frame, int regnum,
 220                                         CORE_ADDR addr);
 221
 222 #endif