Pileus Git - ~andy/linux/blob - 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
  15 extern "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  */
  34 typedef 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  */
  49 typedef 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  */
  67 extern 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  */
  87 extern 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  */
 107 extern 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  */
 125 extern 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  */
 144 extern 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  */
 177 extern 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  */
 191 extern 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  */
 203 extern 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  */
 218 extern 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  */
 229 extern 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  */
 241 extern void CsrWifiFsmInstallWakeupCallback(CsrWifiFsmContext *context, CsrWifiFsmExternalWakupCallbackPtr callback);
 242
 243 #ifdef __cplusplus
 244 }
 245 #endif
 246
 247 #endif /* CSR_WIFI_FSM_H */
 248