test_wut.c File Reference

Unit test of he Wakeup Timer (WUT) facility. More...

#include <stdio.h>
#include <stdlib.h>
#include <PBS/PBS.h>
#include <PBS/TMR.h>
#include <PBS/FPA.h>
#include <PBS/PTS.h>
#include <PBS/SPIN.h>
#include <PBS/WCT.h>
#include <PBS/WUT.h>
#include <PBS/TOC.h>
#include <PBS/TOV.h>
#include <PBS/QI.h>
#include <PBS/Q.h>
#include <string.h>
#include <pthread.h>
#include <errno.h>

Classes
struct	_Msg
	Standard message to be exchanged between timer ISR and task. More...
struct	_Handler_Ctx
	The context parameter passed to the WUT timer. More...
Defines
#define	ONE_SECOND   (1000 * 1000 * 1000)
	Convenience definition for 1 second in nanosecond units.
Typedefs
typedef struct _Msg	Msg
	Typedef for struct _Msg.
typedef struct _Handler_Ctx	Handler_Ctx
	Typedef for struct _Handler_Ctx.
Functions
int	test_wut (int wait)
int	test_wut_1 (int wait)
	Basic test of the WUT facility.
int	test_wut_2 (int wait)
	Tests that closely space timer interrupts do not kill the machine.
static FPA_fcb *	init_fpa (int msg_cnt, int msg_size)
	Internal helper routine to create an FPA pool of messsages.
static void	loop (int count, TMR_tick *times, int *dctrs, int ptus)
	Silly routine used in measuring the overheads.
WUT_cb_status	handler (Handler_Ctx *ctx, WUT_tmr *wut)
	Timer ISR to deliver a message packet back to the task.
WUT_cb_status	panic_handler (Handler_Ctx *ctx, WUT_tmr *wut)
	Requeues closely spaced interrupts to test that the WUT timer ISR behaves correctly.
int	main (int argc, char **argv)
	Entry point for host testing.
void	test_timeout (void)
	Tests the Posix timeout mechanism.
Variables
static unsigned int	Test_Count = 0

---

Detailed Description

Unit test of he Wakeup Timer (WUT) facility.

Author:

JJRussell - russell@slac.stanford.edu

    CVS $Id: test_wut.c,v 1.7 2011/03/24 23:05:45 apw Exp $

The WUT facility provides fine-grain timing interrupts, at the level of the resolution of the internal processor clock.

Host Platform Implementation

On host platforms WUT does this by using the pthread__timedcond () routine running in the context of what was hoped to be a very high priority thread. Unfortunately, neither the Solaris nor Linux support task priorities, so while the routines are functional, the timeliness of the signal delivery is somewhat suspect.

VxWorks Platform Implementation

On VxWorks PPC platforms, the VxWorks decrement timer ISR is replaced with a WUT specific ISR. The WUT ISR services the WUT timer queue and, in addition, performs a callback to the VxWorks tickAnnounce routine in a specially installed timer entry. This mimics the behaviour of the VxWorks ISR and allows users to continue to use the wdb routines for low resolution timer interrupts.

Because it replaces the VxWorks decrement timer ISR and maintains its own timer queue, the WUT facility is easily the most complicated facility within PBS. Whereas most of PBS is simple packaging of routines to make a green layer behind the user and the OS, WUT is fairly sophisicated.

Tests

This program tests the Wakeup timer facility. It does this by taking out a periodic timer for 25 (or so iterations). The only free parameter is the period of the timer. If not specified, it defaults to 1 second.

A second test was added to verify that on VxWorks platforms, the WUT timer ISR gives sufficient time so that VxWorks can keep its work que under control.

To run the program on Unix platforms

     $ test_wut [period]

To run the program on VxWorks platorms, at the shell type

     $ test_wut [period]

where period is a number given in Hertz. The default value is 1 Hz.

---

Typedef Documentation

Msg

Typedef for struct _Msg.

Both of the standard tests exchange a message of this form between the firing WUT timer ISR and the receiving task. The WUT timer ISR fills in various pieces of information so that the WUT facility can be checked both for integrity and performance.

---

Function Documentation

WUT_cb_status handler	(	Handler_Ctx *	ctx,
		WUT_tmr *	wut
	)

Timer ISR to deliver a message packet back to the task.

Returns:

Whether to reschedule the timer ISR was rescheduled or not

Parameters:

	ctx	Test context handle
	wut	The WUT timer entry being serviced

References _Msg::cnt, _Handler_Ctx::fpa, _Msg::node, ONE_SECOND, _Handler_Ctx::que, _Msg::tov, and _Msg::wct.

Referenced by test_wut_1().

static FPA_fcb * init_fpa	(	int	msg_cnt,
		int	msg_size
	)			[static]

Internal helper routine to create an FPA pool of messsages.

Returns:

Pointer to the created FPA pool

Parameters:

	msg_cnt	The number of messages in the pool
	msg_size	The size, in bytes, of one message

Referenced by test_wut_1(), and test_wut_2().

int main	(	int	argc,
		char **	argv
	)

Entry point for host testing.

Returns:

Status

Parameters:

	argc	The count of command line arguments, basically unused
	argv	The vector of command line arguments, basically unused

Usage

To run this test

     $ test_wut

References test_wut_1(), and test_wut_2().

WUT_cb_status panic_handler	(	Handler_Ctx *	ctx,
		WUT_tmr *	wut
	)

Requeues closely spaced interrupts to test that the WUT timer ISR behaves correctly.

Returns:

Whether to reschedule the timer ISR was rescheduled or not

Parameters:

	ctx	Test context handle
	wut	The WUT timer entry being serviced

References _Msg::cnt, _Handler_Ctx::fpa, _Msg::node, _Handler_Ctx::que, _Msg::tov, and _Msg::wct.

Referenced by test_wut_2().

void test_timeout

(

void

)

Tests the Posix timeout mechanism.

This test is inactive. It was used when developing the WUT code. This functionality gets tested during test_wut_1. It is being kept around for historical reasons.

int test_wut_1

(

int

wait

)

Basic test of the WUT facility.

Parameters:

wait

Unused

This is a basic test of the WUT facility. A timer is created that periodically fires every second. When it fires it delivers a message back to this task. This task pends on the receiving que with a time-out value of 1/4 second. So every second one gets 3 time-out messages and one valid received message.

References _Msg::cnt, _Handler_Ctx::fpa, handler(), init_fpa(), loop(), ONE_SECOND, _Handler_Ctx::que, _Msg::tov, and _Msg::wct.

Referenced by main().

int test_wut_2

(

int

wait

)

Tests that closely space timer interrupts do not kill the machine.

Returns:

Status

Parameters:

wait

Unused

Tests that closely spaced interrupts do not kill the machine On VxWorks platforms, if the WUT ISR does not give VxWorks enough time to service its work que, the dreaded Work Que Panic can occur. This test generates very closely spaced timer ISR's to check that the WUT ISR does do the right thing.

References _Msg::cnt, _Handler_Ctx::fpa, init_fpa(), _Msg::node, ONE_SECOND, panic_handler(), _Handler_Ctx::que, _Msg::tov, and _Msg::wct.

Referenced by main().