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