latc.c File Reference

Provides the functionality associated with the principal LAT configuration interface along with the additional functions required by LPA and LCI. More...

#include "LATC/LATC_msgs.h"
#include "latc_p.h"
#include "enums_p.h"
#include "consume.h"
#include "data.h"
#include "record.h"
#include "latp_p.h"
#include "AG_regEnums_s.h"
#include "number.ic"
#include "PBS/MBA.h"
#include "PBS/WCT.h"
#include "MSG/MSG_pubdefs.h"
#include "LEM/list.h"

Functions
LATC_controller *	LATC_new (void)
	Allocate a new controller.
void	LATC_delete (LATC_controller *cnt)
	Release the previously allocated resources.
unsigned	LATC_initialise (void)
	Allocate the resources required for LATC.
unsigned	LATC_teardown (void)
	Release the resources acquired by LATC_initialise.
unsigned	LATC_cache (unsigned fid)
	Read a LATC configuration.
unsigned	LATC_configure (LATC_source source, unsigned runId)
	Configure the LAT using the currently cached configuration.
unsigned	LATC_verify (LATC_source source, unsigned runId)
	Verify the captured configuration of the LAT matches the in-memory cache.
unsigned	LATC_capture (void)
	Read the registers of the LAT.
unsigned	LATC_consign (unsigned dst)
	Write out the captured data to file/SSR.
unsigned	LATC_ignore (unsigned fid)
	Read the LATC ignore map file.
unsigned	LATC_getCacheKey (void)
	Return the file key identifying the last cached configuration.
unsigned	LATC_getConfigureKey (void)
	Return the file key identifying the last configuration loaded.
unsigned	LATC_getIgnoreKey (void)
	Return the file key identifying the ignore map.
unsigned	LATC_loadAfeConfig (unsigned int mask, unsigned int value0, unsigned int value1, unsigned int rcMask, unsigned int feMask)
	Load the AFE configuration register.
unsigned	LATC_loadCfeConfig0 (unsigned int mask, unsigned int value)
	Load CFE configuration register 0.
unsigned	LATC_loadCfeConfig1 (unsigned int mask, unsigned int value0, unsigned int value1, unsigned int cMask)
	Load CFE configuration register 1.
unsigned	LATC_loadTkrSplits (int nLow, int nHigh)
	Load TKR splits values.
unsigned	LATC_loadTfeDac (unsigned int mask, unsigned int value, int nLow, int nHigh)
	Load the TFE DAC register.
unsigned	LATC_enableTriggers (int marker)
	Enable triggers.
unsigned	LATC_disableTriggers (int marker)
	Disable triggers.
unsigned	LATC_getHskInfo (LATC_hsk *info)
	Get LATC housekeeping information.
unsigned	LATC_sizeofHskInfo (void)
	Get the size of the LATC housekeeping information.
unsigned	LATC_setDirty (void)
	Set the LATC "dirty" flag.
Variables
static LATC_controller *	latc
	Pointer to the global LATC_controller structure.

---

Detailed Description

Provides the functionality associated with the principal LAT configuration interface along with the additional functions required by LPA and LCI.

Author:

James Swain & Owen Saxton

Id

latc.c,v 1.47 2007/08/26 21:28:05 saxton Exp

---

Function Documentation

unsigned LATC_cache

(

unsigned

fid

)

Read a LATC configuration.

Parameters:

fid

The file ID of the master configuration file.

Return values:

	LATC_SUCCESS	if all goes well
	LATC_BADFOPEN	if the fid, or any of the names the configuration master file contains, does not match a valid file.
	LATC_BADTYPE	if the file contains a bad type identifier
	LATC_BADREAD	if an error occurs while the file is being read

References LATC_controller::cache, LATC_controller::cacheFid, and LATC_controller::cacheKey.

unsigned LATC_capture

(

void

)

Read the registers of the LAT.

Return values:

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

References LATC_controller::cache, LATC_controller::capture, checkBit(), LATC_controller::cr, LATC_controller::decode, LATC_controller::ignore, and LATC_read().

unsigned LATC_configure	(	LATC_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:

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

References _LATC_hsk::appConfig, _LATC_hsk::appRunId, _LATC_hsk::appSource, _LATC_hsk::appStatus, _LATC_hsk::appTimeSec, _LATC_hsk::appTimeSub, LATC_controller::cache, LATC_controller::cacheFid, LATC_controller::cacheKey, LATC_controller::configKey, LATC_controller::cr, _LATC_hsk::dirty, LATC_controller::hsk, and LATC_load().

unsigned LATC_consign

(

unsigned

dst

)

Write out the captured data to file/SSR.

Parameters:

dst

Ignored

Return values:

	LATC_SUCCESS	if all goes well.
	LATC_BADFOPEN	if the file cannot be created
	LATC_BADWRITE	if the final write of the buffer failed
	LATC_BADCLOSE	if the file close failed
	LATC_BADWRITE	if either the map or the configuration data write has an error

References LATC_controller::capture, LATC_controller::fpa, and LATC_record().

void LATC_delete

(

LATC_controller *

cnt

)

Release the previously allocated resources.

Parameters:

cnt

Pointer to the controller structure

References LATC_controller::buf, LATC_controller::cache, LATC_controller::capture, LATC_controller::cr, LATC_controller::decode, LATC_controller::fpa, LATC_controller::hsk, and LATC_controller::ignore.

Referenced by LATC_new(), and LATC_teardown().

unsigned LATC_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 LATC cache.

Parameters:

marker

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

Return values:

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

References LATC_controller::cache, LATC_controller::cr, and setTrigger().

unsigned LATC_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 LATC cache.

Parameters:

marker

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

Return values:

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

References LATC_controller::cache, LATC_controller::cr, and setTrigger().

unsigned LATC_getCacheKey

(

void

)

Return the file key identifying the last cached configuration.

Returns:

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

References LATC_controller::cacheKey.

unsigned LATC_getConfigureKey

(

void

)

Return the file key identifying the last configuration loaded.

Returns:

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

References LATC_controller::configKey.

unsigned LATC_getHskInfo

(

LATC_hsk *

info

)

Get LATC housekeeping information.

LATC housekeeping information is copied to the supplied area.

Parameters:

info

The address of the area to receive the housekeeping information.

Return values:

LATC_SUCCESS

Always success

References LATC_controller::hsk.

unsigned LATC_getIgnoreKey

(

void

)

Return the file key identifying the ignore map.

Returns:

The file key for the ignore file

References LATC_controller::ignoreKey.

unsigned LATC_ignore

(

unsigned

fid

)

Read the LATC ignore map file.

Parameters:

fid

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

Return values:

LATC_SUCCESS

if all goes well

References LATC_controller::ignore, LATC_controller::ignoreFid, and LATC_controller::ignoreKey.

unsigned LATC_initialise

(

void

)

Allocate the resources required for LATC.

Return values:

	LATC_SUCCESS	Success
	LATC_BADALLOC	If there was an error allocating memory

References LATC_new().

unsigned LATC_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:

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

References LATC_controller::cache, LATC_controller::cr, and loadAfeConfig().

unsigned LATC_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:

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

References LATC_controller::cache, LATC_controller::cr, and loadCfeConfig0().

unsigned LATC_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:

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

References LATC_controller::cache, LATC_controller::cr, and loadCfeConfig1().

unsigned LATC_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:

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

References LATC_controller::cache, LATC_controller::cr, and loadTfeDac().

unsigned LATC_loadTkrSplits	(	int	nLow,
		int	nHigh
	)

Load TKR splits 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:

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

References LATC_controller::cache, LATC_controller::cr, and loadTkrSplits().

LATC_controller* LATC_new

(

void

)

Allocate a new controller.

Allocate the resources required for the LATC_controller structure and initialise it

Returns:

Pointer to an allocated and initialised LATC_controller structure

References LATC_controller::buf, LATC_controller::cache, LATC_controller::capture, LATC_controller::cr, LATC_controller::decode, DECODE_SIZE, LATC_controller::fpa, LATC_controller::hsk, LATC_controller::ignore, and LATC_delete().

Referenced by LATC_initialise().

unsigned LATC_setDirty

(

void

)

Set the LATC "dirty" flag.

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

Return values:

LATC_SUCCESS

Always success.

References _LATC_hsk::dirty, and LATC_controller::hsk.

unsigned LATC_sizeofHskInfo

(

void

)

Get the size of the LATC housekeeping information.

The size of the LATC housekeeping information block is returned.

Returns:

The size (in bytes) of the LATC housekeeping information.

unsigned LATC_teardown

(

void

)

Release the resources acquired by LATC_initialise.

Return values:

LATC_SUCCESS

Always

References LATC_delete().

unsigned LATC_verify	(	LATC_source	source,
		unsigned	runId
	)

Verify 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:

	LATC_SUCCESS	If the current LAT state matches the cached
	LATC_DIFFER	If the current LAT state differs from the cached

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