1 /*---------------------------------------------------------------------------* 2 Project: TwlSDK - ELF Loader 3 File: el.h 4 5 Copyright 2006-2008 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:: 2008-12-10#$ 14 $Rev: 9620 $ 15 $Author: shirait $ 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 Codes 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: Function to get the heap 88 free: Function to free the heap 89 90 Returns: 0 on success and -1 on failure. 91 *---------------------------------------------------------------------------*/ 92 s32 EL_Init( ELAlloc alloc, ELFree free); 93 94 95 /*---------------------------------------------------------------------------* 96 Name: EL_CalcEnoughBufferSizeforLink* 97 98 Description: Tests a dynamic link and returns a buffer size sufficient to relocate it. 99 Dynamic objects use external references, so a slightly large size will sometimes be returned. 100 101 102 Arguments: FilePath: The path name to the dynamic object 103 buf: The buffer address to relocate to (nothing is actually written in it) 104 readfunc: A read function prepared by the application 105 len: The dynamic object size 106 obj_image: The memory address where the dynamic object exists 107 obj_len: The dynamic object size 108 link_mode: Mode when testing a dynamic link 109 (this constant is used to make a trade-off between processing time and accuracy) 110 111 Returns: The buffer size on success and -1 on failure. 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* 120 121 Description: Relocates a dynamic object (from a file, user function, or memory). 122 123 Arguments: FilePath: The path name to the dynamic object 124 readfunc: A read function prepared by the application 125 len: The dynamic object size 126 obj_image: The memory address where the dynamic object exists 127 obj_len: The dynamic object size 128 buf: The buffer address to relocate to 129 130 Returns: A dynamic module handle on success and 0 on failure. 131 *---------------------------------------------------------------------------*/ 132 ELDlld EL_LinkFile( const char* FilePath, void* buf); 133 ELDlld EL_Link( ELReadImage readfunc, u32 len, void* buf); 134 ELDlld EL_LinkImage( void* obj_image, u32 obj_len, void* buf); 135 136 137 /*---------------------------------------------------------------------------* 138 Name: EL_ResolveAll 139 140 Description: Resolves unresolved symbols. 141 142 Arguments: None. 143 144 Returns: EL_RELOCATED on success and EL_FAILED on failure. 145 *---------------------------------------------------------------------------*/ 146 u16 EL_ResolveAll( void); 147 148 149 /*---------------------------------------------------------------------------* 150 Name: EL_Export 151 152 Description: Registers symbol information with the DLL system. 153 154 Arguments: None. 155 156 Returns: TRUE on success. 157 *---------------------------------------------------------------------------*/ 158 BOOL EL_Export( ELAdrEntry* AdrEnt); 159 160 161 /*---------------------------------------------------------------------------* 162 Name: EL_AddStaticSym 163 164 Description: Registers dynamic module symbol information with the DLL system. 165 (This is defined as a weak symbol in the ELF library, and will be overwritten by the definition in files created by makelst) 166 167 Arguments: None. 168 169 Returns: None. 170 *---------------------------------------------------------------------------*/ 171 void EL_AddStaticSym( void); 172 173 174 /*---------------------------------------------------------------------------* 175 Name: EL_GetGlobalAdr 176 177 Description: Searches a dynamic module for a symbol and returns its address. 178 179 Arguments: my_dlld: The dynamic module handle to search 180 ent_name: The symbol name 181 182 Returns: The symbol's address on success and 0 on failure. 183 *---------------------------------------------------------------------------*/ 184 void* EL_GetGlobalAdr( ELDlld my_dlld, const char* ent_name); 185 186 187 /*---------------------------------------------------------------------------* 188 Name: EL_Unlink 189 190 Description: Unlinks a dynamic module. 191 192 Arguments: my_dlld: The dynamic module handle to unlink 193 194 Returns: EL_SUCCESS on success and EL_FAILED on failure. 195 *---------------------------------------------------------------------------*/ 196 u16 EL_Unlink( ELDlld my_dlld); 197 198 199 /*---------------------------------------------------------------------------* 200 Name: EL_IsResolved 201 202 Description: Determines whether all of a dynamic module's external references have been resolved. 203 204 Arguments: my_dlld: The dynamic module handle to check 205 206 Returns: TRUE if there are still unresolved external references. 207 *---------------------------------------------------------------------------*/ 208 BOOL EL_IsResolved( ELDlld my_dlld); 209 210 211 /*---------------------------------------------------------------------------* 212 Name: EL_GetLibSize 213 214 Description: Returns the size of a linked dynamic module. 215 The current size of the dynamic module will be returned, even if it still has unresolved external references. 216 You can get the final size after relocation is complete by confirming in advance that EL_ResolveAll returns EL_RELOCATED. 217 218 219 220 Arguments: my_dlld: The dynamic module handle that will have its size checked 221 222 Returns: The size on success and 0 on failure. 223 *---------------------------------------------------------------------------*/ 224 u32 EL_GetLibSize( ELDlld my_dlld); 225 226 227 /*---------------------------------------------------------------------------* 228 Name: EL_GetResultCode 229 230 Description: Returns the detailed result of the last process to be run. 231 232 Arguments: None. 233 234 Returns: An ELResult error code. 235 *---------------------------------------------------------------------------*/ 236 ELResult EL_GetResultCode( void); 237 238 239 #ifdef __cplusplus 240 } /* extern "C" */ 241 #endif 242 243 #endif /*TWL_COMMON_EL_H_*/ 244