Johnny Kim | c5c77ba | 2015-05-11 14:30:56 +0900 | [diff] [blame] | 1 | #ifndef __WILC_TIMER_H__ |
| 2 | #define __WILC_TIMER_H__ |
| 3 | |
| 4 | /*! |
| 5 | * @file wilc_timer.h |
| 6 | * @brief Timer (One Shot and Periodic) OS wrapper functionality |
| 7 | * @author syounan |
| 8 | * @sa wilc_oswrapper.h top level OS wrapper file |
| 9 | * @date 16 Aug 2010 |
| 10 | * @version 1.0 |
| 11 | */ |
| 12 | |
Dean Lee | c3ea8a7 | 2015-06-16 15:28:21 +0900 | [diff] [blame] | 13 | #include "wilc_platform.h" |
| 14 | #include "wilc_errorsupport.h" |
| 15 | |
Johnny Kim | c5c77ba | 2015-05-11 14:30:56 +0900 | [diff] [blame] | 16 | typedef void (*tpfWILC_TimerFunction)(void *); |
| 17 | |
| 18 | /*! |
| 19 | * @struct tstrWILC_TimerAttrs |
| 20 | * @brief Timer API options |
| 21 | * @author syounan |
| 22 | * @date 16 Aug 2010 |
| 23 | * @version 1.0 |
| 24 | */ |
| 25 | typedef struct { |
Johnny Kim | c5c77ba | 2015-05-11 14:30:56 +0900 | [diff] [blame] | 26 | /* a dummy member to avoid compiler errors*/ |
Greg Kroah-Hartman | 63d03e4 | 2015-06-02 14:16:04 +0900 | [diff] [blame] | 27 | u8 dummy; |
Johnny Kim | c5c77ba | 2015-05-11 14:30:56 +0900 | [diff] [blame] | 28 | } tstrWILC_TimerAttrs; |
| 29 | |
| 30 | /*! |
Johnny Kim | c5c77ba | 2015-05-11 14:30:56 +0900 | [diff] [blame] | 31 | * @brief Creates a new timer |
| 32 | * @details Timers are a useful utility to execute some callback function |
| 33 | * in the future. |
| 34 | * A timer object has 3 states : IDLE, PENDING and EXECUTING |
| 35 | * IDLE : initial timer state after creation, no execution for the |
| 36 | * callback function is planned |
| 37 | * PENDING : a request to execute the callback function is made |
| 38 | * using WILC_TimerStart. |
| 39 | * EXECUTING : the timer has expired and its callback is now |
| 40 | * executing, when execution is done the timer returns to PENDING |
| 41 | * if the feature CONFIG_WILC_TIMER_PERIODIC is enabled and |
| 42 | * the flag tstrWILC_TimerAttrs.bPeriodicTimer is set. otherwise the |
| 43 | * timer will return to IDLE |
| 44 | * @param[out] pHandle handle to the newly created timer object |
| 45 | * @param[in] pfEntry pointer to the callback function to be called when the |
| 46 | * timer expires |
| 47 | * the underlaying OS may put many restrictions on what can be |
| 48 | * called inside a timer's callback, as a general rule no blocking |
| 49 | * operations (IO or semaphore Acquision) should be perfomred |
| 50 | * It is recommended that the callback will be as short as possible |
| 51 | * and only flags other threads to do the actual work |
| 52 | * also it should be noted that the underlaying OS maynot give any |
| 53 | * guarentees on which contect this callback will execute in |
| 54 | * @param[in] pstrAttrs Optional attributes, NULL for default |
| 55 | * @return Error code indicating sucess/failure |
| 56 | * @sa WILC_TimerAttrs |
| 57 | * @author syounan |
| 58 | * @date 16 Aug 2010 |
| 59 | * @version 1.0 |
| 60 | */ |
| 61 | WILC_ErrNo WILC_TimerCreate(WILC_TimerHandle *pHandle, |
| 62 | tpfWILC_TimerFunction pfCallback, tstrWILC_TimerAttrs *pstrAttrs); |
| 63 | |
| 64 | |
| 65 | /*! |
| 66 | * @brief Destroys a given timer |
| 67 | * @details This will destroy a given timer freeing any resources used by it |
| 68 | * if the timer was PENDING Then must be cancelled as well(i.e. |
| 69 | * goes to IDLE, same effect as calling WILC_TimerCancel first) |
| 70 | * if the timer was EXECUTING then the callback will be allowed to |
| 71 | * finish first then all resources are freed |
| 72 | * @param[in] pHandle handle to the timer object |
| 73 | * @param[in] pstrAttrs Optional attributes, NULL for default |
| 74 | * @return Error code indicating sucess/failure |
| 75 | * @sa WILC_TimerAttrs |
| 76 | * @author syounan |
| 77 | * @date 16 Aug 2010 |
| 78 | * @version 1.0 |
| 79 | */ |
| 80 | WILC_ErrNo WILC_TimerDestroy(WILC_TimerHandle *pHandle, |
| 81 | tstrWILC_TimerAttrs *pstrAttrs); |
| 82 | |
| 83 | /*! |
| 84 | * @brief Starts a given timer |
| 85 | * @details This function will move the timer to the PENDING state until the |
| 86 | * given time expires (in msec) then the callback function will be |
| 87 | * executed (timer in EXECUTING state) after execution is dene the |
Dean Lee | 72ed4dc | 2015-06-12 14:11:44 +0900 | [diff] [blame] | 88 | * timer either goes to IDLE (if bPeriodicTimer==false) or |
| 89 | * PENDING with same timeout value (if bPeriodicTimer==true) |
Johnny Kim | c5c77ba | 2015-05-11 14:30:56 +0900 | [diff] [blame] | 90 | * @param[in] pHandle handle to the timer object |
| 91 | * @param[in] u32Timeout timeout value in msec after witch the callback |
| 92 | * function will be executed. Timeout value of 0 is not allowed for |
| 93 | * periodic timers |
| 94 | * @param[in] pstrAttrs Optional attributes, NULL for default, |
| 95 | * set bPeriodicTimer to run this timer as a periodic timer |
| 96 | * @return Error code indicating sucess/failure |
| 97 | * @sa WILC_TimerAttrs |
| 98 | * @author syounan |
| 99 | * @date 16 Aug 2010 |
| 100 | * @version 1.0 |
| 101 | */ |
Chaehyun Lim | 4e4467f | 2015-06-11 14:35:55 +0900 | [diff] [blame] | 102 | WILC_ErrNo WILC_TimerStart(WILC_TimerHandle *pHandle, u32 u32Timeout, void *pvArg, |
Johnny Kim | c5c77ba | 2015-05-11 14:30:56 +0900 | [diff] [blame] | 103 | tstrWILC_TimerAttrs *pstrAttrs); |
| 104 | |
| 105 | |
| 106 | /*! |
| 107 | * @brief Stops a given timer |
| 108 | * @details This function will move the timer to the IDLE state cancelling |
| 109 | * any sheduled callback execution. |
| 110 | * if this function is called on a timer already in the IDLE state |
| 111 | * it will have no effect. |
| 112 | * if this function is called on a timer in EXECUTING state |
| 113 | * (callback has already started) it will wait until executing is |
| 114 | * done then move the timer to the IDLE state (which is trivial |
| 115 | * work if the timer is non periodic) |
| 116 | * @param[in] pHandle handle to the timer object |
| 117 | * @param[in] pstrAttrs Optional attributes, NULL for default, |
| 118 | * @return Error code indicating sucess/failure |
| 119 | * @sa WILC_TimerAttrs |
| 120 | * @author syounan |
| 121 | * @date 16 Aug 2010 |
| 122 | * @version 1.0 |
| 123 | */ |
| 124 | WILC_ErrNo WILC_TimerStop(WILC_TimerHandle *pHandle, |
| 125 | tstrWILC_TimerAttrs *pstrAttrs); |
| 126 | |
| 127 | |
| 128 | |
| 129 | #endif |