//*****************************************************************************/
// Base objects for BEAM TMS System
// T.Barnaby, BEAM Ltd, 2006-12-07
//*****************************************************************************/
//
module Tms {
typeDomain = 0;
apiVersion = 2;
enum Errors {
ErrorOk, ErrorMisc, ErrorWarning, ErrorInit, ErrorConfig,
ErrorParam, ErrorNotImplemented,
ErrorComms, ErrorCommsTimeout, ErrorMC,
ErrorFpga, ErrorStateTable, ErrorCycleNumber,
ErrorDataNotAvailable, ErrorDataGone, ErrorDataFuture,
ErrorTimeout
}; /// The System Error List
enum CyclePeriod {
CyclePeriodStart, CyclePeriodCalibration,
CyclePeriodHarmonic0, CyclePeriodHarmonic1,
CyclePeriodHarmonic2, CyclePeriodHarmonic3,
CyclePeriodHarmonic4, CyclePeriodHarmonic5,
CyclePeriodHarmonic6, CyclePeriodHarmonic7
}; /// The Cycle Period
enum DataFunction {
DataFunctionRaw, DataFunctionMean0, DataFunctionMean1
};
enum TestOutput {
TestOutputFrefLocal, TestOutputPllL1, TestOutputPllL2
};
/// 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
};
//
/// 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 spare; ///< Spare data entry. Used to pad to 64bits
};
//
/// 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
Array<DataValue> dataValues;� ///< The data
};
//
/// This class defines the Pick-Up state table
class PuStateTable {
UInt32 state; ///< The State table entry
UInt32 numBunches; ///< The number of bunches to capture
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 info; ///< Information on this parameter set
UInt32 channel; ///< The channel number this configuration is for, 0 defines all channels
UInt32 pllInitialFrequency; ///< This�defines�the�initial�PLL�frequency.�This�is�loaded�on START_CYCLE�and�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.
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.
};
//
// 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 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
};
//
// Special PUPE configuration for test purposes
class PupeConfig {
UInt32 internalTimingMask; ///< Use internal, software/hardware generated, timing signals for the given signals.
Bool internalAdcClockRef; ///< Use internally generated free running ADC Clock.
};
//
/// 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 configure(in ConfigInfo configInfo); ///< Configure the system for use. This includes mapping the individual physical PickUp channels to logical pickup channels.
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\u2019s�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.
// 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 captureTestData(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 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 100ms before the next CYCLE_START event.
Error getStatus(in PuChannel�puChannel, out PuStatus puStatus);
Error getData(in PuChannel�puChannel, 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); ///< 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 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 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\u2019s�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.
Error puServerStarted(in UInt32 number); ///< A TmsPuServer has started
// Test functions
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 captureTestData(in PuChannel puPhysChannel, in TestCaptureInfo captureInfo, out Array<UInt64> data); ///< This function will capture test data
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
};
//
/// This interface provides functions to configure and capture data from the TMS as a whole
interface TmsProcess {
Error getVersion(out String version); ///< Gets the software version
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 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 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 100ms before the next CYCLE_START event.
Error getCycleInfo(out UInt32 cycleNumber, out String cycleType); ///< Gets the current cycle number and 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.
};
//
};
