/*****************************************************************************
* All the timer module public interface are described in this header file.
*
* Important: 
* BUILD OPTIONS:
* Use gInterruptDrivenTimers_d build option for interrupt based Software timer.
* Use gPolledTimers_d build option for polling based Software timer.
* The library has to be rebuild effect the change in compiler option.
*
* NUMBER OF SOFTWARE TIMERS:
* Any number of timer can be supported.It is compile time value.
* (TMR_Interface.h).
* Needs to recompile the TMR.lib for change in software timers.
*
* (c) Copyright 2005, Freescale, Inc. All rights reserved.
*
* Freescale Semiconductor Confidential Proprietary
*
* No part of this document must be reproduced in any form - including copied,
* transcribed, printed or by any electronic means - without specific written
* permission from Freescale Semiconductor Denmark A/S.
*****************************************************************************/
#ifndef _TIMER_INTERFACE_H
#define _TIMER_INTERFACE_H

#include "EmbeddedTypes.h"
#include "TS_Interface.h"

/*****************************************************************************
******************************************************************************
* Public macros
******************************************************************************
*****************************************************************************/

/*****************************************************************************
* User must specify the number of timers required here.
* Update gNumberOfApplicationTimers_c for number of application timers.
*
* Example to reserve three timers for application
* #define gNumberOfApplicationTimers_c 3 
* 
*****************************************************************************/
#define gNumberOfApplicationTimers_c 6

/*****************************************************************************
* Application must use gApplicationTimerIDOffset_c for application timer ID.
* Example with gNumberOfApplicationTimers_c set to 3 application 
* timer ID will be 
* gApplicationTimerIDOffset_c, 
* gApplicationTimerIDOffset_c+1
* gApplicationTimerIDOffset_c+2
* 
*****************************************************************************/
#define gApplicationTimerIDOffset_c gNumberOfBeeStackTimers_c

/*****************************************************************************
* Use either gInterruptDrivenTimers_d or gPolledTimers_d
*****************************************************************************/

#ifndef gPolledTimers_d /*default interrupt timer is chosen       */
/*****************************************************************************
* Controls whether interrupt/poll timer is integrated in the 		
* BeeStack.                                                      
*                                                                
* Valid range:                                                   
*  1           = enabled the timer specified                     
*  0		        = disables the timer specified                    
*****************************************************************************/
  #define gInterruptDrivenTimers_d	1
  #define gPolledTimers_d	0
#else
  #define gInterruptDrivenTimers_d	0
  /*"gPolledTimers_d=1" has to be given in CW compiler options to 
  use polled timer.*/
#endif

/*
* Error directive if timer mode symbols are not used properly
*/
#if (gInterruptDrivenTimers_d) && (gPolledTimers_d) /*both modes are defined*/
 #error "Define either gInterruptDrivenTimers_d or gPolledTimers_d"
#endif

/*****************************************************************************
******************************************************************************
* Private macros
******************************************************************************
*****************************************************************************/
/* 
Number of timer supported,can be any  number of timers less than 255 
Note: 0 to 19 timer ID's used by BeeStack. So do not use those timer ID's.
17,18,19 (reserved for BeeStack)
timer ID 20 onwards available for applications.
*/
#define gNumberOfBeeStackTimers_c  19
#define gSoftwareTimerCount_c  gNumberOfBeeStackTimers_c + \
                               gNumberOfApplicationTimers_c

#define gNormalTimer_c    0    /*  Normal Timer  */ 
#define gIntervalTimer_c  1   /*  Interval Timer  */ 

/* TMR_Task events. This event ID is posted by TMR_InterruptHandler and
  consumed by TMR_Task  */
#define gTMR_EventTimeOut_c (1<<0)
/*****************************************************************************
******************************************************************************
* Public type definitions
******************************************************************************
*****************************************************************************/
/*  This typedef for timer_t. At the interace level TMR module accepts 
    timeout in milli seconds. This require a 32 bit variable. */ 
    
typedef uint32_t timer_t;

/*****************************************************************************
******************************************************************************
* Private prototypes, Used by TMR public interface functions.Do not use these
* functions directly.
******************************************************************************
*****************************************************************************/
void TMR_SoftTimerInit
  (
    uint8_t timerType,
    uint8_t timerID, 
    timer_t timerOutMilliSec, 
    void(*pTimeoutHandler)(uint8_t)
  );


/*****************************************************************************
******************************************************************************
* Public prototypes
******************************************************************************
*****************************************************************************/
/*****************************************************************************
* Default timeout handler.This function does nothing.
*
* Interface assumptions:
*
* Return value:
* None
*
* Revison history:
* date    Author  Comments
* ------  ------  --------
* 071205  LS      Created
*****************************************************************************/
void TMR_DefaultTimeoutHandler(uint8_t timerId);

/*****************************************************************************
* Initialize the timer in capture and compare mode. Generates interrupt only
* if interrupt based timer is used. 
*														
* Interface assumptions:
*
* Arguments:
* None
*
* Return value:
* No return value provided. 
*
* Revison history:
*
* date    Author   Comments
* ------  -------  --------
* 071205  LS       Created
*****************************************************************************/
void TMR_Init (void);


/*****************************************************************************
* Stops the timer specified. 
*
* Interface assumptions:
*
* Arguments:
* Timer to stop specified by TimerID.
*
* Return value:
* No return value provided. 
*
* Revison history:
*
* date     Author   Comments
* ------   -------  --------
* 071205   LS       Created
*****************************************************************************/
void TMR_StopTimer(uint8_t timerID); 

/*****************************************************************************
* This is a macro.
* Stops the timer specified. This can be used to stop both Interval as well as
* ordinary timer.
*
* Interface assumptions:
*
* Arguments:
* Timer to stop specified by TimerID.
*
* Return value:
* No return value provided. 
*
* Revison history:
*
* date     Author   Comments
* ------   -------  --------
* 071205   LS       Created
*****************************************************************************/
#define TMR_StopInterval(timerID) TMR_StopTimer(timerID)


/*****************************************************************************
* Starts a software timer specified by TimerID with the specified attributes.
* Once the time expires the timer can be again re-used.
*
* Interface assumptions:
* Assumes the specified timer is not being used. If used timer is specified
* then it will initialize the timer with new attributes.
*
* Arguments:
* timerID = Software Timer ID (IN)
* timeOutDurationInMs = Time Out value (IN)
* pTimeoutHandler = function pointer to callback function
*
* Return value:
* No return value provided. 
*
* Revison history:
*
* date     Author   Comments
* ------   -------  --------
* 071205   LS       Created
*
*****************************************************************************/
#define TMR_StartTimer(timerID, timeOutDurationInMs,pTimeoutHandler) \
  TMR_SoftTimerInit(gNormalTimer_c,timerID,timeOutDurationInMs, pTimeoutHandler);
  

/*****************************************************************************
* Starts a software interval timer specified by TimerID with the specified
* attributes.The timer executes the call back function periodically specified
* by timeOut.
*
* Interface assumptions:
*
* Arguments:
* timerID = Software Timer ID (IN)
* timeOutDurationInMs = Time Out value
* pTimeoutHandler = function pointer to callback function
*
* Return value:
* No return value provided. 
*
* Revison history:
*
* date     Author   Comments
* ------   -------  --------
* 071205   LS       Created
*****************************************************************************/
#define TMR_StartInterval(timerID, timeOutDurationInMs, pTimeoutHandler) \
  TMR_SoftTimerInit(gIntervalTimer_c,timerID,timeOutDurationInMs, pTimeoutHandler)
  

/*****************************************************************************
* This function will return the status of software timer specified by timerID. 
*
* Arguments:
* Timer id whose status has to be known
*
* Interface assumptions:
*
* Return value:
* Return TRUE if the timer is expired else FALSE.
*
* Revison history:
*
* date     Author   Comments
* ------   -------  --------
* 071205   LS     Created
*****************************************************************************/
bool_t TMR_TimerStatus(uint8_t timerID);


/*****************************************************************************
* If poll based timer is used this function has be called frequently in the 
* main while loop.
*
* Interface assumptions:
* This accepts reasonable tolerance and this depends on how often TMR_Main is
* called. Should be called atleast once in 4 mSec.
*
* In task scheduler environment poll timer cannot be used. Task scheduler
* based projects should use interrupt based timer.
*
* The implementation of TMR_Main and TMR_InterruptHandler are same.
*
* Return value:
* No return value provided. 
*
* Revison history:
*
* date     Author   Comments
* ------   -------  --------
* 071205   LS       Created
*****************************************************************************/
void TMR_Main(void);

/*****************************************************************************
* Interrupt driven timer should use this routine as timer ISR. This ISR will
* be called when a timer timeout happens.
*
* Interface assumptions:
* In task scheduler environment poll timer cannot be used. Task scheduler
* based projects should use interrupt based timer.
*
* The implementation of TMR_Main and TMR_InterruptHandler are same.
*
* Return value:
* No return value provided. 
*
* Revison history:
*
* date     Author   Comments
* ------   -------  --------
* 071205   LS       Created
*****************************************************************************/
__interrupt void TMR_InterruptHandler(void);

/*****************************************************************************
* This function updates the expired timers.Calls the callback function
*
* Interface assumptions:
* event_t is 16bit unsigned integer.in Task scheduler environment scheduler
* will call this task with all the events. Events are bit masks.
* Return value:
* None
*
* Revison history:
*
* date     Author   Comments
* ------   -------  --------
* 071205   LS       Created
*****************************************************************************/
void TMR_Task(event_t events);


/*****************************************************************************
* This function can be used to check whether a particular timer is being
* used or not
*
* Interface assumptions:
*
* Return value:
* TRUE : TimerID timer is available
* FALSE : TimerId timer is in use.
*
* Revison history:
*
* date     Author   Comments
* ------   -------  --------
* 071205   LS       Created
*****************************************************************************/
bool_t TMR_IsTimerOff(uint8_t timerID);


/*****************************************************************************
* This is used to check whether timer module is running or stopped.
* This function is used by system power management to decide whether to enter 
* light sleep or deep sleep mode.
*
* Interface assumptions:
*
* Return value:
* Return TRUE if no timer running else FALSE.
*
* Revison history:
* date     Author   Comments
* ------   -------  --------
* 25112005 ANP  Created
*****************************************************************************/
bool_t TMR_AreAllTimersOff(void);


/*****************************************************************************
******************************************************************************
* Public memory declarations
******************************************************************************
*****************************************************************************/

/*****************************************************************************
******************************************************************************
* Public functions
******************************************************************************
*****************************************************************************/
/* None */

#endif _TIMER_INTERFACE_H