control.c File Reference

Principal routines of the charge injection calibration utility. More...

#include <lci_p.h>
#include <LCI/LCI_msgs.h>
#include <LCI/LCI_cmddefs.h>
#include <LCI/LCI_cmdxtrn.h>
#include <LCI_DB/schema.h>
#include <LSEC/LSEC.h>
#include <CDM/CDM_pubdefs.h>
#include <CPU_DB/CPU_DB_pubdefs.h>
#include <IMM/RBM_pubdefs.h>
#include <IMM/FPM_pubdefs.h>
#include <EDS/EBF_match.h>
#include <EDS/EBF_cid.h>
#include <FBS/FBS_pubrtos.h>
#include <CCSDS/CCSDS_pkt.h>
#include <LSF/LSF_cpu.h>
#include <LSF/LSF_origin.h>
#include <LSF/LSF_reason.h>
#include <MSG/MSG_pubdefs.h>
#include <ITC/ITC_pubdefs.h>
#include <LEM/list.h>
#include <PBS/BSWP.h>
#include <PBS/FPA.h>
#include <PBS/MBA.h>
#include <PBS/SEM.h>
#include <PBS/WCT.h>
#include <LCBD/LCBD.h>
#include <string.h>

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 int	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_getRunInfo (LCI_runInfo *info)
	Get extended information about the calibration run.
unsigned	LCI_init (unsigned capacity, unsigned cpuid, unsigned srcid)
	Initialize the calibration system.
unsigned	LCI_initialise (void)
	Initialize the calibration system from its config database.
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_sizeofRunInfo (void)
	Get the size of the extended calibration run information.
unsigned	LCI_start (const TASK_attr *attr)
	Start the LCI task.
unsigned	LCI_startCycle (void)
	Request the next calibration cycle.
unsigned	LCI_startTask (void)
	Start the LCI task using its config database.
unsigned	LCI_status (void)
	Get the calibration state.
unsigned	LCI_stopTask (void)
	Stop the LCI task.
unsigned	LCI_teardown (void)
	Tear down the calibration system.
unsigned	LCI_terminate (unsigned status)
	Terminate a calibration.

---

Detailed Description

Principal routines of the charge injection calibration utility.

Author:

James Swain & Owen Saxton

$Id: control.c,v 1.34 2011/03/29 19:32:57 saxton Exp $

---

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

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 int 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_getRunInfo

(

LCI_runInfo *

info

)

Get extended information about the calibration run.

This routine fills a block of information detailing the current state of calibration runs.

Parameters:

info	The address of a block to be filled with the current run information.

Return values:

LCI_SUCCESS

success always

References _LCI_runInfo::cfgFid, _LCI_runInfo::endSec, _LCI_runInfo::endSub, _LCI_runInfo::latcFid, _LCI_runInfo::runId, _LCI_runInfo::spare, _LCI_runInfo::startSec, _LCI_runInfo::startSub, and _LCI_runInfo::status.

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_initialise

(

void

)

Initialize the calibration system from its config database.

This routine is normally called at system initialization time to initialize the calibration system . It uses a configuration database to supply the capacity, cpuid and srcid parameters.

Returns:

Any of the return codes from LCI_init

References LCI_init().

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

unsigned LCI_sizeofRunInfo

(

void

)

Get the size of the extended calibration run information.

This routine returns the size of the area needed to hold the extended run information for the last calibration.

Returns:

The size, in bytes, of the extended run information.

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_startTask

(

void

)

Start the LCI task using its config database.

This routine is normally called during system initialization. It starts the LCI task using the CPU configuration database to supply its attributes.

Returns:

Any of the return codes from LCI_startTask

References LCI_start().

unsigned LCI_status

(

void

)

Get the calibration state.

This routine returns the current state of LCI.

Returns:

Current state of LCI

unsigned LCI_stopTask

(

void

)

Stop the LCI task.

This routine stops the LCI task and sets the state to INITIALISED.

Returns:

LCI_STATE if the state is not WAITING, an error status code from ITC_stopTask or LCI_SUCCESS if all goes well

unsigned LCI_teardown

(

void

)

Tear down the calibration system.

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

Return values:

LCI_STATE	If the LCI task is not in the INITIALISED state
LCI_SUCCESS	If all goes well

References LCI_Apid67c, LCI_Apid67d, and LCI_deleteController().

Referenced by LCI_init().

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