//*****************************************************************************/ // Base objects for BEAM TMS System // T.Barnaby, BEAM Ltd, 2006-12-07 //*****************************************************************************/ // module Tms { typeDomain = 0; apiVersion = 3; 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 harmonic; ///< The harmonic number for this state 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. 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 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. Bool disableBlr; ///< Disable the BLR algorithm }; // /// 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. }; // };