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
  15 extern "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  */
  38 typedef 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  */
  53 typedef 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  */
  70 typedef 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  */
  93 typedef 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  */
 107 typedef 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  */
 127 typedef 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  */
 144 typedef 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  */
 159 typedef 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  */
 175 typedef 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  */
 192 typedef 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  */
 202 typedef 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  */
 219 typedef 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  */
 237 typedef 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  */
 252 typedef 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  */
 271 typedef 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  */
 288 typedef 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  */
 303 typedef 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  */
 330 typedef 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  */
 346 typedef 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  */
 360 typedef 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  */
 375 typedef 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  */
 384 struct 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 */