LCFG.h File Reference

Public definitions for the LAT configuration system (LCFG). More...

#include <RIM/RIM.h>

Classes
struct	_LCFG_hsk
	Structure to hold LCFG housekeeping information. More...
Typedefs
typedef enum _LCFG_source	LCFG_source
	Identifiers for callers of configure and verify.
typedef RIM_type	LCFG_type
	Type used to identify components (TEM, TFE etc).
typedef RIM_addr	LCFG_addr
	Type used to define an address.
typedef struct _LCFG_hsk	LCFG_hsk
	Structure to hold LCFG housekeeping information.
Enumerations
enum	_LCFG_source {   LCFG_SRC_UNKNOWN = 0,   LCFG_SRC_LPA = 1,   LCFG_SRC_LCI = 2,   LCFG_SRC_COMMAND = 3 }
	Identifiers for callers of configure and verify. More...
enum	{ LCFG_BAD_TYPE = RIM_BAD_TYPE }
	Value for an unrecognized type.
enum	{   LCFG_BCAST_ADDR = RIM_BCAST_ADDR,   N_LCFG_ADDR_CPTS = N_RIM_ADDR_CPTS }
	Constants associated with addressing LAT component instances.
Functions
unsigned	LCFG_cache (unsigned fid)
	Read a LAT configuration.
unsigned	LCFG_capture (void)
	Read the registers of the LAT.
unsigned	LCFG_configure (LCFG_source source, unsigned runId)
	Configure the LAT using the currently cached configuration.
unsigned	LCFG_consign (unsigned dst)
	Write out the captured data to the SSR.
unsigned	LCFG_disableTriggers (int marker)
	Disable triggers.
unsigned	LCFG_enableTriggers (int marker)
	Enable triggers.
unsigned	LCFG_getCacheKey (void)
	Return the file key identifying the last cached configuration.
unsigned	LCFG_getConfigureKey (void)
	Return the file key identifying the last configuration loaded.
unsigned	LCFG_getHskInfo (LCFG_hsk *info)
	Get LAT configuration housekeeping information.
unsigned	LCFG_getIgnoreKey (void)
	Return the file key identifying the ignore map.
unsigned	LCFG_ignore (unsigned fid)
	Read the ignore map from the file identified by fid.
unsigned	LCFG_initialise (void)
	Allocate the resources required for LCFG.
unsigned	LCFG_loadAfeConfig (unsigned int mask, unsigned int value0, unsigned int value1, unsigned int rcMask, unsigned int feMask)
	Load the AFE configuration register.
unsigned	LCFG_loadCfeConfig0 (unsigned int mask, unsigned int value)
	Load CFE configuration register 0.
unsigned	LCFG_loadCfeConfig1 (unsigned int mask, unsigned int value0, unsigned int value1, unsigned int cMask)
	Load CFE configuration register 1.
unsigned	LCFG_loadTfeDac (unsigned int mask, unsigned int value, int nLow, int nHigh)
	Load the TFE DAC register.
unsigned	LCFG_loadTkrSplits (int nLow, int nHigh)
	Load TKR split values.
unsigned	LCFG_setDirty (void)
	Set the LCFG "dirty" flag.
unsigned	LCFG_sizeofHskInfo (void)
	Get the size of the LAT configuration housekeeping information.
unsigned	LCFG_teardown (void)
	Release the resources acquired by LCFG_initialise.
unsigned	LCFG_verify (LCFG_source source, unsigned runId)
	Verify that the captured configuration of the LAT matches the in-memory cache.

---

Detailed Description

Public definitions for the LAT configuration system (LCFG).

Author:

James Swain & Owen Saxton

Id

LCFG.h,v 1.4 2011/03/27 17:14:05 saxton Exp

---

Enumeration Type Documentation

enum _LCFG_source

Identifiers for callers of configure and verify.

Enumerator:

LCFG_SRC_UNKNOWN	Unknown.
LCFG_SRC_LPA	LPA.
LCFG_SRC_LCI	LCI.
LCFG_SRC_COMMAND	Command.

---

Function Documentation

unsigned LCFG_cache

(

unsigned

fid

)

Read a LAT configuration.

Parameters:

fid

The file ID of the master file containing the file IDs of the LAT configuration files to be read

Return values:

	LCFG_SUCCESS	if all goes well
	LCFG_BADFOPEN	if the fid, or any of the names the configuration master file contains, does not match a valid file.
	LCFG_BADTYPE	if the file contains a bad type identifier
	LCFG_BADREAD	if an error occurs while the file is being read

References LCFG_controller::cache, LCFG_controller::cacheFid, LCFG_controller::cacheKey, and LCFG_consume().

unsigned LCFG_capture

(

void

)

Read the registers of the LAT.

Return values:

	LCFG_SUCCESS	if all goes well
	LEM_*	if there was an error arising from one of the read commands

References LCFG_controller::cache, LCFG_controller::capture, LCFG_controller::cr, LCFG_decode::cr, LCFG_controller::decode, LCFG_decode::di, LCFG_finishRead(), LCFG_controller::read, and LCFG_controller::rqi.

unsigned LCFG_configure	(	LCFG_source	source,
		unsigned	runId
	)

Configure the LAT using the currently cached configuration.

Parameters:

	source	The identity of the caller (LPA, LCI, command)
	runId	The ID of the run associated with an LPA or LCI source

Return values:

	LCFG_SUCCESS	if all goes well
	LEM_*	if there are errors arising from the register load commands

References _LCFG_hsk::appConfig, _LCFG_hsk::appRunId, _LCFG_hsk::appSource, _LCFG_hsk::appStatus, _LCFG_hsk::appTimeSec, _LCFG_hsk::appTimeSub, LCFG_controller::cache, LCFG_controller::cacheFid, LCFG_controller::cacheKey, LCFG_controller::configKey, LCFG_controller::cr, _LCFG_hsk::dirty, LCFG_controller::hsk, LCFG_finishLoad(), and LCFG_controller::load.

unsigned LCFG_consign

(

unsigned

dst

)

Write out the captured data to the SSR.

Parameters:

dst

Ignored

Return values:

	LCFG_SUCCESS	if all goes well.
	LCFG_BADFOPEN	if the file cannot be created
	LCFG_BADWRITE	if the final write of the buffer failed
	LCFG_BADCLOSE	if the file close failed
	LCFG_BADWRITE	if either the map or the configuration data write has an error

References LCFG_controller::capture, LCFG_controller::fpa, and LCFG_record().

unsigned LCFG_disableTriggers

(

int

marker

)

Disable triggers.

The window open mask is cleared. If the marker parameter is non-zero, the LAT is first configured to broadcast a trigger message to CPUs upon receipt of a solicited trigger, a solicited trigger is fired, and the configuration restored from the LCFG cache.

Parameters:

marker

If non-zero, causes a solicited trigger with this value in the event data.

Return values:

	LCFG_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References LCFG_controller::cache, LCFG_controller::cr, and LCFG_setTrigger().

unsigned LCFG_enableTriggers

(

int

marker

)

Enable triggers.

The window open mask is loaded with the value held in the cache. If the marker parameter is non-zero, the LAT is first configured to broadcast a trigger message to CPUs upon receipt of a solicited trigger, a solicited trigger is fired, and the configuration restored from the LCFG cache.

Parameters:

marker

If non-zero, causes a solicited trigger with this value in the event data.

Return values:

	LCFG_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References LCFG_controller::cache, LCFG_controller::cr, and LCFG_setTrigger().

unsigned LCFG_getCacheKey

(

void

)

Return the file key identifying the last cached configuration.

Returns:

The file key for the LCFG master file of the last cached configuration

References LCFG_controller::cacheKey.

unsigned LCFG_getConfigureKey

(

void

)

Return the file key identifying the last configuration loaded.

Returns:

The file key for the LCFG master file of the last configuration loaded

References LCFG_controller::configKey.

unsigned LCFG_getHskInfo

(

LCFG_hsk *

info

)

Get LAT configuration housekeeping information.

LAT configuration housekeeping information is copied to the supplied area.

Parameters:

info

The address of the area to receive the housekeeping information.

Return values:

LCFG_SUCCESS

Always success

References LCFG_controller::hsk.

unsigned LCFG_getIgnoreKey

(

void

)

Return the file key identifying the ignore map.

Returns:

The file key for the ignore file

References LCFG_controller::ignoreKey.

unsigned LCFG_ignore

(

unsigned

fid

)

Read the ignore map from the file identified by fid.

Parameters:

fid

ID of the file containing the map data to use as the ignore map

Return values:

LCFG_SUCCESS

if all goes well

References LCFG_controller::ignore, LCFG_controller::ignoreFid, LCFG_controller::ignoreKey, and LCFG_consumeMap().

unsigned LCFG_initialise

(

void

)

Allocate the resources required for LCFG.

Return values:

	LCFG_SUCCESS	If the control structure was allocated and initialised successfully
	LCFG_BADALLOC	If there was an error allocating memory
	LCFG_FPAINIT	If fixed packet initialization failed

References LCFG_controller::buf, LCFG_controller::cache, LCFG_controller::capture, LCFG_controller::cr, LCFG_controller::decode, LCFG_controller::fpa, LCFG_controller::hsk, LCFG_controller::ignore, LCFG_DATAGRAM_SIZE, LCFG_N_DATAGRAMS, LCFG_newDecode(), LCFG_newLoad(), LCFG_newRead(), LCFG_teardown(), LCFG_controller::load, LCFG_controller::read, and LCFG_controller::rqi.

unsigned LCFG_loadAfeConfig	(	unsigned int	mask,
		unsigned int	value0,
		unsigned int	value1,
		unsigned int	rcMask,
		unsigned int	feMask
	)

Load the AFE configuration register.

The AFE configuration register is loaded with a modified version of the value from the LAT configuration, with the specified bits replaced.

Parameters:

	mask	Mask of bits to be changed from the configuration.
	value0	The value to be masked and merged with the configuration value for front-ends not selected by the RC and FE masks.
	value1	The value to be masked and merged with the configuration value for front-ends selected by the RC and FE masks.
	rcMask	Mask of bits, one per RC, specifying which RCs are selected.
	feMask	Mask of bits, one per FE, specifying which FEs within selected RCs are selected.

Return values:

	LCFG_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References LCFG_controller::cache, LCFG_controller::cr, LCFG_finishLoad(), and LCFG_controller::load.

unsigned LCFG_loadCfeConfig0	(	unsigned int	mask,
		unsigned int	value
	)

Load CFE configuration register 0.

CFE configuration register 0 is loaded with a modified version of the value from the LAT configuration, with the specified bits replaced.

Parameters:

	mask	Mask of bits to be changed from the configuration.
	value	The value to be masked and merged with the configuration value.

Return values:

	LCFG_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References LCFG_controller::cache, LCFG_controller::cr, LCFG_finishLoad(), and LCFG_controller::load.

unsigned LCFG_loadCfeConfig1	(	unsigned int	mask,
		unsigned int	value0,
		unsigned int	value1,
		unsigned int	cMask
	)

Load CFE configuration register 1.

CFE configuration register 1 is loaded with a modified version of the value from the LAT configuration, with the specified bits replaced.

Parameters:

	mask	Mask of bits to be changed from the configuration.
	value0	The value to be masked and merged with the configuration value for front-ends whose bit is clear in the column mask.
	value1	The value to be masked and merged with the configuration value for front-ends whose bit is set in the column mask.
	cMask	Mask of bits, one per column, specifying which value is to be used for loading the config register.

Return values:

	LCFG_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References LCFG_controller::cache, LCFG_controller::cr, LCFG_finishLoad(), and LCFG_controller::load.

unsigned LCFG_loadTfeDac	(	unsigned int	mask,
		unsigned int	value,
		int	nLow,
		int	nHigh
	)

Load the TFE DAC register.

The TFE DAC register is loaded with a modified version of the value from the LAT configuration, with the specified bits replaced.

Parameters:

	mask	Mask of bits to be changed from the configuration.
	value	The value to be masked and merged with the configuration value.
	nLow	Number of TFEs talking on the low side, or -1 if the configured values are being used.
	nHigh	Number of TFEs talking on the high side, or -1 if the configured values are being used.

Return values:

	LCFG_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References LCFG_controller::cache, LCFG_controller::cr, LCFG_finishLoad(), and LCFG_controller::load.

unsigned LCFG_loadTkrSplits	(	int	nLow,
		int	nHigh
	)

Load TKR split values.

The tracker RC and FE registers are loaded to reflect the given split values.

Parameters:

	nLow	Number of TFEs to talk on the low side, or -1 if the configured values are to be used.
	nHigh	Number of TFEs to talk on the high side, or -1 if the configured values are to be used.

Return values:

	LCFG_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References LCFG_controller::cache, LCFG_controller::cr, LCFG_finishLoad(), and LCFG_controller::load.

unsigned LCFG_setDirty

(

void

)

Set the LCFG "dirty" flag.

This routine is used to indicate that a register whose value is normally managed by LCFG has had its value changed externally, e.g. by LRA.

Return values:

LCFG_SUCCESS

Always success.

References _LCFG_hsk::dirty, and LCFG_controller::hsk.

unsigned LCFG_sizeofHskInfo

(

void

)

Get the size of the LAT configuration housekeeping information.

The size of the LAT configuration housekeeping information block is returned.

Returns:

The size (in bytes) of the housekeeping information.

unsigned LCFG_teardown

(

void

)

Release the resources acquired by LCFG_initialise.

Return values:

LCFG_SUCCESS

This function cannot fail - the return code is for future expansion

References LCFG_controller::buf, LCFG_controller::cache, LCFG_controller::capture, LCFG_controller::cr, LCFG_controller::decode, LCFG_controller::fpa, LCFG_controller::hsk, LCFG_controller::ignore, LCFG_deleteDecode(), LCFG_deleteLoad(), LCFG_deleteRead(), LCFG_controller::load, LCFG_controller::read, and LCFG_controller::rqi.

Referenced by LCFG_initialise().

unsigned LCFG_verify	(	LCFG_source	source,
		unsigned	runId
	)

Verify that the captured configuration of the LAT matches the in-memory cache.

Parameters:

	source	The identity of the caller (LPA, LCI, command)
	runId	The ID of the run associated with an LPA or LCI source

Return values:

	LCFG_SUCCESS	If the current LAT state matches the cached LAT state
	LCFG_DIFFER	If the current LAT state differs from the cached LAT state

References _LCFG_hsk::appConfig, LCFG_controller::cache, LCFG_controller::capture, LCFG_controller::hsk, LCFG_controller::ignore, LCFG_controller::ignoreFid, _LCFG_hsk::verConfig, _LCFG_hsk::verIgnore, _LCFG_hsk::verRunId, _LCFG_hsk::verSource, _LCFG_hsk::verStatus, _LCFG_hsk::verTimeSec, and _LCFG_hsk::verTimeSub.