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