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 #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 */ 63 extern CsrWifiFsmContext* CsrWifiFsmInit(void *applicationContext, void *externalContext, u16 maxProcesses, CsrLogTextTaskId loggingTaskId); 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 73 * The reset function does NOT need to free the fsm data pointer as 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. 94 * The reset function does NOT need to free the fsm data pointer as 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 119 * u32 Time in ms until next timeout or 0xFFFFFFFF for no timer set 120 */ 121 extern u32 CsrWifiFsmExecute(CsrWifiFsmContext *context); 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 */ 140 extern void CsrWifiFsmSendEventExternal(CsrWifiFsmContext *context, CsrWifiFsmEvent *event, u16 source, u16 destination, CsrPrim primtype, u16 id); 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 { \ 158 CsrWifiFsmAlienEvent *_evt = kmalloc(sizeof(CsrWifiFsmAlienEvent), GFP_KERNEL); \ 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 171 * u32 32 bit ms tick 172 */ 173 extern u32 CsrWifiFsmGetTimeOfDayMs(CsrWifiFsmContext *context); 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 185 * u32 Time in ms until next timeout or 0xFFFFFFFF for no timer set 186 */ 187 extern u32 CsrWifiFsmGetNextTimeout(CsrWifiFsmContext *context); 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 */ 199 extern void CsrWifiFsmFastForward(CsrWifiFsmContext *context, u16 ms); 200 201 /** 202 * @brief 203 * shift the current time of day by ms amount 204 * 205 * @par Description 206 * useful to speed up tests where time needs to pass 207 * 208 * @param[in] context : FSM context 209 * @param[in] ms : ms to adjust time by 210 * 211 * @return 212 * void 213 */ 214 extern void CsrWifiFsmTestAdvanceTime(CsrWifiFsmContext *context, u32 ms); 215 216 /** 217 * @brief 218 * Check if the fsm has events to process 219 * 220 * @param[in] context : FSM context 221 * 222 * @return 223 * u8 returns TRUE if there are events for the FSM to process 224 */ 225 extern u8 CsrWifiFsmHasEvents(CsrWifiFsmContext *context); 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 239 #endif /* CSR_WIFI_FSM_H */ 240 241