xos_timer.h

/** @file */

// xos_timer.h - XOS Timer API interface and data structures.

// Copyright (c) 2003-2015 Cadence Design Systems, Inc.
//
// Permission is hereby granted, free of charge, to any person obtaining
// a copy of this software and associated documentation files (the
// "Software"), to deal in the Software without restriction, including
// without limitation the rights to use, copy, modify, merge, publish,
// distribute, sublicense, and/or sell copies of the Software, and to
// permit persons to whom the Software is furnished to do so, subject to
// the following conditions:
//
// The above copyright notice and this permission notice shall be included
// in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
// TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

// NOTE: Do not include this file directly in your application. Including
// xos.h will automatically include this file.


#ifndef __XOS_TIMER_H__
#define __XOS_TIMER_H__

#include "xos_types.h"

#ifdef __cplusplus
extern "C" {
#endif


//-----------------------------------------------------------------------------
///
/// Function pointer type for timer callbacks.
///
//-----------------------------------------------------------------------------
typedef void (XosTimerFunc)(void * arg);


//-----------------------------------------------------------------------------
///
/// Timer event structure. Used to track pending timer events.
///
//-----------------------------------------------------------------------------
typedef struct XosTimer {
    struct XosTimer *   next;   ///< Pointer to next event in list.
    uint64_t            when;   ///< Time (clock cycles) at which to trigger.
    uint64_t            delta;  ///< Delta for next re-trigger, 0 if none.
    XosTimerFunc *      fn;     ///< Function to call when timer expires.
    void *              arg;    ///< Argument to pass to called function.
    bool                active; ///< Set if active (in some list of events).
#if XOS_OPT_TIMER_WAIT
    XosThreadQueue      waitq;  ///< Queue of threads waiting on this timer.
#endif
#if XOS_TIMER_DEBUG
    uint32_t            signature;
#endif
} XosTimer;


//-----------------------------------------------------------------------------
// Extern declarations.
//-----------------------------------------------------------------------------

// System clock frequency in cycles per second.
extern uint32_t xos_clock_freq;


///@{
//-----------------------------------------------------------------------------
// Functions to convert from clock cycles to time units and vice versa.
//
// Note that these are integer conversions so for example a cycle count of less
// than one second will convert to zero seconds.
//-----------------------------------------------------------------------------

///  Converts CPU cycles to time in seconds.
///
///  \param     cycles          Number of CPU cycles.
///
///  \return    Equivalent number of seconds (truncated to integer).
static inline uint64_t
xos_cycles_to_secs(uint64_t cycles)
{
    return cycles / xos_clock_freq;
}

/// Converts CPU cycles to time in milliseconds.
///
///  \param     cycles          Number of CPU cycles.
///
///  \return    Equivalent number of milliseconds (truncated to integer).
static inline uint64_t
xos_cycles_to_msecs(uint64_t cycles)
{
    return (cycles * 1000) / xos_clock_freq;
}

/// Converts CPU cycles to time in microseconds.
///
///  \param     cycles          Number of CPU cycles.
///
///  \return    Equivalent number of microseconds (truncated to integer).
static inline uint64_t
xos_cycles_to_usecs(uint64_t cycles)
{
    return (cycles * 1000000) / xos_clock_freq;
}

/// Converts time in seconds to CPU cycle count.
///
///  \param     secs            Number of seconds.
///
///  \return    Equivalent number of CPU cycles.
static inline uint64_t
xos_secs_to_cycles(uint64_t secs)
{
    return secs * xos_clock_freq;
}

/// Converts time in milliseconds to CPU cycle count.
///
///  \param     msecs           Number of milliseconds.
///
///  \return    Equivalent number of CPU cycles.
static inline uint64_t
xos_msecs_to_cycles(uint64_t msecs)
{
    return (msecs * xos_clock_freq) / 1000;
}

/// Converts time in microseconds to CPU cycle count.
///
///  \param     usecs           Number of microseconds.
///
///  \return    Equivalent number of CPU cycles.
static inline uint64_t
xos_usecs_to_cycles(uint64_t usecs)
{
    return (usecs * xos_clock_freq) / 1000000;
}
///@}


//-----------------------------------------------------------------------------
///
///  Set system clock frequency. This is expected to be set only once, and only
///  if the clock frequency is not known at compile time.
///
///  \param     freq            Frequency in cycles per second.
///
///  \return    Returns nothing.
///
//-----------------------------------------------------------------------------
static inline void
xos_set_clock_freq(uint32_t freq)
{
    xos_clock_freq = freq;
}


//-----------------------------------------------------------------------------
///
///  Get current system clock frequency.
///
///  \return    Returns current system clock frequency in cycles per second.
///
//-----------------------------------------------------------------------------
static inline uint32_t
xos_get_clock_freq()
{
    return xos_clock_freq;
}


//-----------------------------------------------------------------------------
///
///  Initialize timer support and start the system timer.
///  This function must be called before calling any other timer function.
///
///  NOTE: The smaller the tick period, the more precisely delays can be
///  specified using timers.  However, we also need to make the tick period
///  large enough to allow time both to execute the tick timer interrupt handler
///  and for the application to make reasonable forward progress.  If tick_period
///  is too small, the timer interrupt may re-trigger before the timer interrupt
///  handler has returned to the application, thus keeping the processor busy in
///  constantly executing the timer interrupt handler without leaving any cycles
///  for the application. Or, the application might get some cycles but only a 
///  fraction of what is spent in the timer interrupt handler, thus severely
///  impacting application performance.
///
///  The exact number of cycles needed to execute the timer interrupt handler
///  is not specified here.  It depends on many factors (e.g. use of caches, 
///  various processor configuration options, etc) and can vary by orders of
///  magnitude.  Also note that the time to execute this handler is variable:
///  when timers expire upon a given tick timer interrupt, their respective
///  timer handler functions are called from within the interrupt handler.
///
///  \param     timer_num       Which Xtensa timer to use (0..2). This timer
///                             must exist and be configured at level 1 or at a
///                             medium-priority interrupt level (<=EXCM_LEVEL).
///                             If 'timer_num' is -1, then this function will
///                             automatically choose the highest priority timer
///                             that is suitable for use. This value will be
///                             passed to xos_system_timer_select().
///
///  \param     tick_period     Number of clock (CCOUNT) cycles between ticks.
///                             Must range between 0 and UINT32_MAX.
///                             Zero is used to specify dynamic tick (tickless)
///                             mode.
///
///  \return    Returns XOS_OK on success, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_start_system_timer(int32_t timer_num, uint32_t tick_period);


//-----------------------------------------------------------------------------
///
///  Get the timer number of the system timer. Useful mainly when XOS has been
///  allowed to choose its own timer via xos_start_system_timer(). Not valid if
///  called before the system timer has been started.
///
///  \return    Returns one of XOS_SYS_TIMER_0, XOS_SYS_TIMER_1, XOS_SYS_TIMER_2
///             or XOS_SYS_TIMER_EXTERNAL, or XOS_SYS_TIMER_NONE.
///
//-----------------------------------------------------------------------------
int32_t
xos_get_system_timer_num(void);


//-----------------------------------------------------------------------------
///
///  Initialize timer object.
///
///  \param     timer           Pointer to timer event structure.
///
///  \return    Returns nothing.
///
///  NOTE: This function should not be called on a timer object once it has 
///  been activated.
///
//-----------------------------------------------------------------------------
void xos_timer_init(XosTimer * timer);


//-----------------------------------------------------------------------------
//  Flags for xos_timer_start().
//-----------------------------------------------------------------------------
#define XOS_TIMER_DELTA         0x0000
#define XOS_TIMER_PERIODIC      0x0001
#define XOS_TIMER_ABSOLUTE      0x0002
#define XOS_TIMER_FROM_NOW      0x0000
#define XOS_TIMER_FROM_LAST     0x0010


//-----------------------------------------------------------------------------
///
///  Start the timer, and when the timer expires, call the specified function
///  (invoke (*fn)(arg)). If the timer is periodic, it will be automatically
///  restarted when it expires.
///
///  The specified timer event structure must have been initialized before
///  first use by calling xos_timer_init().
///
///  The callback function will be called in an interrupt context. Hence it is
///  NOT safe to use any coprocessors in the function, including the FPU. If a
///  coprocessor must be used, then its state must be saved and restored across
///  its use.
///
///  NOTE: If you are using the timer only to wait on (via xos_timer_wait())
///  then it is not necessary to specify a callback function. You should pass
///  NULL for the callback function and zero for the callback argument.
///
///  \param     timer           Pointer to timer event structure. Must have been
///                             initialized. May be active or not.
///
///  \param     when            When to call the function (see flags).
///
///  \param     flags           Set of option flags XOS_TIMER_* \n
///                             The following flags are mutually exclusive:
///                             - XOS_TIMER_DELTA -- when is number of cycles from
///                               [see below] (default)
///                             - XOS_TIMER_PERIODIC -- when is number of cycles
///                               from [see below], and timer continually
///                               re-triggers at that interval
///                             - XOS_TIMER_ABSOLUTE -- when is absolute value of
///                               cycle count \n
///  \n
///                             The following flags are mutually exclusive:
///                             - XOS_TIMER_FROM_NOW -- *DELTA and *PERIODIC are
///                               relative to now (default)
///                             - XOS_TIMER_FROM_LAST -- *DELTA and *PERIODIC are
///                               relative to the timer event's last specified expiry
///                               time (usually in the future if active, in the past
///                               if not, absolute 0 if was never activated).
///
///  \param     func            Function to call (called in timer interrupt context).
///                             This argument is optional. Specify NULL if no function
///                             is to be called.
///
///  \param     arg             Argument passed to callback function. Only relevant if
///                             'func' is not NULL.
///
///  \return    Returns XOS_OK on success, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_timer_start(XosTimer *     timer,
                uint64_t       when,
                uint32_t       flags,
                XosTimerFunc * func,
                void *         arg);


//-----------------------------------------------------------------------------
///
///  Stop the timer and remove it from the list of active timers. Has no effect
///  if the timer is not active. Any waiting threads are woken up.
/// 
///  The timer structure must have been initialized at least once, else its
///  contents are undefined and can lead to unpredictable results.
///
///  \param     timer           Pointer to timer object.
///
///  \return    Returns XOS_OK on success, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_timer_stop(XosTimer * timer);


//-----------------------------------------------------------------------------
///
///  Reset and restart the timer.
///
///  The timer is reset to go off at time "when" from now. If the timer was not
///  active, it will be activated. If the timer was active, it will be restarted.
///  If the timer is periodic, the period will be set to "when".
///  The timer object must have been initialized at some point before this call.
///
///  \param     timer           Pointer to timer object.
///
///  \param     when            Number of cycles from now that the timer will expire.
///
///  \return    Returns XOS_OK on success, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_timer_restart(XosTimer * timer, uint64_t when);


//-----------------------------------------------------------------------------
///
///  Check if the timer is active. The timer is active if it has been started
///  and not yet expired or canceled.
///
///  \param     timer           Pointer to timer object.
///
///  \return    Returns non-zero if the timer is active, else zero.
///
//-----------------------------------------------------------------------------
static inline int32_t
xos_timer_is_active(XosTimer * timer)
{
    return timer ? timer->active : 0;
}


//-----------------------------------------------------------------------------
///
///  Get the repeat period for a periodic timer. For a one-shot timer this will
///  return zero. The period is reported in system clock cycles.
///
///  \param     timer           Pointer to timer object.
///
///  \return    Returns period in cycles, or zero for non-periodic timers.
///
//-----------------------------------------------------------------------------
static inline uint64_t
xos_timer_get_period(XosTimer * timer)
{
    return timer ? timer->delta : 0;
}


//-----------------------------------------------------------------------------
///
///  Set the repeat period for a periodic timer. The period must be specified
///  in system clock cycles.
///
///  If the timer is active, the change in period does not take effect until 
///  the timer expires at least once after this call.
///  Note that setting a period of zero will effectively turn a periodic timer
///  into a one-shot timer. Similarly, a one-shot timer can be turned into a
///  periodic timer.
///
///  \param     timer           Pointer to timer object.
///
///  \param     period          Repeat period in system clock cycles.
///
///  \return    Returns XOS_OK on success, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_timer_set_period(XosTimer * timer, uint64_t period);


//-----------------------------------------------------------------------------
///
///  Get the current system cycle count. This accounts for the periodic rollover
///  of the 32-bit CCOUNT cycle counter and returns a 64-bit value.
///
///  \return    Returns the current system cycle count.
///
//-----------------------------------------------------------------------------
static inline uint64_t
xos_get_system_cycles(void)
{
    extern uint64_t xos_system_cycles;
    extern uint32_t xos_last_ccount;

    // xos_last_ccount was updated when xos_system_cycles was last updated.
    // We need to add in the number of cycles elapsed since then.
    return xos_system_cycles + (xos_get_ccount() - xos_last_ccount);
}


//-----------------------------------------------------------------------------
///
///  Put calling thread to sleep for at least the specified number of cycles.
///  The actual number of cycles spent sleeping may be larger depending upon
///  the granularity of the system timer. Once the specified time has elapsed
///  the thread will be woken and made ready.
///
///  \param     cycles          Number of system clock cycles to sleep.
///
///  \return    Returns XOS_OK on success, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_thread_sleep(uint64_t cycles);


//-----------------------------------------------------------------------------
///
///  Put calling thread to sleep for at least the specified number of msec.
///  The actual amount of time spent sleeping may be larger depending upon
///  the granularity of the system timer. Once the specified time has elapsed
///  the thread will be woken and made ready.
///
///  \return    msecs           The number of milliseconds to sleep.
///
///  \return    Returns XOS_OK on success, else error code.
///
//-----------------------------------------------------------------------------
static inline int32_t
xos_thread_sleep_msec(uint64_t msecs)
{
    return xos_thread_sleep(xos_msecs_to_cycles(msecs));
}


//-----------------------------------------------------------------------------
///
///  Put calling thread to sleep for at least the specified number of usec.
///  The actual amount of time spent sleeping may be larger depending upon
///  the granularity of the system timer. Once the specified time has elapsed
///  the thread will be woken and made ready.
///
///  \return    usecs           The number of microseconds to sleep.
///
///  \return    Returns XOS_OK on success, else error code.
///
//-----------------------------------------------------------------------------
static inline int32_t
xos_thread_sleep_usec(uint64_t usecs)
{
    return xos_thread_sleep(xos_usecs_to_cycles(usecs));
}


//-----------------------------------------------------------------------------
///
///  Wait on a timer until it expires or is cancelled. The calling thread will
///  be blocked. The timer must be active.
///  NOTE: This operation is only available if XOS_OPT_TIMER_WAIT is set
///  to 1 in the configuration options.
///
///  \param     timer           Pointer to timer object.
///
///  \return    Returns XOS_OK on normal timeout, else an error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_timer_wait(XosTimer * timer);


//-----------------------------------------------------------------------------
// System timer control interface.
//-----------------------------------------------------------------------------


//-----------------------------------------------------------------------------
// Defines for system timer ID.
//-----------------------------------------------------------------------------
#define XOS_SYS_TIMER_0             0    ///< Internal timer 0
#define XOS_SYS_TIMER_1             1    ///< Internal timer 1
#define XOS_SYS_TIMER_2             2    ///< Internal timer 2
#define XOS_SYS_TIMER_EXTERNAL      -2   ///< External timer
#define XOS_SYS_TIMER_NONE          -1   ///< No system timer selected


//-----------------------------------------------------------------------------
///
///  This function handles XOS timer tick processing. It must be called by the
///  timer interrupt handler on every timer interrupt. This function computes
///  the time to the next tick and sets it up by calling xos_system_timer_set().
///
//-----------------------------------------------------------------------------
void
xos_tick_handler(void);


//-----------------------------------------------------------------------------
///
///  Selects the timer to use. The selection may be one of the internal timers
///  or an external timer. The default implementation selects an internal timer.
///  This function can be overridden to provide custom timer processing or to
///  support an external timer.
///
///  \param     timer_num       The internal timer number to select (0-2) or
///                             -1 to auto-select a timer. This parameter can
///                             be ignored by custom implementations that use
///                             an external timer.
///
///  \param     psel            Pointer to a location where the selected timer
///                             ID must be returned. The timer ID must be one
///                             of XOS_SYS_TIMER_0, XOS_SYS_TIMER_1, XOS_SYS_TIMER_2
///                             or XOS_SYS_TIMER_EXTERNAL.
///
///  \return    Returns XOS_OK on success, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_system_timer_select(int32_t timer_num, int32_t *psel);


//-----------------------------------------------------------------------------
///
///  Starts the system timer and sets up the first interrupt. This function can
///  be overridden to provide custom timer processing or to support an external
///  timer.
///
///  \param     cycles          The number of CPU cycles from now when the
///                             first interrupt must occur.
///
//-----------------------------------------------------------------------------
void
xos_system_timer_init(uint32_t cycles);


//-----------------------------------------------------------------------------
///
///  Sets the next trigger value of the system timer. The parameter 'cycles' is
///  the number of CPU cycles from now when the interrupt must occur.
///  This function can be overridden to provide custom timer processing or to
///  support an external timer.
///
///  \param     cycles          The number of CPU cycles from now when the
///                             next interrupt must occur.
///
//-----------------------------------------------------------------------------
void
xos_system_timer_set(uint32_t cycles);


#ifdef __cplusplus
}
#endif

#endif  // __XOS_TIMER_H__