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 */ 30typedef 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 */ 45typedef 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 */ 63extern 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 */ 83extern 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 */ 103extern 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 */ 121extern 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 */ 140extern 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 */ 173extern 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 */ 187extern 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 */ 199extern 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 */ 214extern 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 */ 225extern 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 */ 237extern void CsrWifiFsmInstallWakeupCallback(CsrWifiFsmContext *context, CsrWifiFsmExternalWakupCallbackPtr callback); 238 239#endif /* CSR_WIFI_FSM_H */ 240 241