/**
\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
for about 3 seconds worth of data (3 processing cycles). 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 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 occurred and the complete list
of errors in the 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 as 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 bunch, then sample, then channel.
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.


*/
