1 /* unwind_env.h

     2  *

     3  * Copyright 2003 ARM Limited.

     4  */

     5 /*

     6   Licence

     7   

     8   1. Subject to the provisions of clause 2, ARM hereby grants to LICENSEE a 

     9   perpetual, non-exclusive, nontransferable, royalty free, worldwide licence 

    10   to use this Example Implementation of Exception Handling solely for the 

    11   purpose of developing, having developed, manufacturing, having 

    12   manufactured, offering to sell, selling, supplying or otherwise 

    13   distributing products which comply with the Exception Handling ABI for the 

    14   ARM Architecture specification. All other rights are reserved to ARM or its 

    15   licensors.

    16   

    17   2. THIS EXAMPLE IMPLEMENTATION OF EXCEPTION HANDLING  IS PROVIDED "AS IS" 

    18   WITH NO WARRANTIES EXPRESS, IMPLIED OR STATUTORY, INCLUDING BUT NOT LIMITED 

    19   TO ANY WARRANTY OF SATISFACTORY QUALITY, MERCHANTABILITY, NONINFRINGEMENT 

    20   OR FITNESS FOR A PARTICULAR PURPOSE.

    21 */

    22 /*

    23  * RCS $Revision: 1.3 $

    24  * Checkin $Date: 2003/10/23 13:57:32 $

    25  * Revising $Author: agrant $

    26  */

    27 

    28 /* Environment definition - abstractions and requirements - to aid

    29  * portability of the ARM exceptions code.

    30  */

    31 

    32 #ifndef UNWINDENV_H

    33 #define UNWINDENV_H

    34 

    35 /* ---------------------------------------------------------------------- */

    36 

    37 /* Source language

    38  *

    39  * The compiler is expected to define preprocessor symbols as follows:

    40  * __cplusplus when compiling in C++ mode.

    41  * __thumb when compiling to Thumb code.

    42  *

    43  * Some use is made of embedded assembly language, introduced by __asm.

    44  * This is described in ARM's toolchain documentation. Some edits may be

    45  * required for other compilers. The compiler should define one or more of:

    46  * __TARGET_ARCH_4T __TARGET_ARCH_4TXM __TARGET_ARCH_5T __TARGET_ARCH_5TXM

    47  * __TARGET_ARCH_5TE __TARGET_ARCH_6

    48  * so the correct assembly wrappers are generated for certain functions.

    49  *

    50  * __APCS_INTERWORK should be defined if ARM/Thumb interworking is required.

    51  *

    52  * For all the above symbols, if your compiler does not provide appropriate

    53  * definitions, add them here.

    54  *

    55  * Some source language extensions are also used.

    56  */

    57 

    58 /* ---------------------------------------------------------------------- */

    59 

    60 /* Library structure

    61  *

    62  * ARM's private make system contains an automated facility for compiling

    63  * source files multiple times to create multiple object files. The source

    64  * regions intended to constitute object file xxx.o are delimited by

    65  * #ifdef xxx_c / #endif directives. The exact preprocessor symbols used

    66  * for this conditionalisation are described in a comment at the start of

    67  * each file. When porting to a different system, compilations must be

    68  * performed with these preprocessor symbols appropriately defined

    69  * (or remove the conditionalisation).

    70  *

    71  * ARM declares (or redeclares) some routines as weak in order that

    72  * references to them are weak, so that the static linker will not load

    73  * unwanted code. This is achieved by decorating routine declarations

    74  * with appropriate language extensions. Note that compilers supporting

    75  * similar features but via a different syntax may require edits to

    76  * the library source.

    77  *

    78  * Define those decorations here (define as empty if not required):

    79  */

    80 

    81 #define WEAKDECL __weak        /* token in C and C++ */

    82 #define WEAKASMDECL [WEAK]     /* token in assembler */

    83 

    84 /* ---------------------------------------------------------------------- */

    85 

    86 /* Source language support and language extensions */

    87 

    88 /* It is possible to compile the C++ semantics code using a compiler

    89  * which does not support C++ exceptions; this was useful to ARM whilst

    90  * ARM's compiler was being developed, and the facility has not been

    91  * removed. C++ exceptions syntax is conditionalised by

    92  * #ifdef ARM_EXCEPTIONS_ENABLED / #endif. Define ARM_EXCEPTIONS_ENABLED

    93  * by some means here if you want a usable library:

    94  */

    95 

    96 #ifdef __cplusplus

    97 extern "C" {

    98   /* For conditionalisation, specifically on ARM_EXCEPTIONS_ENABLED */

    99 #include "basics.h"

   100 }

   101 #endif

   102 

   103 /* The following definitions of syntax decoration may be empty if the

   104  * facility is not required. Note that compilers supporting similar

   105  * features but via a different syntax may require edits to the library

   106  * source.

   107  * 

   108  * Define the decorations here (define as empty if not required):

   109  */

   110   

   111 /* If the compiler understands noreturn functions: */

   112 #define NORETURNDECL __declspec(noreturn)

   113 

   114 /* ---------------------------------------------------------------------- */

   115 

   116 /* Types */

   117 

   118 /* The implementation requires types uint8_t, uint16_t, uint32_t and

   119  * uint64_t to be defined as unsigned integers of the appropriate number

   120  * of bits.

   121  *

   122  * Do that here:

   123  */

   124 

   125 #include <stdint.h>

   126 

   127 /* The C++ semantics support requires definition of the RTTI object

   128  * layout. We use the same structures and names as the generic C++

   129  * ABI for Itanium.

   130  *

   131  * Define those structures here:

   132  */

   133 

   134 #ifdef __cplusplus

   135 extern "C" {

   136 #include "cxxabi.h"

   137 }

   138 #endif

   139 

   140 /* ---------------------------------------------------------------------- */

   141 

   142 /* External requirements */

   143 

   144 /* The C++ exception-handling 'globals' should be allocated per-thread.

   145  * The Exceptions ABI does not specify how this happens, but it is

   146  * intended that the details are localised to __cxa_get_globals.

   147  *

   148  * In the ARM implementation of __cxa_get_globals, it is assumed that a

   149  * zero-initialised location in a known per-thread place is somehow

   150  * obtainable, and can be assigned (by __cxa_get_globals) a pointer to

   151  * the allocated globals data structure. The macro EH_GLOBALS should be

   152  * defined here to yield a suitable address of type void*. This is used

   153  * only in __cxa_get_globals.

   154  *

   155  * Define it here:

   156  */

   157 

   158 #ifdef __cplusplus

   159 extern "C" {

   160   /* for __user_libspace() machinery */

   161 #include <interns.h>

   162 #define EH_GLOBALS libspace.eh_globals

   163 }

   164 #endif

   165 

   166 

   167 /* A routine is required for C++ derived class to base class conversion.

   168  * This is used once, in __cxa_type_match. It is likely that suitable

   169  * code exists as part of the RTTI support code. Therefore access it

   170  * via a macro:

   171  * DERIVED_TO_BASE_CONVERSION(PTR, P_NEW_PTR, CLASS_INFO, BASE_INFO)

   172  *   Convert PTR from a pointer to a derived class (described by

   173  *   CLASS_INFO) to a pointer to a base class (described by BASE_INFO)

   174  *   and store the resulting pointer in P_NEW_PTR. Return true (or

   175  *   non-zero) if the base class was found and the conversion was done,

   176  *   otherwise return false (or zero).

   177  *

   178  * Define the macro here:

   179  */

   180 

   181 #ifdef __cplusplus

   182 /* In the ARM implementation, a suitable routine exists elsewhere in the

   183  * C++ runtime library, where it is part of the dynamic_cast mechanism.

   184  */

   185 extern "C" int __derived_to_base_conversion(void** p_ptr, void** p_new_ptr,

   186                                             const std::type_info * class_info,

   187                                             const std::type_info * base_info,

   188                                             char** access_flags, int use_access_flags);

   189 

   190 #define DERIVED_TO_BASE_CONVERSION(PTR, P_NEW_PTR, CLASS_INFO, BASE_INFO) \

   191   __derived_to_base_conversion(&(PTR), (P_NEW_PTR), (CLASS_INFO), (BASE_INFO), NULL, 0)

   192 #endif

   193 

   194 

   195 /* ---------------------------------------------------------------------- */

   196 

   197 /* Runtime debug support

   198  *

   199  * Here we define the interface to a "bottleneck function" to be called

   200  * by exception handling code at 'interesting' points during execution,

   201  * and breakpointable by a debugger.

   202  *

   203  * This is not part of the Exceptions ABI but is expected to be

   204  * standardised elsewhere, probably in a Debug ABI.

   205  *

   206  * If you don't want this, define DEBUGGER_BOTTLENECK as a dummy, e.g.

   207  * #define DEBUGGER_BOTTLENECK(UCBP,LANG,ACTIVITY,ARG) (void)0

   208  */

   209 

   210 #ifdef __cplusplus

   211 extern "C" {

   212 #endif

   213 

   214   struct _Unwind_Control_Block;

   215 

   216   typedef enum {

   217     _UASUBSYS_CPP      = 0x00,

   218     _UASUBSYS_UNWINDER = 0xff

   219   } _Unwind_Activity_subsystem;

   220 

   221   typedef enum {

   222     _UAACT_STARTING     = 0x0,

   223     _UAACT_ENDING       = 0x1,

   224     _UAACT_BARRIERFOUND = 0x2,

   225     _UAACT_PADENTRY     = 0x3,

   226     _UAACT_CPP_TYPEINFO = 0x80

   227   } _Unwind_Activity_activity;

   228 

   229   typedef enum {

   230     _UAARG_ENDING_UNSPECIFIED           = 0x0,

   231     _UAARG_ENDING_TABLECORRUPT          = 0x1,

   232     _UAARG_ENDING_NOUNWIND              = 0x2,

   233     _UAARG_ENDING_VRSFAILED             = 0x3,

   234     /* C++ only: */

   235     _UAARG_ENDING_CPP_BADOPCODE         = 0x4,

   236     /* Unwinder only: */

   237     _UAARG_ENDING_UNWINDER_LOOKUPFAILED = 0x4,

   238     _UAARG_ENDING_UNWINDER_BUFFERFAILED = 0x5

   239   } _Unwind_Activity_arg;

   240 

   241   void _Unwind_Activity(struct _Unwind_Control_Block *ucbp, uint32_t reason, uint32_t arg);

   242 #define DEBUGGER_BOTTLENECK(UCBP,LANG,ACTIVITY,ARG) \

   243   _Unwind_Activity((UCBP),(((LANG)<<24)|ACTIVITY),(uint32_t)(ARG))

   244 

   245 #ifdef __cplusplus

   246 }

   247 #endif

   248 

   249 

   250 /* ---------------------------------------------------------------------- */

   251 

   252 /* Printed diagnostics

   253  *

   254  * These may be useful for debugging purposes during development, provided

   255  * the execution environment supports diagnostics via printf.

   256  *

   257  * #define PR_DIAGNOSTICS for printed diagnostics from the personality routine.

   258  * #define VRS_DIAGNOSTICS for printed diagnostics about VRS operations.

   259  * #define UNWIND_ACTIVITY_DIAGNOSTICS for printed information from _Unwind_Activity.

   260  */

   261 

   262 /* ---------------------------------------------------------------------- */

   263 

   264 #endif /* defined UNWINDENV_H */