drivers/staging/wilc1000/wilc_timer.h

   1 #ifndef __WILC_TIMER_H__
   2 #define __WILC_TIMER_H__
   3
   4 /*!
   5  *  @file       wilc_timer.h
   6  *  @brief      Timer (One Shot and Periodic) OS wrapper functionality
   7  *  @author     syounan
   8  *  @sa         wilc_oswrapper.h top level OS wrapper file
   9  *  @date       16 Aug 2010
  10  *  @version    1.0
  11  */
  12
  13 typedef void (*tpfWILC_TimerFunction)(void *);
  14
  15 /*!
  16  *  @struct             tstrWILC_TimerAttrs
  17  *  @brief              Timer API options
  18  *  @author             syounan
  19  *  @date               16 Aug 2010
  20  *  @version            1.0
  21  */
  22 typedef struct {
  23         /* a dummy member to avoid compiler errors*/
  24         u8 dummy;
  25 } tstrWILC_TimerAttrs;
  26
  27 /*!
  28  *  @brief      Creates a new timer
  29  *  @details    Timers are a useful utility to execute some callback function
  30  *              in the future.
  31  *              A timer object has 3 states : IDLE, PENDING and EXECUTING
  32  *              IDLE : initial timer state after creation, no execution for the
  33  *              callback function is planned
  34  *              PENDING : a request to execute the callback function is made
  35  *              using WILC_TimerStart.
  36  *              EXECUTING : the timer has expired and its callback is now
  37  *              executing, when execution is done the timer returns to PENDING
  38  *              if the feature CONFIG_WILC_TIMER_PERIODIC is enabled and
  39  *              the flag tstrWILC_TimerAttrs.bPeriodicTimer is set. otherwise the
  40  *              timer will return to IDLE
  41  *  @param[out] pHandle handle to the newly created timer object
  42  *  @param[in]  pfEntry pointer to the callback function to be called when the
  43  *              timer expires
  44  *              the underlaying OS may put many restrictions on what can be
  45  *              called inside a timer's callback, as a general rule no blocking
  46  *              operations (IO or semaphore Acquision) should be perfomred
  47  *              It is recommended that the callback will be as short as possible
  48  *              and only flags other threads to do the actual work
  49  *              also it should be noted that the underlaying OS maynot give any
  50  *              guarentees on which contect this callback will execute in
  51  *  @param[in]  pstrAttrs Optional attributes, NULL for default
  52  *  @return     Error code indicating sucess/failure
  53  *  @sa         WILC_TimerAttrs
  54  *  @author     syounan
  55  *  @date       16 Aug 2010
  56  *  @version    1.0
  57  */
  58 WILC_ErrNo WILC_TimerCreate(WILC_TimerHandle *pHandle,
  59                             tpfWILC_TimerFunction pfCallback, tstrWILC_TimerAttrs *pstrAttrs);
  60
  61
  62 /*!
  63  *  @brief      Destroys a given timer
  64  *  @details    This will destroy a given timer freeing any resources used by it
  65  *              if the timer was PENDING Then must be cancelled as well(i.e.
  66  *              goes to IDLE, same effect as calling WILC_TimerCancel first)
  67  *              if the timer was EXECUTING then the callback will be allowed to
  68  *              finish first then all resources are freed
  69  *  @param[in]  pHandle handle to the timer object
  70  *  @param[in]  pstrAttrs Optional attributes, NULL for default
  71  *  @return     Error code indicating sucess/failure
  72  *  @sa         WILC_TimerAttrs
  73  *  @author     syounan
  74  *  @date       16 Aug 2010
  75  *  @version    1.0
  76  */
  77 WILC_ErrNo WILC_TimerDestroy(WILC_TimerHandle *pHandle,
  78                              tstrWILC_TimerAttrs *pstrAttrs);
  79
  80 /*!
  81  *  @brief      Starts a given timer
  82  *  @details    This function will move the timer to the PENDING state until the
  83  *              given time expires (in msec) then the callback function will be
  84  *              executed (timer in EXECUTING state) after execution is dene the
  85  *              timer either goes to IDLE (if bPeriodicTimer==WILC_FALSE) or
  86  *              PENDING with same timeout value (if bPeriodicTimer==WILC_TRUE)
  87  *  @param[in]  pHandle handle to the timer object
  88  *  @param[in]  u32Timeout timeout value in msec after witch the callback
  89  *              function will be executed. Timeout value of 0 is not allowed for
  90  *              periodic timers
  91  *  @param[in]  pstrAttrs Optional attributes, NULL for default,
  92  *              set bPeriodicTimer to run this timer as a periodic timer
  93  *  @return     Error code indicating sucess/failure
  94  *  @sa         WILC_TimerAttrs
  95  *  @author     syounan
  96  *  @date       16 Aug 2010
  97  *  @version    1.0
  98  */
  99 WILC_ErrNo WILC_TimerStart(WILC_TimerHandle *pHandle, WILC_Uint32 u32Timeout, void *pvArg,
 100                            tstrWILC_TimerAttrs *pstrAttrs);
 101
 102
 103 /*!
 104  *  @brief      Stops a given timer
 105  *  @details    This function will move the timer to the IDLE state cancelling
 106  *              any sheduled callback execution.
 107  *              if this function is called on a timer already in the IDLE state
 108  *              it will have no effect.
 109  *              if this function is called on a timer in EXECUTING state
 110  *              (callback has already started) it will wait until executing is
 111  *              done then move the timer to the IDLE state (which is trivial
 112  *              work if the timer is non periodic)
 113  *  @param[in]  pHandle handle to the timer object
 114  *  @param[in]  pstrAttrs Optional attributes, NULL for default,
 115  *  @return     Error code indicating sucess/failure
 116  *  @sa         WILC_TimerAttrs
 117  *  @author     syounan
 118  *  @date       16 Aug 2010
 119  *  @version    1.0
 120  */
 121 WILC_ErrNo WILC_TimerStop(WILC_TimerHandle *pHandle,
 122                           tstrWILC_TimerAttrs *pstrAttrs);
 123
 124
 125
 126 #endif