Gitiles
Code Review Sign In
gerrit.rockbox.org / rockbox / 3cb272c97a23f6b28a60201614f38fd1a566de08 / . / lib / unwarminder / unwarminder.h
blob: 1c5adbf6936bca9e66452726d6964e457b8d9539 [file] [log] [blame]
Marcin Bukatb4eab592012-01-25 09:57:59 +0100[diff] [blame]1/***************************************************************************
2 * ARM Stack Unwinder, Michael.McTernan.2001@cs.bris.ac.uk
3 *
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 **************************************************************************/
11/** \file
12 * Interface to the ARM stack unwinding module.
13 **************************************************************************/
14
15#ifndef UNWARMINDER_H
16#define UNWARMINDER_H
17
18/***************************************************************************
19 * Nested Include Files
20 **************************************************************************/
21
22#include "types.h"
23
24/***************************************************************************
25 * Manifest Constants
26 **************************************************************************/
27
28/** \def UNW_DEBUG
29 * If this define is set, additional information will be produced while
30 * unwinding the stack to allow debug of the unwind module itself.
31 */
32/* #define UNW_DEBUG 1 */
33
34/***************************************************************************
35 * Type Definitions
36 **************************************************************************/
37
38/** Possible results for UnwindStart to return.
39 */
40typedef enum UnwResultTag
41{
42 /** Unwinding was successful and complete. */
43 UNWIND_SUCCESS = 0,
44
45 /** More than UNW_MAX_INSTR_COUNT instructions were interpreted. */
46 UNWIND_EXHAUSTED,
47
48 /** Unwinding stopped because the reporting func returned FALSE. */
49 UNWIND_TRUNCATED,
50
51 /** Read data was found to be inconsistent. */
52 UNWIND_INCONSISTENT,
53
54 /** Unsupported instruction or data found. */
55 UNWIND_UNSUPPORTED,
56
57 /** General failure. */
58 UNWIND_FAILURE,
59
60 /** Illegal instruction. */
61 UNWIND_ILLEGAL_INSTR,
62
63 /** Unwinding hit the reset vector. */
64 UNWIND_RESET,
65
66 /** Failed read for an instruction word. */
67 UNWIND_IREAD_W_FAIL,
68
69 /** Failed read for an instruction half-word. */
70 UNWIND_IREAD_H_FAIL,
71
72 /** Failed read for an instruction byte. */
73 UNWIND_IREAD_B_FAIL,
74
75 /** Failed read for a data word. */
76 UNWIND_DREAD_W_FAIL,
77
78 /** Failed read for a data half-word. */
79 UNWIND_DREAD_H_FAIL,
80
81 /** Failed read for a data byte. */
82 UNWIND_DREAD_B_FAIL,
83
84 /** Failed write for a data word. */
85 UNWIND_DWRITE_W_FAIL
86}
87UnwResult;
88
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
94 * ARM.
95 *
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.
100 */
101typedef Boolean (*UnwindReportFunc)(void *data,
102 Int32 address);
103
104/** Structure that holds memory callback function pointers.
105 */
106typedef struct UnwindCallbacksTag
107{
108 /** Report an unwind result. */
109 UnwindReportFunc report;
110
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
117 * will continue.
118 */
119 Boolean (*readW)(const Int32 address, Int32 *val);
120
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.
124 */
125 Boolean (*readH)(const Int32 address, Int16 *val);
126
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.
130 */
131 Boolean (*readB)(const Int32 address, Int8 *val);
132
133#if defined(UNW_DEBUG)
134 /** Print a formatted line for debug. */
135 int (*printf)(const char *format, ...);
136#endif
137
138}
139UnwindCallbacks;
140
141/***************************************************************************
142 * Macros
143 **************************************************************************/
144
145/***************************************************************************
146 * Function Prototypes
147 **************************************************************************/
148
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.
152 */
153UnwResult UnwindStart(Int32 pcValue,
154 Int32 spValue,
155 const UnwindCallbacks *cb,
156 void *data);
157
158#endif /* UNWARMINDER_H */
159
160/* END OF FILE */