drivers/staging/csr/csr_sched.h

   1 #ifndef CSR_SCHED_H__
   2 #define CSR_SCHED_H__
   3 /*****************************************************************************
   4
   5             (c) Cambridge Silicon Radio Limited 2010
   6             All rights reserved and confidential information of CSR
   7
   8             Refer to LICENSE.txt included with this source for details
   9             on the license terms.
  10
  11 *****************************************************************************/
  12 #include "csr_types.h"
  13 #include "csr_time.h"
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif
  18
  19 /* An identifier issued by the scheduler. */
  20 typedef u32 CsrSchedIdentifier;
  21
  22 /* A task identifier */
  23 typedef u16 CsrSchedTaskId;
  24
  25 /* A queue identifier */
  26 typedef u16 CsrSchedQid;
  27 #define CSR_SCHED_QID_INVALID     ((CsrSchedQid) 0xFFFF)
  28
  29 /* A message identifier */
  30 typedef CsrSchedIdentifier CsrSchedMsgId;
  31
  32 /* A timer event identifier */
  33 typedef CsrSchedIdentifier CsrSchedTid;
  34 #define CSR_SCHED_TID_INVALID     ((CsrSchedTid) 0)
  35
  36 /* Scheduler entry functions share this structure */
  37 typedef void (*schedEntryFunction_t)(void **inst);
  38
  39 /* Time constants. */
  40 #define CSR_SCHED_TIME_MAX                ((CsrTime) 0xFFFFFFFF)
  41 #define CSR_SCHED_MILLISECOND             ((CsrTime) (1000))
  42 #define CSR_SCHED_SECOND                  ((CsrTime) (1000 * CSR_SCHED_MILLISECOND))
  43 #define CSR_SCHED_MINUTE                  ((CsrTime) (60 * CSR_SCHED_SECOND))
  44
  45 /* Queue and primitive that identifies the environment */
  46 #define CSR_SCHED_TASK_ID        0xFFFF
  47 #define CSR_SCHED_PRIM                   (CSR_SCHED_TASK_ID)
  48 #define CSR_SCHED_EXCLUDED_MODULE_QUEUE      0xFFFF
  49
  50 /*
  51  * Background interrupt definitions
  52  */
  53 typedef u16 CsrSchedBgint;
  54 #define CSR_SCHED_BGINT_INVALID ((CsrSchedBgint) 0xFFFF)
  55
  56 typedef void (*CsrSchedBgintHandler)(void *);
  57
  58 /*----------------------------------------------------------------------------*
  59  *  NAME
  60  *      CsrSchedBgintReg
  61  *
  62  *  DESCRIPTION
  63  *      Register a background interrupt handler function with the scheduler.
  64  *        When CsrSchedBgint() is called from the foreground (e.g. an interrupt
  65  *        routine) the registered function is called.
  66  *
  67  *        If "cb" is null then the interrupt is effectively disabled. If a
  68  *        no bgints are available, CSR_SCHED_BGINT_INVALID is returned, otherwise
  69  *        a CsrSchedBgint value is returned to be used in subsequent calls to
  70  *        CsrSchedBgint().  id is a possibly NULL identifier used for logging
  71  *        purposes only.
  72  *
  73  *  RETURNS
  74  *      CsrSchedBgint -- CSR_SCHED_BGINT_INVALID denotes failure to obtain a CsrSchedBgintSet.
  75  *
  76  *----------------------------------------------------------------------------*/
  77 CsrSchedBgint CsrSchedBgintReg(CsrSchedBgintHandler cb,
  78     void *context,
  79     const char *id);
  80
  81 /*----------------------------------------------------------------------------*
  82  *  NAME
  83  *      CsrSchedBgintUnreg
  84  *
  85  *  DESCRIPTION
  86  *      Unregister a background interrupt handler function.
  87  *
  88  *      ``irq'' is a background interrupt handle previously obtained
  89  *      from a call to CsrSchedBgintReg().
  90  *
  91  *  RETURNS
  92  *      void.
  93  *
  94  *----------------------------------------------------------------------------*/
  95 void CsrSchedBgintUnreg(CsrSchedBgint bgint);
  96
  97 /*----------------------------------------------------------------------------*
  98  *  NAME
  99  *      CsrSchedBgintSet
 100  *
 101  *  DESCRIPTION
 102  *      Set background interrupt.
 103  *
 104  *  RETURNS
 105  *      void.
 106  *
 107  *----------------------------------------------------------------------------*/
 108 void CsrSchedBgintSet(CsrSchedBgint bgint);
 109
 110 /*----------------------------------------------------------------------------*
 111  *  NAME
 112  *      CsrSchedMessagePut
 113  *
 114  *  DESCRIPTION
 115  *      Sends a message consisting of the integer "mi" and the void * pointer
 116  *      "mv" to the message queue "q".
 117  *
 118  *      "mi" and "mv" are neither inspected nor changed by the scheduler - the
 119  *      task that owns "q" is expected to make sense of the values. "mv" may
 120  *      be null.
 121  *
 122  *  NOTE
 123  *      If "mv" is not null then it will typically be a chunk of CsrPmemAlloc()ed
 124  *      memory, though there is no need for it to be so. Tasks should normally
 125  *      obey the convention that when a message built with CsrPmemAlloc()ed memory
 126  *      is given to CsrSchedMessagePut() then ownership of the memory is ceded to the
 127  *      scheduler - and eventually to the recipient task. I.e., the receiver of
 128  *      the message will be expected to CsrPmemFree() the message storage.
 129  *
 130  *  RETURNS
 131  *      void.
 132  *
 133  *----------------------------------------------------------------------------*/
 134 #if defined(CSR_LOG_ENABLE) && defined(CSR_LOG_INCLUDE_FILE_NAME_AND_LINE_NUMBER)
 135 void CsrSchedMessagePutStringLog(CsrSchedQid q,
 136     u16 mi,
 137     void *mv,
 138     u32 line,
 139     const char *file);
 140 #define CsrSchedMessagePut(q, mi, mv) CsrSchedMessagePutStringLog((q), (mi), (mv), __LINE__, __FILE__)
 141 #else
 142 void CsrSchedMessagePut(CsrSchedQid q,
 143     u16 mi,
 144     void *mv);
 145 #endif
 146
 147 /*----------------------------------------------------------------------------*
 148  *  NAME
 149  *      CsrSchedMessageBroadcast
 150  *
 151  *  DESCRIPTION
 152  *      Sends a message to all tasks.
 153  *
 154  *      The user must supply a "factory function" that is called once
 155  *      for every task that exists. The "factory function", msg_build_func,
 156  *      must allocate and initialise the message and set the msg_build_ptr
 157  *      to point to the message when done.
 158  *
 159  *  NOTE
 160  *      N/A
 161  *
 162  *  RETURNS
 163  *      void
 164  *
 165  *----------------------------------------------------------------------------*/
 166 #if defined(CSR_LOG_ENABLE) && defined(CSR_LOG_INCLUDE_FILE_NAME_AND_LINE_NUMBER)
 167 void CsrSchedMessageBroadcastStringLog(u16 mi,
 168     void *(*msg_build_func)(void *),
 169     void *msg_build_ptr,
 170     u32 line,
 171     const char *file);
 172 #define CsrSchedMessageBroadcast(mi, fn, ptr) CsrSchedMessageBroadcastStringLog((mi), (fn), (ptr), __LINE__, __FILE__)
 173 #else
 174 void CsrSchedMessageBroadcast(u16 mi,
 175     void *(*msg_build_func)(void *),
 176     void *msg_build_ptr);
 177 #endif
 178
 179 /*----------------------------------------------------------------------------*
 180  *  NAME
 181  *      CsrSchedMessageGet
 182  *
 183  *  DESCRIPTION
 184  *      Obtains a message from the message queue belonging to the calling task.
 185  *      The message consists of one or both of a u16 and a void *.
 186  *
 187  *  RETURNS
 188  *      CsrBool - TRUE if a message has been obtained from the queue, else FALSE.
 189  *      If a message is taken from the queue, then "*pmi" and "*pmv" are set to
 190  *      the "mi" and "mv" passed to CsrSchedMessagePut() respectively.
 191  *
 192  *      "pmi" and "pmv" can be null, in which case the corresponding value from
 193  *      them message is discarded.
 194  *
 195  *----------------------------------------------------------------------------*/
 196 CsrBool CsrSchedMessageGet(u16 *pmi, void **pmv);
 197
 198 /*----------------------------------------------------------------------------*
 199  *  NAME
 200  *      CsrSchedTimerSet
 201  *
 202  *  DESCRIPTION
 203  *      Causes the void function "fn" to be called with the arguments
 204  *      "fniarg" and "fnvarg" after "delay" has elapsed.
 205  *
 206  *      "delay" must be less than half the range of a CsrTime.
 207  *
 208  *      CsrSchedTimerSet() does nothing with "fniarg" and "fnvarg" except
 209  *      deliver them via a call to "fn()".   (Unless CsrSchedTimerCancel()
 210  *      is used to prevent delivery.)
 211  *
 212  *  NOTE
 213  *      The function will be called at or after "delay"; the actual delay will
 214  *      depend on the timing behaviour of the scheduler's tasks.
 215  *
 216  *  RETURNS
 217  *      CsrSchedTid - A timed event identifier, can be used in CsrSchedTimerCancel().
 218  *
 219  *----------------------------------------------------------------------------*/
 220 #if defined(CSR_LOG_ENABLE) && defined(CSR_LOG_INCLUDE_FILE_NAME_AND_LINE_NUMBER)
 221 CsrSchedTid CsrSchedTimerSetStringLog(CsrTime delay,
 222     void (*fn)(u16 mi, void *mv),
 223     u16 fniarg,
 224     void *fnvarg,
 225     u32 line,
 226     const char *file);
 227 #define CsrSchedTimerSet(d, fn, fni, fnv) CsrSchedTimerSetStringLog((d), (fn), (fni), (fnv), __LINE__, __FILE__)
 228 #else
 229 CsrSchedTid CsrSchedTimerSet(CsrTime delay,
 230     void (*fn)(u16 mi, void *mv),
 231     u16 fniarg,
 232     void *fnvarg);
 233 #endif
 234
 235 /*----------------------------------------------------------------------------*
 236  *  NAME
 237  *      CsrSchedTimerCancel
 238  *
 239  *  DESCRIPTION
 240  *      Attempts to prevent the timed event with identifier "eventid" from
 241  *      occurring.
 242  *
 243  *  RETURNS
 244  *      CsrBool - TRUE if cancelled, FALSE if the event has already occurred.
 245  *
 246  *----------------------------------------------------------------------------*/
 247 #if defined(CSR_LOG_ENABLE) && defined(CSR_LOG_INCLUDE_FILE_NAME_AND_LINE_NUMBER)
 248 CsrBool CsrSchedTimerCancelStringLog(CsrSchedTid eventid,
 249     u16 *pmi,
 250     void **pmv,
 251     u32 line,
 252     const char *file);
 253 #define CsrSchedTimerCancel(e, pmi, pmv) CsrSchedTimerCancelStringLog((e), (pmi), (pmv), __LINE__, __FILE__)
 254 #else
 255 CsrBool CsrSchedTimerCancel(CsrSchedTid eventid,
 256     u16 *pmi,
 257     void **pmv);
 258 #endif
 259
 260 /*----------------------------------------------------------------------------*
 261  *  NAME
 262  *      CsrSchedTaskQueueGet
 263  *
 264  *  DESCRIPTION
 265  *      Return the queue identifier for the currently running queue
 266  *
 267  *  RETURNS
 268  *      CsrSchedQid - The current task queue identifier, or 0xFFFF if not available.
 269  *
 270  *----------------------------------------------------------------------------*/
 271 CsrSchedQid CsrSchedTaskQueueGet(void);
 272
 273
 274 /*----------------------------------------------------------------------------*
 275  *  NAME
 276  *      CsrSchedTaskQueueGet
 277  *
 278  *  DESCRIPTION
 279  *      Return the queue identifier for the currently running queue
 280  *
 281  *  RETURNS
 282  *      char - The current task queue identifier, or 0xFFFF if not available.
 283  *
 284  *----------------------------------------------------------------------------*/
 285 char* CsrSchedTaskNameGet(CsrSchedQid );
 286
 287
 288 #ifdef __cplusplus
 289 }
 290 #endif
 291
 292 #endif