Root/drivers/staging/csr/csr_wifi_fsm.h

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

Archive Download this file



interactive