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 #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