/** \file TmsC.h \brief This file contains the TmsAPi class definitions. \namespace Tms \class Tms::PuControl \fn BError Tms::PuControl::getVersion(BString& version) \param version A string variable filled in with the version number string. \class Tms::TmsControl \fn BError Tms::TmsControl::getVersion(BString& version) \param version A string variable filled in with the version number string. \fn BError Tms::TmsControl::setProcessPriority(UInt32 priority) \param priority This is the priority of the process. It can be set to one of: PriorityLow, PriorityNormal, PriorityHigh. \fn BError Tms::TmsControl::init() This function restarts the TMS system. It re-initialises each of the TmsPuServer processes running on the Module Controllers and reboots each of the PUPE boards from scratch loading the current FPGA firmware. All errors and statistics values are reset. \fn BError Tms::TmsControl::configure(ConfigInfo configInfo) \param configInfo The channel mapping table. This function configures the logical to physical channel mapping table. \fn BError Tms::TmsControl::getConfiguration(ConfigInfo& configInfo) \param configInfo The channel mapping table that is filled in with the current curent channel mapping. This function reads the current logical to physical channel mapping table. \fn BError Tms::TmsControl::setControlInfo(CycleParam params) \param params Cycle information parameters (state/phase table information). This function over-writes or adds an entry in the Cycle Parameter database. The Cycle Parameters define the setting for each processing cycle including the state and phase tables for the PUPE FPGA engines. \fn BError Tms::TmsControl::getControlInfo(BString cycleType, UInt32 puChannel, CycleParam& params) \param cycleType This string defines the cycle type for which to get the information. \param puChannel This defines the channel to get the information for. 0 means all channels. \param params The resuting cycle parameters are placed in this object. This function reads back the set of Cycle parameters for the given cycle type and channel number. Normall the same cycle parameters are used for all PUPE engines. In this case setting the puChannel to 0 reads the Cycle Parameters that are being used on all channels. If a specific channel has other parameters the puChannel variable can be set to the appropriate channel number to get its particular settings. \fn BError Tms::TmsControl::delControlInfo(BString cycleType, UInt32 puChannel) \param cycleType This string defines the cycle type to delete from the database. \param puChannel This defines the specific channel to delete the information for. 0 means all channels. This function will delete a set of Cycle parameters from the TMS's Cycle parameter database. \fn BError Tms::TmsControl::getControlList(BList<CycleParamItem>& itemList) \param itemList The list of CycleType information is returned. This function will return a list of entries describing the Cycle Paramter sets present in the TMS database. \fn BError Tms::TmsControl::setNextCycle(UInt32 cycleNumber, BString cycleType) \param cycleNumber This is the next cycle number. This should be an incrementing 32bit unsigned value. \param cycleType This is a string defining the cycle type for the next cycle. This call configures the TMS system for the next processing cycle. It defines the cycle number that will be used to tag data captured during the cycle and it defines the type of machine cycle. The cycleType is used to lookup the appropriate state/phase table information to use in the FPGA's. The call should be made at least 10ms before the CYCLE_START event for the cycle it refers to. This gives time for the FPGA's to be loaded with the appropriate state/phase table information. As the function is time critical, the communications channel should be set to a high priority using the setPriority() call and the processing threads priority should be set to high using the setProcessPriority() call. The call will return the error: "ErrorCycleNumber", "The next cycle has already started" if the call has not completed before the CYCLE_START event. All client data reads, for this cycle, will also return this error message. \fn BError Tms::TmsControl::test(BList<BError>& errors) \param errors The list of errors is placed in this list object. This function will perform a test of the TMS system. It will report each test performed and the status of the test in the BError object. A status value of 0 indicates all was Ok, any other value is an error where the number indicates the error. A string gives the test name and the Ok or error condition as a string. \fn BError Tms::TmsControl::getStatus(BList<NameValue>& statusList) \param statusList The list of status items is placed in this list object. This function gets the status of the TMS system. It returns a list of name/value pairs. \fn BError Tms::TmsControl::getStatistics(BList<NameValue>& statsList) \param statsList The statistics list is placed in this list object. This function gets the statistics values from the TMS system. It returns a list of name/value pairs. \fn BError Tms::TmsControl::getPuChannel(UInt32 puChannel, PuChannel& puPhysChannel) \param puChannel The logical channel number. \param puPhysChannel The physical channel identifier is returned in this variable. This function is given a logical pick-up channel number. It will return the physical module, pupe number and pupe channle that has been allocated to this channel. \fn BError Tms::TmsControl::setTestMode(PuChannel puPhysChannel, UInt32 testOutput, UInt32 timingDisableMask) \param puPhysChannel The physical channel identifier. \param testOutput The signal to output on the test output. 0 is FREF any other value is undefined at the moment. \param timingDisableMask This 8 bit mask defines which of the timing input signals are disabled. This function sets up a particular pick-up channel's digital test output source and allows the channels input timing signals to be set to a software driven mode rather than taken from the hardware timing inputs. The timing mask bits are: 7 - FREF, 6 - HCHANGE, 5 - INJECTION, 4 - CAL_STOP, 3 - CAL_START, 2 - CYCLE_STOP, 1 - CYCLE_START, 0 - SYSCLOCK \fn BError Tms::TmsControl::setTimingSignals(PuChannel puPhysChannel, UInt32 timingSignals) \param puPhysChannel The physical channel identifier. \param timingSignals The 8 bit mask defining the state of the software driven timing signals. If the setTestMode() function had been used to "enable" particular timing signals to be driven by software, then this function can be used to set/reset particular timing signals for the pick-up channel given. The timing signals bits are: 7 - FREF, 6 - HCHANGE, 5 - INJECTION, 4 - CAL_STOP, 3 - CAL_START, 2 - CYCLE_STOP, 1 - CYCLE_START, 0 - SYSCLOCK \fn BError Tms::TmsControl::captureTestData(PuChannel puPhysChannel, TestCaptureInfo captureInfo, BArray<UInt64>& data) \param puPhysChannel The physical channel identifier. \param captureInfo The specification of the diagnostics trigger and data to capture. \param data The diagnostics 64bit data array is stored in this array. This function is for diagnostics purposes. It is used to capture internal signals from the PUPE FPGA processing system. The captureInfo parameter defines the signals to be captured, the clock rate and the trigger to start capture as well as the start time before the trigger become active and the delay, in clock cycle, after trigger that the data capture starts. The call will block until the trigger condition is matched and the resulting data is returned. The call will timeout after 10seconds returning the error, "ErrorTimeout". In the current system 4096 data samples will be returned. \fn BError Tms::TmsControl::setTestData(PuChannel puPhysChannel, Int32 on, BArray<UInt32> data) \param puPhysChannel The physical channel identifier. \param on Boolean to enable the internal data source. 0 is off, 1 is on. \param data The array of 32bit data values to use as the FREF,Sigma,DeltaX and DeltaY test signal. This call loads the PUPE systems test data SDRAM with the data passed in the data array. It then sets up the individual channel to sources its FREF, Sigma, DeltaX and DelatY signals from the test SDRAM. The data source should have a multiple of 2 samples. The "on" parameter is used to enable or disable the individual channels inputs from this test data SDRAM. \fn BError Tms::TmsControl::setPupeConfig(PuChannel puPhysChannel, PupeConfig pupeConfig) \param puPhysChannel The physical channel identifier. \param pupeConfig The configuration parameters to use. This functions sets up some special configuration parameters for the PUPE channel. It is used mainly for diagnostics and test purposes. The main settings it can affect are: The ADC Clock sources PLL synchronisation, internal timing for the digtital timing signals and the enabling/dissabling of the BLR algorithem. \fn BError Tms::TmsControl::getPupeConfig(PuChannel puPhysChannel, PupeConfig& pupeConfig) \param puPhysChannel The physical channel identifier. \param pupeConfig The returned configuration parameters. This function returns the current configuration of the given channel. \fn BError Tms::TmsControl::puServerStarted(UInt32 number) \param number The number of the PuServer started. This is an internal function called by the TmsPuServer processes to indicate to the TmsServer that they have just started running and are present in the system. The TmsServer will initialise the appropriate tmsPuServer program and its individual PUPE engines on receipt of this call. \class Tms::TmsProcess \fn Tms::TmsProcess::TmsProcess(BString name = "") \param name The name of the TmsProcess BOAP object to connect to. The BOAP object name has the general form: "//HostName/ObjectName" \fn BError Tms::TmsProcess::getVersion(BString& version) \param version A string variable filled in with the version number string. \fn BError Tms::TmsProcess::getCycleInfo(UInt32& cycleNumber, BString& cycleType) \param cycleNumber The current cycle number is returned here \param cycleType The current cycle type is returned here. This function returns the current TMS cycle number being processed and the type of the cycle. \fn BError Tms::TmsProcess::getCycleInformation(UInt32 cycleNumber, CycleInformation& cycleInformation) \param cycleNumber The current cycle number to get information on \param cycleInformation The returned cycle information This function provides information on the given cycle. It interrogates the first PUPE channel and returns the Cycle information based on the internal state of that channel. The main information returned includes the cycle type and a list of all of the Cycle Periods captured and the times and ammount of data in each. \fn BError Tms::TmsProcess::getData(DataInfo dataInfo, Data& data) \param dataInfo Information on the type of data required. \param data The raw data is returned in this object. This is the main user function used by clients of the TMS system. It is used to return portions of the acquired data. The fields of the dataInfo parameter define which data is required and are defined in the DataInfo class documentation. The call will check to see if the data for the cycle number requested is still present in the PUPE memory. The PUPE memory has enough storage form about 3 seconds worth of data (3 processing cycle). If the data has gone the call will return the error "ErrorDataGone". If the system has not processed the requested cycle, but will do so within 256 seconds, the call will block awaiting the data. If the channel number is given as 0 the call will interrogate each of the Pick-Up channels and return the combined data from all of them. Note that this could take significant time and may not be possible for if the parameter numValues is large. Within the Data structure returned there is an array of error values, one per channel. If an error occurs on any set of the channels the call will return the first error that occured and the complete list of errors in the data.errors array. The actual data will be returned for all channels that did not have an error. Those channels that had anb error will have data values of 0 returned. If the bunch number is given a 0, then the system will return the data for all of the bunches. The data will be returned in the following order, where B - Bunch, C - Channel:\n [C1.B1, C1.B2, C1.B3, C1.B4], [C1.B1, C1.B2, C1.B3, C1.B4], ... [C2.B1, C2.B2, C2.B3, C2.B4], [C2.B1, C2.B2, C2.B3, C2.B4], ... \n That is the data is ordered by channel, then sample, then bunch. See the TMS Software documentation manual for more details of this functions operation. \fn BError Tms::TmsProcess::addEventServer(BString name) \param name The BOAP object name to add. Adds an event server that gets called on certain TmsServer events such as data ready, CYCLE_START, CYCLE_STOP and errors. \fn BError Tms::TmsProcess::requestData(DataInfo dataInfo) \param dataInfo Information on the type of data required. This calls sets up a request for data. The dataInfo parameter works in the same manner as the "getData" call, defining the portion of data required. This call will return immediatly. Assuming the client has informed the TMS system of an event server object using the "addEventServer" call, then the client will receive the "dataEvent" event when the data become available. The client can then fetch the data using the conventional "getData" call. In the current version of the software the "requestData" call simply sends a message when the data for the requested cycle is ready. In future implementations the TMS system could actually fetch the data automatically from the PUPE boards and store it in memory ready for later retrieval by the getData call. */