1 /*---------------------------------------------------------------------------* 2 Project: TwlSDK - ELF Loader 3 File: el.h 4 5 Copyright 2006-2009 Nintendo. All rights reserved. 6 7 These coded instructions, statements, and computer programs contain 8 proprietary information of Nintendo of America Inc. and/or Nintendo 9 Company Ltd., and are protected by Federal copyright law. They may 10 not be disclosed to third parties or copied or duplicated in any form, 11 in whole or in part, without the prior written consent of Nintendo. 12 13 $Date:: 2009-06-04#$ 14 $Rev: 10698 $ 15 $Author: okubata_ryoma $ 16 *---------------------------------------------------------------------------*/ 17 #ifndef TWL_COMMON_EL_H_ 18 #define TWL_COMMON_EL_H_ 19 20 #ifdef SDK_TWL 21 #include <twl.h> 22 #else 23 #include <nitro.h> 24 #endif 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 31 /*------------------------------------------------------ 32 Typedef 33 -----------------------------------------------------*/ 34 typedef u32 ELDlld; 35 typedef void *(*ELAlloc)(size_t size); 36 typedef void (*ELFree)(void* ptr); 37 typedef u32 (*ELReadImage)( u32 offset, void* buf, u32 size); 38 39 40 /*------------------------------------------------------ 41 Constants specified with the EL_CalcEnoughBufferSizeforLink* functions 42 -----------------------------------------------------*/ 43 typedef enum ELLinkMode { 44 EL_LINKMODE_ROUGH = 0, 45 EL_LINKMODE_ONESHOT, 46 EL_LINKMODE_RELATION 47 } ELLinkMode; 48 49 /*------------------------------------------------------ 50 Error code 51 -----------------------------------------------------*/ 52 #define EL_SUCCESS 0 53 #define EL_FAILED 1 54 #define EL_RELOCATED 0xF1 //For EL_ResolveAll only 55 56 /*------------------------------------------------------ 57 Detailed error codes obtained with EL_GetResultCode 58 -----------------------------------------------------*/ 59 typedef enum ELResult { 60 EL_RESULT_SUCCESS = 0, 61 EL_RESULT_FAILURE = 1, 62 EL_RESULT_INVALID_PARAMETER, 63 EL_RESULT_INVALID_ELF, 64 EL_RESULT_UNSUPPORTED_ELF, 65 EL_RESULT_CANNOT_ACCESS_ELF, //Error when opening or reading an ELF file 66 EL_RESULT_NO_MORE_RESOURCE //malloc failed 67 } ELResult; 68 69 70 /*------------------------------------------------------ 71 Address table for exporting 72 -----------------------------------------------------*/ 73 typedef struct { 74 void* next; /*Next address entry*/ 75 char* name; /*String*/ 76 void* adr; /*Address*/ 77 u16 func_flag; /*0: Data. 1: Function.*/ 78 u16 thumb_flag; /*0: ARM code. 1: Thumb code.*/ 79 }ELAdrEntry; 80 81 82 /*---------------------------------------------------------------------------* 83 Name: EL_Init 84 85 Description: Initializes the dynamic link system. 86 87 Arguments: alloc: Heap-allocation function 88 free: Heap deallocation function 89 90 Returns: 0 if successful; -1 if failed. 91 *---------------------------------------------------------------------------*/ 92 s32 EL_Init( ELAlloc alloc, ELFree free); 93 94 95 /*---------------------------------------------------------------------------* 96 Name: EL_CalcEnoughBufferSizeforLink* 97 98 Description: Returns a buffer size sufficient to test and relocate the dynamic link. 99 Return a slightly larger size when the dynamic object is referencing externally. 100 101 102 Arguments: FilePath: Path name of the dynamic object 103 buf: Buffer address for the relocating destination (writing is not actually performed) 104 readfunc: Read function prepared by the application 105 len: Size of the dynamic object 106 obj_image: Address on the memory where the dynamic object exists 107 obj_len: Size of the dynamic object 108 link_mode: Mode for testing dynamic links 109 (This constant is used to make a trade-off between processing time and accuracy) 110 111 Returns: Buffer size when successful; -1 if failed. 112 *---------------------------------------------------------------------------*/ 113 s32 EL_CalcEnoughBufferSizeforLinkFile( const char* FilePath, const void* buf, ELLinkMode link_mode); 114 s32 EL_CalcEnoughBufferSizeforLink( ELReadImage readfunc, u32 len, const void* buf, ELLinkMode link_mode); 115 s32 EL_CalcEnoughBufferSizeforLinkImage( void* obj_image, u32 obj_len, const void* buf, ELLinkMode link_mode); 116 117 118 /*---------------------------------------------------------------------------* 119 Name: EL_Link*Ex 120 121 Description: Relocates a dynamic object (from a file, user function, or memory) while checking whether it fits in the given buffer. 122 123 124 Arguments: FilePath: Path name of the dynamic object 125 readfunc: Read function prepared by the application 126 len: Size of the dynamic object 127 obj_image: Address on the memory where the dynamic object exists 128 obj_len: Size of the dynamic object 129 buf: Buffer address for the relocation destination 130 buf_size: Size of the buffer to relocate to 131 132 Returns: Dynamic module handle when successful, 0 if failed. 133 *---------------------------------------------------------------------------*/ 134 ELDlld EL_LinkFileEx( const char* FilePath, void* buf, u32 buf_size); 135 ELDlld EL_LinkEx( ELReadImage readfunc, u32 len, void* buf, u32 buf_size); 136 ELDlld EL_LinkImageEx( void* obj_image, u32 obj_len, void* buf, u32 buf_size); 137 138 /*---------------------------------------------------------------------------* 139 Name: EL_Link* 140 141 Description: Relocates dynamic objects (files/user functions/from memory). 142 143 Arguments: FilePath: Path name of the dynamic object 144 readfunc: Read function prepared by the application 145 len: Size of the dynamic object 146 obj_image: Address on the memory where the dynamic object exists 147 obj_len: Size of the dynamic object 148 buf: Buffer address for the relocation destination 149 150 Returns: Dynamic module handle when successful, 0 if failed. 151 *---------------------------------------------------------------------------*/ 152 ELDlld EL_LinkFile( const char* FilePath, void* buf); 153 ELDlld EL_Link( ELReadImage readfunc, u32 len, void* buf); 154 ELDlld EL_LinkImage( void* obj_image, u32 obj_len, void* buf); 155 156 157 /*---------------------------------------------------------------------------* 158 Name: EL_ResolveAll 159 160 Description: Resolves unresolved symbols. 161 162 Arguments: None. 163 164 Returns: EL_RELOCATED when successful, EL_FAILED if failed. 165 *---------------------------------------------------------------------------*/ 166 u16 EL_ResolveAll( void); 167 168 169 /*---------------------------------------------------------------------------* 170 Name: EL_Export 171 172 Description: Registers symbol information to the DLL system. 173 174 Arguments: None. 175 176 Returns: If successful, TRUE. 177 *---------------------------------------------------------------------------*/ 178 BOOL EL_Export( ELAdrEntry* AdrEnt); 179 180 181 /*---------------------------------------------------------------------------* 182 Name: EL_AddStaticSym 183 184 Description: Registers dynamic module symbol information with the DLL system. 185 (This is defined as a weak symbol in the ELF library, and will be overwritten by the definition in files created by makelst.) 186 187 Arguments: None. 188 189 Returns: None. 190 *---------------------------------------------------------------------------*/ 191 void EL_AddStaticSym( void); 192 193 194 /*---------------------------------------------------------------------------* 195 Name: EL_GetGlobalAdr 196 197 Description: Searches a symbol from the dynamic module and returns the address. 198 199 Arguments: my_dlld: Handle of dynamic module targeted for the search 200 ent_name: Symbol name 201 202 Returns: Address of symbol when successful, 0 if failed. 203 *---------------------------------------------------------------------------*/ 204 void* EL_GetGlobalAdr( ELDlld my_dlld, const char* ent_name); 205 206 207 /*---------------------------------------------------------------------------* 208 Name: EL_Unlink 209 210 Description: Unlinks the dynamic module. 211 212 Arguments: my_dlld: Handle of dynamic module to unlink 213 214 Returns: EL_SUCCESS when successful, EL_FAILED if failed. 215 *---------------------------------------------------------------------------*/ 216 u16 EL_Unlink( ELDlld my_dlld); 217 218 219 /*---------------------------------------------------------------------------* 220 Name: EL_IsResolved 221 222 Description: Determines whether all of a dynamic module's external references have been resolved. 223 224 Arguments: my_dlld: Dynamic module handle to check 225 226 Returns: TRUE if there are still unresolved external references. 227 *---------------------------------------------------------------------------*/ 228 BOOL EL_IsResolved( ELDlld my_dlld); 229 230 231 /*---------------------------------------------------------------------------* 232 Name: EL_GetLibSize 233 234 Description: Returns the size of a linked dynamic module. 235 The current size of the dynamic module will be returned, even if it still has unresolved external references. 236 You can get the final size after relocation is complete by confirming in advance that EL_ResolveAll returns EL_RELOCATED. 237 238 239 240 Arguments: my_dlld: Dynamic module handle that will have its size checked 241 242 Returns: Size if successful; 0 if failed. 243 *---------------------------------------------------------------------------*/ 244 u32 EL_GetLibSize( ELDlld my_dlld); 245 246 247 /*---------------------------------------------------------------------------* 248 Name: EL_GetResultCode 249 250 Description: Returns detailed results of final processes. 251 252 Arguments: None. 253 254 Returns: Error code of type ELResult. 255 *---------------------------------------------------------------------------*/ 256 ELResult EL_GetResultCode( void); 257 258 259 #ifdef __cplusplus 260 } /* extern "C" */ 261 #endif 262 263 #endif /*TWL_COMMON_EL_H_*/ 264