PBS.c File Reference

PBS library, contains the initialization routines for PBS. More...

#include <stdio.h>
#include <stdlib.h>
#include <PBS_DB/PBS_DB_schema.h>
#include <PBS/PBS.h>
#include <PBS/REG.h>
#include <PBS/MBA.h>
#include <PBS/TAU.h>
#include <PBS/TBD.h>
#include <PBS/PTS.h>
#include <PBS/WUT.h>
#include <PBS/WCT.h>
#include <PBI/Unions.h>
#include <PBI/PTR.h>
#include <CDM/CDM_pubdefs.h>
#include <impl/PBS.c.xx-xxx-xxx>

Functions
int	TASK_sys_init (void)
	Performs one time only initialization of the TASK facility.
int	TASK_sys_shutdown (void)
	Performs the shutdown of the TASK facility. This essentially undoes what TASK_sys_init did.
int	PBS_configure (void)
	One-time PBS library initialization routine via a configuration file.
int	PBS_initialize (int wut_tmr_cnt, int keepalive_period)
	One-time PBS library initialization routine.
int	PBS_initialize2 (int wut_tmr_cnt, int keepalive_period, MBA_create_cb mba_create, void *mba_prm)
	One-time PBS library initialization routine.
int	PBS_shutdown ()
	Shuts down the PBS facility.
void	PBS_fast_clear (void *ptr, unsigned int nbytes)
	Clears (Zeroes) the specified memory.
int	PBS_crashPrint (PBS_crashType type, const PBS_crashCtx *ctx, unsigned int options, const char *string)
	Very simple default PBS crash handler.
PBS_crashHandler	PBS_crashHandlerSet (PBS_crashHandler crashHandler)
	Installs a new user crash handler.
void	PBS_crash (PBS_crashType type, const PBS_crashCtx *ctx, unsigned int options, const char *string)
	General purposes reboot routine.
void	PBS_reboot (unsigned int reason, unsigned int parameter, void *pc, unsigned int options, const char *string)
	Routine to initiate a commanded reboot.
void	PBS_panic (unsigned int reason, unsigned int parameter, void *pc, unsigned int options, const char *string)
	Routine to initiate a panic reboot.
Variables
static int	PbsInitialized = 0
	Static flag indicating the PBS facility has been initialized.

---

Detailed Description

PBS library, contains the initialization routines for PBS.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: PBS.c,v 1.12 2011/03/24 23:05:46 apw Exp $

Warning:

This is currently a kludge.

---

Function Documentation

int PBS_configure

(

void

)

One-time PBS library initialization routine via a configuration file.

Return values:

	0,Success
	1,PBS	already initialized
	-1,Error

References PBS_initialize(), and PBS_initialize2().

void PBS_crash	(	PBS_crashType	type,
		const PBS_crashCtx *	ctx,
		unsigned int	options,
		const char *	string
	)

General purposes reboot routine.

Parameters:

type

The type of reboot being requested, i.e. one of

See also:

PBS_crashType.

Parameters:

ctx

A filled in

See also:

PBS_crashCtx block.

Parameters:

options

A set options. See

See also:

PBS_crashOptions for further details.

Parameters:

string

An arbitrary user string. This is used iff there is an active PBS crash handler, in which case it is merely passed through to it.

References PBS_LOCK.

PBS_crashHandler PBS_crashHandlerSet

(

PBS_crashHandler

crashHandler

)

Installs a new user crash handler.

Returns:

The old crash handler

Parameters:

crashHandler

The new crash handler routine. If this may be NULL or PBS_CRASH_HANDLER_DEFAULT

This routine may be specified as NULL, in which case no user crash handler callback routine is executed.

Note:

While one can currently get the same effect using either of the two example pieces of code below. If one uses the former, then the PBS crash handler is always

See also:

PBS_crashPrint(), while if one uses the later, the crash handler tracks the current runtime default.

   PBS_crashHandlerSet (PBS_crashPrint);

   PBS_crashHandlerSet (PBS_CRASH_HANDLER_DEFAULT);

References PBS_CRASH_HANDLER_DEFAULT, and PBS_crashPrint().

Referenced by PBS_initialize2().

int PBS_crashPrint	(	PBS_crashType	type,
		const PBS_crashCtx *	ctx,
		unsigned int	options,
		const char *	string
	)

Very simple default PBS crash handler.

Returns:

options

Parameters:

type

The type of reboot being requested, i.e. one of

See also:

PBS_crashType.

Parameters:

	ctx	Pointer to a completed PBS_crashCtx block.
	options	A set options. See

See also:

PBS_crashOptions for further details.

Parameters:

string

An arbitrary user string. It is just printed as the first line of the output.

This is the current default user handler, i..e the one gets if PBS_CRASH_HANDLER_DEFAULT is specified as the argument to

See also:

PBS_crashHandlerSet().

References _PBS_crashCtx::msr, _PBS_crashCtx::parameter, _PBS_crashCtx::pc, _PBS_crashCtx::reason, _PBS_crashCtx::sp, _PBS_crashCtx::tid, and _PBS_crashCtx::tim.

Referenced by PBS_crashHandlerSet().

void PBS_fast_clear	(	void *	ptr,
		unsigned int	nbytes
	)

Clears (Zeroes) the specified memory.

Parameters:

	ptr	Pointer to the memory to zero
	nbytes	The number of bytes to zero

This provides a fast way of zeroing large chunks of memory on PPC platforms using the dcbz instruction. This instruction zeroes a cache line at a time. The savings in speed varies by processor, but factors of 5 or more are in the ballpark, saturating out at a factor of 2 once the data cache size is exceeded (32Kbytes).

On other platforms, the library supplied routine is used.

Warning:

On PPC platforms, this will work if and only if the memory being cleared is cache enabled. For the most part this is not a problem since usually all memory but memory mapped to IO space and set aside for driver use is marked cacheable. This routine does check to make sure the data cache is globally enabled. If not, the generic clear routine is called. The routine is protected if the data cache is globally disabled, in this case, dropping make and using the generic routine.

int PBS_initialize	(	int	wut_tmr_cnt,
		int	keepalive_period
	)

One-time PBS library initialization routine.

Parameters:

	wut_tmr_cnt	The number of WUT timers to keep in the system pool. If specified as 0, a default value of 256 will be used.
	keepalive_period	The period (in nanoseconds) of the periodic keepalive timer. If specified as 0, a default value of 20,000,000, corresponding to 50Hz will be used.

Returns:

Status, 1 indicates PBS was already initialized

This is a one-time initialization of the PBS library. This call not only initializes static resources, but also replaces the VxWorks decrement counter interrupt routine (the 'timer') with the high resolution WUT timers.

References PBS_initialize2().

Referenced by PBS_configure().

int PBS_initialize2	(	int	wut_tmr_cnt,
		int	keepalive_period,
		MBA_create_cb	mba_create,
		void *	mba_prm
	)

One-time PBS library initialization routine.

Parameters:

	wut_tmr_cnt	The number of WUT timers to keep in the system pool. If specified as 0, a default value of 256 will be used.
	keepalive_period	The period (in nanoseconds) of the periodic keepalive timer. If specified as 0, a default value of 20,000,000, corresponding to 50Hz will be used.
	mba_create	Alternate MBA partition creation routine. If specified as NULL, a default creation routine will be used and prm will be interpretted as a list of bad blocks, i.e. of type MBA_badBlockList.
	mba_prm	Arbitrary parameter passed to the MBA partition creation routine.

Returns:

Status, 1 indicates PBS was already initialized

This is a one-time initialization of the PBS library. This call not only initializes static resources, but also replaces the VxWorks decrement counter interrupt routine (the 'timer') with the high resolution WUT timers.

References MBA_initialize(), PBS_CRASH_HANDLER_DEFAULT, PBS_crashHandlerSet(), PbsInitialized, PTS_frequency(), PTS_GETS, PTS_initialize(), TASK_sys_init(), TAU_initialize, TBD_initialize(), WCT_K_NSECS_IN_A_SEC, WCT_set(), WUT_sys_connect(), and WUT_sys_init().

Referenced by PBS_configure(), and PBS_initialize().

void PBS_panic	(	unsigned int	reason,
		unsigned int	parameter,
		void *	pc,
		unsigned int	options,
		const char *	string
	)

Routine to initiate a panic reboot.

Parameters:

	reason	An application specific reason for the reboot. For example, this may identify the reason why the software is in a panic.
	parameter	An additional opaque user application parameter
	pc	The PC of where the reboot panic originated. Typically one would use PBS_PC() to get fill this value.
	options	A set options. Set

See also:

PBS_crashOptions for further details.

Parameters:

string

An arbitrary user string. This is used iff there is an active PBS crash handler, in which case it is merely passed through to it.

This routine is typically called when a piece of application code finds itself confronted with a software or hardware error which it cannot handle.

This routine will

1. fill out the remaining fields of the PCB_crashCtx block
2. callback any user supplied PBS_crashHandler, see

   See also:

   PBS_crashHandlerSet ().

3. call the underlying OS dependent reboot or abort routine.

References PBS_CRASH_TYPE_PANIC, and PBS_LOCK.

Referenced by BUG_check().

void PBS_reboot	(	unsigned int	reason,
		unsigned int	parameter,
		void *	pc,
		unsigned int	options,
		const char *	string
	)

Routine to initiate a commanded reboot.

Parameters:

	string	An arbitrary user string. This is used iff there is an active PBS crash handler, in which case it is merely passed through to it.
	reason	An command specific reason for the reboot. For example this may identify the source of the reboot command
	parameter	An additional opaque user parameter
	pc	The PC of where the reboot command originated. Typically one would use PBS_PC() to get fill this value.
	options	A set options. See

See also:

PBS_crashOptions for further details.

This routine is called when a command instructing the OS to reboot has been received.

This routine will

1. fill out the remaining fields of the PCB_crashCtx block
2. callback any user supplied PBS_crashHandler, see

   See also:

   PBS_crashHandlerSet ().

3. call the underlying OS dependent reboot or abort routine.

References PBS_CRASH_TYPE_COMMAND, and PBS_LOCK.

int PBS_shutdown

(

void

)

Shuts down the PBS facility.

Warning:

This function is only meant to be used during development. Its main use is to allow the semi-graceful reloading of PBS in the VxWorks environment.

References PbsInitialized, TASK_sys_shutdown(), TAU_shutdown, TBD_destroy(), and WUT_sys_shutdown().

int TASK_sys_init

(

void

)

Performs one time only initialization of the TASK facility.

Returns:

Status

Referenced by PBS_initialize2().

int TASK_sys_shutdown

(

void

)

Performs the shutdown of the TASK facility. This essentially undoes what TASK_sys_init did.

Returns:

Status

Referenced by PBS_shutdown().