lib/unwarminder/unwarminder.h

   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  */
  40 typedef 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 }
  87 UnwResult;
  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  */
 101 typedef Boolean (*UnwindReportFunc)(void   *data,
 102                                     Int32   address);
 103
 104 /** Structure that holds memory callback function pointers.
 105  */
 106 typedef 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 }
 139 UnwindCallbacks;
 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  */
 153 UnwResult UnwindStart(Int32                  pcValue,
 154                       Int32                  spValue,
 155                       const UnwindCallbacks *cb,
 156                       void                  *data);
 157
 158 #endif /* UNWARMINDER_H */
 159
 160 /* END OF FILE */