1 /* 2 * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved. 3 * Copyright (c) 2020-2023 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_base.h" 41 #include "los_task.h" 42 #include "los_sortlink_pri.h" 43 44 #ifdef __cplusplus 45 #if __cplusplus 46 extern "C" { 47 #endif /* __cplusplus */ 48 #endif /* __cplusplus */ 49 50 /** 51 * @ingroup los_swtmr 52 * Software timer error code: The timeout handling function is NULL. 53 * 54 * Value: 0x02000300 55 * 56 * Solution: Define the timeout handling function. 57 */ 58 #define LOS_ERRNO_SWTMR_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x00) 59 60 /** 61 * @ingroup los_swtmr 62 * Software timer error code: The expiration time is 0. 63 * 64 * Value: 0x02000301 65 * 66 * Solution: Re-define the expiration time. 67 */ 68 #define LOS_ERRNO_SWTMR_INTERVAL_NOT_SUITED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x01) 69 70 /** 71 * @ingroup los_swtmr 72 * Software timer error code: Invalid software timer mode. 73 * 74 * Value: 0x02000302 75 * 76 * Solution: Check the mode value. The value range is [0,3]. 77 */ 78 #define LOS_ERRNO_SWTMR_MODE_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x02) 79 80 /** 81 * @ingroup los_swtmr 82 * Software timer error code: The passed-in software timer ID is NULL. 83 * 84 * Value: 0x02000303 85 * 86 * Solution: Define the software timer ID before passing it in. 87 */ 88 #define LOS_ERRNO_SWTMR_RET_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x03) 89 90 /** 91 * @ingroup los_swtmr 92 * Software timer error code: The number of software timers exceeds the configured permitted maximum number. 93 * 94 * Value: 0x02000304 95 * 96 * Solution: Re-configure the permitted maximum number of software timers, or wait for a software timer to become 97 * available. 98 */ 99 #define LOS_ERRNO_SWTMR_MAXSIZE LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x04) 100 101 /** 102 * @ingroup los_swtmr 103 * Software timer error code: Invalid software timer ID. 104 * 105 * Value: 0x02000305 106 * 107 * Solution: Pass in a valid software timer ID. 108 */ 109 #define LOS_ERRNO_SWTMR_ID_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x05) 110 111 /** 112 * @ingroup los_swtmr 113 * Software timer error code: The software timer is not created. 114 * 115 * Value: 0x02000306 116 * 117 * Solution: Create a software timer. 118 */ 119 #define LOS_ERRNO_SWTMR_NOT_CREATED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x06) 120 121 /** 122 * @ingroup los_swtmr 123 * Software timer error code: Insufficient memory for software timer linked list creation. 124 * 125 * Value: 0x02000307 126 * 127 * Solution: Allocate bigger memory partition to software timer linked list creation. 128 */ 129 #define LOS_ERRNO_SWTMR_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x07) 130 131 /** 132 * @ingroup los_swtmr 133 * Software timer error code: Invalid configured number of software timers. 134 * 135 * Value: 0x02000308 136 * 137 * Solution: Re-configure the number of software timers. 138 */ 139 #define LOS_ERRNO_SWTMR_MAXSIZE_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x08) 140 141 /** 142 * @ingroup los_swtmr 143 * Software timer error code: The software timer is being used during an interrupt. 144 * 145 * Value: 0x02000309 146 * 147 * Solution: Change the source code and do not use the software timer during an interrupt. 148 */ 149 #define LOS_ERRNO_SWTMR_HWI_ACTIVE LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x09) 150 151 /** 152 * @ingroup los_swtmr 153 * Software timer error code: Insufficient memory allocated by membox. 154 * 155 * Value: 0x0200030a 156 * 157 * Solution: Expand the memory allocated by membox. 158 */ 159 #define LOS_ERRNO_SWTMR_HANDLER_POOL_NO_MEM LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0a) 160 161 /** 162 * @ingroup los_swtmr 163 * Software timer error code: The software timer queue fails to be created. 164 * 165 * Value: 0x0200030b 166 * 167 * Solution: Check whether more memory can be allocated to the queue to be created. 168 */ 169 #define LOS_ERRNO_SWTMR_QUEUE_CREATE_FAILED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0b) 170 171 /** 172 * @ingroup los_swtmr 173 * Software timer error code: The software timer task fails to be created. 174 * 175 * Value: 0x0200030c 176 * 177 * Solution: Check whether the memory is sufficient and re-create the task. 178 */ 179 #define LOS_ERRNO_SWTMR_TASK_CREATE_FAILED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0c) 180 181 /** 182 * @ingroup los_swtmr 183 * Software timer error code: The software timer is not started. 184 * 185 * Value: 0x0200030d 186 * 187 * Solution: Start the software timer. 188 */ 189 #define LOS_ERRNO_SWTMR_NOT_STARTED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0d) 190 191 /** 192 * @ingroup los_swtmr 193 * Software timer error code: Invalid software timer state. 194 * 195 * Value: 0x0200030e 196 * 197 * Solution: Check the software timer state. 198 */ 199 #define LOS_ERRNO_SWTMR_STATUS_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0e) 200 201 /** 202 * @ingroup los_swtmr 203 * This error code is not in use temporarily. 204 */ 205 #define LOS_ERRNO_SWTMR_SORTLIST_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x0f) 206 207 /** 208 * @ingroup los_swtmr 209 * Software timer error code: The passed-in number of remaining Ticks configured on the software timer is NULL. 210 * 211 * Value: 0x02000310 212 * 213 * Solution: Define a variable of the number of remaining Ticks before passing in the number of remaining Ticks. 214 */ 215 #define LOS_ERRNO_SWTMR_TICK_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x10) 216 217 /** 218 * @ingroup los_swtmr 219 * Software timer error code: The software sortlink fails to be created. 220 * 221 * Value: 0x02000311 222 * 223 * Solution: Check whether the memory is sufficient and re-create the sortlink. 224 */ 225 #define LOS_ERRNO_SWTMR_SORTLINK_CREATE_FAILED LOS_ERRNO_OS_ERROR(LOS_MOD_SWTMR, 0x11) 226 227 /** 228 * @ingroup los_swtmr 229 * Software timer mode 230 */ 231 enum enSwTmrType { 232 LOS_SWTMR_MODE_ONCE, /**< One-off software timer */ 233 LOS_SWTMR_MODE_PERIOD, /**< Periodic software timer */ 234 LOS_SWTMR_MODE_NO_SELFDELETE, /**< One-off software timer, but not self-delete */ 235 LOS_SWTMR_MODE_OPP /**< After the one-off timer finishes timing, 236 the periodic software timer is enabled. 237 This mode is not supported temporarily. */ 238 }; 239 240 /** 241 * @ingroup los_swtmr 242 * @brief Define the type of a callback function that handles software timer timeout. 243 * 244 * @par Description: 245 * This API is used to define the type of a callback function that handles software timer timeout, so that it can be 246 * called when software timer timeout. 247 * 248 * @attention 249 * <ul> 250 * <li>None.</li> 251 * </ul> 252 * 253 * @param arg [IN] the parameter of the callback function that handles software timer timeout. 254 * 255 * @retval None. 256 * @par Dependency: 257 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 258 * @see None. 259 */ 260 typedef VOID (*SWTMR_PROC_FUNC)(UINTPTR arg); 261 262 /** 263 * @ingroup los_swtmr 264 * Software timer control structure 265 */ 266 typedef struct tagSwTmrCtrl { 267 SortLinkList stSortList; 268 UINT8 ucState; /**< Software timer state */ 269 UINT8 ucMode; /**< Software timer mode */ 270 UINT16 usTimerID; /**< Software timer ID */ 271 UINT32 uwOverrun; /**< Times that a software timer repeats timing */ 272 UINT32 uwCount; /**< Times that a software timer works */ 273 UINT32 uwInterval; /**< Timeout interval of a periodic software timer */ 274 UINT32 uwExpiry; /**< Timeout interval of an one-off software timer */ 275 UINTPTR uwArg; /**< Parameter passed in when the callback function 276 that handles software timer timeout is called */ 277 SWTMR_PROC_FUNC pfnHandler; /**< Callback function that handles software timer timeout */ 278 UINTPTR uwOwnerPid; /** Owner of this software timer */ 279 UINT64 startTime; /**< Software timer start time */ 280 } SWTMR_CTRL_S; 281 282 /** 283 * @ingroup los_swtmr 284 * @brief Start a software timer. 285 * 286 * @par Description: 287 * This API is used to start a software timer that has a specified ID. 288 * @attention 289 * <ul> 290 * <li>The specific timer must be created first</li> 291 * </ul> 292 * 293 * @param swtmrID [IN] Software timer ID created by LOS_SwtmrCreate. The value of ID should be in 294 * [0, LOSCFG_BASE_CORE_SWTMR_LIMIT - 1]. 295 * 296 * @retval #LOS_ERRNO_SWTMR_ID_INVALID Invalid software timer ID. 297 * @retval #LOS_ERRNO_SWTMR_NOT_CREATED The software timer is not created. 298 * @retval #LOS_ERRNO_SWTMR_STATUS_INVALID Invalid software timer state. 299 * @retval #LOS_OK The software timer is successfully started. 300 * @par Dependency: 301 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 302 * @see LOS_SwtmrStop | LOS_SwtmrCreate 303 */ 304 extern UINT32 LOS_SwtmrStart(UINT16 swtmrID); 305 306 /** 307 * @ingroup los_swtmr 308 * @brief Stop a software timer. 309 * 310 * @par Description: 311 * This API is used to stop a software timer that has a specified ID. 312 * @attention 313 * <ul> 314 * <li>The specific timer should be created and started firstly.</li> 315 * </ul> 316 * 317 * @param swtmrID [IN] Software timer ID created by LOS_SwtmrCreate. The value of ID should be in 318 * [0, LOSCFG_BASE_CORE_SWTMR_LIMIT - 1]. 319 * 320 * @retval #LOS_ERRNO_SWTMR_ID_INVALID Invalid software timer ID. 321 * @retval #LOS_ERRNO_SWTMR_NOT_CREATED The software timer is not created. 322 * @retval #LOS_ERRNO_SWTMR_NOT_STARTED The software timer is not started. 323 * @retval #LOS_ERRNO_SWTMR_STATUS_INVALID Invalid software timer state. 324 * @retval #LOS_OK The software timer is successfully stopped. 325 * @par Dependency: 326 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 327 * @see LOS_SwtmrStart | LOS_SwtmrCreate 328 */ 329 extern UINT32 LOS_SwtmrStop(UINT16 swtmrID); 330 331 /** 332 * @ingroup los_swtmr 333 * @brief Obtain the number of remaining Ticks configured on a software timer. 334 * 335 * @par Description: 336 * This API is used to obtain the number of remaining Ticks configured on the software timer of which the ID is 337 * specified by usSwTmrID. 338 * @attention 339 * <ul> 340 * <li>The specific timer should be created and started successfully, error happeneds otherwise.</li> 341 * </ul> 342 * 343 * @param swtmrID [IN] Software timer ID created by LOS_SwtmrCreate. The value of ID should be in 344 * [0, LOSCFG_BASE_CORE_SWTMR_LIMIT - 1]. 345 * @param tick [OUT] Number of remaining Ticks configured on the software timer. 346 * 347 * @retval #LOS_ERRNO_SWTMR_ID_INVALID Invalid software timer ID. 348 * @retval #LOS_ERRNO_SWTMR_NOT_CREATED The software timer is not created. 349 * @retval #LOS_ERRNO_SWTMR_NOT_STARTED The software timer is not started. 350 * @retval #LOS_ERRNO_SWTMR_STATUS_INVALID Invalid software timer state. 351 * @retval #LOS_OK The number of remaining Ticks is successfully obtained. 352 * @par Dependency: 353 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 354 * @see LOS_SwtmrCreate 355 */ 356 extern UINT32 LOS_SwtmrTimeGet(UINT16 swtmrID, UINT32 *tick); 357 358 /** 359 * @ingroup los_swtmr 360 * @brief Create a software timer. 361 * 362 * @par Description: 363 * This API is used to create a software timer that has specified timing duration, timeout handling function, 364 * and trigger mode, and to return a handle by which the software timer can be referenced. 365 * @attention 366 * <ul> 367 * <li>Do not use the delay interface in the callback function that handles software timer timeout.</li> 368 * <li>There are LOSCFG_BASE_CORE_SWTMR_LIMIT timers available, change it's value when necessary.</li> 369 * </ul> 370 * 371 * @param interval [IN] Timing duration of the software timer to be created (unit: tick). 372 * @param mode [IN] Software timer mode. Pass in one of the modes specified by enSwTmrType. There are three 373 * types of modes, one-off, periodic, and continuously periodic after one-off, of which the third mode is not 374 * supported temporarily. 375 * @param handler [IN] Callback function that handles software timer timeout. 376 * @param swtmrID [OUT] Software timer ID created by LOS_SwtmrCreate. 377 * @param arg [IN] Parameter passed in when the callback function that handles software timer timeout is 378 * called. 379 * 380 * @retval #LOS_ERRNO_SWTMR_INTERVAL_NOT_SUITED The software timer timeout interval is 0. 381 * @retval #LOS_ERRNO_SWTMR_MODE_INVALID Invalid software timer mode. 382 * @retval #LOS_ERRNO_SWTMR_PTR_NULL The callback function that handles software timer timeout is NULL. 383 * @retval #LOS_ERRNO_SWTMR_RET_PTR_NULL The passed-in software timer ID is NULL. 384 * @retval #LOS_ERRNO_SWTMR_MAXSIZE The number of software timers exceeds the configured permitted 385 * maximum number. 386 * @retval #LOS_OK The software timer is successfully created. 387 * @par Dependency: 388 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 389 * @see LOS_SwtmrDelete 390 */ 391 extern UINT32 LOS_SwtmrCreate(UINT32 interval, UINT8 mode, SWTMR_PROC_FUNC handler, UINT16 *swtmrID, UINTPTR arg); 392 393 /** 394 * @ingroup los_swtmr 395 * @brief Delete a software timer. 396 * 397 * @par Description: 398 * This API is used to delete a software timer. 399 * @attention 400 * <ul> 401 * <li>The specific timer should be created and then stopped firstly.</li> 402 * </ul> 403 * 404 * @param swtmrID [IN] Software timer ID created by LOS_SwtmrCreate. The value of ID should be in 405 * [0, LOSCFG_BASE_CORE_SWTMR_LIMIT - 1]. 406 * 407 * @retval #LOS_ERRNO_SWTMR_ID_INVALID Invalid software timer ID. 408 * @retval #LOS_ERRNO_SWTMR_NOT_CREATED The software timer is not created. 409 * @retval #LOS_ERRNO_SWTMR_STATUS_INVALID Invalid software timer state. 410 * @retval #LOS_OK The software timer is successfully deleted. 411 * @par Dependency: 412 * <ul><li>los_swtmr.h: the header file that contains the API declaration.</li></ul> 413 * @see LOS_SwtmrCreate 414 */ 415 extern UINT32 LOS_SwtmrDelete(UINT16 swtmrID); 416 417 #ifdef __cplusplus 418 #if __cplusplus 419 } 420 #endif /* __cplusplus */ 421 #endif /* __cplusplus */ 422 423 #endif /* _LOS_SWTMR_H */ 424