1 /***************************************************************************
2 * ARM Stack Unwinder, Michael.McTernan.2001@cs.bris.ac.uk
4 * This program is PUBLIC DOMAIN.
5 * This means that there is no copyright and anyone is able to take a copy
6 * for free and use it as they wish, with or without modifications, and in
7 * any context, commerically or otherwise. The only limitation is that I
8 * don't guarantee that the software is fit for any purpose or accept any
9 * liablity for it's use or misuse - this software is without warranty.
10 **************************************************************************/
12 * Interface to the ARM stack unwinding module.
13 **************************************************************************/
18 /***************************************************************************
19 * Nested Include Files
20 **************************************************************************/
24 /***************************************************************************
26 **************************************************************************/
29 * If this define is set, additional information will be produced while
30 * unwinding the stack to allow debug of the unwind module itself.
32 /* #define UNW_DEBUG 1 */
34 /***************************************************************************
36 **************************************************************************/
38 /** Possible results for UnwindStart to return.
40 typedef enum UnwResultTag
42 /** Unwinding was successful and complete. */
45 /** More than UNW_MAX_INSTR_COUNT instructions were interpreted. */
48 /** Unwinding stopped because the reporting func returned FALSE. */
51 /** Read data was found to be inconsistent. */
54 /** Unsupported instruction or data found. */
57 /** General failure. */
60 /** Illegal instruction. */
63 /** Unwinding hit the reset vector. */
66 /** Failed read for an instruction word. */
69 /** Failed read for an instruction half-word. */
72 /** Failed read for an instruction byte. */
75 /** Failed read for a data word. */
78 /** Failed read for a data half-word. */
81 /** Failed read for a data byte. */
84 /** Failed write for a data word. */
89 /** Type for function pointer for result callback.
90 * The function is passed two parameters, the first is a void * pointer,
91 * and the second is the return address of the function. The bottom bit
92 * of the passed address indicates the execution mode; if it is set,
93 * the execution mode at the return address is Thumb, otherwise it is
96 * The return value of this function determines whether unwinding should
97 * continue or not. If TRUE is returned, unwinding will continue and the
98 * report function maybe called again in future. If FALSE is returned,
99 * unwinding will stop with UnwindStart() returning UNWIND_TRUNCATED.
101 typedef Boolean (*UnwindReportFunc
)(void *data
,
104 /** Structure that holds memory callback function pointers.
106 typedef struct UnwindCallbacksTag
108 /** Report an unwind result. */
109 UnwindReportFunc report
;
111 /** Read a 32 bit word from memory.
112 * The memory address to be read is passed as \a address, and
113 * \a *val is expected to be populated with the read value.
114 * If the address cannot or should not be read, FALSE can be
115 * returned to indicate that unwinding should stop. If TRUE
116 * is returned, \a *val is assumed to be valid and unwinding
119 Boolean (*readW
)(const Int32 address
, Int32
*val
);
121 /** Read a 16 bit half-word from memory.
122 * This function has the same usage as for readW, but is expected
123 * to read only a 16 bit value.
125 Boolean (*readH
)(const Int32 address
, Int16
*val
);
127 /** Read a byte from memory.
128 * This function has the same usage as for readW, but is expected
129 * to read only an 8 bit value.
131 Boolean (*readB
)(const Int32 address
, Int8
*val
);
133 #if defined(UNW_DEBUG)
134 /** Print a formatted line for debug. */
135 int (*printf
)(const char *format
, ...);
141 /***************************************************************************
143 **************************************************************************/
145 /***************************************************************************
146 * Function Prototypes
147 **************************************************************************/
149 /** Start unwinding the current stack.
150 * This will unwind the stack starting at the PC value supplied and
151 * the stack pointer value supplied.
153 UnwResult
UnwindStart(Int32 pcValue
,
155 const UnwindCallbacks
*cb
,
158 #endif /* UNWARMINDER_H */