1 /* ---------------------------------------------------------------------------- 2 * Copyright (c) Huawei Technologies Co., Ltd. 2013-2019. All rights reserved. 3 * Description: Dynload ElfLib HeadFile 4 * Author: Huawei LiteOS Team 5 * Create: 2013-01-01 6 * Redistribution and use in source and binary forms, with or without modification, 7 * are permitted provided that the following conditions are met: 8 * 1. Redistributions of source code must retain the above copyright notice, this list of 9 * conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list 11 * of conditions and the following disclaimer in the documentation and/or other materials 12 * provided with the distribution. 13 * 3. Neither the name of the copyright holder nor the names of its contributors may be used 14 * to endorse or promote products derived from this software without specific prior written 15 * permission. 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 17 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 18 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 20 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 21 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 22 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 23 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 25 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 26 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 * --------------------------------------------------------------------------- */ 28 29 /** 30 * @defgroup los_dynload Dynamic loading 31 * @ingroup kernel 32 */ 33 34 #ifndef _LOS_LD_ELFLIB_H 35 #define _LOS_LD_ELFLIB_H 36 37 #include "los_typedef.h" 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif /* __cplusplus */ 42 43 /** 44 * @ingroup los_dynload 45 * Define an enum type indicates load strategy. 46 * 47 * Type of load strategy of dynamic load, ZIP means using zipped shared object, NOZIP means using normal shared object. 48 */ 49 enum LOAD_STRATEGY { 50 ZIP, 51 NOZIP 52 }; 53 54 /** 55 * @ingroup los_dynload 56 * Define the structure of the parameters used for dynamic. 57 * 58 * Information of specified parameters passed in during dynamic load. 59 */ 60 typedef struct tagDynloadParam { 61 enum LOAD_STRATEGY enLoadStrategy; 62 } DYNLOAD_PARAM_S; 63 64 /** 65 * @ingroup los_dynload 66 * @brief Register the dynamic parameters. 67 * 68 * @par Description: 69 * This API is used to register the dynamic load parameters. 70 * @attention 71 * <ul> 72 * <li></li> 73 * </ul> 74 * 75 * @param dynloadParam [IN] dynamic load parameters to be registered. 76 * 77 * @par Dependency: 78 * <ul><li>los_ld_elflib.h: the header file that contains the API declaration.</li></ul> 79 * @see LOS_FindSymByName | LOS_LdDestroy 80 * @since Huawei LiteOS V100R001C00 81 */ 82 extern VOID LOS_DynParamReg(const DYNLOAD_PARAM_S *dynloadParam); 83 84 /** 85 * @ingroup los_dynload 86 * @brief Load a shared object file. 87 * 88 * @par Description: 89 * This API is used to load a shared object file under a particular module file path. 90 * @attention 91 * <ul> 92 * <li>The parameter passed to this API should be a legal path of a shared object file.</li> 93 * </ul> 94 * 95 * @param elfFileName [IN] Shared object file path. 96 * 97 * @retval NULL The shared object file fails to be loaded. 98 * @retval VOID* The shared object file is successfully loaded. 99 * @par Dependency: 100 * <ul><li>los_ld_elflib.h: the header file that contains the API declaration.</li></ul> 101 * @see LOS_ModuleUnload 102 * @since Huawei LiteOS V100R001C00 103 */ 104 extern VOID *LOS_SoLoad(const CHAR *elfFileName); 105 106 /** 107 * @ingroup los_dynload 108 * @brief Load a shared object file(.so) or relocatable object file(.o) from the memory. 109 * 110 * @par Description: 111 * This API is used to load a shared or relocatable object file that is in memory. 112 * @attention 113 * <ul> 114 * <li>The shared object file does not depend on other shared objects.</li> 115 * </ul> 116 * 117 * @param elfFileName [IN] Shared or relocatable object file name. 118 * @param fileNameLen [IN] The length of shared or relocatable object file name. 119 * @param elfFileBuf [IN] Shared or relocatable object file buffer in memory. 120 * @param bufLen [IN] the length of shared or relocatable file buffer in memory. 121 * 122 * @retval NULL The shared or relocatable object file fails to be loaded. 123 * @retval VOID* The shared or relocatable object file is successfully loaded. 124 * @par Dependency: 125 * <ul><li>los_ld_elflib.h: the header file that contains the API declaration.</li></ul> 126 * @see LOS_ModuleUnload 127 * @since Huawei LiteOS V200R003C00 128 */ 129 extern VOID *LOS_MemLoad(const CHAR *elfFileName, UINT32 fileNameLen, 130 const CHAR *elfFileBuf, UINT32 bufLen); 131 132 /** 133 * @ingroup los_dynload 134 * @brief Load an relocatable object file(.o). 135 * 136 * @par Description: 137 * This API is used to load an relocatable object file under a particular module file path. 138 * @attention 139 * <ul> 140 * <li>The parameter passed to this API should be a legal path of an relocatable object file.</li> 141 * </ul> 142 * 143 * @param elfFileName [IN] Relocatable object file path. 144 * 145 * @retval NULL The relocatable object file fails to be loaded. 146 * @retval VOID* The relocatable object file is successfully loaded. 147 * @par Dependency: 148 * <ul><li>los_ld_elflib.h: the header file that contains the API declaration.</li></ul> 149 * @see LOS_ModuleUnload 150 * @since Huawei LiteOS V100R001C00 151 */ 152 extern VOID *LOS_ObjLoad(const CHAR *elfFileName); 153 154 /** 155 * @ingroup los_dynload 156 * @brief Unload a module. 157 * 158 * @par Description: 159 * This API is used to unload a module with a particular module handle. 160 * @attention 161 * <ul> 162 * <li>None.</li> 163 * </ul> 164 * 165 * @param handle [IN] Module handle. 166 * 167 * @retval #LOS_NOK The module fails to be unloaded. 168 * @retval #LOS_OK The module is successfully unloaded. 169 * @par Dependency: 170 * <ul><li>los_ld_elflib.h: the header file that contains the API declaration.</li></ul> 171 * @see LOS_ObjLoad 172 * @since Huawei LiteOS V100R001C00 173 */ 174 extern INT32 LOS_ModuleUnload(VOID *handle); 175 176 /** 177 * @ingroup los_dynload 178 * @brief Destroy a dynamic loader. 179 * 180 * @par Description: 181 * This API is used to destroy a dynamic linker. 182 * @attention 183 * <ul> 184 * <li>When dynamic loading is no longer needed, call this API to destroy the dynamic linker.</li> 185 * </ul> 186 * 187 * @param None. 188 * 189 * @retval None. 190 * @par Dependency: 191 * <ul><li>los_ld_elflib.h: the header file that contains the API declaration.</li></ul> 192 * @see LOS_FindSymByName 193 * @since Huawei LiteOS V100R001C00 194 */ 195 extern VOID LOS_LdDestroy(VOID); 196 197 /** 198 * @ingroup los_dynload 199 * @brief Search for a symbol address. 200 * 201 * @par Description: 202 * This API is used to search for the address of a symbol according to a particular module handle and symbol name. 203 * @attention 204 * <ul> 205 * <li>If the value of handle is NULL, Huawei LiteOS searches for symbols (including system symbols) in the global 206 * symbol table. If handle is set to a valid module handle, Huawei LiteOS searches for symbols in the module that 207 * comes with the module handle.</li> 208 * </ul> 209 * 210 * @param handle [IN] Module handle. 211 * @param name [IN] Name of the symbol to be searched for. 212 * 213 * @retval NULL The symbol address is not found. 214 * @retval VOID* Symbol address. 215 * @par Dependency: 216 * <ul><li>los_ld_elflib.h: the header file that contains the API declaration.</li></ul> 217 * @see LOS_LdDestroy 218 * @since Huawei LiteOS V100R001C00 219 */ 220 extern VOID *LOS_FindSymByName(VOID *handle, CHAR *name); 221 222 /** 223 * @ingroup los_dynload 224 * @brief Add a default path. 225 * 226 * @par Description: 227 * This API is used to add a path to default paths. 228 * @attention 229 * <ul> 230 * <li></li> 231 * </ul> 232 * 233 * @param path [IN] Path to be added to default paths. 234 * 235 * @retval #LOS_NOK The path is added unsuccessfully. 236 * @retval #LOS_OK The path is added successfully. 237 * @par Dependency: 238 * <ul><li>los_ld_elflib.h: the header file that contains the API declaration.</li></ul> 239 * @see LOS_FindSymByName | LOS_LdDestroy 240 * @since Huawei LiteOS V100R001C00 241 */ 242 extern INT32 LOS_PathAdd(CHAR *path); 243 244 /** 245 * @ingroup los_dynload 246 * @brief Set the memory pool address used by dynload 247 * 248 * @par Description: 249 * This API is used to set the memory pool address used by dynload. 250 * @attention 251 * <ul> 252 * <li>The parameter passed to this API should be a legal memory pool address by managed with LiteOS's memory 253 * algorithm, and whose value is outside of the LiteOS system memory</li> 254 * </ul> 255 * 256 * @param memPool [IN] the memory pool address. 257 * 258 * @retval TRUE Set successful. 259 * @retval FALSE Set failed. 260 * @par Dependency: 261 * <ul><li>los_ld_elflib.h: the header file that contains the API declaration.</li></ul> 262 * @see LOS_ModuleUnload 263 * @since Huawei LiteOS V200R002C00 264 */ 265 extern BOOL LOS_DynMemPoolSet(VOID *memPool); 266 267 #ifdef __cplusplus 268 } 269 #endif /* __cplusplus */ 270 271 #endif /* _LOS_LD_ELFLIB_H */ 272