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