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