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

apiVersion = 9;

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 { 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. }; // };