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 los_swtmr Software timer 34 * @ingroup kernel 35 */ 36 37 #ifndef _LOS_SWTMR_H 38 #define _LOS_SWTMR_H 39 40 #include "los_config.h" 41 #include "los_sortlink.h" 42 43 #ifdef __cplusplus 44 #if __cplusplus 45 extern "C" { 46 #endif /* __cplusplus */ 47 #endif /* __cplusplus */ 48 49 /** 50 * @ingroup los_swtmr 51 * Software timer error code: The timeout handling function is NULL. 52 * 53 * Value: 0x02000300 54 * 55 * Solution: Define the timeout handling function. 56 */ 57 #define LOS_ERRNO_SWTMR_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x00) 58 59 /** 60 * @ingroup los_swtmr 61 * Software timer error code: The expiration time is 0. 62 * 63 * Value: 0x02000301 64 * 65 * Solution: Re-define the expiration time. 66 */ 67 #define LOS_ERRNO_SWTMR_INTERVAL_NOT_SUITED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x01) 68 69 /** 70 * @ingroup los_swtmr 71 * Software timer error code: Invalid software timer mode. 72 * 73 * Value: 0x02000302 74 * 75 * Solution: Check the mode value. The value range is [0,3]. 76 */ 77 #define LOS_ERRNO_SWTMR_MODE_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x02) 78 79 /** 80 * @ingroup los_swtmr 81 * Software timer error code: The passed-in software timer ID is NULL. 82 * 83 * Value: 0x02000303 84 * 85 * Solution: Define the software timer ID before passing it in. 86 */ 87 #define LOS_ERRNO_SWTMR_RET_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x03) 88 89 /** 90 * @ingroup los_swtmr 91 * Software timer error code: The number of software timers exceeds the configured permitted maximum number. 92 * 93 * Value: 0x02000304 94 * 95 * Solution: Re-configure the permitted maximum number of software timers, or wait for a software timer to become 96 * available. 97 */ 98 #define LOS_ERRNO_SWTMR_MAXSIZE LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x04) 99 100 /** 101 * @ingroup los_swtmr 102 * Software timer error code: Invalid software timer ID. 103 * 104 * Value: 0x02000305 105 * 106 * Solution: Pass in a valid software timer ID. 107 */ 108 #define LOS_ERRNO_SWTMR_ID_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x05) 109 110 /** 111 * @ingroup los_swtmr 112 * Software timer error code: The software timer is not created. 113 * 114 * Value: 0x02000306 115 * 116 * Solution: Create a software timer. 117 */ 118 #define LOS_ERRNO_SWTMR_NOT_CREATED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x06) 119 120 /** 121 * @ingroup los_swtmr 122 * Software timer error code: Insufficient memory for software timer linked list creation. 123 * 124 * Value: 0x02000307 125 * 126 * Solution: Allocate bigger memory partition to software timer linked list creation. 127 */ 128 #define LOS_ERRNO_SWTMR_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x07) 129 130 /** 131 * @ingroup los_swtmr 132 * Software timer error code: Invalid configured number of software timers. 133 * 134 * Value: 0x02000308 135 * 136 * Solution: Re-configure the number of software timers. 137 */ 138 #define LOS_ERRNO_SWTMR_MAXSIZE_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x08) 139 140 /** 141 * @ingroup los_swtmr 142 * Software timer error code: The software timer is being used during an interrupt. 143 * 144 * Value: 0x02000309 145 * 146 * Solution: Change the source code and do not use the software timer during an interrupt. 147 */ 148 #define LOS_ERRNO_SWTMR_HWI_ACTIVE LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x09) 149 150 /** 151 * @ingroup los_swtmr 152 * Software timer error code: Insufficient memory allocated by membox. 153 * 154 * Value: 0x0200030a 155 * 156 * Solution: Expand the memory allocated by membox. 157 */ 158 #define LOS_ERRNO_SWTMR_HANDLER_POOL_NO_MEM LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0a) 159 160 /** 161 * @ingroup los_swtmr 162 * Software timer error code: The software timer queue fails to be created. 163 * 164 * Value: 0x0200030b 165 * 166 * Solution: Check whether more memory can be allocated to the queue to be created. 167 */ 168 #define LOS_ERRNO_SWTMR_QUEUE_CREATE_FAILED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0b) 169 170 /** 171 * @ingroup los_swtmr 172 * Software timer error code: The software timer task fails to be created. 173 * 174 * Value: 0x0200030c 175 * 176 * Solution: Check whether the memory is sufficient and re-create the task. 177 */ 178 #define LOS_ERRNO_SWTMR_TASK_CREATE_FAILED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0c) 179 180 /** 181 * @ingroup los_swtmr 182 * Software timer error code: The software timer is not started. 183 * 184 * Value: 0x0200030d 185 * 186 * Solution: Start the software timer. 187 */ 188 #define LOS_ERRNO_SWTMR_NOT_STARTED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0d) 189 190 /** 191 * @ingroup los_swtmr 192 * Software timer error code: Invalid software timer state. 193 * 194 * Value: 0x0200030e 195 * 196 * Solution: Check the software timer state. 197 */ 198 #define LOS_ERRNO_SWTMR_STATUS_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0e) 199 200 /** 201 * @ingroup los_swtmr 202 * This error code is not in use temporarily. 203 */ 204 #define LOS_ERRNO_SWTMR_SORTLIST_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0f) 205 206 /** 207 * @ingroup los_swtmr 208 * Software timer error code: The passed-in number of remaining Ticks configured on the software timer is NULL. 209 * 210 * Value: 0x02000310 211 * 212 * Solution: Define a variable of the number of remaining Ticks before passing in the number of remaining Ticks. 213 */ 214 #define LOS_ERRNO_SWTMR_TICK_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x10) 215 216 #if (LOSCFG_BASE_CORE_SWTMR_ALIGN == 1) 217 #define OS_ERRNO_SWTMR_ROUSES_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x11) 218 #define OS_ERRNO_SWTMR_ALIGN_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x12) 219 220 enum enSwTmrRousesType { 221 OS_SWTMR_ROUSES_IGNORE, /* timer don't need to wake up system */ 222 OS_SWTMR_ROUSES_ALLOW, /* timer can wake up system */ 223 }; 224 225 enum enSwTmrAlignSensitive { 226 OS_SWTMR_ALIGN_SENSITIVE, /* timer don't need to align */ 227 OS_SWTMR_ALIGN_INSENSITIVE, /* timer need to align */ 228 }; 229 #endif 230 231 /** 232 * @ingroup los_swtmr 233 * Software timer mode 234 */ 235 enum EnSwTmrType { 236 LOS_SWTMR_MODE_ONCE, /* One-off software timer */ 237 LOS_SWTMR_MODE_PERIOD, /* Periodic software timer */ 238 LOS_SWTMR_MODE_NO_SELFDELETE, /* One-off software timer, but not self-delete */ 239 LOS_SWTMR_MODE_OPP, /* After the one-off timer finishes timing, 240 the periodic software timer is enabled. 241 This mode is not supported temporarily. */ 242 }; 243 244 /** 245 * @ingroup los_swtmr 246 * @brief Define the type of a callback function that handles software timer timeout. 247 * 248 * @par Description: 249 * This API is used to define the type of a callback function that handles software timer timeout, so that it can be 250 * called when software timer timeout. 251 * 252 * @attention 253 * <ul> 254 * <li>None.</li> 255 * </ul> 256 * 257 * @param para [IN] the parameter of the callback function that handles software timer timeout. 258 * 259 * @retval None. 260 * @par Dependency: 261 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 262 * @see None. 263 */ 264 typedef VOID (*SWTMR_PROC_FUNC)(UINT32 para); 265 266 /** 267 * @ingroup los_swtmr 268 * Software timer control structure 269 */ 270 typedef struct tagSwTmrCtrl { 271 struct tagSwTmrCtrl *pstNext; /* Pointer to the next software timer */ 272 UINT8 ucState; /* Software timer state */ 273 UINT8 ucMode; /* Software timer mode */ 274 UINT8 ucOverrun; /* Times that a software timer repeats timing */ 275 #if (LOSCFG_BASE_CORE_SWTMR_ALIGN == 1) 276 UINT8 ucRouses; /* wake up enable */ 277 UINT8 ucSensitive; /* align enable */ 278 #endif 279 UINT32 usTimerID; /* Software timer ID */ 280 UINT32 uwInterval; /* Timeout interval of a periodic software timer */ 281 UINT32 uwArg; /* Parameter passed in when the callback function 282 that handles software timer timeout is called */ 283 SWTMR_PROC_FUNC pfnHandler; /* Callback function that handles software timer timeout */ 284 SortLinkList stSortList; 285 UINT64 startTime; 286 } SWTMR_CTRL_S; 287 288 289 /** 290 * @ingroup los_swtmr 291 * @brief Start a software timer. 292 * 293 * @par Description: 294 * This API is used to start a software timer that has a specified ID. 295 * @attention 296 * <ul> 297 * <li>The specific timer must be created first</li> 298 * </ul> 299 * 300 * @param swtmrID [IN] Software timer ID created by LOS_SwtmrCreate. 301 * 302 * @retval #LOS_ERRNO_SWTMR_ID_INVALID Invalid software timer ID. 303 * @retval #LOS_ERRNO_SWTMR_NOT_CREATED The software timer is not created. 304 * @retval #LOS_ERRNO_SWTMR_STATUS_INVALID Invalid software timer state. 305 * @retval #LOS_OK The software timer is successfully started. 306 * @par Dependency: 307 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 308 * @see LOS_SwtmrStop | LOS_SwtmrCreate 309 */ 310 extern UINT32 LOS_SwtmrStart(UINT32 swtmrID); 311 312 /** 313 * @ingroup los_swtmr 314 * @brief Stop a software timer. 315 * 316 * @par Description: 317 * This API is used to stop a software timer that has a specified ID. 318 * @attention 319 * <ul> 320 * <li>The specific timer should be created and started firstly.</li> 321 * </ul> 322 * 323 * @param swtmrID [IN] Software timer ID created by LOS_SwtmrCreate. 324 * 325 * @retval #LOS_ERRNO_SWTMR_ID_INVALID Invalid software timer ID. 326 * @retval #LOS_ERRNO_SWTMR_NOT_CREATED The software timer is not created. 327 * @retval #LOS_ERRNO_SWTMR_NOT_STARTED The software timer is not started. 328 * @retval #LOS_ERRNO_SWTMR_STATUS_INVALID Invalid software timer state. 329 * @retval #LOS_OK The software timer is successfully stopped. 330 * @par Dependency: 331 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 332 * @see LOS_SwtmrStart | LOS_SwtmrCreate 333 */ 334 extern UINT32 LOS_SwtmrStop(UINT32 swtmrID); 335 336 /** 337 * @ingroup los_swtmr 338 * @brief Obtain the number of remaining Ticks configured on a software timer. 339 * 340 * @par Description: 341 * This API is used to obtain the number of remaining Ticks configured on the software timer of which the ID is 342 * specified by usSwTmrID. 343 * @attention 344 * <ul> 345 * <li>The specific timer should be created and started successfully, error happens otherwise.</li> 346 * </ul> 347 * 348 * @param swtmrID [IN] Software timer ID created by LOS_SwtmrCreate. 349 * @param tick [OUT] Number of remaining Ticks configured on the software timer. 350 * 351 * @retval #LOS_ERRNO_SWTMR_ID_INVALID Invalid software timer ID. 352 * @retval #LOS_ERRNO_SWTMR_NOT_CREATED The software timer is not created. 353 * @retval #LOS_ERRNO_SWTMR_NOT_STARTED The software timer is not started. 354 * @retval #LOS_ERRNO_SWTMR_STATUS_INVALID Invalid software timer state. 355 * @retval #LOS_OK The number of remaining Ticks is successfully obtained. 356 * @par Dependency: 357 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 358 * @see LOS_SwtmrCreate 359 */ 360 extern UINT32 LOS_SwtmrTimeGet(UINT32 swtmrID, UINT32 *tick); 361 362 /** 363 * @ingroup los_swtmr 364 * @brief Create a software timer. 365 * 366 * @par Description: 367 * This API is used to create a software timer that has specified timing duration, timeout handling function, 368 * and trigger mode, and to return a handle by which the software timer can be referenced. 369 * @attention 370 * <ul> 371 * <li>Do not use the delay interface in the callback function that handles software timer timeout.</li> 372 * <li>There are LOSCFG_BASE_CORE_SWTMR_LIMIT timers available, change it's value when necessary.</li> 373 * </ul> 374 * 375 * @param interval [IN] Timing duration of the software timer to be created (unit: ms). 376 * @param mode [IN] Software timer mode. Pass in one of the modes specified by EnSwTmrType. There are three 377 * types of modes, one-off, periodic, and continuously periodic after one-off, of which the third mode is not 378 * supported temporarily. 379 * @param handler [IN] Callback function that handles software timer timeout. 380 * @param swtmrID [OUT] Software timer ID created by LOS_SwtmrCreate. 381 * @param arg [IN] Parameter passed in when the callback function that handles software timer timeout is 382 * called. 383 * 384 * @retval #LOS_ERRNO_SWTMR_INTERVAL_NOT_SUITED The software timer timeout interval is 0. 385 * @retval #LOS_ERRNO_SWTMR_MODE_INVALID Invalid software timer mode. 386 * @retval #LOS_ERRNO_SWTMR_PTR_NULL The callback function that handles software timer timeout is NULL. 387 * @retval #LOS_ERRNO_SWTMR_RET_PTR_NULL The passed-in software timer ID is NULL. 388 * @retval #LOS_ERRNO_SWTMR_MAXSIZE The number of software timers exceeds the configured permitted 389 * maximum number. 390 * @retval #LOS_OK The software timer is successfully created. 391 * @par Dependency: 392 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 393 * @see LOS_SwtmrDelete 394 */ 395 #if (LOSCFG_BASE_CORE_SWTMR_ALIGN == 1) 396 extern UINT32 LOS_SwtmrCreate(UINT32 interval, 397 UINT8 mode, 398 SWTMR_PROC_FUNC handler, 399 UINT32 *swtmrID, 400 UINT32 arg, 401 UINT8 rouses, 402 UINT8 sensitive); 403 #else 404 extern UINT32 LOS_SwtmrCreate(UINT32 interval, 405 UINT8 mode, 406 SWTMR_PROC_FUNC handler, 407 UINT32 *swtmrID, 408 UINT32 arg); 409 #endif 410 411 /** 412 * @ingroup los_swtmr 413 * @brief Delete a software timer. 414 * 415 * @par Description: 416 * This API is used to delete a software timer. 417 * @attention 418 * <ul> 419 * <li>The specific timer should be created and then stopped firstly.</li> 420 * </ul> 421 * 422 * @param swtmrID [IN] Software timer ID created by LOS_SwtmrCreate. 423 * 424 * @retval #LOS_ERRNO_SWTMR_ID_INVALID Invalid software timer ID. 425 * @retval #LOS_ERRNO_SWTMR_NOT_CREATED The software timer is not created. 426 * @retval #LOS_ERRNO_SWTMR_STATUS_INVALID Invalid software timer state. 427 * @retval #LOS_OK The software timer is successfully deleted. 428 * @par Dependency: 429 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 430 * @see LOS_SwtmrCreate 431 */ 432 extern UINT32 LOS_SwtmrDelete(UINT32 swtmrID); 433 434 /** 435 * @ingroup los_swtmr 436 * Software timer state 437 */ 438 enum SwtmrState { 439 OS_SWTMR_STATUS_UNUSED, /**< The software timer is not used. */ 440 OS_SWTMR_STATUS_CREATED, /**< The software timer is created. */ 441 OS_SWTMR_STATUS_TICKING /**< The software timer is timing. */ 442 }; 443 444 /** 445 * @ingroup los_swtmr 446 * Structure of the callback function that handles software timer timeout 447 */ 448 typedef struct { 449 SWTMR_PROC_FUNC handler; /**< Callback function that handles software timer timeout */ 450 UINT32 arg; /**< Parameter passed in when the callback function 451 that handles software timer timeout is called */ 452 UINT32 swtmrID; /**< The id used to obtain the software timer handle */ 453 } SwtmrHandlerItem; 454 455 extern SWTMR_CTRL_S *g_swtmrCBArray; 456 457 #define OS_SWT_FROM_SID(swtmrId) ((SWTMR_CTRL_S *)g_swtmrCBArray + ((swtmrId) % LOSCFG_BASE_CORE_SWTMR_LIMIT)) 458 459 /** 460 * @ingroup los_swtmr 461 * @brief Initialization software timer. 462 * 463 * @par Description: 464 * <ul> 465 * <li>This API is used to initialization software.</li> 466 * </ul> 467 * @attention 468 * <ul> 469 * <li>None.</li> 470 * </ul> 471 * 472 * @param None. 473 * 474 * @retval None. 475 * @par Dependency: 476 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 477 * @see None. 478 */ 479 extern UINT32 OsSwtmrInit(VOID); 480 481 /** 482 * @ingroup los_swtmr 483 * @brief Get next timeout. 484 * 485 * @par Description: 486 * <ul> 487 * <li>This API is used to get next timeout.</li> 488 * </ul> 489 * @attention 490 * <ul> 491 * <li>None.</li> 492 * </ul> 493 * 494 * @param None. 495 * 496 * @retval None. 497 * @par Dependency: 498 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 499 * @see None. 500 */ 501 extern UINT32 OsSwtmrGetNextTimeout(VOID); 502 503 extern VOID OsSwtmrResponseTimeReset(UINT64 startTime); 504 505 #ifdef __cplusplus 506 #if __cplusplus 507 } 508 #endif /* __cplusplus */ 509 #endif /* __cplusplus */ 510 511 #endif /* _LOS_SWTMR_H */ 512