/** @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__