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