atomtimer.c File Reference

#include <stdio.h>
#include "atom.h"

Data Structures
struct	delay_timer
Typedefs
typedef struct delay_timer	DELAY_TIMER
Functions
uint8_t	atomTimerRegister (ATOM_TIMER *timer_ptr)
uint8_t	atomTimerCancel (ATOM_TIMER *timer_ptr)
uint32_t	atomTimeGet (void)
void	atomTimeSet (uint32_t new_time)
void	atomTimerTick (void)
uint8_t	atomTimerDelay (uint32_t ticks)

---

Detailed Description

Timer and system tick library.

This module implements kernel system tick / clock functionality and timer functionality for kernel and application code.

Timer callbacks

Application and kernel code uses this module to request callbacks at a specific number of system ticks in the future. atomTimerRegister() can be called with a structure filled out requesting callbacks in a specific number of ticks. When the timer expires the requested callback function is called.

Thread delays

Application threads can use atomTimerDelay() to request that the thread delay for the specified number of system ticks. The thread will be put in the timer list and taken off the ready queue. When the timer expires the thread will be made ready-to-run again. This internally uses the same atomTimerRegister() function that is used for registering all timers.

System tick / Clock

This module also implements the system tick. At a predefined interval (SYSTEM_TICKS_PER_SEC) architecture ports arrange for atomTimerTick() to be called. The tick increments the system tick count, which can be queried by application code using atomTimeGet(). On this tick, the registered timer list is checked for any timers which have expired. Those which have expired have their callback functions called. It is also on this system tick that round-robin rescheduling time-slices occur. On exit from the tick interrupt handler the kernel checks whether there are two or more threads ready-to-run at the same priority, and if so uses round-robin to schedule in the next thread. This is in contrast to other (non-timer-tick) interrupts which do not allow for round-robin rescheduling to occur, as they should only occur on a new timer tick.

---

Typedef Documentation

typedef struct delay_timer DELAY_TIMER

---

Function Documentation

uint32_t atomTimeGet

(

void

)

atomTimeGet

Returns the current system tick time.

This function can be called from interrupt context.

Return values:

Current

system tick count

uint8_t atomTimerCancel

(

ATOM_TIMER *

timer_ptr

)

atomTimerCancel

Cancel a timer callback previously registered using atomTimerRegister().

This function can be called from interrupt context, but loops internally through the time list, so the potential execution cycles cannot be determined in advance.

Parameters:

[in]

timer_ptr

Pointer to timer to cancel

Return values:

	ATOM_OK	Success
	ATOM_ERR_PARAM	Bad parameters
	ATOM_ERR_NOT_FOUND	Timer registration was not found

References ATOM_ERR_NOT_FOUND, ATOM_ERR_PARAM, ATOM_OK, CRITICAL_END, CRITICAL_START, CRITICAL_STORE, atom_timer::next_timer, and uint8_t.

Referenced by atomMutexDelete(), atomMutexPut(), atomQueueDelete(), atomSemDelete(), and atomSemPut().

uint8_t atomTimerDelay

(

uint32_t

ticks

)

atomTimerDelay

Suspend a thread for the given number of system ticks.

Note that the wakeup time is the number of ticks from the current system tick, therefore, for a one tick delay, the thread may be woken up at any time between the atomTimerDelay() call and the next system tick. For a minimum number of ticks, you should specify minimum number of ticks + 1.

This function can only be called from thread context.

Parameters:

[in]

ticks

Number of system ticks to delay (must be > 0)

Return values:

	ATOM_OK	Successful delay
	ATOM_ERR_PARAM	Bad parameter (ticks must be non-zero)
	ATOM_ERR_CONTEXT	Not called from thread context

References ATOM_ERR_CONTEXT, ATOM_ERR_PARAM, ATOM_ERR_TIMER, ATOM_OK, atomCurrentContext(), atomSched(), atomTimerRegister(), atom_timer::cb_data, atom_timer::cb_func, atom_timer::cb_ticks, CRITICAL_END, CRITICAL_START, CRITICAL_STORE, FALSE, POINTER, atom_tcb::suspend_timo_cb, atom_tcb::suspended, delay_timer::tcb_ptr, TRUE, and uint8_t.

uint8_t atomTimerRegister

(

ATOM_TIMER *

timer_ptr

)

atomTimerRegister

Register a timer callback.

Callers should fill out and pass in a timer descriptor, containing the number of system ticks until they would like a callback, together with a callback function and optional parameter. The number of ticks must be greater than zero.

On the relevant system tick count, the callback function will be called.

These timers are used by some of the OS library routines, but they can also be used by application code requiring timer facilities at system tick resolution.

This function can be called from interrupt context, but loops internally through the time list, so the potential execution cycles cannot be determined in advance.

Parameters:

[in]

timer_ptr

Pointer to timer descriptor

Return values:

	ATOM_OK	Success
	ATOM_ERR_PARAM	Bad parameters

References ATOM_ERR_PARAM, ATOM_OK, atom_timer::cb_func, atom_timer::cb_ticks, CRITICAL_END, CRITICAL_START, CRITICAL_STORE, atom_timer::next_timer, and uint8_t.

Referenced by atomMutexGet(), atomQueueGet(), atomQueuePut(), atomSemGet(), and atomTimerDelay().

void atomTimerTick

(

void

)

atomTimerTick

System tick handler.

User ports are responsible for calling this routine once per system tick.

On each system tick this routine is called to do the following: 1. Increase the system tick count 2. Call back to any registered timer callbacks

Returns:

None

References atomOSStarted.

void atomTimeSet

(

uint32_t

new_time

)

atomTimeSet

This is an internal function not for use by application code.

Sets the current system tick time.

Currently only required for automated test suite to test clock behaviour.

This function can be called from interrupt context.

Parameters:

[in]

new_time

New system tick time value

Returns:

None