Upgrade GDB from 7.4.1 to 7.6.1 on the vendor branch
[dragonfly.git] / contrib / gdb-7 / gdb / frame-unwind.h
CommitLineData
5796c8dc
SS
1/* Definitions for a frame unwinder, for GDB, the GNU debugger.
2
ef5ccd6c 3 Copyright (C) 2003-2013 Free Software Foundation, Inc.
5796c8dc
SS
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
23struct frame_data;
24struct frame_info;
25struct frame_id;
26struct frame_unwind;
27struct gdbarch;
28struct regcache;
29struct 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
c50c785c
JM
35 functions are called with this frame's `struct frame_info' and
36 prologue cache.
5796c8dc
SS
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,
ef5ccd6c
JM
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. */
5796c8dc
SS
50
51typedef int (frame_sniffer_ftype) (const struct frame_unwind *self,
52 struct frame_info *this_frame,
53 void **this_prologue_cache);
54
c50c785c
JM
55typedef enum unwind_stop_reason (frame_unwind_stop_reason_ftype)
56 (struct frame_info *this_frame, void **this_prologue_cache);
57
5796c8dc
SS
58/* A default frame sniffer which always accepts the frame. Used by
59 fallback prologue unwinders. */
60
61int default_frame_sniffer (const struct frame_unwind *self,
62 struct frame_info *this_frame,
63 void **this_prologue_cache);
64
c50c785c
JM
65/* A default stop_reason callback which always claims the frame is
66 unwindable. */
67
68enum unwind_stop_reason
69 default_frame_unwind_stop_reason (struct frame_info *this_frame,
70 void **this_cache);
71
5796c8dc
SS
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
95typedef 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
127typedef 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
133typedef 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
140typedef struct gdbarch *(frame_prev_arch_ftype) (struct frame_info *this_frame,
141 void **this_prologue_cache);
142
143struct 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? */
c50c785c 150 frame_unwind_stop_reason_ftype *stop_reason;
5796c8dc
SS
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
c50c785c 163 to install a more specific sigtramp unwinder that overrides the
5796c8dc 164 traditional brute-force unwinder. */
c50c785c
JM
165extern void frame_unwind_prepend_unwinder (struct gdbarch *,
166 const struct frame_unwind *);
5796c8dc
SS
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
172extern void frame_unwind_append_unwinder (struct gdbarch *gdbarch,
173 const struct frame_unwind *unwinder);
174
c50c785c
JM
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. */
5796c8dc 178
c50c785c
JM
179extern void frame_unwind_find_by_frame (struct frame_info *this_frame,
180 void **this_cache);
5796c8dc
SS
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
187struct 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
193struct 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
199struct 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
205struct 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
212struct 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
219struct value *frame_unwind_got_address (struct frame_info *frame, int regnum,
220 CORE_ADDR addr);
221
222#endif