1 /* Definitions for a frame unwinder, for GDB, the GNU debugger. 2 3 Copyright 2003, 2004 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 2 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, write to the Free Software 19 Foundation, Inc., 59 Temple Place - Suite 330, 20 Boston, MA 02111-1307, USA. */ 21 22 #if !defined (FRAME_UNWIND_H) 23 #define FRAME_UNWIND_H 1 24 25 struct frame_data; 26 struct frame_info; 27 struct frame_id; 28 struct frame_unwind; 29 struct gdbarch; 30 struct regcache; 31 32 #include "frame.h" /* For enum frame_type. */ 33 34 /* The following unwind functions assume a chain of frames forming the 35 sequence: (outer) prev <-> this <-> next (inner). All the 36 functions are called with called with the next frame's `struct 37 frame_info' and and this frame's prologue cache. 38 39 THIS frame's register values can be obtained by unwinding NEXT 40 frame's registers (a recursive operation). 41 42 THIS frame's prologue cache can be used to cache information such 43 as where this frame's prologue stores the previous frame's 44 registers. */ 45 46 /* Given the NEXT frame, take a wiff of THIS frame's registers (namely 47 the PC and attributes) and if SELF is the applicable unwinder, 48 return non-zero. Possibly also initialize THIS_PROLOGUE_CACHE. */ 49 50 typedef int (frame_sniffer_ftype) (const struct frame_unwind *self, 51 struct frame_info *next_frame, 52 void **this_prologue_cache); 53 54 /* Assuming the frame chain: (outer) prev <-> this <-> next (inner); 55 use the NEXT frame, and its register unwind method, to determine 56 the frame ID of THIS frame. 57 58 A frame ID provides an invariant that can be used to re-identify an 59 instance of a frame. It is a combination of the frame's `base' and 60 the frame's function's code address. 61 62 Traditionally, THIS frame's ID was determined by examining THIS 63 frame's function's prologue, and identifying the register/offset 64 used as THIS frame's base. 65 66 Example: An examination of THIS frame's prologue reveals that, on 67 entry, it saves the PC(+12), SP(+8), and R1(+4) registers 68 (decrementing the SP by 12). Consequently, the frame ID's base can 69 be determined by adding 12 to the THIS frame's stack-pointer, and 70 the value of THIS frame's SP can be obtained by unwinding the NEXT 71 frame's SP. 72 73 THIS_PROLOGUE_CACHE can be used to share any prolog analysis data 74 with the other unwind methods. Memory for that cache should be 75 allocated using frame_obstack_zalloc(). */ 76 77 typedef void (frame_this_id_ftype) (struct frame_info *next_frame, 78 void **this_prologue_cache, 79 struct frame_id *this_id); 80 81 /* Assuming the frame chain: (outer) prev <-> this <-> next (inner); 82 use the NEXT frame, and its register unwind method, to unwind THIS 83 frame's registers (returning the value of the specified register 84 REGNUM in the previous frame). 85 86 Traditionally, THIS frame's registers were unwound by examining 87 THIS frame's function's prologue and identifying which registers 88 that prolog code saved on the stack. 89 90 Example: An examination of THIS frame's prologue reveals that, on 91 entry, it saves the PC(+12), SP(+8), and R1(+4) registers 92 (decrementing the SP by 12). Consequently, the value of the PC 93 register in the previous frame is found in memory at SP+12, and 94 THIS frame's SP can be obtained by unwinding the NEXT frame's SP. 95 96 Why not pass in THIS_FRAME? By passing in NEXT frame and THIS 97 cache, the supplied parameters are consistent with the sibling 98 function THIS_ID. 99 100 Can the code call ``frame_register (get_prev_frame (NEXT_FRAME))''? 101 Won't the call frame_register (THIS_FRAME) be faster? Well, 102 ignoring the possability that the previous frame does not yet 103 exist, the ``frame_register (FRAME)'' function is expanded to 104 ``frame_register_unwind (get_next_frame (FRAME)'' and hence that 105 call will expand to ``frame_register_unwind (get_next_frame 106 (get_prev_frame (NEXT_FRAME)))''. Might as well call 107 ``frame_register_unwind (NEXT_FRAME)'' directly. 108 109 THIS_PROLOGUE_CACHE can be used to share any prolog analysis data 110 with the other unwind methods. Memory for that cache should be 111 allocated using frame_obstack_zalloc(). */ 112 113 typedef void (frame_prev_register_ftype) (struct frame_info *next_frame, 114 void **this_prologue_cache, 115 int prev_regnum, 116 int *optimized, 117 enum lval_type * lvalp, 118 CORE_ADDR *addrp, 119 int *realnump, void *valuep); 120 121 struct frame_unwind 122 { 123 /* The frame's type. Should this instead be a collection of 124 predicates that test the frame for various attributes? */ 125 enum frame_type type; 126 /* Should an attribute indicating the frame's address-in-block go 127 here? */ 128 frame_this_id_ftype *this_id; 129 frame_prev_register_ftype *prev_register; 130 const struct frame_data *unwind_data; 131 frame_sniffer_ftype *sniffer; 132 }; 133 134 /* Register a frame unwinder, _prepending_ it to the front of the 135 search list (so it is sniffed before previously registered 136 unwinders). By using a prepend, later calls can install unwinders 137 that override earlier calls. This allows, for instance, an OSABI 138 to install a a more specific sigtramp unwinder that overrides the 139 traditional brute-force unwinder. */ 140 extern void frame_unwind_prepend_unwinder (struct gdbarch *gdbarch, 141 const struct frame_unwind *unwinder); 142 143 /* Given the NEXT frame, take a wiff of THIS frame's registers (namely 144 the PC and attributes) and if it is the applicable unwinder return 145 the unwind methods, or NULL if it is not. */ 146 147 typedef const struct frame_unwind *(frame_unwind_sniffer_ftype) (struct frame_info *next_frame); 148 149 /* Add a frame sniffer to the list. The predicates are polled in the 150 order that they are appended. The initial list contains the dummy 151 frame sniffer. */ 152 153 extern void frame_unwind_append_sniffer (struct gdbarch *gdbarch, 154 frame_unwind_sniffer_ftype *sniffer); 155 156 /* Iterate through the next frame's sniffers until one returns with an 157 unwinder implementation. Possibly initialize THIS_CACHE. */ 158 159 extern const struct frame_unwind *frame_unwind_find_by_frame (struct frame_info *next_frame, 160 void **this_cache); 161 162 #endif 163