GDB copyright headers update after running GDB's copyright.py script.
[external/binutils.git] / 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