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