• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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