lci_p.h File Reference

Internal definitions for the LCI system. More...

#include <LCI/lci.h>
#include <LSEC/LSEC.h>
#include <EDS/EBF_pkt.h>
#include <EDS/EBF_dir.h>
#include <LCBD/LCBD_evt.h>
#include <LEM/list.h>
#include <ITC/ITC_pubdefs.h>
#include <stdio.h>

Typedefs
typedef struct _LCI_controller	LCI_controller
	Declaration of the opaque controller structure.
typedef struct _LCI_collection	LCI_collection
	Declaration of the opaque collection structure.
typedef struct _LCI_configuration	LCI_configuration
	Declaration of the opaque configuration structure.
typedef struct _LCI_cue	LCI_cue
	Declaration of the opaque cue structure.
Enumerations
enum	{   LCI_CNF_MAJ = 6,   LCI_CNF_MIN = 0 }
	Current version.
enum	{   LCI_MIN_PERIOD = 20000,   LCI_DEF_PERIOD = 20000,   LCI_CNF_ULATC = 0xffff,   LCI_CNF_INCREMENTED = 0,   LCI_CNF_RESTARTED = 1,   LCI_CNF_NO_RELOAD = 0,   LCI_CNF_RELOAD = 1,   GEM_N_TAM_REGS = 16,   GEM_N_SCHD_REGS = 32 }
	Configuration constants.
enum	_LCI_monType {   LCI_MON_TIMES = 0x01,   LCI_MON_CYCLES = 0x02 }
	Monitoring type flags. More...
enum	LCI_CUE_END {   LCI_CUE_FAILED = -1,   LCI_CUE_UNSET = 0,   LCI_CUE_SIGNALED = 1,   LCI_CUE_TIMEDOUT = 2 }
	State information returned from LCI_waitCue indicating how the cue was terminated. More...
Functions
void	LCI_abort (void)
	Abort a calibration.
unsigned	LCI_calibrate (unsigned latccfg, unsigned lcicfg, unsigned lcirunid, ITC_NodeID iniNode, ITC_TaskID iniTask, ITC_QueueID iniQueue)
	Start a new calibration.
void	LCI_cb_statusFree (ITC_QueueItem *qitem, unsigned int status, void *prm0, void *prm1, void *prm2, unsigned int tx)
	ITC send completion callback.
unsigned	LCI_comp (unsigned comp)
	Set the calibration compression level.
unsigned	LCI_cycle (void *prm, const struct _ITC_QueueItem *qitem, void *pay, unsigned int len)
	Perform a single calibration cycle.
unsigned	LCI_cycles (void)
	Get the calibration cycle count.
void	LCI_deleteController (LCI_controller *cnt)
	Free the calibration controller structure.
unsigned	LCI_init (unsigned capacity, unsigned cpuid, unsigned srcid)
	Initialize the calibration system.
unsigned	LCI_monitor (unsigned mon)
	Set the calibration monitoring level.
LCI_controller *	LCI_newController (unsigned cap, unsigned cpuid, unsigned srcid)
	Create calibration controller structure.
unsigned	LCI_start (const TASK_attr *attr)
	Start the LCI task.
unsigned	LCI_startCycle (void)
	Request the next calibration cycle.
unsigned	LCI_status (void)
	Get the calibration state.
unsigned	LCI_terminate (unsigned status)
	Terminate a calibration.
void	LCI_collClearCounts (LCI_collection *cll)
	Clear collection counters.
void	LCI_collCounts (LCI_collection *cll, unsigned int *nWait, unsigned int *nSignal, unsigned int *nTimeout)
	Get collection counters.
LCI_collection *	LCI_collCreate (LSEC_control *lsec)
	Allocate and initialise a collection structure.
void	LCI_collDelete (LCI_collection *cll)
	Free a structure previously allocated using LCI_collCreate.
unsigned	LCI_collect (LCI_collection *cll, unsigned nev, unsigned period)
	Initiate the calibration triggers and wait for each event to be collected and constructed.
unsigned	LCI_collected (LCI_collection *cll)
	Get the number of events collected.
void	LCI_collRunInit (LCI_collection *cll, LCBD lcbd, LEM_micr *cr)
	Initialize for a new calibration run.
void	LCI_collRunTerm (LCI_collection *cll)
	Terminate a calibration run.
void	LCI_collTime (LCI_collection *cll, int clear, long long *ctime)
	Return accumulated collection time.
unsigned	LCI_confBufferModel (unsigned select, LEM_micr *cr, unsigned *mods)
	Set the TEM buffer model.
unsigned	LCI_confCache (LCI_configuration *cnf, unsigned latc_fid)
	Read in the LATC files.
unsigned	LCI_confClose (LCI_configuration *cnf)
	Close the file that acts as the source of the configuration.
void	LCI_confCopy (LCI_configuration *cnfIn, LCI_configuration *cnfOut)
	Copy a configuration.
LCI_configuration *	LCI_confCreate (LSEC_control *lsec)
	Create a new configuration structure.
void	LCI_confDelete (LCI_configuration *cnf)
	Free memory previously allocated with a call to LCI_confCreate.
unsigned	LCI_configure (LCI_configuration *cnf, LEM_micr *cr, unsigned runId)
	Load the configuration onto the LAT.
unsigned	LCI_confMode (LCI_configuration *cnf)
	Return the configuration type.
void	LCI_confNodeId (LCI_configuration *cnf, unsigned siu_id)
	Set the destination address to be used in the TAM configuration.
unsigned	LCI_confOpen (LCI_configuration *cnf, const char *fn)
	Open the file and associate it with this configuration structure.
unsigned	LCI_confOpenFid (LCI_configuration *cnf, unsigned fid)
	Open the file and associate it with this configuration structure.
unsigned	LCI_confPeriod (LCI_configuration *cnf)
	Return the period between triggers.
unsigned	LCI_confRead (LCI_configuration *cnf)
	Get the values for the next step of the configuration.
void	LCI_confReport (LCI_configuration *cnf, FILE *fp)
	Produce a formatted report of the contents of a binary configuration.
void	LCI_confTimes (LCI_configuration *cnf, int clear, long long *lci_time, long long *lat_time)
	Return accumulated configuration times.
unsigned	LCI_confTriggers (LCI_configuration *cnf)
	Return the number of triggers required.
void	LCI_clearCue (LCI_cue *cue)
	Clear a cue.
void	LCI_clearCueCounts (LCI_cue *cue)
	Clear cue counters.
unsigned	LCI_deleteCue (LCI_cue *cue)
	Delete a cue.
void	LCI_getCueCounts (LCI_cue *cue, unsigned int *nWait, unsigned int *nSignal, unsigned int *nTimeout)
	Get cue counters.
LCI_cue *	LCI_newCue (void)
	Create a new cue.
void	LCI_signalCue (LCI_cue *cue)
	Signal cue completion.
unsigned	LCI_waitCue (LCI_cue *cue, unsigned timeout)
	Wait for a cue to complete or time out.
Variables
enum _LCI_monType	LCI_monType

---

Detailed Description

Internal definitions for the LCI system.

Author:

James Swain & Owen Saxton

$Id: lci_p.h,v 1.2 2011/03/29 19:32:57 saxton Exp $

---

Enumeration Type Documentation

enum _LCI_monType

Monitoring type flags.

Enumerator:

LCI_MON_TIMES	Show times at the end of a calibration.
LCI_MON_CYCLES	Show cycle number at start of each cycle.

enum LCI_CUE_END

State information returned from LCI_waitCue indicating how the cue was terminated.

Enumerator:

LCI_CUE_FAILED	The wake-up timer failed to start.
LCI_CUE_UNSET	No end state to report (the cue has never been used or is currently waiting)
LCI_CUE_SIGNALED	The cue was signalled.
LCI_CUE_TIMEDOUT	The wake-up timer went off.

---

Function Documentation

void LCI_abort

(

void

)

Abort a calibration.

This routine is called when an abort calibration telecommand is received. If the current state is calibrating, it changes the state to aborting

Referenced by LCI_ABORT().

unsigned LCI_calibrate	(	unsigned	latccfg,
		unsigned	lcicfg,
		unsigned	lcirunid,
		ITC_NodeID	iniNode,
		ITC_TaskID	iniTask,
		ITC_QueueID	iniQueue
	)

Start a new calibration.

This routine is called when a start calibration telecommand is received. It first uses LATC to perform an initial LAT configuration then peforms a configure, collect, compact, consign cycle for each LCI configuration in the LCI file.

Parameters:

latccfg	File ID for the LATC configuration master to use with this calibration
lcicfg	File ID for the LCI configuration file to use to drive this calibration
lcirunid	Run ID to use in the datagrams
iniNode	Node ID of the task that initiated the calibration (used to send a message back when the calibration completes)
iniTask	Task ID of the task that initiated the calibration (used to send a message back when the calibration completes)
iniQueue	ID of the queue that will receive the status message.

Return values:

LCI_STATE	LCI is not in the correct state to start a calibration
ITC_ALOCFAIL	Memory allocation failure
ITC_FPAGET	Memory allocation from FPA failed
ITC_SENDNID	Invalid/unreachable destination node
ITC_SENDQID	Invalid/unreachable destination queue
ITC_SHRMEM	Shared memory pool stopping/stopped
ITC_SUCCESS	If an item is sent to the LCI bulk queue

References LCI_collClearCounts(), LCI_collRunInit(), LCI_collTime(), LCI_confBufferModel(), LCI_confCache(), LCI_confMode(), LCI_confNodeId(), LCI_confOpenFid(), LCI_confTimes(), LCI_startCycle(), and LCI_terminate().

Referenced by LCI_CALIBRATE().

void LCI_cb_statusFree	(	ITC_QueueItem *	qitem,
		unsigned int	status,
		void *	prm0,
		void *	prm1,
		void *	prm2,
		unsigned int	tx
	)

ITC send completion callback.

Completion call-back for use with ITC when sending the status back to the task that initiated calibration - just returns the qitem to the pool.

Parameters:

qitem	Queue item to be returned to the pool
status	Success or failure of the ITC delivery
prm0	User defined parameter 0 (pointer to the FPM pool)
prm1	User defined (NULL)
prm2	User defined (NULL)
tx	Transmission status

void LCI_clearCue

(

LCI_cue *

cue

)

Clear a cue.

This routine puts the cue into a known cleared state, ready for the next wait.

Parameters:

cue	Pointer to an allocated, initialised cue structure (from LCI_newCue)

References LCI_CUE_UNSET.

Referenced by LCI_collect().

void LCI_clearCueCounts

(

LCI_cue *

cue

)

Clear cue counters.

This routine zeroes the counts of waits, signals and timeouts.

Parameters:

cue	Pointer to a cue being used.

Referenced by LCI_collClearCounts().

void LCI_collClearCounts

(

LCI_collection *

cll

)

Clear collection counters.

This routine calls through to the cue counter clear routine.

Parameters:

cll	Pointer to an allocated and initialised collection structure that has been used to collect events

References LCI_clearCueCounts().

Referenced by LCI_calibrate().

void LCI_collCounts	(	LCI_collection *	cll,
		unsigned int *	nWait,
		unsigned int *	nSignal,
		unsigned int *	nTimeout
	)

Get collection counters.

This routine calls through to the cue counters get routine, returning the counts accumulated since the last clear.

Parameters:

cll	Pointer to a collection structure.
nWait	Address of an integer to receive the number of wait calls, or NULL if not needed.
nSignal	Address of an integer to receive the number of signal calls, or NULL if not needed.
nTimeout	Address of an integer to receive the number of timeouts, or NULL if not needed.

References LCI_getCueCounts().

Referenced by LCI_terminate().

LCI_collection* LCI_collCreate

(

LSEC_control *

lsec

)

Allocate and initialise a collection structure.

Parameters:

lsec	LSEC access handle.

Returns:

Pointer to an allocated, initialised LCI_collection

References LCI_collDelete(), and LCI_newCue().

Referenced by LCI_newController().

void LCI_collDelete

(

LCI_collection *

cll

)

Free a structure previously allocated using LCI_collCreate.

Parameters:

cll	Pointer to an allocated and initialised LCI_collection structure

References LCI_deleteCue().

Referenced by LCI_collCreate(), and LCI_deleteController().

unsigned LCI_collect	(	LCI_collection *	cll,
		unsigned	nev,
		unsigned	period
	)

Initiate the calibration triggers and wait for each event to be collected and constructed.

Parameters:

cll	Pointer to an intialised event collection structure
nev	Number of events to be collected
period	The period (in 50 ns ticks) between triggers

Return values:

LCI_SUCCESS	If all the expected events were successfully collected
LCI_LOSTEVT	If some of the events were not collected

References LCI_clearCue(), and LCI_waitCue().

unsigned LCI_collected

(

LCI_collection *

cll

)

Get the number of events collected.

Parameters:

cll	Pointer to an allocated and initialised collection structure that has been used to collect events

Returns:

Number of events collected

void LCI_collRunInit	(	LCI_collection *	cll,
		LCBD	lcbd,
		LEM_micr *	cr
	)

Initialize for a new calibration run.

This routine saves the lcbd and cr pointers and sets up the event callback routine.

Parameters:

cll	Pointer to a collection structure.
lcbd	Pointer to the LCB control block,
cr	Pointer to a multi-item command-response list.

Referenced by LCI_calibrate().

void LCI_collRunTerm

(

LCI_collection *

cll

)

Terminate a calibration run.

The event callback is set back to its original value.

Parameters:

cll	Pointer to a collection structure.

Referenced by LCI_terminate().

void LCI_collTime	(	LCI_collection *	cll,
		int	clear,
		long long *	ctime
	)

Return accumulated collection time.

Parameters:

cll	Pointer to a collection structure.
clear	If TRUE, clear the time after copying it.
ctime	Address of a variable to receive the accumulated time taken to do collections, or NULL if no time wanted.

Referenced by LCI_calibrate().

unsigned LCI_comp

(

unsigned

comp

)

Set the calibration compression level.

This routine sets the LCI compression level and returns the old value. This feature is used only for testing.

Parameters:

comp	Compression level to set LSEC_COMP_NORM Normal LSEC_COMP_ONLY None, send only data for type LSEC_COMP_NONE None, send all data

Returns:

Previous compression level

unsigned LCI_confBufferModel	(	unsigned	select,
		LEM_micr *	cr,
		unsigned *	mods
	)

Set the TEM buffer model.

This routine sets the value of the buffer model select bit in the TEM CONFIGURATION register, necessary because the calibration requires non-standard single buffering. It optionally also returns the operational state of the various data acquisition modules (TEMs, GEM and AEM), needed for event data checking.

Parameters:

select	Zero to select the multi buffer model, non-zero to select the single buffer model
cr	Pointer to the multi-item command/response list.
mods	Pointer to an integer to receive the bit mask of operational acquisition modules, or NULL if this information is not required.

Return values:

LCI_SUCCESS	Success
LCI_TEMCR	The command and response masks don't have the same TEMs present
LEM_*	If there was an error reading or loading one of the registers

Referenced by LCI_calibrate(), and LCI_terminate().

unsigned LCI_confCache	(	LCI_configuration *	cnf,
		unsigned	latc_fid
	)

Read in the LATC files.

Parameters:

cnf	Pointer to an initialised configuration structure
latc_fid	ID of the LATC configuration to cache

Return values:

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

References _LCI_configuration::latc, and _LCI_configuration::rld.

Referenced by LCI_calibrate().

unsigned LCI_confClose

(

LCI_configuration *

cnf

)

Close the file that acts as the source of the configuration.

Parameters:

cnf	Pointer to an opened configuration

Return values:

LCI_SUCCESS	If the file closes successfully
LCI_FCLOSE	If there is an error closing the file

References _LCI_configuration::fd.

Referenced by LCI_terminate().

void LCI_confCopy	(	LCI_configuration *	cnfIn,
		LCI_configuration *	cnfOut
	)

Copy a configuration.

Parameters:

cnfIn	The configuration structure to be copied from
cnfOut	The configuration structure to be copied to

LCI_configuration* LCI_confCreate

(

LSEC_control *

lsec

)

Create a new configuration structure.

Parameters:

lsec	The LSEC handle.

Returns:

Pointer to an allocated, initialised configuration structure

References _LCI_configuration::lsec.

Referenced by LCI_newController().

void LCI_confDelete

(

LCI_configuration *

cnf

)

Free memory previously allocated with a call to LCI_confCreate.

Parameters:

cnf	A configuration structure created by a call to LCI_confCreate

Referenced by LCI_deleteController().

unsigned LCI_configure	(	LCI_configuration *	cnf,
		LEM_micr *	cr,
		unsigned	runId
	)

Load the configuration onto the LAT.

Parameters:

cnf	Pointer to a populated configuration structure
cr	Pointer to the common configuration multi-item command response list
runId	The current run ID.

Returns:

LCI_SUCCESS if all goes well, or one of the LEM errors if there is a problem loading the configuration onto the LAT

References LCI_cnfValues::acd, LCI_cnfValues::cal, LCI_gemInput::delay, LCI_cnfInput::gem, _LCI_configuration::inp, _LCI_configuration::lat_time, LCI_gemInput::latcDelay, _LCI_configuration::lci_time, LCI_version::mode, _LCI_configuration::rld, _LCI_configuration::siu_id, LCI_cnfValues::tkr, _LCI_configuration::val, and _LCI_configuration::ver.

unsigned LCI_confMode

(

LCI_configuration *

cnf

)

Return the configuration type.

Parameters:

cnf	Pointer to the configuration structure

Returns:

One of LSEC_MODE_XXX

References LCI_version::mode, and _LCI_configuration::ver.

Referenced by LCI_calibrate().

void LCI_confNodeId	(	LCI_configuration *	cnf,
		unsigned	siu_id
	)

Set the destination address to be used in the TAM configuration.

Parameters:

cnf	Pointer to the configuration structure
siu_id	LATp address of the node that the events will be collected on

References _LCI_configuration::siu_id.

Referenced by LCI_calibrate().

unsigned LCI_confOpen	(	LCI_configuration *	cnf,
		const char *	fn
	)

Open the file and associate it with this configuration structure.

Parameters:

cnf	Pointer to an initialised configuration structure
fn	Name of file to open

Return values:

LCI_SUCCESS	if the file opens successfully
LCI_FOPEN	if the file failed to open successfully
LCI_FREAD	if there is an error recovering the version information (including file too short).
LCI_VERSION	if the file version information is bad (unknown type, major version mismatch, minor version decrease).

References LCI_cnfInput::acd, LCI_cnfValues::acd, LCI_cnfInput::cal, LCI_cnfValues::cal, _LCI_configuration::fd, LCI_cnfInput::gem, _LCI_configuration::inp, _LCI_configuration::lci, LCI_version::maj, LCI_version::min, LCI_version::mode, _LCI_configuration::rld, LCI_cnfInput::tkr, LCI_cnfValues::tkr, _LCI_configuration::val, and _LCI_configuration::ver.

Referenced by LCI_confOpenFid().

unsigned LCI_confOpenFid	(	LCI_configuration *	cnf,
		unsigned	fid
	)

Open the file and associate it with this configuration structure.

Parameters:

cnf	Pointer to an initialised configuration structure
fid	The ID of the file to open

Return values:

LCI_SUCCESS	if the file opens successfully
LCI_FOPEN	if the file failed to open successfully
LCI_FREAD	if there is an error recovering the version information (including file too short).
LCI_VERSION	if the file version information is bad (unknown type, major version mismatch, minor version decrease).

References _LCI_configuration::lci, and LCI_confOpen().

Referenced by LCI_calibrate().

unsigned LCI_confPeriod

(

LCI_configuration *

cnf

)

Return the period between triggers.

Parameters:

cnf	Pointer to an initialised, populated configuration structure

Returns:

The period between triggers (in 50ns clock ticks)

References LCI_cnfInput::gem, _LCI_configuration::inp, and LCI_gemInput::period.

unsigned LCI_confRead

(

LCI_configuration *

cnf

)

Get the values for the next step of the configuration.

Parameters:

cnf	Pointer to an opened configuration

Return values:

LCI_SUCCESS	if a configuration was read successfully
LCI_ENDOFILE	if there are no more configurations in the file (returned, but not reported).
LCI_FREAD	if there is an error during the read or the configuration is incomplete

References LCI_version::mode, and _LCI_configuration::ver.

void LCI_confReport	(	LCI_configuration *	cnf,
		FILE *	fp
	)

Produce a formatted report of the contents of a binary configuration.

Parameters:

cnf	Pointer to the configuration structure to output
fp	Pointer to file to print report

References LCI_version::maj, LCI_version::min, LCI_version::mode, and _LCI_configuration::ver.

void LCI_confTimes	(	LCI_configuration *	cnf,
		int	clear,
		long long *	lci_time,
		long long *	lat_time
	)

Return accumulated configuration times.

Parameters:

cnf	Pointer to an initialised, populated configuration structure.
clear	If TRUE, clear the times after copying them.
lci_time	Address of a variable to receive the accumulated time taken to do LCI configurations or NULL if the time is not wanted.
lat_time	Address of a variable to receive the accumulated time taken to do any LAT configurations or NULL if the time is not wanted.

References _LCI_configuration::lat_time, and _LCI_configuration::lci_time.

Referenced by LCI_calibrate().

unsigned LCI_confTriggers

(

LCI_configuration *

cnf

)

Return the number of triggers required.

Parameters:

cnf	Pointer to an initialised, populated configuration structure

Returns:

Number of triggers to request for this configuration

References LCI_cnfInput::gem, _LCI_configuration::inp, and LCI_gemInput::nev.

unsigned LCI_cycle	(	void *	prm,
		const struct _ITC_QueueItem *	qitem,
		void *	pay,
		unsigned int	len
	)

Perform a single calibration cycle.

This routine is called when a calibration cycle request is received. Provided there is configuration data to read and the abort flag has not been set, it performs a single calibration cycle and queues the next one if this one is successful.

Return values:

LCI_ABORTED	if the abort flag was found to be set at the start of the cycle
LCI_FOPER	if there is an error during the read or the configuration is incomplete
LCI_QITEM	The attempt to allocate a QueueItem fails
ITC_ALOCFAIL	Memory allocation failure
ITC_FPAGET	Memory allocation from FPA failed
ITC_SENDNID	Invalid/unreachable destination node
ITC_SENDQID	Invalid/unreachable destination queue
ITC_SHRMEM	Shared memory pool stopping/stopped
LCI_SUCCESS	if the calibration cycle is successfully completed

References LCI_MON_CYCLES, LCI_startCycle(), and LCI_terminate().

Referenced by LCI_init().

unsigned LCI_cycles

(

void

)

Get the calibration cycle count.

This rouine returns the number of cycles performed since the last calibration command was issued.

Returns:

Number of cycles performed since the last command to calibrate was issued

void LCI_deleteController

(

LCI_controller *

cnt

)

Free the calibration controller structure.

This routine frees all the resources associated with the LCI task.

References LCI_collDelete(), and LCI_confDelete().

Referenced by LCI_init(), LCI_newController(), and LCI_teardown().

unsigned LCI_deleteCue

(

LCI_cue *

cue

)

Delete a cue.

This routine destroys the semaphore and wake-up timer and then frees the memory associated with the cue structure

Parameters:

cue	Pointer to an initialised cue structure (make sure that it is not currently running!)

Return values:

LCI_SUCCESS	if all goes well
LCI_WUTDFAIL	if the wake-up timer could not be destroyed, because it was in a bad state

References LCI_CUE_UNSET.

Referenced by LCI_collDelete().

void LCI_getCueCounts	(	LCI_cue *	cue,
		unsigned int *	nWait,
		unsigned int *	nSignal,
		unsigned int *	nTimeout
	)

Get cue counters.

This routine obtains the counts of waits, signals and timeouts since the last time the cue was cleared.

Parameters:

cue	Pointer to a cue being used.
nWait	Address of an integer to receive the number of wait calls, or NULL if not needed.
nSignal	Address of an integer to receive the number of signal calls, or NULL if not needed.
nTimeout	Address of an integer to receive the number of timeouts, or NULL if not needed.

Referenced by LCI_collCounts().

unsigned LCI_init	(	unsigned	capacity,
		unsigned	cpuid,
		unsigned	srcid
	)

Initialize the calibration system.

This routine performs resource allocation, initializes the ITC message queues, and sets the state to INITIALISED.

Parameters:

srcid	ID of the source of data being processed through LCI
cpuid	ID of the CPU LCI is being run on
capacity	Maximum number of events per calibration cycle.

Returns:

LCI_SUCCESS if all goes well, otherwise one of many errors from LCI (typically LCI_MEMERROR if an allocation fails), PBS, IMM or ITC.

References LCI_Apid67c, LCI_Apid67d, LCI_cycle(), LCI_deleteController(), LCI_newController(), and LCI_teardown().

Referenced by LCI_initialise().

unsigned LCI_monitor

(

unsigned

mon

)

Set the calibration monitoring level.

This routine sets the LCI monitoring level and returns the old value.

Parameters:

mon	Monitoring level to set, as the logical OR of the bits: LCI_MON_TIMES Display timing information LCI_MON_CYCLES Display cycle information

Returns:

Previous monitoring level

LCI_controller* LCI_newController	(	unsigned	cap,
		unsigned	cpuid,
		unsigned	srcid
	)

Create calibration controller structure.

This routine allocates memory for an LCI_controller structure and all associated structures.

Parameters:

srcid	ID of the source of data being processed through LCI
cpuid	ID of the CPU LCI is being run on
cap	Capacity of the calibration task, the maximum number of events that can be collected each cycle

Returns:

Pointer to a new LCI_controller

References LCI_collCreate(), LCI_confCreate(), and LCI_deleteController().

Referenced by LCI_init().

LCI_cue* LCI_newCue

(

void

)

Create a new cue.

This routine allocates memory for the cue structure then creates the timer and semaphore to be held by the structure

Returns:

Pointer to an allocated and initialised cue structure, or NULL if there is an error.

Referenced by LCI_collCreate().

void LCI_signalCue

(

LCI_cue *

cue

)

Signal cue completion.

This routine signals completion by setting the end state to LCI_CUE_SIGNALED and giving the semaphore

Parameters:

cue	Pointer to a cue that is being waited upon

References LCI_CUE_SIGNALED.

unsigned LCI_start

(

const TASK_attr *

attr

)

Start the LCI task.

This routine starts the LCI task and waits for it be up and running before setting the state to WAITING.

Parameters:

attr	Task attributes to use for the LCI task.

Returns:

Error status code from ITC_startTaskW, LCI_STATE if the state is not INITIALISED, LCI_ATTRIBS if the task attribute pointer is NULL or LCI_SUCCESS if all goes well.

Referenced by LCI_startTask().

unsigned LCI_startCycle

(

void

)

Request the next calibration cycle.

This routine is called whenever the next (or first) calibration cycle is to be performed. It puts an empty item to the LCI bulk queue to initiate the cycle. This indirection is needed to allow any abort requests to be processed in a timely manner.

Return values:

LCI_QITEM	The attempt to allocate a QueueItem fails
ITC_ALOCFAIL	Memory allocation failure
ITC_FPAGET	Memory allocation from FPA failed
ITC_SENDNID	Invalid/unreachable destination node
ITC_SENDQID	Invalid/unreachable destination queue
ITC_SHRMEM	Shared memory pool stopping/stopped
ITC_SUCCESS	If an item is sent to the LCI bulk queue

!!! KULDGE - ITC won't accept a NULL payload pointer.

Referenced by LCI_calibrate(), and LCI_cycle().

unsigned LCI_status

(

void

)

Get the calibration state.

This routine returns the current state of LCI.

Returns:

Current state of LCI

unsigned LCI_terminate

(

unsigned

status

)

Terminate a calibration.

This routine finishes out the calibration by sending a status message back to the originating task and setting the state to WAITING.

Parameters:

status

Termination status of the last calibration cycle, and hence of the whole calibration

Return values:

ITC_SUCCESS	Success
LCI_QITEM	The attempt to allocate a QueueItem fails
ITC_ALOCFAIL	Memory allocation failure
ITC_FPAGET	Memory allocation from FPA failed
ITC_SENDNID	Invalid/unreachable destination node
ITC_SENDQID	Invalid/unreachable destination queue
ITC_SHRMEM	Shared memory pool stopping/stopped

References LCI_collCounts(), LCI_collRunTerm(), LCI_confBufferModel(), LCI_confClose(), and LCI_MON_TIMES.

Referenced by LCI_calibrate(), and LCI_cycle().

unsigned LCI_waitCue	(	LCI_cue *	cue,
		unsigned	timeout
	)

Wait for a cue to complete or time out.

This routine starts the wake-up timer and takes the semaphore

Parameters:

cue	Pointer to an allocated, initialised cue structure (from LCI_newCue)
timeout	Time, in microseconds, until the call times out.

Return values:

LCI_CUE_SIGNALED	Another task called signal
LCI_CUE_TIMEDOUT	If the timer expired before the cue was signalled.
LCI_CUE_FAILED	Timer failed to start (because of incorrect state)

References cue_wut_cb(), and LCI_CUE_FAILED.

Referenced by LCI_collect().