1 /* 2 * This file is part of the openHiTLS project. 3 * 4 * openHiTLS is licensed under the Mulan PSL v2. 5 * You can use this software according to the terms and conditions of the Mulan PSL v2. 6 * You may obtain a copy of Mulan PSL v2 at: 7 * 8 * http://license.coscl.org.cn/MulanPSL2 9 * 10 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, 11 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, 12 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. 13 * See the Mulan PSL v2 for more details. 14 */ 15 16 /** 17 * @defgroup bsl 18 * @brief Base Support Layer 19 */ 20 21 /** 22 * @defgroup bsl_err 23 * @ingroup bsl 24 * @brief error module 25 */ 26 27 #ifndef BSL_ERR_H 28 #define BSL_ERR_H 29 30 #include <stdint.h> 31 #include <stdbool.h> 32 #include "bsl_errno.h" 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /** 39 * @ingroup bsl_err 40 * @brief Start value of the customized level-1 error module. 41 * 42 * Start value of the customized level-1 error module. The value 0x80 is 128. 43 */ 44 #define BSL_ERR_NEW_MODULE 0x80 45 46 /** 47 * @ingroup bsl_err 48 * @brief Initialize Error code module. 49 * 50 * The user must call this interface to initialize. 51 * 52 * @attention NONE 53 * @retval #BSL_SUCCESS, error code module is successfully initialized. 54 * @retval #BSL_MALLOC_FAIL, memory space is insufficient and thread lock space cannot be applied for. 55 * @retval #BSL_SAL_ERR_UNKNOWN, thread lock initialization failed. 56 */ 57 int32_t BSL_ERR_Init(void); 58 59 /** 60 * @ingroup bsl_err 61 * @brief Error code module deinitialization. 62 * 63 * Called by the user when the process exits. 64 * 65 * @attention none 66 */ 67 void BSL_ERR_DeInit(void); 68 69 /** 70 * @ingroup bsl_err 71 * @brief Delete the error stack 72 * 73 * Delete the error stack, which is called when a process or thread exits. 74 * 75 * @attention This function must be called when the thread exits. Otherwise, memory leakage occurs. 76 * @param isRemoveAll [IN] Indicates whether to delete all error stacks. 77 * The value is true when a process exits and false when a thread exits. 78 */ 79 void BSL_ERR_RemoveErrorStack(bool isRemoveAll); 80 81 /** 82 * @ingroup bsl_err 83 * @brief Obtains the error code of the last push in the error stack. 84 * 85 * This API is called when an error occurs on a HiTLS interface to obtain the error code. 86 * The interface can be called continuously. The error code returned each time forms 87 * the error stack of the interface until BSL_SUCCESS is returned. 88 * 89 * @attention None. 90 * @retval Error code. The most significant 16 bits indicate the ID of the module where the error occurs, 91 * and the least significant 16 bits indicate the cause number. 92 */ 93 int32_t BSL_ERR_GetLastError(void); 94 95 /** 96 * @ingroup bsl_err 97 * @brief Obtains the error code, file name, and line number of the last push message in the error stack. 98 * 99 * When an error occurs in a HiTLS interface, the user obtains an error code, file name, and line 100 * number. The obtained information is deleted from the error stack. 101 * The interface can be called continuously. The error code returned each time forms the error stack of 102 * the interface until BSL_SUCCESS is returned. 103 * 104 * @attention If either of the two parameters is null, the file name and line number cannot be obtained 105 * @param file [OUT] Obtains the name of the file where the error occurs, excluding the directory path 106 * @param lineNo [OUT] Obtain the line number of the file where the error occurs 107 * @retval Error code. The most significant 16 bits indicate the ID of the module where the error occurs, 108 * and the least significant 16 bits indicate the cause number. 109 */ 110 int32_t BSL_ERR_GetLastErrorFileLine(const char **file, uint32_t *lineNo); 111 112 /** 113 * @ingroup bsl_err 114 * @brief Obtain the error code, file name, and line number of the last push message in the error stack. 115 * 116 * When an error occurs on a HiTLS interface, the user obtains an error code, file name, and line number. 117 * The obtained information is not deleted from the error stack. 118 * 119 * @attention If either of the two parameters is null, the file name and line number cannot be obtained. 120 * @param file [OUT] Obtains the name of the file where the error occurs, excluding the directory path. 121 * @param lineNo [OUT] Obtain the line number of the file where the error occurs. 122 * @retval Error code. The most significant 16 bits indicate the ID of the module where the error occurs, 123 * and the least significant 16 bits indicate the cause number. 124 */ 125 int32_t BSL_ERR_PeekLastErrorFileLine(const char **file, uint32_t *lineNo); 126 127 /** 128 * @ingroup bsl_err 129 * @brief Obtain the earliest push error code in the error stack. 130 * 131 * This API is called when an error occurs on a HiTLS API to obtain the error code. 132 * The API can be called all the time. 133 * The error code returned each time forms the error stack of the interface until BSL_SUCCESS is returned. 134 * 135 * @attention None. 136 * @retval Error code. The most significant 16 bits indicate the ID of the module where the error occurs, 137 * and the least significant 16 bits indicate the cause number. 138 */ 139 int32_t BSL_ERR_GetError(void); 140 141 /** 142 * @ingroup bsl_err 143 * @brief Obtain the error code, file name, and line number of the earliest push message in the error stack. 144 * 145 * The user calls this API after an error occurs on a HiTLS API to obtain an error code, 146 * file name, and line number. The obtained information will be deleted from the error stack. 147 * This API can be called continuously. The returned error code forms the error stack of the 148 * API until BSL_SUCCESS is returned. 149 * 150 * @attention If either of the two parameters is null, the file name and line number cannot be obtained. 151 * @param file [OUT] Obtains the name of the file where the error occurs, excluding the directory path. 152 * @param lineNo [OUT] Obtain the line number of the file where the error occurs. 153 * @retval Error code. The most significant 16 bits indicate the ID of the module where the error occurs, 154 * and the least significant 16 bits indicate the cause number. 155 */ 156 int32_t BSL_ERR_GetErrorFileLine(const char **file, uint32_t *lineNo); 157 158 /** 159 * @ingroup bsl_err 160 * @brief Obtain the error code, file name, and line number of the earliest push message in the error stack. 161 * 162 * When an error occurs on a HiTLS interface, the user obtains an error code, file name, and line number. 163 * The obtained information is not deleted from the error stack. 164 * 165 * @attention If either of the two parameters is null, the file name and line number cannot be obtained. 166 * @param file [OUT] Obtains the name of the file where the error occurs, excluding the directory path. 167 * @param lineNo [OUT] Obtain the line number of the file where the error occurs. 168 * @retval Error code. The most significant 16 bits indicate the ID of the module where the error occurs, 169 * and the least significant 16 bits indicate the cause number. 170 */ 171 int32_t BSL_ERR_PeekErrorFileLine(const char **file, uint32_t *lineNo); 172 173 /** 174 * @ingroup bsl_err 175 * @brief Clear the error stack. 176 * 177 * If an error is detected after the HiTLS API is called, if the error information is ignored, 178 * call this API to clear the error information before calling the HiTLS API again. 179 * 180 * @attention None 181 */ 182 void BSL_ERR_ClearError(void); 183 184 /** 185 * @ingroup bsl_err 186 * @brief Add error description. 187 */ 188 typedef struct { 189 int32_t error; /**< Error code */ 190 const char *string; /**< Description string corresponding to an error code. */ 191 } BSL_ERR_Desc; 192 193 /** 194 * @ingroup bsl_err 195 * @brief Add an error description string to an error code. 196 * 197 * The error description string is added to the error code. 198 * The error description can be extended to the user side. 199 * 200 * @attention This function is thread-safe. It stores only string pointers and does not perform deep 201 * copy. The same error can be added multiple times and overwrites the previously added error. 202 * @param descList [IN] BSL_ERR_Desc array 203 * @param num [IN] Length of descList 204 * @retval #BSL_SUCCESS. 205 * @retval For details, see bsl_errno.h 206 */ 207 int32_t BSL_ERR_AddErrStringBatch(const BSL_ERR_Desc *descList, uint32_t num); 208 209 /** 210 * @ingroup bsl_err 211 * @brief Delete the error description 212 * 213 * The error description is deleted. 214 * If BSL_ERR_AddErrStringBatch is called, you need to use this API to release the memory. 215 * 216 * @attention This API must be called when a process exits. 217 * Otherwise, memory leakage occurs. Called before releasing the lock. 218 */ 219 void BSL_ERR_RemoveErrStringBatch(void); 220 221 /** 222 * @ingroup bsl_err 223 * @brief Obtain the error description string based on the error code. 224 * 225 * Obtain the corresponding error description string based on the error code. 226 * 227 * @attention None 228 * @param error [IN] Error code 229 * @retval Error description 230 */ 231 const char *BSL_ERR_GetString(int32_t error); 232 233 /** 234 * @ingroup bsl_err 235 * @brief Set the pop-up flag at the level of the current error stack. 236 * 237 * Set the pop-up flag. 238 * 239 * @attention none 240 * @retval #BSL_ERR_ERR_ACQUIRE_WRITE_LOCK_FAIL, failed to obtain the write lock. 241 * @retval #BSL_ERR_ERR_NO_STACK, no error stack. 242 * @retval #BSL_ERR_ERR_NO_ERROR, no error. 243 * @retval #BSL_SUCCESS, the flag is set successfully. 244 */ 245 int32_t BSL_ERR_SetMark(void); 246 247 /** 248 * @ingroup bsl_err 249 * @brief Pop to the marked error stack level and clear the mark 250 * 251 * Pop up to the error stack level of the mark and clear the mark 252 * 253 * @attention none 254 * @retval #BSL_ERR_ERR_ACQUIRE_WRITE_LOCK_FAIL, failed to obtain the write lock. 255 * @retval #BSL_ERR_ERR_NO_STACK, no error stack. 256 * @retval #BSL_ERR_ERR_NO_ERROR, no error. 257 * @retval #BSL_ERR_ERR_NO_Mark, no mark. 258 * @retval #BSL_SUCCESS, pop-up succeeded. 259 */ 260 int32_t BSL_ERR_PopToMark(void); 261 262 /** 263 * @ingroup bsl_err 264 * @brief Clear the latest flag in the error stack. 265 * 266 * Clear the latest flag in the error stack. 267 * 268 * @attention None. 269 * @retval #BSL_ERR_ERR_ACQUIRE_WRITE_LOCK_FAIL, failed to obtain the write lock. 270 * @retval #BSL_ERR_ERR_NO_STACK, no error stack. 271 * @retval #BSL_SUCCESS, cleared successfully. 272 */ 273 int32_t BSL_ERR_ClearLastMark(void); 274 275 #ifdef __cplusplus 276 } 277 #endif 278 279 #endif // BSL_ERR_H 280