1 /* --------------------------------------------------------------------------- 2 * Copyright (c) Huawei Technologies Co., Ltd. 2013-2018. All rights reserved. 3 * Description: Software Timer Manager 4 * Redistribution and use in source and binary forms, with or without modification, 5 * are permitted provided that the following conditions are met: 6 * 1. Redistributions of source code must retain the above copyright notice, this list of 7 * conditions and the following disclaimer. 8 * 2. Redistributions in binary form must reproduce the above copyright notice, this list 9 * of conditions and the following disclaimer in the documentation and/or other materials 10 * provided with the distribution. 11 * 3. Neither the name of the copyright holder nor the names of its contributors may be used 12 * to endorse or promote products derived from this software without specific prior written 13 * permission. 14 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 15 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 16 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 17 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 18 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 19 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 20 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 21 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 22 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 23 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 24 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25 * --------------------------------------------------------------------------- */ 26 27 /** 28 * @defgroup los_swtmr Software timer 29 * @ingroup kernel 30 */ 31 32 #ifndef _LOS_SWTMR_H 33 #define _LOS_SWTMR_H 34 35 #include "los_task.h" 36 37 #ifdef __cplusplus 38 #if __cplusplus 39 extern "C" { 40 #endif /* __cplusplus */ 41 #endif /* __cplusplus */ 42 43 44 /** 45 * @ingroup los_swtmr 46 * Software timer error code: The timeout handling function is NULL. 47 * 48 * Value: 0x02000300 49 * 50 * Solution: Define the timeout handling function. 51 */ 52 #define LOS_ERRNO_SWTMR_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x00) 53 54 /** 55 * @ingroup los_swtmr 56 * Software timer error code: The expiration time is 0. 57 * 58 * Value: 0x02000301 59 * 60 * Solution: Re-define the expiration time. 61 */ 62 #define LOS_ERRNO_SWTMR_INTERVAL_NOT_SUITED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x01) 63 64 /** 65 * @ingroup los_swtmr 66 * Software timer error code: Invalid software timer mode. 67 * 68 * Value: 0x02000302 69 * 70 * Solution: Check the mode value. The value range is [0,3]. 71 */ 72 #define LOS_ERRNO_SWTMR_MODE_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x02) 73 74 /** 75 * @ingroup los_swtmr 76 * Software timer error code: The passed-in software timer ID is NULL. 77 * 78 * Value: 0x02000303 79 * 80 * Solution: Define the software timer ID before passing it in. 81 */ 82 #define LOS_ERRNO_SWTMR_RET_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x03) 83 84 /** 85 * @ingroup los_swtmr 86 * Software timer error code: The number of software timers exceeds the configured permitted maximum number. 87 * 88 * Value: 0x02000304 89 * 90 * Solution: Re-configure the permitted maximum number of software timers, or wait for a software timer to become 91 * available. 92 */ 93 #define LOS_ERRNO_SWTMR_MAXSIZE LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x04) 94 95 /** 96 * @ingroup los_swtmr 97 * Software timer error code: Invalid software timer ID. 98 * 99 * Value: 0x02000305 100 * 101 * Solution: Pass in a valid software timer ID. 102 */ 103 #define LOS_ERRNO_SWTMR_ID_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x05) 104 105 /** 106 * @ingroup los_swtmr 107 * Software timer error code: The software timer is not created. 108 * 109 * Value: 0x02000306 110 * 111 * Solution: Create a software timer. 112 */ 113 #define LOS_ERRNO_SWTMR_NOT_CREATED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x06) 114 115 /** 116 * @ingroup los_swtmr 117 * Software timer error code: Insufficient memory for software timer linked list creation. 118 * 119 * Value: 0x02000307 120 * 121 * Solution: Allocate bigger memory partition to software timer linked list creation. 122 */ 123 #define LOS_ERRNO_SWTMR_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x07) 124 125 /** 126 * @ingroup los_swtmr 127 * Software timer error code: Invalid configured number of software timers. 128 * 129 * Value: 0x02000308 130 * 131 * Solution: Re-configure the number of software timers. 132 */ 133 #define LOS_ERRNO_SWTMR_MAXSIZE_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x08) 134 135 /** 136 * @ingroup los_swtmr 137 * Software timer error code: The software timer is being used during an interrupt. 138 * 139 * Value: 0x02000309 140 * 141 * Solution: Change the source code and do not use the software timer during an interrupt. 142 */ 143 #define LOS_ERRNO_SWTMR_HWI_ACTIVE LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x09) 144 145 /** 146 * @ingroup los_swtmr 147 * Software timer error code: Insufficient memory allocated by membox. 148 * 149 * Value: 0x0200030a 150 * 151 * Solution: Expand the memory allocated by membox. 152 */ 153 #define LOS_ERRNO_SWTMR_HANDLER_POOL_NO_MEM LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0a) 154 155 /** 156 * @ingroup los_swtmr 157 * Software timer error code: The software timer queue fails to be created. 158 * 159 * Value: 0x0200030b 160 * 161 * Solution: Check whether more memory can be allocated to the queue to be created. 162 */ 163 #define LOS_ERRNO_SWTMR_QUEUE_CREATE_FAILED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0b) 164 165 /** 166 * @ingroup los_swtmr 167 * Software timer error code: The software timer task fails to be created. 168 * 169 * Value: 0x0200030c 170 * 171 * Solution: Check whether the memory is sufficient and re-create the task. 172 */ 173 #define LOS_ERRNO_SWTMR_TASK_CREATE_FAILED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0c) 174 175 /** 176 * @ingroup los_swtmr 177 * Software timer error code: The software timer is not started. 178 * 179 * Value: 0x0200030d 180 * 181 * Solution: Start the software timer. 182 */ 183 #define LOS_ERRNO_SWTMR_NOT_STARTED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0d) 184 185 /** 186 * @ingroup los_swtmr 187 * Software timer error code: Invalid software timer state. 188 * 189 * Value: 0x0200030e 190 * 191 * Solution: Check the software timer state. 192 */ 193 #define LOS_ERRNO_SWTMR_STATUS_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0e) 194 195 /** 196 * @ingroup los_swtmr 197 * This error code is not in use temporarily. 198 */ 199 #define LOS_ERRNO_SWTMR_SORTLIST_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0f) 200 201 /** 202 * @ingroup los_swtmr 203 * Software timer error code: The passed-in number of remaining Ticks configured on the software timer is NULL. 204 * 205 * Value: 0x02000310 206 * 207 * Solution: Define a variable of the number of remaining Ticks before passing in the number of remaining Ticks. 208 */ 209 #define LOS_ERRNO_SWTMR_TICK_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x10) 210 211 /** 212 * @ingroup los_swtmr 213 * Software timer mode 214 */ 215 enum EnSwTmrType { 216 LOS_SWTMR_MODE_ONCE, /* One-off software timer */ 217 LOS_SWTMR_MODE_PERIOD, /* Periodic software timer */ 218 LOS_SWTMR_MODE_NO_SELFDELETE, /* One-off software timer, but not self-delete */ 219 LOS_SWTMR_MODE_OPP, /* After the one-off timer finishes timing, 220 the periodic software timer is enabled. 221 This mode is not supported temporarily. */ 222 }; 223 224 /** 225 * @ingroup los_swtmr 226 * @brief Define the type of a callback function that handles software timer timeout. 227 * 228 * @par Description: 229 * This API is used to define the type of a callback function that handles software timer timeout, so that it can be 230 * called when software timer timeout. 231 * 232 * @attention 233 * <ul> 234 * <li>None.</li> 235 * </ul> 236 * 237 * @param para [IN] the parameter of the callback function that handles software timer timeout. 238 * 239 * @retval None. 240 * @par Dependency: 241 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 242 * @see None. 243 */ 244 typedef VOID (*SWTMR_PROC_FUNC)(UINT32 para); 245 246 /** 247 * @ingroup los_swtmr 248 * Software timer control structure 249 */ 250 typedef struct tagSwTmrCtrl { 251 struct tagSwTmrCtrl *pstNext; /* Pointer to the next software timer */ 252 UINT8 ucState; /* Software timer state */ 253 UINT8 ucMode; /* Software timer mode */ 254 UINT16 usTimerID; /* Software timer ID */ 255 UINT32 uwCount; /* Times that a software timer works */ 256 UINT32 uwInterval; /* Timeout interval of a periodic software timer */ 257 UINT32 uwArg; /* Parameter passed in when the callback function 258 that handles software timer timeout is called */ 259 SWTMR_PROC_FUNC pfnHandler; /* Callback function that handles software timer timeout */ 260 } SWTMR_CTRL_S; 261 262 263 /** 264 * @ingroup los_swtmr 265 * @brief Start a software timer. 266 * 267 * @par Description: 268 * This API is used to start a software timer that has a specified ID. 269 * @attention 270 * <ul> 271 * <li>The specific timer must be created first</li> 272 * </ul> 273 * 274 * @param swtmrID [IN] Software timer ID created by LOS_SwtmrCreate. The value of ID should be in 275 * [0, LOSCFG_BASE_CORE_SWTMR_LIMIT - 1]. 276 * 277 * @retval #LOS_ERRNO_SWTMR_ID_INVALID Invalid software timer ID. 278 * @retval #LOS_ERRNO_SWTMR_NOT_CREATED The software timer is not created. 279 * @retval #LOS_ERRNO_SWTMR_STATUS_INVALID Invalid software timer state. 280 * @retval #LOS_OK The software timer is successfully started. 281 * @par Dependency: 282 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 283 * @see LOS_SwtmrStop | LOS_SwtmrCreate 284 */ 285 extern UINT32 LOS_SwtmrStart(UINT16 swtmrID); 286 287 /** 288 * @ingroup los_swtmr 289 * @brief Stop a software timer. 290 * 291 * @par Description: 292 * This API is used to stop a software timer that has a specified ID. 293 * @attention 294 * <ul> 295 * <li>The specific timer should be created and started firstly.</li> 296 * </ul> 297 * 298 * @param swtmrID [IN] Software timer ID created by LOS_SwtmrCreate. The value of ID should be in 299 * [0, LOSCFG_BASE_CORE_SWTMR_LIMIT - 1]. 300 * 301 * @retval #LOS_ERRNO_SWTMR_ID_INVALID Invalid software timer ID. 302 * @retval #LOS_ERRNO_SWTMR_NOT_CREATED The software timer is not created. 303 * @retval #LOS_ERRNO_SWTMR_NOT_STARTED The software timer is not started. 304 * @retval #LOS_ERRNO_SWTMR_STATUS_INVALID Invalid software timer state. 305 * @retval #LOS_OK The software timer is successfully stopped. 306 * @par Dependency: 307 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 308 * @see LOS_SwtmrStart | LOS_SwtmrCreate 309 */ 310 extern UINT32 LOS_SwtmrStop(UINT16 swtmrID); 311 312 /** 313 * @ingroup los_swtmr 314 * @brief Obtain the number of remaining Ticks configured on a software timer. 315 * 316 * @par Description: 317 * This API is used to obtain the number of remaining Ticks configured on the software timer of which the ID is 318 * specified by usSwTmrID. 319 * @attention 320 * <ul> 321 * <li>The specific timer should be created and started successfully, error happends otherwise.</li> 322 * </ul> 323 * 324 * @param swtmrID [IN] Software timer ID created by LOS_SwtmrCreate. The value of ID should be in 325 * [0, LOSCFG_BASE_CORE_SWTMR_LIMIT - 1]. 326 * @param tick [OUT] Number of remaining Ticks configured on the software timer. 327 * 328 * @retval #LOS_ERRNO_SWTMR_ID_INVALID Invalid software timer ID. 329 * @retval #LOS_ERRNO_SWTMR_NOT_CREATED The software timer is not created. 330 * @retval #LOS_ERRNO_SWTMR_NOT_STARTED The software timer is not started. 331 * @retval #LOS_ERRNO_SWTMR_STATUS_INVALID Invalid software timer state. 332 * @retval #LOS_OK The number of remaining Ticks is successfully obtained. 333 * @par Dependency: 334 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 335 * @see LOS_SwtmrCreate 336 */ 337 extern UINT32 LOS_SwtmrTimeGet(UINT16 swtmrID, UINT32 *tick); 338 339 /** 340 * @ingroup los_swtmr 341 * @brief Create a software timer. 342 * 343 * @par Description: 344 * This API is used to create a software timer that has specified timing duration, timeout handling function, 345 * and trigger mode, and to return a handle by which the software timer can be referenced. 346 * @attention 347 * <ul> 348 * <li>Do not use the delay interface in the callback function that handles software timer timeout.</li> 349 * <li>Threre are LOSCFG_BASE_CORE_SWTMR_LIMIT timers available, change it's value when necessory.</li> 350 * </ul> 351 * 352 * @param interval [IN] Timing duration of the software timer to be created (unit: ms). 353 * @param mode [IN] Software timer mode. Pass in one of the modes specified by EnSwTmrType. There are three 354 * types of modes, one-off, periodic, and continuously periodic after one-off, of which the 355 * third mode is not supported temporarily. 356 * @param handler [IN] Callback function that handles software timer timeout. 357 * @param swtmrID [OUT] Software timer ID created by LOS_SwtmrCreate. 358 * @param arg [IN] Parameter passed in when the callback function that handles software timer timeout is 359 * called. 360 * 361 * @retval #LOS_ERRNO_SWTMR_INTERVAL_NOT_SUITED The software timer timeout interval is 0. 362 * @retval #LOS_ERRNO_SWTMR_MODE_INVALID Invalid software timer mode. 363 * @retval #LOS_ERRNO_SWTMR_PTR_NULL The callback function that handles software timer timeout is NULL. 364 * @retval #LOS_ERRNO_SWTMR_RET_PTR_NULL The passed-in software timer ID is NULL. 365 * @retval #LOS_ERRNO_SWTMR_MAXSIZE The number of software timers exceeds the configured permitted 366 * maximum number. 367 * @retval #LOS_OK The software timer is successfully created. 368 * @par Dependency: 369 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 370 * @see LOS_SwtmrDelete 371 */ 372 extern UINT32 LOS_SwtmrCreate(UINT32 interval, UINT8 mode, SWTMR_PROC_FUNC handler, UINT16 *swtmrID, UINT32 arg); 373 /** 374 * @ingroup los_swtmr 375 * @brief Modify a software timer. 376 * 377 * @par Description: 378 * This API is used to Modify the timing duration, timeout handling function, and trigger mode of a created timer. 379 * @attention 380 * <ul> 381 * <li>Do not use the delay interface in the callback function that handles software timer timeout.</li> 382 * </ul> 383 * 384 * @param swtmrID [IN] Software timer ID created by LOS_SwtmrCreate. 385 * @param interval [IN] Timing duration of the software timer to be created (unit: ms). 386 * @param mode [IN] Software timer mode. Pass in one of the modes specified by EnSwTmrType. 387 There are three types of modes, one-off, periodic, and continuously periodic after one-off, 388 of which the third mode is not supported temporarily. 389 * @param handler [IN] Callback function that handles software timer timeout. 390 * @param arg [IN] Parameter passed in when the callback function that handles software timer timeout is called. 391 * 392 * @retval #LOS_ERRNO_SWTMR_INTERVAL_NOT_SUITED The software timer timeout interval is 0. 393 * @retval #LOS_ERRNO_SWTMR_MODE_INVALID Invalid software timer mode. 394 * @retval #LOS_ERRNO_SWTMR_ID_INVALID Invalid software timer ID. 395 * @retval #LOS_ERRNO_SWTMR_NOT_CREATED The software timer is not created. 396 * @retval #LOS_ERRNO_SWTMR_STATUS_INVALID Invalid software timer state. 397 * @retval #LOS_OK The software timer is successfully created. 398 * @par Dependency: 399 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 400 * @see LOS_SwtmrDelete 401 */ 402 extern UINT32 LOS_SwtmrModify(UINT16 swtmrID, UINT32 interval, UINT8 mode, SWTMR_PROC_FUNC handler, UINT32 arg); 403 404 /** 405 * @ingroup los_swtmr 406 * @brief Delete a software timer. 407 * 408 * @par Description: 409 * This API is used to delete a software timer. 410 * @attention 411 * <ul> 412 * <li>The specific timer should be created and then stopped firstly.</li> 413 * </ul> 414 * 415 * @param swtmrID [IN] Software timer ID created by LOS_SwtmrCreate. The value of ID should be in 416 * [0, LOSCFG_BASE_CORE_SWTMR_LIMIT - 1]. 417 * 418 * @retval #LOS_ERRNO_SWTMR_ID_INVALID Invalid software timer ID. 419 * @retval #LOS_ERRNO_SWTMR_NOT_CREATED The software timer is not created. 420 * @retval #LOS_ERRNO_SWTMR_STATUS_INVALID Invalid software timer state. 421 * @retval #LOS_OK The software timer is successfully deleted. 422 * @par Dependency: 423 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 424 * @see LOS_SwtmrCreate 425 */ 426 extern UINT32 LOS_SwtmrDelete(UINT16 swtmrID); 427 extern UINT32 LOS_SwtmrUsage(VOID); 428 429 #ifdef __cplusplus 430 #if __cplusplus 431 } 432 #endif /* __cplusplus */ 433 #endif /* __cplusplus */ 434 435 #endif /* _LOS_SWTMR_H */ 436