Root/drivers/staging/csr/csr_wifi_fsm_types.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_TYPES_H
12#define CSR_WIFI_FSM_TYPES_H
13
14#ifdef __cplusplus
15extern "C" {
16#endif
17
18#include <linux/types.h>
19#include "csr_macro.h"
20#include "csr_panic.h"
21#include "csr_sched.h"
22
23#ifdef CSR_WIFI_FSM_MUTEX_ENABLE
24#include "csr_framework_ext.h"
25#endif
26
27#include "csr_wifi_fsm.h"
28
29#define CSR_WIFI_FSM_MAX_TRANSITION_HISTORY 10
30
31/**
32 * @brief
33 * FSM event list header.
34 *
35 * @par Description
36 * Singly linked list of events.
37 */
38typedef struct CsrWifiFsmEventList
39{
40    CsrWifiFsmEvent *first;
41    CsrWifiFsmEvent *last;
42} CsrWifiFsmEventList;
43
44
45/**
46 * @brief
47 * FSM timer id.
48 *
49 * @par Description
50 * Composite Id made up of the type, dest and a unique id so
51 * CsrWifiFsmRemoveTimer knows where to look when removing the timer
52 */
53typedef struct CsrWifiFsmTimerId
54{
55    CsrPrim type;
56    u16 primtype;
57    CsrSchedQid destination;
58    u16 uniqueid;
59} CsrWifiFsmTimerId;
60
61/**
62 * @brief
63 * FSM timer header.
64 *
65 * @par Description
66 * All timer MUST have this struct as the FIRST member.
67 * The first members of the structure MUST remain compatable
68 * with the CsrWifiFsmEvent so that timers are just specialised events
69 */
70typedef struct CsrWifiFsmTimer
71{
72    CsrPrim type;
73    u16 primtype;
74    CsrSchedQid destination;
75    CsrSchedQid source;
76
77    /* Private pointer to allow an optimal Event list */
78    struct CsrWifiFsmTimer *next;
79
80    CsrWifiFsmTimerId timerid;
81    u32 timeoutTimeMs;
82} CsrWifiFsmTimer;
83
84
85/**
86 * @brief
87 * Fsm Alien Event
88 *
89 * @par Description
90 * Allows the wrapping of alien events that do not use CsrWifiFsmEvent
91 * as the first member of the Event struct
92 */
93typedef struct
94{
95    CsrWifiFsmEvent event;
96    void *alienEvent;
97} CsrWifiFsmAlienEvent;
98
99
100/**
101 * @brief
102 * FSM timer list header.
103 *
104 * @par Description
105 * Singly linked list of timers.
106 */
107typedef struct CsrWifiFsmTimerList
108{
109    CsrWifiFsmTimer *first;
110    CsrWifiFsmTimer *last;
111    u16 nexttimerid;
112} CsrWifiFsmTimerList;
113
114/**
115 * @brief
116 * Process Entry Function Pointer
117 *
118 * @par Description
119 * Defines the entry function for a processes.
120 * Called at process initialisation.
121 *
122 * @param[in] context : FSM context
123 *
124 * @return
125 * void
126 */
127typedef void (*CsrWifiFsmProcEntryFnPtr)(CsrWifiFsmContext *context);
128
129/**
130 * @brief
131 * Process Transition Function Pointer
132 *
133 * @par Description
134 * Defines a transition function for a processes.
135 * Called when an event causes a transition on a process
136 *
137 * @param[in] CsrWifiFsmContext* : FSM context
138 * @param[in] void* : FSM data (can be NULL)
139 * @param[in] const CsrWifiFsmEvent* : event to process
140 *
141 * @return
142 * void
143 */
144typedef void (*CsrWifiFsmTransitionFnPtr)(CsrWifiFsmContext *context, void *fsmData, const CsrWifiFsmEvent *event);
145
146/**
147 * @brief
148 * Process reset/shutdown Function Pointer
149 *
150 * @par Description
151 * Defines the reset/shutdown function for a processes.
152 * Called to reset or shutdown an fsm.
153 *
154 * @param[in] context : FSM context
155 *
156 * @return
157 * void
158 */
159typedef void (*CsrWifiFsmProcResetFnPtr)(CsrWifiFsmContext *context);
160
161/**
162 * @brief
163 * FSM Default Destination CallbackFunction Pointer
164 *
165 * @par Description
166 * Defines the default destination function for the FSM
167 * to call when an event does not have a valid destination.
168 * This
169 *
170 * @param[in] context : External context
171 *
172 * @return
173 * u16 a valid destination OR CSR_WIFI_FSM_ENV
174 */
175typedef u16 (*CsrWifiFsmDestLookupCallbackPtr)(void *context, const CsrWifiFsmEvent *event);
176
177
178#ifdef CSR_WIFI_FSM_DUMP_ENABLE
179/**
180 * @brief
181 * Trace Dump Function Pointer
182 *
183 * @par Description
184 * Called when we want to trace the FSM
185 *
186 * @param[in] context : FSM context
187 * @param[in] id : fsm id
188 *
189 * @return
190 * void
191 */
192typedef void (*CsrWifiFsmDumpFnPtr)(CsrWifiFsmContext *context, void *fsmData);
193#endif
194
195/**
196 * @brief
197 * Event ID to transition function entry
198 *
199 * @par Description
200 * Event ID to Transition Entry in a state table.
201 */
202typedef struct
203{
204    u32 eventid;
205    CsrWifiFsmTransitionFnPtr transition;
206#ifdef CSR_LOG_ENABLE
207    const char *transitionName;
208#endif
209} CsrWifiFsmEventEntry;
210
211/**
212 * @brief
213 * Single State's Transition Table
214 *
215 * @par Description
216 * Stores Data for a single State's event to
217 * transition functions mapping
218 */
219typedef struct
220{
221    const u8 numEntries;
222    const u8 saveAll;
223    const CsrWifiFsmEventEntry *eventEntryArray; /* array of transition function pointers for state */
224#ifdef CSR_LOG_ENABLE
225    u16 stateNumber;
226    const char *stateName;
227#endif
228} CsrWifiFsmTableEntry;
229
230/**
231 * @brief
232 * Process State Transtion table
233 *
234 * @par Description
235 * Stores Data for a processes State to transition table
236 */
237typedef struct
238{
239    u16 numStates; /* number of states */
240    const CsrWifiFsmTableEntry *aStateEventMatrix; /* state event matrix */
241} CsrWifiFsmTransitionFunctionTable;
242
243/**
244 * @brief
245 * Const Process definition
246 *
247 * @par Description
248 * Constant process specification.
249 * This is ALL the non dynamic data that defines
250 * a process.
251 */
252typedef struct
253{
254    const char *processName;
255    const u32 processId;
256    const CsrWifiFsmTransitionFunctionTable transitionTable;
257    const CsrWifiFsmTableEntry unhandledTransitions;
258    const CsrWifiFsmTableEntry ignoreFunctions;
259    const CsrWifiFsmProcEntryFnPtr entryFn;
260    const CsrWifiFsmProcResetFnPtr resetFn;
261#ifdef CSR_WIFI_FSM_DUMP_ENABLE
262    const CsrWifiFsmDumpFnPtr dumpFn; /* Called to dump fsm specific trace if not NULL */
263#endif
264} CsrWifiFsmProcessStateMachine;
265
266#ifdef CSR_WIFI_FSM_DUMP_ENABLE
267/**
268 * @brief
269 * Storage for state transition info
270 */
271typedef struct
272{
273    u16 transitionNumber;
274    CsrWifiFsmEvent event;
275    u16 fromState;
276    u16 toState;
277    CsrWifiFsmTransitionFnPtr transitionFn;
278    u16 transitionCount; /* number consecutive of times this transition was seen */
279#ifdef CSR_LOG_ENABLE
280    const char *transitionName;
281#endif
282} CsrWifiFsmTransitionRecord;
283
284/**
285 * @brief
286 * Storage for the last state X transitions
287 */
288typedef struct
289{
290    u16 numTransitions;
291    CsrWifiFsmTransitionRecord records[CSR_WIFI_FSM_MAX_TRANSITION_HISTORY];
292} CsrWifiFsmTransitionRecords;
293#endif
294
295/**
296 * @brief
297 * Dynamic Process data
298 *
299 * @par Description
300 * Dynamic process data that is used to keep track of the
301 * state and data for a process instance
302 */
303typedef struct
304{
305    const CsrWifiFsmProcessStateMachine *fsmInfo; /* state machine info that is constant regardless of context */
306    u16 instanceId; /* Runtime process id */
307    u16 state; /* Current state */
308    void *params; /* Instance user data */
309    CsrWifiFsmEventList savedEventQueue; /* The saved event queue */
310    struct CsrWifiFsmInstanceEntry *subFsm; /* Sub Fsm instance data */
311    struct CsrWifiFsmInstanceEntry *subFsmCaller; /* The Fsm instance that created the SubFsm and should be used for callbacks*/
312#ifdef CSR_WIFI_FSM_DUMP_ENABLE
313    CsrWifiFsmTransitionRecords transitionRecords; /* Last X transitions in the FSM */
314#endif
315} CsrWifiFsmInstanceEntry;
316
317/**
318 * @brief
319 * OnCreate Callback Function Pointer
320 *
321 * @par Description
322 * Called when an fsm is created.
323 *
324 * @param[in] extContext : External context
325 * @param[in] instance : FSM instance
326 *
327 * @return
328 * void
329 */
330typedef void (*CsrWifiFsmOnCreateFnPtr)(void *extContext, const CsrWifiFsmInstanceEntry *instance);
331
332/**
333 * @brief
334 * OnTransition Callback Function Pointer
335 *
336 * @par Description
337 * Called when an event is processed by a fsm
338 *
339 * @param[in] extContext : External context
340 * @param[in] eventEntryArray : Entry data
341 * @param[in] event : Event
342 *
343 * @return
344 * void
345 */
346typedef void (*CsrWifiFsmOnTransitionFnPtr)(void *extContext, const CsrWifiFsmEventEntry *eventEntryArray, const CsrWifiFsmEvent *event);
347
348/**
349 * @brief
350 * OnStateChange Callback Function Pointer
351 *
352 * @par Description
353 * Called when CsrWifiFsmNextState is called
354 *
355 * @param[in] extContext : External context
356 *
357 * @return
358 * void
359 */
360typedef void (*CsrWifiFsmOnStateChangeFnPtr)(void *extContext, u16 nextstate);
361
362/**
363 * @brief
364 * OnIgnore,OnError or OnInvalid Callback Function Pointer
365 *
366 * @par Description
367 * Called when an event is processed by a fsm
368 *
369 * @param[in] extContext : External context
370 * @param[in] event : Event
371 *
372 * @return
373 * void
374 */
375typedef void (*CsrWifiFsmOnEventFnPtr)(void *extContext, const CsrWifiFsmEvent *event);
376
377/**
378 * @brief
379 * Toplevel FSM context data
380 *
381 * @par Description
382 * Holds ALL FSM static and dynamic data for a FSM
383 */
384struct CsrWifiFsmContext
385{
386    CsrWifiFsmEventList eventQueue; /* The internal event queue */
387    CsrWifiFsmEventList externalEventQueue; /* The external event queue */
388#ifdef CSR_WIFI_FSM_MUTEX_ENABLE
389    CsrMutexHandle externalEventQueueLock; /* The external event queue mutex */
390#endif
391    u32 timeOffset; /* Amount to adjust the TimeOfDayMs by */
392    CsrWifiFsmTimerList timerQueue; /* The internal timer queue */
393    u8 useTempSaveList; /* Should the temp save list be used */
394    CsrWifiFsmEventList tempSaveList; /* The temp save event queue */
395    CsrWifiFsmEvent *eventForwardedOrSaved; /* The event that was forwarded or Saved */
396    u16 maxProcesses; /* Size of instanceArray */
397    u16 numProcesses; /* Current number allocated in instanceArray */
398    CsrWifiFsmInstanceEntry *instanceArray; /* Array of processes for this component */
399    CsrWifiFsmInstanceEntry *ownerInstance; /* The Process that owns currentInstance (SubFsm support) */
400    CsrWifiFsmInstanceEntry *currentInstance; /* Current Process that is executing */
401    CsrWifiFsmExternalWakupCallbackPtr externalEventFn; /* External event Callback */
402    CsrWifiFsmOnEventFnPtr appIgnoreCallback; /* Application Ignore event Callback */
403    CsrWifiFsmDestLookupCallbackPtr appEvtDstCallback; /* Application Lookup event Destination Function*/
404
405    void *applicationContext; /* Internal fsm application context */
406    void *externalContext; /* External context (set by the user of the fsm)*/
407    CsrLogTextTaskId loggingTaskId; /* Task Id to use in any logging output */
408
409#ifndef CSR_WIFI_FSM_SCHEDULER_DISABLED
410    CsrSchedTid schedTimerId; /* Scheduler TimerId for use in Scheduler Tasks */
411    u32 schedTimerNexttimeoutMs; /* Next timeout time for the current timer */
412#endif
413
414#ifdef CSR_WIFI_FSM_MUTEX_ENABLE
415#ifdef CSR_WIFI_FSM_TRANSITION_LOCK
416    CsrMutexHandle transitionLock; /* Lock when calling transition functions */
417#endif
418#endif
419
420#ifdef CSR_LOG_ENABLE
421    CsrWifiFsmOnCreateFnPtr onCreate; /* Debug Transition Callback */
422    CsrWifiFsmOnTransitionFnPtr onTransition; /* Debug Transition Callback */
423    CsrWifiFsmOnTransitionFnPtr onUnhandedCallback; /* Unhanded event Callback */
424    CsrWifiFsmOnStateChangeFnPtr onStateChange; /* Debug State Change Callback */
425    CsrWifiFsmOnEventFnPtr onIgnoreCallback; /* Ignore event Callback */
426    CsrWifiFsmOnEventFnPtr onSaveCallback; /* Save event Callback */
427    CsrWifiFsmOnEventFnPtr onErrorCallback; /* Error event Callback */
428    CsrWifiFsmOnEventFnPtr onInvalidCallback; /* Invalid event Callback */
429#endif
430#ifdef CSR_WIFI_FSM_DUMP_ENABLE
431    u16 masterTransitionNumber; /* Increments on every transition */
432#endif
433};
434
435
436#ifdef __cplusplus
437}
438#endif
439
440#endif /* CSR_WIFI_FSM_TYPES_H */
441

Archive Download this file



interactive