1130803Smarcel/* Definitions for a frame unwinder, for GDB, the GNU debugger. 2130803Smarcel 3130803Smarcel Copyright 2003 Free Software Foundation, Inc. 4130803Smarcel 5130803Smarcel This file is part of GDB. 6130803Smarcel 7130803Smarcel This program is free software; you can redistribute it and/or modify 8130803Smarcel it under the terms of the GNU General Public License as published by 9130803Smarcel the Free Software Foundation; either version 2 of the License, or 10130803Smarcel (at your option) any later version. 11130803Smarcel 12130803Smarcel This program is distributed in the hope that it will be useful, 13130803Smarcel but WITHOUT ANY WARRANTY; without even the implied warranty of 14130803Smarcel MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15130803Smarcel GNU General Public License for more details. 16130803Smarcel 17130803Smarcel You should have received a copy of the GNU General Public License 18130803Smarcel along with this program; if not, write to the Free Software 19130803Smarcel Foundation, Inc., 59 Temple Place - Suite 330, 20130803Smarcel Boston, MA 02111-1307, USA. */ 21130803Smarcel 22130803Smarcel#if !defined (FRAME_UNWIND_H) 23130803Smarcel#define FRAME_UNWIND_H 1 24130803Smarcel 25130803Smarcelstruct frame_info; 26130803Smarcelstruct frame_id; 27130803Smarcelstruct frame_unwind; 28130803Smarcelstruct gdbarch; 29130803Smarcelstruct regcache; 30130803Smarcel 31130803Smarcel#include "frame.h" /* For enum frame_type. */ 32130803Smarcel 33130803Smarcel/* The following unwind functions assume a chain of frames forming the 34130803Smarcel sequence: (outer) prev <-> this <-> next (inner). All the 35130803Smarcel functions are called with called with the next frame's `struct 36130803Smarcel frame_info' and and this frame's prologue cache. 37130803Smarcel 38130803Smarcel THIS frame's register values can be obtained by unwinding NEXT 39130803Smarcel frame's registers (a recursive operation). 40130803Smarcel 41130803Smarcel THIS frame's prologue cache can be used to cache information such 42130803Smarcel as where this frame's prologue stores the previous frame's 43130803Smarcel registers. */ 44130803Smarcel 45130803Smarcel/* Assuming the frame chain: (outer) prev <-> this <-> next (inner); 46130803Smarcel use the NEXT frame, and its register unwind method, to determine 47130803Smarcel the frame ID of THIS frame. 48130803Smarcel 49130803Smarcel A frame ID provides an invariant that can be used to re-identify an 50130803Smarcel instance of a frame. It is a combination of the frame's `base' and 51130803Smarcel the frame's function's code address. 52130803Smarcel 53130803Smarcel Traditionally, THIS frame's ID was determined by examining THIS 54130803Smarcel frame's function's prologue, and identifying the register/offset 55130803Smarcel used as THIS frame's base. 56130803Smarcel 57130803Smarcel Example: An examination of THIS frame's prologue reveals that, on 58130803Smarcel entry, it saves the PC(+12), SP(+8), and R1(+4) registers 59130803Smarcel (decrementing the SP by 12). Consequently, the frame ID's base can 60130803Smarcel be determined by adding 12 to the THIS frame's stack-pointer, and 61130803Smarcel the value of THIS frame's SP can be obtained by unwinding the NEXT 62130803Smarcel frame's SP. 63130803Smarcel 64130803Smarcel THIS_PROLOGUE_CACHE can be used to share any prolog analysis data 65130803Smarcel with the other unwind methods. Memory for that cache should be 66130803Smarcel allocated using frame_obstack_zalloc(). */ 67130803Smarcel 68130803Smarceltypedef void (frame_this_id_ftype) (struct frame_info *next_frame, 69130803Smarcel void **this_prologue_cache, 70130803Smarcel struct frame_id *this_id); 71130803Smarcel 72130803Smarcel/* Assuming the frame chain: (outer) prev <-> this <-> next (inner); 73130803Smarcel use the NEXT frame, and its register unwind method, to unwind THIS 74130803Smarcel frame's registers (returning the value of the specified register 75130803Smarcel REGNUM in the previous frame). 76130803Smarcel 77130803Smarcel Traditionally, THIS frame's registers were unwound by examining 78130803Smarcel THIS frame's function's prologue and identifying which registers 79130803Smarcel that prolog code saved on the stack. 80130803Smarcel 81130803Smarcel Example: An examination of THIS frame's prologue reveals that, on 82130803Smarcel entry, it saves the PC(+12), SP(+8), and R1(+4) registers 83130803Smarcel (decrementing the SP by 12). Consequently, the value of the PC 84130803Smarcel register in the previous frame is found in memory at SP+12, and 85130803Smarcel THIS frame's SP can be obtained by unwinding the NEXT frame's SP. 86130803Smarcel 87130803Smarcel Why not pass in THIS_FRAME? By passing in NEXT frame and THIS 88130803Smarcel cache, the supplied parameters are consistent with the sibling 89130803Smarcel function THIS_ID. 90130803Smarcel 91130803Smarcel Can the code call ``frame_register (get_prev_frame (NEXT_FRAME))''? 92130803Smarcel Won't the call frame_register (THIS_FRAME) be faster? Well, 93130803Smarcel ignoring the possability that the previous frame does not yet 94130803Smarcel exist, the ``frame_register (FRAME)'' function is expanded to 95130803Smarcel ``frame_register_unwind (get_next_frame (FRAME)'' and hence that 96130803Smarcel call will expand to ``frame_register_unwind (get_next_frame 97130803Smarcel (get_prev_frame (NEXT_FRAME)))''. Might as well call 98130803Smarcel ``frame_register_unwind (NEXT_FRAME)'' directly. 99130803Smarcel 100130803Smarcel THIS_PROLOGUE_CACHE can be used to share any prolog analysis data 101130803Smarcel with the other unwind methods. Memory for that cache should be 102130803Smarcel allocated using frame_obstack_zalloc(). */ 103130803Smarcel 104130803Smarceltypedef void (frame_prev_register_ftype) (struct frame_info *next_frame, 105130803Smarcel void **this_prologue_cache, 106130803Smarcel int prev_regnum, 107130803Smarcel int *optimized, 108130803Smarcel enum lval_type * lvalp, 109130803Smarcel CORE_ADDR *addrp, 110130803Smarcel int *realnump, void *valuep); 111130803Smarcel 112130803Smarcelstruct frame_unwind 113130803Smarcel{ 114130803Smarcel /* The frame's type. Should this instead be a collection of 115130803Smarcel predicates that test the frame for various attributes? */ 116130803Smarcel enum frame_type type; 117130803Smarcel /* Should an attribute indicating the frame's address-in-block go 118130803Smarcel here? */ 119130803Smarcel frame_this_id_ftype *this_id; 120130803Smarcel frame_prev_register_ftype *prev_register; 121130803Smarcel}; 122130803Smarcel 123130803Smarcel/* Given the NEXT frame, take a wiff of THIS frame's registers (namely 124130803Smarcel the PC and attributes) and if it is the applicable unwinder return 125130803Smarcel the unwind methods, or NULL if it is not. */ 126130803Smarcel 127130803Smarceltypedef const struct frame_unwind *(frame_unwind_sniffer_ftype) (struct frame_info *next_frame); 128130803Smarcel 129130803Smarcel/* Add a frame sniffer to the list. The predicates are polled in the 130130803Smarcel order that they are appended. The initial list contains the dummy 131130803Smarcel frame sniffer. */ 132130803Smarcel 133130803Smarcelextern void frame_unwind_append_sniffer (struct gdbarch *gdbarch, 134130803Smarcel frame_unwind_sniffer_ftype *sniffer); 135130803Smarcel 136130803Smarcel/* Iterate through the next frame's sniffers until one returns with an 137130803Smarcel unwinder implementation. */ 138130803Smarcel 139130803Smarcelextern const struct frame_unwind *frame_unwind_find_by_frame (struct frame_info *next_frame); 140130803Smarcel 141130803Smarcel#endif 142