xref: /openbsd-src/gnu/usr.bin/binutils/gdb/frame.h (revision 63addd46c1e40ca0f49488ddcdc4ab598023b0c1)
1e93f7393Sniklas /* Definitions for dealing with stack frames, for GDB, the GNU debugger.
2b725ae77Skettenis 
3b725ae77Skettenis    Copyright 1986, 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1996,
4b725ae77Skettenis    1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
5e93f7393Sniklas 
6e93f7393Sniklas    This file is part of GDB.
7e93f7393Sniklas 
8e93f7393Sniklas    This program is free software; you can redistribute it and/or modify
9e93f7393Sniklas    it under the terms of the GNU General Public License as published by
10e93f7393Sniklas    the Free Software Foundation; either version 2 of the License, or
11e93f7393Sniklas    (at your option) any later version.
12e93f7393Sniklas 
13e93f7393Sniklas    This program is distributed in the hope that it will be useful,
14e93f7393Sniklas    but WITHOUT ANY WARRANTY; without even the implied warranty of
15e93f7393Sniklas    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16e93f7393Sniklas    GNU General Public License for more details.
17e93f7393Sniklas 
18e93f7393Sniklas    You should have received a copy of the GNU General Public License
19e93f7393Sniklas    along with this program; if not, write to the Free Software
20b725ae77Skettenis    Foundation, Inc., 59 Temple Place - Suite 330,
21b725ae77Skettenis    Boston, MA 02111-1307, USA.  */
22e93f7393Sniklas 
23e93f7393Sniklas #if !defined (FRAME_H)
24e93f7393Sniklas #define FRAME_H 1
25e93f7393Sniklas 
26b725ae77Skettenis /* The following is the intended naming schema for frame functions.
27b725ae77Skettenis    It isn't 100% consistent, but it is aproaching that.  Frame naming
28b725ae77Skettenis    schema:
29e93f7393Sniklas 
30b725ae77Skettenis    Prefixes:
31b725ae77Skettenis 
32b725ae77Skettenis    get_frame_WHAT...(): Get WHAT from the THIS frame (functionaly
33b725ae77Skettenis    equivalent to THIS->next->unwind->what)
34b725ae77Skettenis 
35b725ae77Skettenis    frame_unwind_WHAT...(): Unwind THIS frame's WHAT from the NEXT
36b725ae77Skettenis    frame.
37b725ae77Skettenis 
38b725ae77Skettenis    put_frame_WHAT...(): Put a value into this frame (unsafe, need to
39b725ae77Skettenis    invalidate the frame / regcache afterwards) (better name more
40b725ae77Skettenis    strongly hinting at its unsafeness)
41b725ae77Skettenis 
42b725ae77Skettenis    safe_....(): Safer version of various functions, doesn't throw an
43*63addd46Skettenis    error (leave this for later?).  Returns non-zero / non-NULL if the
44*63addd46Skettenis    request succeeds, zero / NULL otherwize.
45b725ae77Skettenis 
46b725ae77Skettenis    Suffixes:
47b725ae77Skettenis 
48b725ae77Skettenis    void /frame/_WHAT(): Read WHAT's value into the buffer parameter.
49b725ae77Skettenis 
50b725ae77Skettenis    ULONGEST /frame/_WHAT_unsigned(): Return an unsigned value (the
51b725ae77Skettenis    alternative is *frame_unsigned_WHAT).
52b725ae77Skettenis 
53b725ae77Skettenis    LONGEST /frame/_WHAT_signed(): Return WHAT signed value.
54b725ae77Skettenis 
55b725ae77Skettenis    What:
56b725ae77Skettenis 
57b725ae77Skettenis    /frame/_memory* (frame, coreaddr, len [, buf]): Extract/return
58b725ae77Skettenis    *memory.
59b725ae77Skettenis 
60b725ae77Skettenis    /frame/_register* (frame, regnum [, buf]): extract/return register.
61b725ae77Skettenis 
62b725ae77Skettenis    CORE_ADDR /frame/_{pc,sp,...} (frame): Resume address, innner most
63b725ae77Skettenis    stack *address, ...
64b725ae77Skettenis 
65b725ae77Skettenis    */
66b725ae77Skettenis 
67b725ae77Skettenis struct symtab_and_line;
68b725ae77Skettenis struct frame_unwind;
69b725ae77Skettenis struct frame_base;
70b725ae77Skettenis struct block;
71b725ae77Skettenis struct gdbarch;
72b725ae77Skettenis struct ui_file;
73b725ae77Skettenis 
74b725ae77Skettenis /* The frame object.  */
75b725ae77Skettenis 
76b725ae77Skettenis struct frame_info;
77b725ae77Skettenis 
78b725ae77Skettenis /* The frame object's ID.  This provides a per-frame unique identifier
79b725ae77Skettenis    that can be used to relocate a `struct frame_info' after a target
80b725ae77Skettenis    resume or a frame cache destruct.  It of course assumes that the
81b725ae77Skettenis    inferior hasn't unwound the stack past that frame.  */
82b725ae77Skettenis 
83b725ae77Skettenis struct frame_id
84e93f7393Sniklas {
85b725ae77Skettenis   /* The frame's stack address.  This shall be constant through out
86b725ae77Skettenis      the lifetime of a frame.  Note that this requirement applies to
87b725ae77Skettenis      not just the function body, but also the prologue and (in theory
88b725ae77Skettenis      at least) the epilogue.  Since that value needs to fall either on
89b725ae77Skettenis      the boundary, or within the frame's address range, the frame's
90b725ae77Skettenis      outer-most address (the inner-most address of the previous frame)
91b725ae77Skettenis      is used.  Watch out for all the legacy targets that still use the
92b725ae77Skettenis      function pointer register or stack pointer register.  They are
93*63addd46Skettenis      wrong.
94*63addd46Skettenis 
95*63addd46Skettenis      This field is valid only if stack_addr_p is true.  Otherwise, this
96*63addd46Skettenis      frame represents the null frame.  */
97b725ae77Skettenis   CORE_ADDR stack_addr;
98*63addd46Skettenis 
99b725ae77Skettenis   /* The frame's code address.  This shall be constant through out the
100b725ae77Skettenis      lifetime of the frame.  While the PC (a.k.a. resume address)
101b725ae77Skettenis      changes as the function is executed, this code address cannot.
102b725ae77Skettenis      Typically, it is set to the address of the entry point of the
103*63addd46Skettenis      frame's function (as returned by frame_func_unwind().
104*63addd46Skettenis 
105*63addd46Skettenis      This field is valid only if code_addr_p is true.  Otherwise, this
106*63addd46Skettenis      frame is considered to have a wildcard code address, i.e. one that
107*63addd46Skettenis      matches every address value in frame comparisons.  */
108b725ae77Skettenis   CORE_ADDR code_addr;
109*63addd46Skettenis 
110b725ae77Skettenis   /* The frame's special address.  This shall be constant through out the
111b725ae77Skettenis      lifetime of the frame.  This is used for architectures that may have
112b725ae77Skettenis      frames that do not change the stack but are still distinct and have
113b725ae77Skettenis      some form of distinct identifier (e.g. the ia64 which uses a 2nd
114b725ae77Skettenis      stack for registers).  This field is treated as unordered - i.e. will
115b725ae77Skettenis      not be used in frame ordering comparisons such as frame_id_inner().
116*63addd46Skettenis 
117*63addd46Skettenis      This field is valid only if special_addr_p is true.  Otherwise, this
118*63addd46Skettenis      frame is considered to have a wildcard special address, i.e. one that
119*63addd46Skettenis      matches every address value in frame comparisons.  */
120b725ae77Skettenis   CORE_ADDR special_addr;
121*63addd46Skettenis 
122*63addd46Skettenis   /* Flags to indicate the above fields have valid contents.  */
123*63addd46Skettenis   unsigned int stack_addr_p : 1;
124*63addd46Skettenis   unsigned int code_addr_p : 1;
125*63addd46Skettenis   unsigned int special_addr_p : 1;
126e93f7393Sniklas };
127e93f7393Sniklas 
128b725ae77Skettenis /* Methods for constructing and comparing Frame IDs.
129e93f7393Sniklas 
130b725ae77Skettenis    NOTE: Given stackless functions A and B, where A calls B (and hence
131b725ae77Skettenis    B is inner-to A).  The relationships: !eq(A,B); !eq(B,A);
132b725ae77Skettenis    !inner(A,B); !inner(B,A); all hold.
133b725ae77Skettenis 
134b725ae77Skettenis    This is because, while B is inner-to A, B is not strictly inner-to A.
135b725ae77Skettenis    Being stackless, they have an identical .stack_addr value, and differ
136b725ae77Skettenis    only by their unordered .code_addr and/or .special_addr values.
137b725ae77Skettenis 
138b725ae77Skettenis    Because frame_id_inner is only used as a safety net (e.g.,
139b725ae77Skettenis    detect a corrupt stack) the lack of strictness is not a problem.
140b725ae77Skettenis    Code needing to determine an exact relationship between two frames
141b725ae77Skettenis    must instead use frame_id_eq and frame_id_unwind.  For instance,
142b725ae77Skettenis    in the above, to determine that A stepped-into B, the equation
143b725ae77Skettenis    "A.id != B.id && A.id == id_unwind (B)" can be used.  */
144b725ae77Skettenis 
145b725ae77Skettenis /* For convenience.  All fields are zero.  */
146b725ae77Skettenis extern const struct frame_id null_frame_id;
147b725ae77Skettenis 
148b725ae77Skettenis /* Construct a frame ID.  The first parameter is the frame's constant
149b725ae77Skettenis    stack address (typically the outer-bound), and the second the
150*63addd46Skettenis    frame's constant code address (typically the entry point).
151*63addd46Skettenis    The special identifier address is set to indicate a wild card.  */
152b725ae77Skettenis extern struct frame_id frame_id_build (CORE_ADDR stack_addr,
153b725ae77Skettenis 				       CORE_ADDR code_addr);
154b725ae77Skettenis 
155b725ae77Skettenis /* Construct a special frame ID.  The first parameter is the frame's constant
156b725ae77Skettenis    stack address (typically the outer-bound), the second is the
157*63addd46Skettenis    frame's constant code address (typically the entry point),
158*63addd46Skettenis    and the third parameter is the frame's special identifier address. */
159b725ae77Skettenis extern struct frame_id frame_id_build_special (CORE_ADDR stack_addr,
160b725ae77Skettenis 					       CORE_ADDR code_addr,
161b725ae77Skettenis 					       CORE_ADDR special_addr);
162b725ae77Skettenis 
163*63addd46Skettenis /* Construct a wild card frame ID.  The parameter is the frame's constant
164*63addd46Skettenis    stack address (typically the outer-bound).  The code address as well
165*63addd46Skettenis    as the special identifier address are set to indicate wild cards.  */
166*63addd46Skettenis extern struct frame_id frame_id_build_wild (CORE_ADDR stack_addr);
167*63addd46Skettenis 
168b725ae77Skettenis /* Returns non-zero when L is a valid frame (a valid frame has a
169b725ae77Skettenis    non-zero .base).  */
170b725ae77Skettenis extern int frame_id_p (struct frame_id l);
171b725ae77Skettenis 
172b725ae77Skettenis /* Returns non-zero when L and R identify the same frame, or, if
173b725ae77Skettenis    either L or R have a zero .func, then the same frame base.  */
174b725ae77Skettenis extern int frame_id_eq (struct frame_id l, struct frame_id r);
175b725ae77Skettenis 
176b725ae77Skettenis /* Returns non-zero when L is strictly inner-than R (they have
177b725ae77Skettenis    different frame .bases).  Neither L, nor R can be `null'.  See note
178b725ae77Skettenis    above about frameless functions.  */
179b725ae77Skettenis extern int frame_id_inner (struct frame_id l, struct frame_id r);
180b725ae77Skettenis 
181b725ae77Skettenis /* Write the internal representation of a frame ID on the specified
182b725ae77Skettenis    stream.  */
183b725ae77Skettenis extern void fprint_frame_id (struct ui_file *file, struct frame_id id);
184b725ae77Skettenis 
185b725ae77Skettenis 
186b725ae77Skettenis /* For every stopped thread, GDB tracks two frames: current and
187b725ae77Skettenis    selected.  Current frame is the inner most frame of the selected
188b725ae77Skettenis    thread.  Selected frame is the one being examined by the the GDB
189b725ae77Skettenis    CLI (selected using `up', `down', ...).  The frames are created
190b725ae77Skettenis    on-demand (via get_prev_frame()) and then held in a frame cache.  */
191b725ae77Skettenis /* FIXME: cagney/2002-11-28: Er, there is a lie here.  If you do the
192*63addd46Skettenis    sequence: `thread 1; up; thread 2; thread 1' you lose thread 1's
193b725ae77Skettenis    selected frame.  At present GDB only tracks the selected frame of
194b725ae77Skettenis    the current thread.  But be warned, that might change.  */
195b725ae77Skettenis /* FIXME: cagney/2002-11-14: At any time, only one thread's selected
196b725ae77Skettenis    and current frame can be active.  Switching threads causes gdb to
197b725ae77Skettenis    discard all that cached frame information.  Ulgh!  Instead, current
198b725ae77Skettenis    and selected frame should be bound to a thread.  */
199b725ae77Skettenis 
200b725ae77Skettenis /* On demand, create the inner most frame using information found in
201b725ae77Skettenis    the inferior.  If the inner most frame can't be created, throw an
202b725ae77Skettenis    error.  */
203b725ae77Skettenis extern struct frame_info *get_current_frame (void);
204b725ae77Skettenis 
205b725ae77Skettenis /* Invalidates the frame cache (this function should have been called
206b725ae77Skettenis    invalidate_cached_frames).
207b725ae77Skettenis 
208b725ae77Skettenis    FIXME: cagney/2002-11-28: The only difference between
209b725ae77Skettenis    flush_cached_frames() and reinit_frame_cache() is that the latter
210*63addd46Skettenis    explicitly sets the selected frame back to the current frame -- there
211b725ae77Skettenis    isn't any real difference (except that one delays the selection of
212b725ae77Skettenis    a new frame).  Code can instead simply rely on get_selected_frame()
213*63addd46Skettenis    to reinit the selected frame as needed.  As for invalidating the
214*63addd46Skettenis    cache, there should be two methods: one that reverts the thread's
215b725ae77Skettenis    selected frame back to current frame (for when the inferior
216b725ae77Skettenis    resumes) and one that does not (for when the user modifies the
217b725ae77Skettenis    target invalidating the frame cache).  */
218b725ae77Skettenis extern void flush_cached_frames (void);
219b725ae77Skettenis extern void reinit_frame_cache (void);
220b725ae77Skettenis 
221b725ae77Skettenis /* On demand, create the selected frame and then return it.  If the
222b725ae77Skettenis    selected frame can not be created, this function throws an error.  */
223b725ae77Skettenis /* FIXME: cagney/2002-11-28: At present, when there is no selected
224b725ae77Skettenis    frame, this function always returns the current (inner most) frame.
225b725ae77Skettenis    It should instead, when a thread has previously had its frame
226b725ae77Skettenis    selected (but not resumed) and the frame cache invalidated, find
227b725ae77Skettenis    and then return that thread's previously selected frame.  */
228b725ae77Skettenis extern struct frame_info *get_selected_frame (void);
229b725ae77Skettenis 
230b725ae77Skettenis /* Select a specific frame.  NULL, apparently implies re-select the
231b725ae77Skettenis    inner most frame.  */
232b725ae77Skettenis extern void select_frame (struct frame_info *);
233b725ae77Skettenis 
234b725ae77Skettenis /* Given a FRAME, return the next (more inner, younger) or previous
235b725ae77Skettenis    (more outer, older) frame.  */
236b725ae77Skettenis extern struct frame_info *get_prev_frame (struct frame_info *);
237b725ae77Skettenis extern struct frame_info *get_next_frame (struct frame_info *);
238b725ae77Skettenis 
239b725ae77Skettenis /* Given a frame's ID, relocate the frame.  Returns NULL if the frame
240b725ae77Skettenis    is not found.  */
241b725ae77Skettenis extern struct frame_info *frame_find_by_id (struct frame_id id);
242b725ae77Skettenis 
243b725ae77Skettenis /* Base attributes of a frame: */
244b725ae77Skettenis 
245b725ae77Skettenis /* The frame's `resume' address.  Where the program will resume in
246b725ae77Skettenis    this frame.
247b725ae77Skettenis 
248b725ae77Skettenis    This replaced: frame->pc; */
249b725ae77Skettenis extern CORE_ADDR get_frame_pc (struct frame_info *);
250b725ae77Skettenis 
251*63addd46Skettenis /* An address (not necessarily aligned to an instruction boundary)
252b725ae77Skettenis    that falls within THIS frame's code block.
253b725ae77Skettenis 
254b725ae77Skettenis    When a function call is the last statement in a block, the return
255b725ae77Skettenis    address for the call may land at the start of the next block.
256b725ae77Skettenis    Similarly, if a no-return function call is the last statement in
257b725ae77Skettenis    the function, the return address may end up pointing beyond the
258b725ae77Skettenis    function, and possibly at the start of the next function.
259b725ae77Skettenis 
260b725ae77Skettenis    These methods make an allowance for this.  For call frames, this
261b725ae77Skettenis    function returns the frame's PC-1 which "should" be an address in
262b725ae77Skettenis    the frame's block.  */
263b725ae77Skettenis 
264b725ae77Skettenis extern CORE_ADDR get_frame_address_in_block (struct frame_info *this_frame);
265b725ae77Skettenis extern CORE_ADDR frame_unwind_address_in_block (struct frame_info *next_frame);
266b725ae77Skettenis 
267b725ae77Skettenis /* The frame's inner-most bound.  AKA the stack-pointer.  Confusingly
268b725ae77Skettenis    known as top-of-stack.  */
269b725ae77Skettenis 
270b725ae77Skettenis extern CORE_ADDR get_frame_sp (struct frame_info *);
271b725ae77Skettenis extern CORE_ADDR frame_sp_unwind (struct frame_info *);
272b725ae77Skettenis 
273b725ae77Skettenis 
274b725ae77Skettenis /* Following on from the `resume' address.  Return the entry point
275b725ae77Skettenis    address of the function containing that resume address, or zero if
276b725ae77Skettenis    that function isn't known.  */
277b725ae77Skettenis extern CORE_ADDR frame_func_unwind (struct frame_info *fi);
278b725ae77Skettenis extern CORE_ADDR get_frame_func (struct frame_info *fi);
279b725ae77Skettenis 
280b725ae77Skettenis /* Closely related to the resume address, various symbol table
281b725ae77Skettenis    attributes that are determined by the PC.  Note that for a normal
282b725ae77Skettenis    frame, the PC refers to the resume address after the return, and
283b725ae77Skettenis    not the call instruction.  In such a case, the address is adjusted
284*63addd46Skettenis    so that it (approximately) identifies the call site (and not the
285*63addd46Skettenis    return site).
286b725ae77Skettenis 
287b725ae77Skettenis    NOTE: cagney/2002-11-28: The frame cache could be used to cache the
288b725ae77Skettenis    computed value.  Working on the assumption that the bottle-neck is
289b725ae77Skettenis    in the single step code, and that code causes the frame cache to be
290b725ae77Skettenis    constantly flushed, caching things in a frame is probably of little
291b725ae77Skettenis    benefit.  As they say `show us the numbers'.
292b725ae77Skettenis 
293b725ae77Skettenis    NOTE: cagney/2002-11-28: Plenty more where this one came from:
294b725ae77Skettenis    find_frame_block(), find_frame_partial_function(),
295b725ae77Skettenis    find_frame_symtab(), find_frame_function().  Each will need to be
296b725ae77Skettenis    carefully considered to determine if the real intent was for it to
297b725ae77Skettenis    apply to the PC or the adjusted PC.  */
298b725ae77Skettenis extern void find_frame_sal (struct frame_info *frame,
299b725ae77Skettenis 			    struct symtab_and_line *sal);
300b725ae77Skettenis 
301b725ae77Skettenis /* Return the frame base (what ever that is) (DEPRECATED).
302b725ae77Skettenis 
303b725ae77Skettenis    Old code was trying to use this single method for two conflicting
304b725ae77Skettenis    purposes.  Such code needs to be updated to use either of:
305b725ae77Skettenis 
306b725ae77Skettenis    get_frame_id: A low level frame unique identifier, that consists of
307b725ae77Skettenis    both a stack and a function address, that can be used to uniquely
308b725ae77Skettenis    identify a frame.  This value is determined by the frame's
309b725ae77Skettenis    low-level unwinder, the stack part [typically] being the
310b725ae77Skettenis    top-of-stack of the previous frame, and the function part being the
311b725ae77Skettenis    function's start address.  Since the correct identification of a
312b725ae77Skettenis    frameless function requires both the a stack and function address,
313b725ae77Skettenis    the old get_frame_base method was not sufficient.
314b725ae77Skettenis 
315b725ae77Skettenis    get_frame_base_address: get_frame_locals_address:
316b725ae77Skettenis    get_frame_args_address: A set of high-level debug-info dependant
317b725ae77Skettenis    addresses that fall within the frame.  These addresses almost
318b725ae77Skettenis    certainly will not match the stack address part of a frame ID (as
319b725ae77Skettenis    returned by get_frame_base).
320b725ae77Skettenis 
321b725ae77Skettenis    This replaced: frame->frame; */
322b725ae77Skettenis 
323b725ae77Skettenis extern CORE_ADDR get_frame_base (struct frame_info *);
324b725ae77Skettenis 
325b725ae77Skettenis /* Return the per-frame unique identifer.  Can be used to relocate a
326b725ae77Skettenis    frame after a frame cache flush (and other similar operations).  If
327*63addd46Skettenis    FI is NULL, return the null_frame_id.
328*63addd46Skettenis 
329*63addd46Skettenis    NOTE: kettenis/20040508: These functions return a structure.  On
330*63addd46Skettenis    platforms where structures are returned in static storage (vax,
331*63addd46Skettenis    m68k), this may trigger compiler bugs in code like:
332*63addd46Skettenis 
333*63addd46Skettenis    if (frame_id_eq (get_frame_id (l), get_frame_id (r)))
334*63addd46Skettenis 
335*63addd46Skettenis    where the return value from the first get_frame_id (l) gets
336*63addd46Skettenis    overwritten by the second get_frame_id (r).  Please avoid writing
337*63addd46Skettenis    code like this.  Use code like:
338*63addd46Skettenis 
339*63addd46Skettenis    struct frame_id id = get_frame_id (l);
340*63addd46Skettenis    if (frame_id_eq (id, get_frame_id (r)))
341*63addd46Skettenis 
342*63addd46Skettenis    instead, since that avoids the bug.  */
343b725ae77Skettenis extern struct frame_id get_frame_id (struct frame_info *fi);
344*63addd46Skettenis extern struct frame_id frame_unwind_id (struct frame_info *next_frame);
345b725ae77Skettenis 
346b725ae77Skettenis /* Assuming that a frame is `normal', return its base-address, or 0 if
347b725ae77Skettenis    the information isn't available.  NOTE: This address is really only
348b725ae77Skettenis    meaningful to the frame's high-level debug info.  */
349b725ae77Skettenis extern CORE_ADDR get_frame_base_address (struct frame_info *);
350b725ae77Skettenis 
351b725ae77Skettenis /* Assuming that a frame is `normal', return the base-address of the
352b725ae77Skettenis    local variables, or 0 if the information isn't available.  NOTE:
353b725ae77Skettenis    This address is really only meaningful to the frame's high-level
354b725ae77Skettenis    debug info.  Typically, the argument and locals share a single
355b725ae77Skettenis    base-address.  */
356b725ae77Skettenis extern CORE_ADDR get_frame_locals_address (struct frame_info *);
357b725ae77Skettenis 
358b725ae77Skettenis /* Assuming that a frame is `normal', return the base-address of the
359b725ae77Skettenis    parameter list, or 0 if that information isn't available.  NOTE:
360b725ae77Skettenis    This address is really only meaningful to the frame's high-level
361b725ae77Skettenis    debug info.  Typically, the argument and locals share a single
362b725ae77Skettenis    base-address.  */
363b725ae77Skettenis extern CORE_ADDR get_frame_args_address (struct frame_info *);
364b725ae77Skettenis 
365b725ae77Skettenis /* The frame's level: 0 for innermost, 1 for its caller, ...; or -1
366b725ae77Skettenis    for an invalid frame).  */
367b725ae77Skettenis extern int frame_relative_level (struct frame_info *fi);
368b725ae77Skettenis 
369b725ae77Skettenis /* Return the frame's type.  Some are real, some are signal
370b725ae77Skettenis    trampolines, and some are completely artificial (dummy).  */
371b725ae77Skettenis 
372b725ae77Skettenis enum frame_type
373e93f7393Sniklas {
374b725ae77Skettenis   /* A true stack frame, created by the target program during normal
375b725ae77Skettenis      execution.  */
376b725ae77Skettenis   NORMAL_FRAME,
377b725ae77Skettenis   /* A fake frame, created by GDB when performing an inferior function
378b725ae77Skettenis      call.  */
379b725ae77Skettenis   DUMMY_FRAME,
380b725ae77Skettenis   /* In a signal handler, various OSs handle this in various ways.
381b725ae77Skettenis      The main thing is that the frame may be far from normal.  */
382*63addd46Skettenis   SIGTRAMP_FRAME,
383*63addd46Skettenis   /* Sentinel or registers frame.  This frame obtains register values
384*63addd46Skettenis      direct from the inferior's registers.  */
385*63addd46Skettenis   SENTINEL_FRAME
386b725ae77Skettenis };
387b725ae77Skettenis extern enum frame_type get_frame_type (struct frame_info *);
388e93f7393Sniklas 
389b725ae77Skettenis /* Unwind the stack frame so that the value of REGNUM, in the previous
390b725ae77Skettenis    (up, older) frame is returned.  If VALUEP is NULL, don't
391b725ae77Skettenis    fetch/compute the value.  Instead just return the location of the
392b725ae77Skettenis    value.  */
393b725ae77Skettenis extern void frame_register_unwind (struct frame_info *frame, int regnum,
394b725ae77Skettenis 				   int *optimizedp, enum lval_type *lvalp,
395b725ae77Skettenis 				   CORE_ADDR *addrp, int *realnump,
396b725ae77Skettenis 				   void *valuep);
397e93f7393Sniklas 
398b725ae77Skettenis /* Fetch a register from this, or unwind a register from the next
399b725ae77Skettenis    frame.  Note that the get_frame methods are wrappers to
400b725ae77Skettenis    frame->next->unwind.  They all [potentially] throw an error if the
401b725ae77Skettenis    fetch fails.  */
402e93f7393Sniklas 
403b725ae77Skettenis extern void frame_unwind_register (struct frame_info *frame,
404b725ae77Skettenis 				   int regnum, void *buf);
405b725ae77Skettenis extern void get_frame_register (struct frame_info *frame,
406b725ae77Skettenis 				int regnum, void *buf);
407b725ae77Skettenis 
408b725ae77Skettenis extern LONGEST frame_unwind_register_signed (struct frame_info *frame,
409b725ae77Skettenis 					     int regnum);
410b725ae77Skettenis extern LONGEST get_frame_register_signed (struct frame_info *frame,
411b725ae77Skettenis 					  int regnum);
412b725ae77Skettenis extern ULONGEST frame_unwind_register_unsigned (struct frame_info *frame,
413b725ae77Skettenis 					       int regnum);
414b725ae77Skettenis extern ULONGEST get_frame_register_unsigned (struct frame_info *frame,
415b725ae77Skettenis 					     int regnum);
416b725ae77Skettenis 
417b725ae77Skettenis 
418b725ae77Skettenis /* Use frame_unwind_register_signed.  */
419b725ae77Skettenis extern void frame_unwind_unsigned_register (struct frame_info *frame,
420b725ae77Skettenis 					    int regnum, ULONGEST *val);
421b725ae77Skettenis 
422b725ae77Skettenis /* Get the value of the register that belongs to this FRAME.  This
423*63addd46Skettenis    function is a wrapper to the call sequence ``frame_register_unwind
424b725ae77Skettenis    (get_next_frame (FRAME))''.  As per frame_register_unwind(), if
425b725ae77Skettenis    VALUEP is NULL, the registers value is not fetched/computed.  */
426b725ae77Skettenis 
427b725ae77Skettenis extern void frame_register (struct frame_info *frame, int regnum,
428b725ae77Skettenis 			    int *optimizedp, enum lval_type *lvalp,
429b725ae77Skettenis 			    CORE_ADDR *addrp, int *realnump,
430b725ae77Skettenis 			    void *valuep);
431b725ae77Skettenis 
432b725ae77Skettenis /* The reverse.  Store a register value relative to the specified
433b725ae77Skettenis    frame.  Note: this call makes the frame's state undefined.  The
434b725ae77Skettenis    register and frame caches must be flushed.  */
435b725ae77Skettenis extern void put_frame_register (struct frame_info *frame, int regnum,
436b725ae77Skettenis 				const void *buf);
437b725ae77Skettenis 
438b725ae77Skettenis /* Map between a frame register number and its name.  A frame register
439b725ae77Skettenis    space is a superset of the cooked register space --- it also
440b725ae77Skettenis    includes builtin registers.  If NAMELEN is negative, use the NAME's
441b725ae77Skettenis    length when doing the comparison.  */
442b725ae77Skettenis 
443b725ae77Skettenis extern int frame_map_name_to_regnum (struct frame_info *frame,
444b725ae77Skettenis 				     const char *name, int namelen);
445b725ae77Skettenis extern const char *frame_map_regnum_to_name (struct frame_info *frame,
446b725ae77Skettenis 					     int regnum);
447b725ae77Skettenis 
448b725ae77Skettenis /* Unwind the PC.  Strictly speaking return the resume address of the
449b725ae77Skettenis    calling frame.  For GDB, `pc' is the resume address and not a
450b725ae77Skettenis    specific register.  */
451b725ae77Skettenis 
452b725ae77Skettenis extern CORE_ADDR frame_pc_unwind (struct frame_info *frame);
453b725ae77Skettenis 
454b725ae77Skettenis /* Discard the specified frame.  Restoring the registers to the state
455b725ae77Skettenis    of the caller.  */
456b725ae77Skettenis extern void frame_pop (struct frame_info *frame);
457b725ae77Skettenis 
458b725ae77Skettenis /* Return memory from the specified frame.  A frame knows its thread /
459b725ae77Skettenis    LWP and hence can find its way down to a target.  The assumption
460b725ae77Skettenis    here is that the current and previous frame share a common address
461b725ae77Skettenis    space.
462b725ae77Skettenis 
463b725ae77Skettenis    If the memory read fails, these methods throw an error.
464b725ae77Skettenis 
465b725ae77Skettenis    NOTE: cagney/2003-06-03: Should there be unwind versions of these
466b725ae77Skettenis    methods?  That isn't clear.  Can code, for instance, assume that
467b725ae77Skettenis    this and the previous frame's memory or architecture are identical?
468b725ae77Skettenis    If architecture / memory changes are always separated by special
469b725ae77Skettenis    adaptor frames this should be ok.  */
470b725ae77Skettenis 
471b725ae77Skettenis extern void get_frame_memory (struct frame_info *this_frame, CORE_ADDR addr,
472b725ae77Skettenis 			      void *buf, int len);
473b725ae77Skettenis extern LONGEST get_frame_memory_signed (struct frame_info *this_frame,
474b725ae77Skettenis 					CORE_ADDR memaddr, int len);
475b725ae77Skettenis extern ULONGEST get_frame_memory_unsigned (struct frame_info *this_frame,
476b725ae77Skettenis 					   CORE_ADDR memaddr, int len);
477b725ae77Skettenis 
478*63addd46Skettenis /* Same as above, but return non-zero when the entire memory read
479*63addd46Skettenis    succeeds, zero otherwize.  */
480*63addd46Skettenis extern int safe_frame_unwind_memory (struct frame_info *this_frame,
481*63addd46Skettenis 				     CORE_ADDR addr, void *buf, int len);
482*63addd46Skettenis 
483b725ae77Skettenis /* Return this frame's architecture.  */
484b725ae77Skettenis 
485b725ae77Skettenis extern struct gdbarch *get_frame_arch (struct frame_info *this_frame);
486b725ae77Skettenis 
487b725ae77Skettenis 
488b725ae77Skettenis /* Values for the source flag to be used in print_frame_info_base().  */
489b725ae77Skettenis enum print_what
490b725ae77Skettenis   {
491b725ae77Skettenis     /* Print only the source line, like in stepi. */
492b725ae77Skettenis     SRC_LINE = -1,
493b725ae77Skettenis     /* Print only the location, i.e. level, address (sometimes)
494b725ae77Skettenis        function, args, file, line, line num. */
495b725ae77Skettenis     LOCATION,
496b725ae77Skettenis     /* Print both of the above. */
497b725ae77Skettenis     SRC_AND_LOC,
498b725ae77Skettenis     /* Print location only, but always include the address. */
499b725ae77Skettenis     LOC_AND_ADDRESS
500b725ae77Skettenis   };
501b725ae77Skettenis 
502b725ae77Skettenis /* Allocate additional space for appendices to a struct frame_info.
503b725ae77Skettenis    NOTE: Much of GDB's code works on the assumption that the allocated
504b725ae77Skettenis    saved_regs[] array is the size specified below.  If you try to make
505b725ae77Skettenis    that array smaller, GDB will happily walk off its end.  */
506b725ae77Skettenis 
507b725ae77Skettenis #ifdef SIZEOF_FRAME_SAVED_REGS
508b725ae77Skettenis #error "SIZEOF_FRAME_SAVED_REGS can not be re-defined"
509e93f7393Sniklas #endif
510b725ae77Skettenis #define SIZEOF_FRAME_SAVED_REGS \
511b725ae77Skettenis         (sizeof (CORE_ADDR) * (NUM_REGS+NUM_PSEUDO_REGS))
512e93f7393Sniklas 
513b725ae77Skettenis /* Allocate zero initialized memory from the frame cache obstack.
514b725ae77Skettenis    Appendices to the frame info (such as the unwind cache) should
515b725ae77Skettenis    allocate memory using this method.  */
516e93f7393Sniklas 
517b725ae77Skettenis extern void *frame_obstack_zalloc (unsigned long size);
518b725ae77Skettenis #define FRAME_OBSTACK_ZALLOC(TYPE) ((TYPE *) frame_obstack_zalloc (sizeof (TYPE)))
519b725ae77Skettenis #define FRAME_OBSTACK_CALLOC(NUMBER,TYPE) ((TYPE *) frame_obstack_zalloc ((NUMBER) * sizeof (TYPE)))
520e93f7393Sniklas 
521*63addd46Skettenis /* Create a regcache, and copy the frame's registers into it.  */
522*63addd46Skettenis struct regcache *frame_save_as_regcache (struct frame_info *this_frame);
523e93f7393Sniklas 
524b725ae77Skettenis extern struct block *get_frame_block (struct frame_info *,
525b725ae77Skettenis                                       CORE_ADDR *addr_in_block);
526e93f7393Sniklas 
527b725ae77Skettenis /* Return the `struct block' that belongs to the selected thread's
528b725ae77Skettenis    selected frame.  If the inferior has no state, return NULL.
529e93f7393Sniklas 
530b725ae77Skettenis    NOTE: cagney/2002-11-29:
531e93f7393Sniklas 
532b725ae77Skettenis    No state?  Does the inferior have any execution state (a core file
533b725ae77Skettenis    does, an executable does not).  At present the code tests
534b725ae77Skettenis    `target_has_stack' but I'm left wondering if it should test
535b725ae77Skettenis    `target_has_registers' or, even, a merged target_has_state.
536e93f7393Sniklas 
537b725ae77Skettenis    Should it look at the most recently specified SAL?  If the target
538b725ae77Skettenis    has no state, should this function try to extract a block from the
539b725ae77Skettenis    most recently selected SAL?  That way `list foo' would give it some
540*63addd46Skettenis    sort of reference point.  Then again, perhaps that would confuse
541b725ae77Skettenis    things.
542e93f7393Sniklas 
543b725ae77Skettenis    Calls to this function can be broken down into two categories: Code
544b725ae77Skettenis    that uses the selected block as an additional, but optional, data
545b725ae77Skettenis    point; Code that uses the selected block as a prop, when it should
546b725ae77Skettenis    have the relevant frame/block/pc explicitly passed in.
547e93f7393Sniklas 
548b725ae77Skettenis    The latter can be eliminated by correctly parameterizing the code,
549b725ae77Skettenis    the former though is more interesting.  Per the "address" command,
550*63addd46Skettenis    it occurs in the CLI code and makes it possible for commands to
551b725ae77Skettenis    work, even when the inferior has no state.  */
552e93f7393Sniklas 
553b725ae77Skettenis extern struct block *get_selected_block (CORE_ADDR *addr_in_block);
554e93f7393Sniklas 
555b725ae77Skettenis extern struct symbol *get_frame_function (struct frame_info *);
556e93f7393Sniklas 
557b725ae77Skettenis extern CORE_ADDR get_pc_function_start (CORE_ADDR);
558e93f7393Sniklas 
559b725ae77Skettenis extern struct frame_info *find_relative_frame (struct frame_info *, int *);
560e93f7393Sniklas 
561*63addd46Skettenis extern void show_and_print_stack_frame (struct frame_info *fi, int print_level,
562*63addd46Skettenis 					enum print_what print_what);
563e93f7393Sniklas 
564*63addd46Skettenis extern void print_stack_frame (struct frame_info *, int print_level,
565*63addd46Skettenis 			       enum print_what print_what);
566e93f7393Sniklas 
567b725ae77Skettenis extern void show_stack_frame (struct frame_info *);
568e93f7393Sniklas 
569*63addd46Skettenis extern void print_frame_info (struct frame_info *, int print_level,
570*63addd46Skettenis 			      enum print_what print_what, int args);
571e93f7393Sniklas 
572b725ae77Skettenis extern struct frame_info *block_innermost_frame (struct block *);
573e93f7393Sniklas 
574*63addd46Skettenis extern int deprecated_pc_in_call_dummy (CORE_ADDR pc);
575e93f7393Sniklas 
576b725ae77Skettenis /* FIXME: cagney/2003-02-02: Should be deprecated or replaced with a
577b725ae77Skettenis    function called get_frame_register_p().  This slightly weird (and
578b725ae77Skettenis    older) variant of get_frame_register() returns zero (indicating the
579b725ae77Skettenis    register is unavailable) if either: the register isn't cached; or
580b725ae77Skettenis    the register has been optimized out.  Problem is, neither check is
581b725ae77Skettenis    exactly correct.  A register can't be optimized out (it may not
582b725ae77Skettenis    have been saved as part of a function call); The fact that a
583b725ae77Skettenis    register isn't in the register cache doesn't mean that the register
584b725ae77Skettenis    isn't available (it could have been fetched from memory).  */
585e93f7393Sniklas 
586b725ae77Skettenis extern int frame_register_read (struct frame_info *frame, int regnum,
587b725ae77Skettenis 				void *buf);
588e93f7393Sniklas 
589b725ae77Skettenis /* From stack.c.  */
590b725ae77Skettenis extern void args_info (char *, int);
591e93f7393Sniklas 
592b725ae77Skettenis extern void locals_info (char *, int);
593e93f7393Sniklas 
594*63addd46Skettenis extern void (*deprecated_selected_frame_level_changed_hook) (int);
595e93f7393Sniklas 
596b725ae77Skettenis extern void return_command (char *, int);
597e93f7393Sniklas 
598e93f7393Sniklas 
599b725ae77Skettenis /* NOTE: cagney/2002-11-27:
600e93f7393Sniklas 
601b725ae77Skettenis    You might think that the below global can simply be replaced by a
602b725ae77Skettenis    call to either get_selected_frame() or select_frame().
603e93f7393Sniklas 
604b725ae77Skettenis    Unfortunately, it isn't that easy.
605e93f7393Sniklas 
606b725ae77Skettenis    The relevant code needs to be audited to determine if it is
607*63addd46Skettenis    possible (or practical) to instead pass the applicable frame in as a
608b725ae77Skettenis    parameter.  For instance, DEPRECATED_DO_REGISTERS_INFO() relied on
609b725ae77Skettenis    the deprecated_selected_frame global, while its replacement,
610b725ae77Skettenis    PRINT_REGISTERS_INFO(), is parameterized with the selected frame.
611*63addd46Skettenis    The only real exceptions occur at the edge (in the CLI code) where
612b725ae77Skettenis    user commands need to pick up the selected frame before proceeding.
613e93f7393Sniklas 
614b725ae77Skettenis    This is important.  GDB is trying to stamp out the hack:
615e93f7393Sniklas 
616b725ae77Skettenis    saved_frame = deprecated_selected_frame;
617b725ae77Skettenis    deprecated_selected_frame = ...;
618b725ae77Skettenis    hack_using_global_selected_frame ();
619b725ae77Skettenis    deprecated_selected_frame = saved_frame;
620e93f7393Sniklas 
621b725ae77Skettenis    Take care!  */
622e93f7393Sniklas 
623b725ae77Skettenis extern struct frame_info *deprecated_selected_frame;
624b725ae77Skettenis 
625b725ae77Skettenis /* NOTE: drow/2003-09-06:
626b725ae77Skettenis 
627b725ae77Skettenis    This function is "a step sideways" for uses of deprecated_selected_frame.
628b725ae77Skettenis    They should be fixed as above, but meanwhile, we needed a solution for
629b725ae77Skettenis    cases where functions are called with a NULL frame meaning either "the
630b725ae77Skettenis    program is not running" or "use the selected frame".  Lazy building of
631b725ae77Skettenis    deprecated_selected_frame confuses the situation, because now
632b725ae77Skettenis    deprecated_selected_frame can be NULL even when the inferior is running.
633b725ae77Skettenis 
634b725ae77Skettenis    This function calls get_selected_frame if the inferior should have a
635b725ae77Skettenis    frame, or returns NULL otherwise.  */
636b725ae77Skettenis 
637b725ae77Skettenis extern struct frame_info *deprecated_safe_get_selected_frame (void);
638b725ae77Skettenis 
639b725ae77Skettenis /* Create a frame using the specified BASE and PC.  */
640b725ae77Skettenis 
641b725ae77Skettenis extern struct frame_info *create_new_frame (CORE_ADDR base, CORE_ADDR pc);
642b725ae77Skettenis 
643b725ae77Skettenis /* FIXME: cagney/2002-12-06: Has the PC in the current frame changed?
644b725ae77Skettenis    "infrun.c", Thanks to DECR_PC_AFTER_BREAK, can change the PC after
645b725ae77Skettenis    the initial frame create.  This puts things back in sync.
646b725ae77Skettenis 
647b725ae77Skettenis    This replaced: frame->pc = ....; */
648b725ae77Skettenis extern void deprecated_update_frame_pc_hack (struct frame_info *frame,
649b725ae77Skettenis 					     CORE_ADDR pc);
650b725ae77Skettenis 
651b725ae77Skettenis /* FIXME: cagney/2002-12-18: Has the frame's base changed?  Or to be
652b725ae77Skettenis    more exact, was that initial guess at the frame's base as returned
653*63addd46Skettenis    by the deleted read_fp() wrong?  If it was, fix it.  This shouldn't
654b725ae77Skettenis    be necessary since the code should be getting the frame's base
655b725ae77Skettenis    correct from the outset.
656b725ae77Skettenis 
657b725ae77Skettenis    This replaced: frame->frame = ....; */
658b725ae77Skettenis extern void deprecated_update_frame_base_hack (struct frame_info *frame,
659b725ae77Skettenis 					       CORE_ADDR base);
660b725ae77Skettenis 
661e93f7393Sniklas #endif /* !defined (FRAME_H)  */
662