WUT.c.vx-ppc-gcc File Reference

WakeUp Timer facility. More...

#include <intLib.h>
#include <PBS/WCT.h>
#include <impl/WUT_monitor.h.vx-ppc-xxx>
#include <impl/WUT_wakeup.h.vx-ppc-gcc>
#include <impl/WUT_trace.h.vx-ppc-gcc>
#include <WCT_pvtdefs.ih>
#include <PBS/PTS.h>
#include <PBS/INT.ih>
#include <vxWorks.h>
#include <sysLib.h>
#include <tickLib.h>
#include <time.h>
#include <impl/WUT_wakeup.c.vx-ppc-gcc>

Classes
struct	_WCB_specific
	The platform specific piece of the WUT control structure. More...
struct	_WCB
	WakeUp Control Block. More...
Defines
#define	WUT_MONITOR_DISABLE
#define	WUT_TRACE_ENABLE
#define	WUT_A_TIMER_EXCEPTION_VECTOR   0x900
	The address of the decrement counter exception vector.
Typedefs
typedef struct _WCB_specific	WCB_specific
	Typedef for struct _WCB_specific.
Functions
int	wut_sys_connect_timer (WCB *wcb)
static int	wut_wakeup_get (void)
	Gets the value of the countdown register.
static void	wut_wakeup_set (int ctr)
	Sets the timer countdown register to the specified value.
static int	get_decrement_counter (void)
	Gets the value of Power PCs internal decrement counter.
static void	set_decrement_counter (int ctr)
	Sets the Power PCs internal decrement counter to the specified value.
static void	arm_wakeup (TOV tov)
	Sets the timer countdown to be consistent with the specified timeout value.
static unsigned int	calc_wakeup (TOV tov)
	Calculates the value to set the timer countdown based on specified timeout value.
STATIC int	cmp_lt_tov (TOV tov_a, TOV tov_b)
	Platform implementation dependent routine to compare to timeout values.
STATIC int	lock_que (WCB *wcb)
	Platform implementation dependent routine to lock the WUT timer que.
STATIC void	unlock_que (WCB *wcb, int key)
	Platform implementation dependent routine to unlock the WUT timer que.
STATIC void	arm_handler (WCB *wcb, TOV tov)
	Seeds the timer interrupt to handle expire a tov.
STATIC void	arm_handler_nxt_wut (WCB *wcb, const WUT_tmr *wut)
	Seeds the timer interrupt to handle expire at the timeout associated with the specified WUT timer entry.
static __inline void	wut_period_set (unsigned int period)
	Informs VxWorks of a new clock rate.
STATIC void	wut_spc_init (WCB *wcb)
	Initializes the processor specific portion of the control block.
int	wut_sys_connect (WCB *wcb)
	Platform dependent part of the WUT system connection process.
void	WUT_sys_handler ()
	The facility's internal Interrupt Service Routine.
int	WUT_dec_get ()
	Gets the current time left till the next timer expiration.
WUT_cb_status	WUT_keepalive_update (WUT_keepalive_ctx *keepalive, WUT_tmr *wut)
	Simple WUT timer callback routine used to update the WCT clock.
WUT_cb_status	WUT_keepalive_rtn (WUT_keepalive_ctx *keepalive, WUT_tmr *wut)
	Simple WUT timer callback routine used to drive the VxWorks system clock.
Variables
static WCB	Wcb
	Statically allocate control block as a facilty private structure.

---

Detailed Description

WakeUp Timer facility.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: WUT.c.vx-ppc-gcc,v 1.14 2011/03/24 23:05:47 apw Exp $

The VxWorks implementation of the WakeUp Timers (WUT) facility.

---

Function Documentation

void arm_handler	(	WCB *	wcb,
		TOV	tov
	)			[inline]

Seeds the timer interrupt to handle expire a tov.

Parameters:

	wcb	The WUT control block
	tov	The expiration timeout value

References arm_wakeup().

Referenced by add_wut().

void arm_handler_nxt_wut	(	WCB *	wcb,
		const WUT_tmr *	wut
	)			[inline]

Seeds the timer interrupt to handle expire at the timeout associated with the specified WUT timer entry.

Parameters:

	wcb	The WUT control block
	wut	The WUT timer entry.

References arm_wakeup(), _Q_node::flnk, get_wut(), _WUT_tmr::node, and _WUT_tmr::tov.

Referenced by WUT_cancel().

static void arm_wakeup

(

TOV

tov

)

[inline, static]

Sets the timer countdown to be consistent with the specified timeout value.

Parameters:

tov

The timeout value to set the timer countdown to. The difference between the specified timeout value and the current time is calculated. Since timeout values are not in the same units as the timer counter, a conversion must made on this result to get it into the proper units.

References calc_wakeup(), Wcb, WUT_K_WAKEUP_RESET_CUSHION, wut_wakeup_get(), and wut_wakeup_set().

Referenced by arm_handler(), and arm_handler_nxt_wut().

static unsigned int calc_wakeup

(

TOV

tov

)

[inline, static]

Calculates the value to set the timer countdown based on specified timeout value.

Parameters:

tov

The timeout value to set the timer countdown counter to. The difference between the specified timeout value and the current time is calculated. Since timeout values are not in the same units as the timer countdown, a conversion must made on this result to get it into the proper units.

Returns:

The calculated value to set the timer countdown to

References WCT__diff_aticks(), and wut_wakeup_delay().

Referenced by arm_wakeup().

int cmp_lt_tov	(	TOV	tov_a,
		TOV	tov_b
	)			[inline]

Platform implementation dependent routine to compare to timeout values.

Parameters:

	tov_a	The first of the two timeout values to compare
	tov_b	The second of the two timeout values to compare

Returns:

non-zero if tov_a < tov_b, else 0

Referenced by add_wut(), and find().

static int get_decrement_counter

(

void

)

[inline, static]

Gets the value of Power PCs internal decrement counter.

Returns:

The value of the decrement counter.

This is an internal routine only. It provides C language access to the PowerPC instruction mfdec.

Referenced by WUT_dec_get().

int lock_que

(

WCB *

wcb

)

[inline]

Platform implementation dependent routine to lock the WUT timer que.

Parameters:

wcb

Pointer to the WUT control block

Returns:

A key to be used to unlock the que.

References INT__lock().

Referenced by add_wut(), and WUT_cancel().

static void set_decrement_counter

(

int

ctr

)

[inline, static]

Sets the Power PCs internal decrement counter to the specified value.

Parameters:

ctr

The value to set the decrement counter to.

This is an internal routine only. It provides C language access to the PowerPC instruction mtdec.

void unlock_que	(	WCB *	wcb,
		int	key
	)			[inline]

Platform implementation dependent routine to unlock the WUT timer que.

Parameters:

	wcb	Pointer to the WUT control block
	key	The key used to unlock the que (returned from lock_que()

References INT__unlock().

Referenced by add_wut(), and WUT_cancel().

int WUT_dec_get

(

void

)

Gets the current time left till the next timer expiration.

This primarily used as a debugging aid.

References get_decrement_counter().

WUT_cb_status WUT_keepalive_rtn	(	WUT_keepalive_ctx *	keepalive,
		WUT_tmr *	wut
	)

Simple WUT timer callback routine used to drive the VxWorks system clock.

Parameters:

	keepalive	The keepalive control structure.
	wut	The WUT timer entry

Return values:

WUT_K_STATE_CHANGE_YES

VXWORKS Implementation Note

On the PowerPC platform, this routine is used to keep the decrement counter within its limited range, ensuring that no timer entry attempts to seed it with a value beyond it's limits. It is also used to update the VxWork's system clock by calling tickAnnounce().

Return Value

The return value reflects the fact the timer entries state has been changed by the callback routine (its been restarted).

References _WUT_keepalive_ctx::period, remove_key(), _WUT_tmr::tov, TOV_add_nsecs(), WUT_K_STATE_CHANGE_YES, and WUT_restart().

Referenced by WUT_sys_connect(), and WUT_sys_reset().

WUT_cb_status WUT_keepalive_update	(	WUT_keepalive_ctx *	keepalive,
		WUT_tmr *	wut
	)

Simple WUT timer callback routine used to update the WCT clock.

Parameters:

	keepalive	The keepalive control structure.
	wut	The WUT timer entry

Return values:

WUT_K_STATE_CHANGE_YES

This routine is used in systems without an external clock, such as the sysAuxClock or the GPS.

The WUT timer entry updates the WCT clock and the timer entry is then requeued with the specified delay relative to it's previous expiration time. This creates a fairly accurate clock.

The return value reflects the fact the timer entries state has been changed by the callback routine (its been restarted).

VXWORKS IMPLEMENTATION NOTE

The VxWork's routine tickAnnounce(), is called to update the VxWork's system clock and WCT clock.

References _WUT_keepalive_ctx::elapsed, _WUT_keepalive_ctx::period, remove_key(), _WUT_tmr::tov, TOV_add_nsecs(), _WUT_keepalive_ctx::update, WCT_update(), WUT_K_STATE_CHANGE_YES, and WUT_restart().

Referenced by WUT_sys_connect(), and WUT_sys_reset().

static __inline void wut_period_set

(

unsigned int

period

)

[static]

Informs VxWorks of a new clock rate.

Parameters:

period

The period, in nanoseconds, that tickAnnounce is being driven

References TOV_K_NSECS_IN_A_SEC.

Referenced by WUT_sys_reset().

STATIC void wut_spc_init

(

WCB *

wcb

)

Initializes the processor specific portion of the control block.

Parameters:

wcb

The WUT control block

Referenced by WUT_sys_init().

int wut_sys_connect

(

WCB *

wcb

)

Platform dependent part of the WUT system connection process.

Parameters:

wcb

The WUT control block

Returns:

Status

References _WCB::com, _WUT_keepalive::ctx, _WCB_common::keepalive, _WUT_keepalive_ctx::period, and TOV_K_NSECS_IN_A_SEC.

Referenced by WUT_sys_connect().

void WUT_sys_handler

(

void

)

The facility's internal Interrupt Service Routine.

The timer interrupt/task handler.

This routine is registered as the callback routine for the timer countdown. It called back and executes in interrupt context. It services as the dispatcher for the timer entries, examining the top timer entry on an internal que to see if it has expired. If so, it calls back the service handler associated with the timer entry. After servicing the timer entry the next timer entry in the que is checked for expiration.

This continues until an unexpired timer entry is encountered. The time till its expiration is recalculated and the decrement counter is reseeded with this time. Note that it is possible that the first timer entry is itself unexpired. While this is an unusual case, it is not fatal, and the real expiration time is calculated.

It is also worth pointing out that the callback routines associated with the timer entry are executed in interrupt context, but not a interrupt level. In practical terms this means that the stack space is limited and interrupts are not locked. Not locking interrupts during the callback phase is a design decision made to mitigate the interrupt latency.

As with all routines executing in interrupt context, the user is encouraged to get in and get out while using a minimum of resources. Of course, no routines that may block can be called in this context.

Warning:

This is not a user callable routine

References add_key(), _WCB::com, _Q_node::flnk, get_wut(), INT__lock(), INT__unlock(), _Q_head::node, PTS_GETS, PTS_GETX, Q__unlink(), _WCB_common::que, _WUT_tmr::state, Wcb, WCT__diff_aticks_full(), WUT_K_ACTIVE, WUT_K_CANCELLED, WUT_K_EXPIRED, WUT_K_QUEUED, WUT_K_STATE_CHANGE_NO, wut_wakeup_get(), wut_wakeup_isr_delay(), and wut_wakeup_set().

void wut_wakeup_get

(

void

)

[inline, static]

Gets the value of the countdown register.

Returns:

The value of the time countdown register

This is an internal routine only. Depending on the specific platform this may be as simple as providing C language access to the PowerPC instruction mfdec or it may entail an off-chip timer

Referenced by arm_wakeup(), and WUT_sys_handler().

void wut_wakeup_set

(

int

ctr

)

[inline, static]

Sets the timer countdown register to the specified value.

Parameters:

ctr

The value to set the timer countdown register to.

This is an internal routine only. It may be as simple as providing C language access to the PowerPC instruction mtdec or, depending on the platform, it may access an off-chip timer.

Referenced by arm_wakeup(), and WUT_sys_handler().