Commit | Line | Data |
---|---|---|
494cca16 AC |
1 | /* Definitions for a frame unwinder, for GDB, the GNU debugger. |
2 | ||
3 | Copyright 2003 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_info; | |
26 | struct frame_id; | |
27 | struct frame_unwind; | |
28 | struct gdbarch; | |
29 | struct regcache; | |
30 | ||
31 | /* Return the frame unwind methods for the function that contains PC, | |
32 | or NULL if this this unwinder can't handle this frame. */ | |
33 | ||
34 | typedef const struct frame_unwind *(frame_unwind_p_ftype) (CORE_ADDR pc); | |
35 | ||
36 | /* Add a frame unwinder to the list. The predicates are polled in the | |
37 | order that they are appended. The initial list contains the dummy | |
38 | frame's predicate. */ | |
39 | ||
40 | extern void frame_unwind_append_predicate (struct gdbarch *gdbarch, | |
41 | frame_unwind_p_ftype *p); | |
42 | ||
43 | /* Iterate through the list of frame unwinders until one returns an | |
44 | implementation. */ | |
45 | ||
46 | extern const struct frame_unwind *frame_unwind_find_by_pc (struct gdbarch | |
47 | *gdbarch, | |
48 | CORE_ADDR pc); | |
49 | ||
6dc42492 AC |
50 | /* The following unwind functions assume a chain of frames forming the |
51 | sequence: (outer) prev <-> this <-> next (inner). All the | |
52 | functions are called with called with the next frame's `struct | |
53 | frame_info' and and this frame's prologue cache. | |
54 | ||
55 | THIS frame's register values can be obtained by unwinding NEXT | |
56 | frame's registers (a recursive operation). | |
57 | ||
58 | THIS frame's prologue cache can be used to cache information such | |
59 | as where this frame's prologue stores the previous frame's | |
60 | registers. */ | |
61 | ||
62 | /* Assuming the frame chain: (outer) prev <-> this <-> next (inner); | |
63 | use the NEXT frame, and its register unwind method, to determine | |
64 | the frame ID of THIS frame. | |
65 | ||
66 | A frame ID provides an invariant that can be used to re-identify an | |
67 | instance of a frame. It is a combination of the frame's `base' and | |
68 | the frame's function's code address. | |
69 | ||
70 | Traditionally, THIS frame's ID was determined by examining THIS | |
71 | frame's function's prologue, and identifying the register/offset | |
72 | used as THIS frame's base. | |
73 | ||
74 | Example: An examination of THIS frame's prologue reveals that, on | |
75 | entry, it saves the PC(+12), SP(+8), and R1(+4) registers | |
76 | (decrementing the SP by 12). Consequently, the frame ID's base can | |
77 | be determined by adding 12 to the THIS frame's stack-pointer, and | |
78 | the value of THIS frame's SP can be obtained by unwinding the NEXT | |
79 | frame's SP. | |
80 | ||
81 | THIS_PROLOGUE_CACHE can be used to share any prolog analysis data | |
82 | with the other unwind methods. Memory for that cache should be | |
83 | allocated using frame_obstack_zalloc(). */ | |
84 | ||
85 | typedef void (frame_this_id_ftype) (struct frame_info *next_frame, | |
86 | void **this_prologue_cache, | |
87 | struct frame_id *this_id); | |
88 | ||
89 | /* Assuming the frame chain: (outer) prev <-> this <-> next (inner); | |
90 | use the NEXT frame, and its register unwind method, to unwind THIS | |
91 | frame's registers (returning the value of the specified register | |
92 | REGNUM in the previous frame). | |
93 | ||
94 | Traditionally, THIS frame's registers were unwound by examining | |
95 | THIS frame's function's prologue and identifying which registers | |
96 | that prolog code saved on the stack. | |
97 | ||
98 | Example: An examination of THIS frame's prologue reveals that, on | |
99 | entry, it saves the PC(+12), SP(+8), and R1(+4) registers | |
100 | (decrementing the SP by 12). Consequently, the value of the PC | |
101 | register in the previous frame is found in memory at SP+12, and | |
102 | THIS frame's SP can be obtained by unwinding the NEXT frame's SP. | |
103 | ||
104 | Why not pass in THIS_FRAME? By passing in NEXT frame and THIS | |
105 | cache, the supplied parameters are consistent with the sibling | |
106 | function THIS_ID. | |
107 | ||
108 | Can the code call ``frame_register (get_prev_frame (NEXT_FRAME))''? | |
109 | Won't the call frame_register (THIS_FRAME) be faster? Well, | |
110 | ignoring the possability that the previous frame does not yet | |
111 | exist, the ``frame_register (FRAME)'' function is expanded to | |
112 | ``frame_register_unwind (get_next_frame (FRAME)'' and hence that | |
113 | call will expand to ``frame_register_unwind (get_next_frame | |
114 | (get_prev_frame (NEXT_FRAME)))''. Might as well call | |
115 | ``frame_register_unwind (NEXT_FRAME)'' directly. | |
116 | ||
117 | THIS_PROLOGUE_CACHE can be used to share any prolog analysis data | |
118 | with the other unwind methods. Memory for that cache should be | |
119 | allocated using frame_obstack_zalloc(). */ | |
120 | ||
121 | typedef void (frame_prev_register_ftype) (struct frame_info *next_frame, | |
122 | void **this_prologue_cache, | |
123 | int prev_regnum, | |
124 | int *optimized, | |
125 | enum lval_type * lvalp, | |
126 | CORE_ADDR *addrp, | |
127 | int *realnump, void *valuep); | |
494cca16 | 128 | |
494cca16 AC |
129 | struct frame_unwind |
130 | { | |
131 | /* Should the frame's type go here? */ | |
132 | /* Should an attribute indicating the frame's address-in-block go | |
133 | here? */ | |
6dc42492 AC |
134 | frame_this_id_ftype *this_id; |
135 | frame_prev_register_ftype *prev_register; | |
494cca16 AC |
136 | }; |
137 | ||
138 | #endif |