Commit | Line | Data |
---|---|---|
635d2b00 GKH |
1 | /***************************************************************************** |
2 | ||
3 | (c) Cambridge Silicon Radio Limited 2011 | |
4 | All rights reserved and confidential information of CSR | |
5 | ||
6 | Refer to LICENSE.txt included with this source for details | |
7 | on the license terms. | |
8 | ||
9 | *****************************************************************************/ | |
10 | ||
11 | #ifndef CSR_WIFI_FSM_H | |
12 | #define CSR_WIFI_FSM_H | |
13 | ||
635d2b00 GKH |
14 | #include "csr_prim_defs.h" |
15 | #include "csr_log_text.h" | |
16 | #include "csr_wifi_fsm_event.h" | |
17 | ||
18 | /* including this file for CsrWifiInterfaceMode*/ | |
19 | #include "csr_wifi_common.h" | |
20 | ||
21 | #define CSR_WIFI_FSM_ENV (0xFFFF) | |
22 | ||
23 | /** | |
24 | * @brief | |
25 | * Toplevel FSM context data | |
26 | * | |
27 | * @par Description | |
28 | * Holds ALL FSM static and dynamic data for a FSM | |
29 | */ | |
30 | typedef struct CsrWifiFsmContext CsrWifiFsmContext; | |
31 | ||
32 | /** | |
33 | * @brief | |
34 | * FSM External Wakeup CallbackFunction Pointer | |
35 | * | |
36 | * @par Description | |
37 | * Defines the external wakeup function for the FSM | |
38 | * to call when an external event is injected into the systen | |
39 | * | |
40 | * @param[in] context : External context | |
41 | * | |
42 | * @return | |
43 | * void | |
44 | */ | |
45 | typedef void (*CsrWifiFsmExternalWakupCallbackPtr)(void *context); | |
46 | ||
47 | /** | |
48 | * @brief | |
49 | * Initialises a top level FSM context | |
50 | * | |
51 | * @par Description | |
52 | * Initialises the FSM Context to an initial state and allocates | |
53 | * space for "maxProcesses" number of instances | |
54 | * | |
55 | * @param[in] osaContext : OSA context | |
56 | * @param[in] applicationContext : Internal fsm application context | |
57 | * @param[in] externalContext : External context | |
58 | * @param[in] maxProcesses : Max processes to allocate room for | |
59 | * | |
60 | * @return | |
61 | * CsrWifiFsmContext* fsm context | |
62 | */ | |
8c87f69a | 63 | extern CsrWifiFsmContext* CsrWifiFsmInit(void *applicationContext, void *externalContext, u16 maxProcesses, CsrLogTextTaskId loggingTaskId); |
635d2b00 GKH |
64 | |
65 | /** | |
66 | * @brief | |
67 | * Resets the FSM's back to first conditions | |
68 | * | |
69 | * @par Description | |
70 | * This function is used to free any dynamic resources allocated for the | |
71 | * given context by CsrWifiFsmInit(). | |
72 | * The FSM's reset function is called to cleanup any fsm specific memory | |
58af42a4 | 73 | * The reset function does NOT need to free the fsm data pointer as |
635d2b00 GKH |
74 | * CsrWifiFsmShutdown() will do it. |
75 | * the FSM's init function is call again to reinitialise the FSM context. | |
76 | * CsrWifiFsmReset() should NEVER be called when CsrWifiFsmExecute() is running. | |
77 | * | |
78 | * @param[in] context : FSM context | |
79 | * | |
80 | * @return | |
81 | * void | |
82 | */ | |
83 | extern void CsrWifiFsmReset(CsrWifiFsmContext *context); | |
84 | ||
85 | /** | |
86 | * @brief | |
87 | * Frees resources allocated by CsrWifiFsmInit | |
88 | * | |
89 | * @par Description | |
90 | * This function is used to free any dynamic resources allocated for the | |
91 | * given context by CsrWifiFsmInit(), prior to complete termination of | |
92 | * the program. | |
93 | * The FSM's reset function is called to cleanup any fsm specific memory. | |
58af42a4 | 94 | * The reset function does NOT need to free the fsm data pointer as |
635d2b00 GKH |
95 | * CsrWifiFsmShutdown() will do it. |
96 | * CsrWifiFsmShutdown() should NEVER be called when CsrWifiFsmExecute() is running. | |
97 | * | |
98 | * @param[in] context : FSM context | |
99 | * | |
100 | * @return | |
101 | * void | |
102 | */ | |
103 | extern void CsrWifiFsmShutdown(CsrWifiFsmContext *context); | |
104 | ||
105 | /** | |
106 | * @brief | |
107 | * Executes the fsm context | |
108 | * | |
109 | * @par Description | |
110 | * Executes the FSM context and runs until ALL events in the context are processed. | |
111 | * When no more events are left to process then CsrWifiFsmExecute() returns to a time | |
112 | * specifying when to next call the CsrWifiFsmExecute() | |
113 | * Scheduling, threading, blocking and external event notification are outside | |
114 | * the scope of the FSM and CsrWifiFsmExecute(). | |
115 | * | |
116 | * @param[in] context : FSM context | |
117 | * | |
118 | * @return | |
26a6b2e1 | 119 | * u32 Time in ms until next timeout or 0xFFFFFFFF for no timer set |
635d2b00 | 120 | */ |
26a6b2e1 | 121 | extern u32 CsrWifiFsmExecute(CsrWifiFsmContext *context); |
635d2b00 GKH |
122 | |
123 | /** | |
124 | * @brief | |
125 | * Adds an event to the FSM context's external event queue for processing | |
126 | * | |
127 | * @par Description | |
128 | * Adds an event to the contexts external queue | |
129 | * This is thread safe and adds an event to the fsm's external event queue. | |
130 | * | |
131 | * @param[in] context : FSM context | |
132 | * @param[in] event : event to add to the event queue | |
133 | * @param[in] source : source of the event (this can be a synergy task queue or an fsm instance id) | |
134 | * @param[in] destination : destination of the event (This can be a fsm instance id or CSR_WIFI_FSM_ENV) | |
135 | * @param[in] id : event id | |
136 | * | |
137 | * @return | |
138 | * void | |
139 | */ | |
8c87f69a | 140 | extern void CsrWifiFsmSendEventExternal(CsrWifiFsmContext *context, CsrWifiFsmEvent *event, u16 source, u16 destination, CsrPrim primtype, u16 id); |
635d2b00 GKH |
141 | |
142 | /** | |
143 | * @brief | |
144 | * Adds an Alien event to the FSM context's external event queue for processing | |
145 | * | |
146 | * @par Description | |
147 | * Adds an event to the contexts external queue | |
148 | * This is thread safe and adds an event to the fsm's external event queue. | |
149 | * | |
150 | * @param[in] context : FSM context | |
151 | * @param[in] event : event to add to the event queue | |
152 | * @param[in] source : source of the event (this can be a synergy task queue or an fsm instance id) | |
153 | * @param[in] destination : destination of the event (This can be a fsm instance id or CSR_WIFI_FSM_ENV) | |
154 | * @param[in] id : event id | |
155 | */ | |
156 | #define CsrWifiFsmSendAlienEventExternal(_context, _alienEvent, _source, _destination, _primtype, _id) \ | |
157 | { \ | |
786eeeb3 | 158 | CsrWifiFsmAlienEvent *_evt = kmalloc(sizeof(CsrWifiFsmAlienEvent), GFP_KERNEL); \ |
635d2b00 GKH |
159 | _evt->alienEvent = _alienEvent; \ |
160 | CsrWifiFsmSendEventExternal(_context, (CsrWifiFsmEvent *)_evt, _source, _destination, _primtype, _id); \ | |
161 | } | |
162 | ||
163 | ||
164 | /** | |
165 | * @brief | |
166 | * Current time of day in ms | |
167 | * | |
168 | * @param[in] context : FSM context | |
169 | * | |
170 | * @return | |
26a6b2e1 | 171 | * u32 32 bit ms tick |
635d2b00 | 172 | */ |
26a6b2e1 | 173 | extern u32 CsrWifiFsmGetTimeOfDayMs(CsrWifiFsmContext *context); |
635d2b00 GKH |
174 | |
175 | /** | |
176 | * @brief | |
177 | * Gets the time until the next FSM timer expiry | |
178 | * | |
179 | * @par Description | |
180 | * Returns the next timeout time or 0 if no timers are set. | |
181 | * | |
182 | * @param[in] context : FSM context | |
183 | * | |
184 | * @return | |
26a6b2e1 | 185 | * u32 Time in ms until next timeout or 0xFFFFFFFF for no timer set |
635d2b00 | 186 | */ |
26a6b2e1 | 187 | extern u32 CsrWifiFsmGetNextTimeout(CsrWifiFsmContext *context); |
635d2b00 GKH |
188 | |
189 | /** | |
190 | * @brief | |
191 | * Fast forwards the fsm timers by ms Milliseconds | |
192 | * | |
193 | * @param[in] context : FSM context | |
194 | * @param[in] ms : Milliseconds to fast forward by | |
195 | * | |
196 | * @return | |
197 | * void | |
198 | */ | |
8c87f69a | 199 | extern void CsrWifiFsmFastForward(CsrWifiFsmContext *context, u16 ms); |
635d2b00 GKH |
200 | |
201 | /** | |
202 | * @brief | |
203 | * shift the current time of day by ms amount | |
204 | * | |
205 | * @par Description | |
58af42a4 | 206 | * useful to speed up tests where time needs to pass |
635d2b00 GKH |
207 | * |
208 | * @param[in] context : FSM context | |
209 | * @param[in] ms : ms to adjust time by | |
210 | * | |
211 | * @return | |
212 | * void | |
213 | */ | |
26a6b2e1 | 214 | extern void CsrWifiFsmTestAdvanceTime(CsrWifiFsmContext *context, u32 ms); |
635d2b00 GKH |
215 | |
216 | /** | |
217 | * @brief | |
218 | * Check if the fsm has events to process | |
219 | * | |
220 | * @param[in] context : FSM context | |
221 | * | |
222 | * @return | |
5379b13d | 223 | * u8 returns TRUE if there are events for the FSM to process |
635d2b00 | 224 | */ |
5379b13d | 225 | extern u8 CsrWifiFsmHasEvents(CsrWifiFsmContext *context); |
635d2b00 GKH |
226 | |
227 | /** | |
228 | * @brief | |
229 | * function that installs the contexts wakeup function | |
230 | * | |
231 | * @param[in] context : FSM context | |
232 | * @param[in] callback : Callback function pointer | |
233 | * | |
234 | * @return | |
235 | * void | |
236 | */ | |
237 | extern void CsrWifiFsmInstallWakeupCallback(CsrWifiFsmContext *context, CsrWifiFsmExternalWakupCallbackPtr callback); | |
238 | ||
635d2b00 GKH |
239 | #endif /* CSR_WIFI_FSM_H */ |
240 |