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