//*****************************************************************************/
//	Base objects for BEAM TMS System
//			T.Barnaby,	BEAM Ltd,	2006-12-07
//*****************************************************************************/
//
module Tms {

typeDomain = 0;
apiVersion = 9;

#ifdef ZAP
enum Errors		{
			 ErrorOk, ErrorMisc, ErrorWarning, ErrorInit, ErrorConfig,
			 ErrorParam, ErrorNotImplemented, 
			 ErrorComms, ErrorCommsTimeout, ErrorMC,
			 ErrorFpga, ErrorStateTable, ErrorCycleNumber,
			 ErrorDataNotAvailable, ErrorDataGone, ErrorDataFuture,
			 ErrorTimeout
			};	/// The System Error List

#endif

enum CyclePeriod	{
			CyclePeriodAll, CyclePeriodCalibration,
			CyclePeriodEvent0, CyclePeriodEvent1,
			CyclePeriodEvent2, CyclePeriodEvent3,
			CyclePeriodEvent4, CyclePeriodEvent5,
			CyclePeriodEvent6, CyclePeriodEvent7,
			CyclePeriodEvent8, CyclePeriodEvent9
			};	/// The Cycle Period

enum DataType		{
			DataTypeRaw
			};

enum DataFunction	{
			DataFunctionRaw, DataFunctionMean, DataFunctionMeanAll, DataFunctionMean0, DataFunctionMean1
			};

enum TestOutput		{
			TestOutputFrefLocal, TestOutputPllL1, TestOutputPllL2
			};
enum Priority		{
			PriorityLow, PriorityNormal, PriorityHigh
			};


/// A simple Name/Value class. This class associates a name with a value.
class NameValue {
	String		name;			///< The Name of the value
	String		value;			///< The actual value in string form
};
//

/// This class stores a Physical Pick-Up channel id
class PuChannel {
	UInt8		moduleNum;		///< The Module number
	UInt8		pupeNum;		///< The PUPE number
	UInt8		pupeChan;		///< The PUPE channel
};
//

/// This class stores the status of an individual Pick-Up
class PuStatus {
	Bool		running;		///< The Pick-Up is currently running.
	Error		error;			///< The Pick-Up's current error status.
};
//

/// This class describes the configuration of the TMS
class ConfigInfo {
	Array<PuChannel>	puReferences;		///< The logical to physical Pick-Up table. Each PuReference includes a Module Controller identifier, a Physical Pick-Up number and a Physical Channel.
};
//

/// This class defines the data to be acquired and/or fetched
class DataInfo {
	UInt32		cycleNumber;		///< The PS Cycle number
	UInt32		channel;		///< The pick-up channel number
	UInt32		cyclePeriod;		///< The cycle period the data is from
	UInt32		startTime;		///< The start time in milli-seconds in the cycle period (starting from 0)
	UInt32		orbitNumber;		///< The starting orbit number (starting from 0)
	UInt32		bunchNumber;		///< The Bunch number (starting from 1 (0 is all bunches))
	UInt32		function;		///< The data processing function to perform or performed. (0 normal data)
	UInt32		argument;		///< The Argument to the data processing function
	UInt32		numValues;		///< The total number of data points to return
	Bool		beyondPeriod;		///< If set allows reads of data beyond the end of the period
};
//

/// This is the definition of a single data value
class DataValue {
	Int16		sigma;			///< The Sigma value
	Int16		deltaX;			///< The DeltaX value
	Int16		deltaY;			///< The DeltaY value
	Int16		time;			///< The Time in ms this sample was processed
};
//

/// This class stores the raw data
class Data {
	UInt32			numValues;	///< The total number of data samples
	UInt32			dataType;	///< The type of data in the data block
	UInt32			numBunches;	///< The number of bunches
	UInt32			numChannels;	///< The number of channels
	Array<DataValue>	dataValues; 	///< The data
	Array<Error>		errors; 	///< Individual errors for each channel within dataValues
};
//

/// This class defines the Pick-Up state table
class PuStateTable {
	UInt32		period;			///< The Cycle period this state is used for
	UInt32		state;			///< The State table entry
	UInt32		harmonic;		///< The harmonic number for this state
	UInt32		numBunches;		///< The number of bunches to capture
	UInt32		bunchMask;		///< Bitmask defining which buckets the bunches are captured from. Bit 0 is bucket 1, bit 1 is bucket 2 etc
	Array<UInt8>	phaseTable;		///< The Phase table for this state
};
//

/// This class defines the parameters for a PS processing cycle
class CycleParam {
	String			cycleType;		///< The Cycle Type Name of this parameter set, normally the BEAM type the set of parameters is designed to measure
	String			name;			///< The name of this set of parameters
	String			info;			///< Information on this parameter set
	UInt32			ring;			///< The ring this configuration is for, 0 defines all rings
	UInt32			channel;		///< The channel number this configuration is for, 0 defines all channels
	UInt32			pllCycleStartFrequency;	///< This defines the initial PLL frequency. This is loaded on START_CYCLE.
	UInt32			pllInitialFrequency;	///< This defines the initial PLL frequency. This is loaded after the delay given in pllInitialFrequencyDelay.
	UInt32			pllInitialFrequencyDelay;	///< This defines the delay in milliseconds from START_CYCLE when the pllInitialFrequency is loaded.
	UInt32			pllFrefGain;		///< The gain the FREF signal. This is a value in the range +-8191. A normal value would be around 4096.
	UInt32			pllGain;		///< The gain of the PLL feedback system. This is the gain reduction of the PLL in terms of right bit shifts. A bit shift of 7 is about unity gain.
	UInt32			pllDdsMinimum;		///< PLL DDS minimum frequency. If this and pllDdsMaximum is set to 0, this feature is disabled.
	UInt32			pllDdsMaximum;		///< PLL DDS maximum frequency. If this and pllDdsMinimum is set to 0, this feature is disabled.
	UInt32			stateDelay;		///< The delay in FREF periods when in the delay state
	Array<Int32>		frefPhaseDelay;		///< The phase delay parameters for the Fref timing signal for each of the Pick-Up channels. This is set based on the position of the Pick-Up's in the PS ring. Its value is based of Fref / 512.
	Array<PuStateTable>	stateTable;		///< The array of State Table entries for the processing run.
	Array<String>		settings;		///< A string array defining the settings for the states. Used for CycleParam editors
};
//

// This class is used to return the list of CycleParm's
class CycleParamItem {
	String			cycleType;		///< The Cycle Type Name of this parameter set, normally the BEAM type the set of parameters is designed to measure
	UInt32			ring;			///< The ring number this configuration is for, 0 defines all rings
	UInt32			channel;		///< The channel number this configuration is for, 0 defines all channels
};
//

/// This class defines the parameters for a test data capture
class TestCaptureInfo {
	UInt32			source;			///< The source data (0  - 3)
	UInt32			clock;			///< The Clock source
	UInt32			startTime;		///< The start time in ms from CYCLE_START before trigger is activated
	UInt32			postTriggerDelay;	///< The delay, in clock cycles, after the trigger before capture starts
	UInt32			triggerMask;		///< The Trigger bit mask. This is the bit mask of the 8 timing signals
	Bool			triggerAnd;		///< The Trigger function is an AND rather than an OR
	Bool			triggerStore;		///< Store the trigger in the upper 8 data bits
	Bool			triggerSourceData;	///< Use lower 32bits of data as trigger source rather than timing signals
	Bool			triggerStateEnable;	///< Trigger in state enable
	UInt32			triggerState;		///< Trigger state number
};
//

// Special PUPE configuration for test purposes
class PupeConfig {
	UInt32			internalTimingMask;	///< Use internal, software/hardware generated, timing signals for the given signals.
	Bool			doubleInjection;	///< Simulate double injection
	Bool			adcSysclkSync;		///< Sets the ADC clock to be synchronised with the SYSCLK timing clock
	Bool			disableBlr;		///< Disable the BLR algorithm
};
//

/// Cycle information
class CycleInformationPeriod {
	UInt32			cyclePeriod;		///< The Cycle Period
	UInt32			startTime;		///< The start time in ms
	UInt32			endTime;		///< The end time in ms
	UInt32			harmonic;		///< The Machines harmonic number
	UInt32			numBunches;		///< The number of bunches
	UInt32			bunchMask;		///< Bitmask defining which buckets the bunches are captured from. Bit 0 is bucket 1, bit 1 is bucket 2 etc
	UInt32			numValues;		///< The total number of raw data values available
};

class CycleInformation {
	UInt32				cycleNumber;	///< The PS Cycle number
	String				cycleType;	///< The Cycle Type Name
	List<CycleInformationPeriod>	periods;	///< The list of cycle periods
};
//

/// Cycle Type information
class CycleTypeInformationPeriod {
	UInt32			cyclePeriod;		///< The Cycle Period
	UInt32			harmonic;		///< The Machines harmonic number
	UInt32			numBunches;		///< The number of bunches
	UInt32			bunchMask;		///< Bitmask defining which buckets the bunches are captured from. Bit 0 is bucket 1, bit 1 is bucket 2 etc
};

class CycleTypeInformation {
	String					cycleType;	///< The Cycle Type Name
	String					info;		///< Information string on this cycle type
	List<CycleTypeInformationPeriod>	periods;	///< The list of cycle periods
};
//

class Simulation {
	Bool			timing;			///< Simulate timing signals
	Bool			doubleInjection;	///< Simulate double injection
	Bool			data;			///< Simulate FREF and Analogue Sigma, DeltaX and DeltaY data
	Bool			setNextCycle;		///< Simulate setNextCycle
	String			cycleType;		///< The cycle type to set
};
//

/// This interface provides functions to control, test and get statistics from an individual pick-up
interface PuControl {
	Error		getVersion(out String version);			///< Gets the software version
	Error		init();						///< Initialises the system including loading all of the PUPE engines firmware. The call will return an error object indicating success or an error condition as appropriate.
	Error		setProcessPriority(in UInt32 priority);		///< Sets the priority of the process servicing this service
	Error		configure(in UInt32 ring, in ConfigInfo configInfo);		///< Configure the system for use. This includes mapping the individual physical PickUp channels to logical pickup channels.
	Error		setControlInfo(in CycleParam params);		///< Sets the control information for the cycle type given and subsequent cycles. The parameters for the processing cycle are passed, this includes the Phase and State table information. The call will return an error object indicating success or an error
	Error		setNextCycle(in UInt32 cycleNumber, in String cycleType);	///< Sets the cycle number and type for the next processing cycle. The call will return an error object indicating success or an error condition as appropriate. This should be called at least 10ms before the next CYCLE_START event.
	Error		test(out List<Error> errors);			///< Performs a basic test of the system returning a list of errors. The call will return an error object indicating success or an error condition as appropriate.
	Error		getStatus(out List<NameValue> statusList);	///< Returns the current status of the system. This information includes the number of Pick-Up's present and their individual status.
	Error		getStatistics(out List<NameValue> statsList);	///< Returns a list of the statistic values as name/value pairs. The call will return an error object indicating success or an error condition as appropriate.
	Error		getMasterPuChannel(out PuChannel puChannel);	///< Returns the master PU Channel for timing

			// Test functions
	Error		setTestMode(in PuChannel puChannel, in UInt32 testOutput, in UInt32 timingDisableMask);	///< The signal source for the digital test output connector. 0: None, 1: FrefLocal. The timingDisableMask bit mask defines which of the timing inputs should be disabled. If a timing input is disabled it can be still operated by software command.
	Error		setTimingSignals(in PuChannel puChannel, in UInt32 timingSignals);			///< This function sets the given timing signals to the values as defined in the timingSignals bit array.
	Error		captureDiagnostics(in PuChannel puChannel, in TestCaptureInfo captureInfo, out Array<UInt64> data);		///< This function will capture test data
	Error		setTestData(in PuChannel puChannel, in Bool on, in Array<UInt32> data);			///< This function will set a PU channel to sample data from memory rather than the ADC's
	Error		setPupeConfig(in PuChannel puPhysChannel, in PupeConfig pupeConfig);			///< Sets special PUPE configuration for test purposes
	Error		getPupeConfig(in PuChannel puPhysChannel, out PupeConfig pupeConfig);			///< Gets special PUPE configuration for test purposes
};
//

/// This interface provides functions to configure and capture data from individual pick-up
interface PuProcess {
	Error		getVersion(out String version);					///< Gets the software version

	Error		getCycleInformation(in UInt32 cycleNumber, out CycleInformation cycleInformation);	///< Gets information on given cycle number

	Error		getStatus(in PuChannel puChannel, out PuStatus puStatus);
	Error		getData(in PuChannel puChannel, in DataInfo dataInfo, out Data data, out UInt32 orbitNumber);	///< This function returns a set of data from the data present in the data cache or directly from the Pick-Up processing engines. The  DataInfo object describes the data required. The call will return the required data along with an error object indicating success or an error condition as appropriate. The call will block until data is ready.

	Error		addEventServer(in String name);					///< Adds an event server
	Error		requestData(in PuChannel puChannel, in DataInfo dataInfo);	///< This adds a request for some data. The DataInfo object defines the data required. This request can be made at any time. If the data is present in cache the data will be available immediately, if not the system will await the data from a subsequent processing cycle. When the data is available a "data" event will be sent to the client. Not that it is not necessary to use requestData. The client can call getData() directly although this call will block until the data is actually ready.
};
//

/// This interface provides functions to control, test and get statistics from the TMS as a whole
interface TmsControl {
	Error		getVersion(out String version);			///< Gets the software version
	Error		setProcessPriority(in UInt32 priority);		///< Sets the priority of the process servicing this service
	Error		init();						///< Initialises the system including resetting all of the PUPE engines firmware. The call will return an error object indicating success or an error condition as appropriate.
	Error		configure(in ConfigInfo configInfo);		///< Configure the system for use. This includes mapping the individual physical PickUp channels to logical pickup channels.
	Error		getConfiguration(out ConfigInfo configInfo);	///< Get the current configuration
	Error		setControlInfo(in CycleParam params);		///< Sets the control information for the cycle type given. The parameters for the processing cycle are passed, this includes the Phase and State table information. The call will return an error object indicating success or an error
	Error		getControlInfo(in String cycleType, in UInt32 ring, in UInt32 puChannel, out CycleParam params);	///< Gets the control information for the cycle type and puChannel number given. The call will return an error object indicating success or an error
	Error		delControlInfo(in String cycleType, in UInt32 ring, in UInt32 puChannel);	///< Deletes the control information for the cycle type and puChannel number given. The call will return an error object indicating success or an error
	Error		getControlList(out List<CycleParamItem> itemList);					///< Gets the list of Cycle Parameters present in the system
	Error		setNextCycle(in UInt32 cycleNumber, in String cycleType);	///< Sets the cycle number and type for the next processing cycle. The call will return an error object indicating success or an error condition as appropriate. This should be called at least 10ms before the next CYCLE_START event.
	Error		test(out List<Error> errors);			///< Performs a basic test of the system returning a list of errors. The call will return an error object indicating success or an error condition as appropriate.
	Error		getStatus(out List<NameValue> statusList);	///< Returns the current status of the system. This information includes the number of Pick-Up's present and their individual status.
	Error		getStatistics(out List<NameValue> statsList);	///< Returns a list of the statistic values as name/value pairs. The call will return an error object indicating success or an error condition as appropriate.
	Error		getPuChannel(in UInt32 puChannel, out PuChannel puPhysChannel);	///< Returns the physical module/Pupe/Channel number given a logical PickUp id. This can be used so that the individual PickUps test functions can be accessed etc.

			// Test functions
	Error		setSimulation(in Simulation simulation);						///< Sets overall simulation modes
	Error		getSimulation(out Simulation simulation);						///< Gets current simulation modes
	Error		setTestMode(in PuChannel puPhysChannel, in UInt32 testOutput, in UInt32 timingDisableMask);	///< The signal source for the digital test output connector. 0: None, 1: FrefLocal. The timingDisableMask bit mask defines which of the timing inputs should be disabled. If a timing input is disabled it can be still operated by software command.
	Error		setTimingSignals(in PuChannel puPhysChannel, in UInt32 timingSignals);			///< This function sets the given timing signals to the values as defined in the timingSignals bit array.
	Error		captureDiagnostics(in PuChannel puPhysChannel, in TestCaptureInfo captureInfo, out Array<UInt64> data);		///< This function will capture the diagnostics
	Error		setTestData(in PuChannel puPhysChannel, in Bool on, in Array<UInt32> data);		///< This function will set a PU channel to sample data from memory rather than the ADC's
	Error		setPupeConfig(in PuChannel puPhysChannel, in PupeConfig pupeConfig);			///< Sets special PUPE configuration for test purposes
	Error		getPupeConfig(in PuChannel puPhysChannel, out PupeConfig pupeConfig);			///< Gets special PUPE configuration for test purposes

			// Internal functions
	Error		puServerStarted(in UInt32 number);		///< A TmsPuServer has started
};
//

/// This interface provides functions to capture data from the TMS as a whole
interface TmsProcess {
	Error		getVersion(out String version);			///< Gets the software version
	Error		getCycleInfo(out UInt32 cycleNumber, out String cycleType);	///< Gets the current cycle number and type.
	Error		getCycleInformation(in UInt32 cycleNumber, out CycleInformation cycleInformation);	///< Gets information on given cycle number
	Error		getCycleTypeInformation(in String cycleType, out CycleTypeInformation cycleTypeInformation);	///< Gets information on given cycle Type

	Error		getData(in DataInfo dataInfo, out Data data);	///< This function returns a set of data from the data present in the data cache or directly from the Pick-Up processing engines. The  DataInfo object describes the data required. The call will return the required data along with an error object indicating success or an error condition as appropriate. The call will block until data is ready.

	Error		addEventServer(in String name);			///< This call adds an event server to call on events such as the "dataEvent" generated by the requestData(0 call as well as error events. The Client will use this to notify the TmsServer of its local TmsEvent object.
	Error		requestData(in DataInfo dataInfo);		///< This adds a request for some data. The DataInfo object defines the data required. This request can be made at any time. If the data is present in cache the data will be available immediately, if not the system will await the data from a subsequent processing cycle. When the data is available a "data" event will be sent to the client. Not that it is not necessary to use requestData. The client can call getData() directly although this call will block until the data is actually ready.
};
//

/// This interface provides functions for events to be sent to clients from the TMS as a whole
interface TmsEvent {
	Error		errorEvent(in UInt32 cycleNumber, in Error error);	///< This event function gets called on a system error. The errorEvent object contains and error number and string describing the error. The getStatus() call can be used to fetch further information.
	Error		cycleStartEvent(in UInt32 cycleNumber);		///< This event function gets called on the CYCLE_START event with the cycle number about to be processed
	Error		cycleStopEvent(in UInt32 cycleNumber);		///< This event function gets called on the CYCLE_END event with the cycle number completed
	Error		dataEvent(in DataInfo dataInfo);		///< This event function gets called when some requested data becomes available. The DataInfo object contains information on the data. The getData() call can be used to fetch the actual data.
};
//

};
