PBS.h File Reference

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

#include <PBS/MBA.h>
#include <PBS/impl/PBS.h.px-xxx-xxx>

Classes

struct _PBS_crashCtx

Defines the application context parameters of a crash. More...

Defines

#define PBS_CRASH_HANDLER_DEFAULT   (PBS_crashHandler)(-1)

Specifies to PBS_crashHandlerSet that the default crash handler is requested.

#define PBS_V_CRASH_OPTION_VX_REBOOT   28

Starting bit of the VxWorks reboot field in the options. This is a 3 bit wide field passed directly to 'reboot'.

Typedefs

typedef struct _PBS_crashCtx PBS_crashCtx

Typedef for struct _PBS_crashCtx.

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

User callback routine to handle a crash.

typedef enum _PBS_crashOptions PBS_crashOptions

Typedef for.

Enumerations

enum _PBS_crashOptions {
  PBS_M_CRASH_OPTION_CRASH_NO = (1<<31),
  PBS_M_CRASH_OPTION_VX_REBOOT_QUICK = (1<< 30),
  PBS_M_CRASH_OPTION_VX_REBOOT_CLEAR = (1<< 29),
  PBS_M_CRASH_OPTION_VX_REBOOT_NOAUTO = (1<< 28)
}

Enumerates those bits of the options argument that PBS uses. More...

Functions

void PBS_fast_clear (void *ptr, unsigned int nbytes)

Clears (Zeroes) the specified memory.

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 (void)

Shuts down the PBS facility.

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

General purposes reboot routine.

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

Routine to initiate a panic reboot.

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

Routine to initiate a commanded reboot.

PBS_crashHandler PBS_crashHandlerSet (PBS_crashHandler crashHandler)

Installs a new user crash handler.

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

Very simple default PBS crash handler.

Detailed Description

PBS library, contains the interface to initialization routines for PBS.

Author:: JJRussell - russell@slac.stanford.edu

   CVS $Id: PBS.h,v 1.9 2011/03/24 23:05:42 apw Exp $

Typedef Documentation

PBS_crashCtx

Typedef for struct _PBS_crashCtx.

This data structure contains the application specific context parameters of the crash. The intent is to provide enough information that the reason of the crash can be diagnosed.

This block is limited to 8 32-bit values and, if the OS supports it, is committed to the area of memory saved across boots.

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

User callback routine to handle a crash.

Returns:: The new options value

Parameters:

type

The crash type, i.e. one of

See also:: PBS_crashType 's.

Parameters:

	ctx	The crash context block
	options	The crash options (OS dependent)
	string	An arbitrary user string

This routine is meant to provide a formatted dump of the crash. It is user provided by calling

See also:: PBS_crashHandlerSet (). A default version
PBS_crashPrint () has been provided.

PBS_crashOptions

Typedef for.

See also:: enum _PBS_crashOptions

The options word present in many of the PBS crash routines, e.g.

See also:

PBS_crash,

PBS_panic and

PBS_reboot, is a series of bit flags shared between the PBS layer and the underlying OS reboot layer.

The tenative agreement is that PBS gets the upper 16 and the OS reboot layer gets the lower 16. PBS will begin allocating these bits from the top down.

Some of the PBS options are generic, i.e. they have the same meaning on all platforms, while others only have meaning on certain platforms.

In the former category is

See also:: PBS_M_CRASH_OPTION_REBOOT_NO. This option inhibits the calling of the underlying OS reboot function, essentially reducing the call to PBS_crash, PBS_panic and PBS_reboot to only filling out the context block and calling back the user defined handler. This feature may prove useful in testing.

In the latter category is

See also:: PBS_M_CRASH_OPTION_REBOOT_NOAUTO. This option is relevant only to those platforms calling the VXWORKs reboot function. These platforms are mv2304 and the mcp750. This option effectively translates in the the BOOT_NORMAL (option cleared) and BOOT_NOAUTOBOOT.

Enumeration Type Documentation

enum _PBS_crashOptions

Enumerates those bits of the options argument that PBS uses.

Enumerator:

PBS_M_CRASH_OPTION_CRASH_NO	Only call the user level handler,do no call the underlying OS crash/reboot function.
PBS_M_CRASH_OPTION_VX_REBOOT_QUICK	Meaningful only MV23xx and MCP750 platforms, this translates into BOOT_QUICK_AUTOBOOT (4)
PBS_M_CRASH_OPTION_VX_REBOOT_CLEAR	Meaningful only MV23xx and MCP750 platforms, this translates into BOOT_CLEAR (2), clearing memory on the reboot
PBS_M_CRASH_OPTION_VX_REBOOT_NOAUTO	Meaningful only MV23xx and MCP750 platforms, this translates into BOOT_NO_AUTOBOOT (1)

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

fill out the remaining fields of the PCB_crashCtx block
callback any user supplied PBS_crashHandler, see
See also:
PBS_crashHandlerSet ().
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

fill out the remaining fields of the PCB_crashCtx block
callback any user supplied PBS_crashHandler, see
See also:
PBS_crashHandlerSet ().
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().


Classes
struct	_PBS_crashCtx
	Defines the application context parameters of a crash. More...
Defines
#define	PBS_CRASH_HANDLER_DEFAULT (PBS_crashHandler)(-1)
	Specifies to PBS_crashHandlerSet that the default crash handler is requested.
#define	PBS_V_CRASH_OPTION_VX_REBOOT 28
	Starting bit of the VxWorks reboot field in the options. This is a 3 bit wide field passed directly to 'reboot'.
Typedefs
typedef struct _PBS_crashCtx	PBS_crashCtx
	Typedef for struct _PBS_crashCtx.
typedef int(*	PBS_crashHandler )(PBS_crashType type, const PBS_crashCtx ctx, unsigned int options, const char string)
	User callback routine to handle a crash.
typedef enum _PBS_crashOptions	PBS_crashOptions
	Typedef for.
Enumerations
enum	_PBS_crashOptions { PBS_M_CRASH_OPTION_CRASH_NO = (1<<31), PBS_M_CRASH_OPTION_VX_REBOOT_QUICK = (1<< 30), PBS_M_CRASH_OPTION_VX_REBOOT_CLEAR = (1<< 29), PBS_M_CRASH_OPTION_VX_REBOOT_NOAUTO = (1<< 28) }
	Enumerates those bits of the options argument that PBS uses. More...
Functions
void	PBS_fast_clear (void *ptr, unsigned int nbytes)
	Clears (Zeroes) the specified memory.
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 (void)
	Shuts down the PBS facility.
void	PBS_crash (PBS_crashType type, const PBS_crashCtx ctx, unsigned int options, const char string)
	General purposes reboot routine.
void	PBS_panic (unsigned int reason, unsigned int parameter, void pc, unsigned int options, const char string)
	Routine to initiate a panic reboot.
void	PBS_reboot (unsigned int reason, unsigned int parameter, void pc, unsigned int options, const char string)
	Routine to initiate a commanded reboot.
PBS_crashHandler	PBS_crashHandlerSet (PBS_crashHandler crashHandler)
	Installs a new user crash handler.
int	PBS_crashPrint (PBS_crashType type, const PBS_crashCtx ctx, unsigned int options, const char string)
	Very simple default PBS crash handler.