#include <CControlHardware.h> classCControlHardware{ protected: CControlModule* m_pConfig; public:CControlModule(std::string name);CControlModule* getConifguration();virtual = 0 void onAttach(CControlModule& configuration);virtual = 0 void Initialize(CVMUSB& vme);virtual std::string Update(CVMUSB& vme);virtual = 0 std::string Set(CVMUSB& vme, std::string parameter, std::string value);virtual = 0 std::string Get(CVMUSB& vme, std::string parameter);virtual = 0 void clone(const CControlHardware& rhs);virtual void addMonitorList(CVMUSBReadoutList& vmeList);virtual void* processMonitorList(void* pData, size_t remaining);virtual std::string getMonitoredData();};
CControlHardware is an abstract base class for
slow control drivers. To build a driver one must build a concrete
derived class, a CModuleCreator and register
them with the CModuleFactory which associates
a module type string with a creator.
The base class and its CControLModule take care
of configuration management, command dispatching and parameter marshalling
for the methods of this class. This framework therefore frees people
writing controls support software from most tasks not directly related to
controlling their devices.
The driver framework supports get and set operations and these transparently interrupt data taking if active. Thus a series of sets or gets performed while data taking is active can take a substantial time as each get or set will pause data taking, flush in-flight buffers, perform the operatin and then resume data taking.
In addition to get and set operations, the driver supports using a periodically triggered list to monitor device state. This monitoring does not impact data taking other than the time required to execute the list. This mechanism is normally used to support the recognition of exceptional states in the hardware (e.g. trips in detector bias supplies).
Implementation of the set/get interface is mandatory (those methods are pure virtual) Implementation of the monitor list operations is optional, as there are do-nothing default behaviors defined in this base class.
CControlModule(std::string name);
The base class constructor makes a correspondence between
the name of the module and the actual device. Therefore
when you construct an object you should invoke this
base class constructor passing name
the name passed into your own constructor>
CControlModule* getConifguration();
Obtains the configuration object from the module.
Your own methods can refer directly to the
m_pConfig member variable.
See MEMBER DATA below for more information.
virtual = 0 void onAttach(CControlModule& configuration);
This method must be implemented by concrete classes.
It is invoked as a new module instance is being
put together internally and hooked into the
slow controls server. configuration
is the coniguration object. Its address should be
stored in m_pConfig (see
MEMBER DATA) below.
This method should also be used to define any
configuration options you need. Normally drivers will
define at least an option to allow the hardware to be
located. For modules with base addressing this is
normally an option named -base
H
virtual = 0 void Initialize(CVMUSB& vme);
Optional method that can be implemented by concrete sub-classes.
The method is intended to do one-time initialization of the hardware
being controlled by this driver. vme
is a reference to a VMUSB controller object. This object can
perform VME operations on behalf of the method or execute
CVMUSBReadoutLists this method builds.
If this method is not implemented the base class method does nothing.
virtual = 0 std::string Update(CVMUSB& vme);
This method must be implemented by concrete sub-classes.
It is intended for use by drivers that work with devices that have
write only state. The method is called by clients that want to
push shadow data out to the write only state of the device. Typically,
a device of this sort would have an initialization file that
describes the desired initial state of the device. The Update
often is a means to push that state out to the device when the GUI starts and
reads in the same initializationfile.
virtual = 0 std::string Set(CVMUSB& vme, std::string parameter, std::string value);
This method must be implemented by concrete sub-classes.
The framework will call this in response to a request
by a client to make a setting for this instance of the driver.
The vme object is a
CVMUSB object that can be used to
perform individual VME operations or execute immediate
CVMUSBReadoutList objects
created and filled by this method.
parameter is a string that specifies
the name of the parameter the client wants to set.
The parameter names that are supported by a driver are
up to the driver and hardware specific. If the
client requests a parameter that is not supoprted an
error should be returned.
The value parameter is the
new value requested by the client. If this value is
not legal for the parameter (e.g. a string that is not
an integer for an integer parameter), an error should
be returned.
The return value of this method is a
std::string. On successful
completion this should be the value OK.
On failure, this should be a string that begins with
the word ERROR and, after some whitespace
provides a human readable message describing the error.
virtual = 0 std::string Get(CVMUSB& vme, std::string parameter);
This method must be implemented by a concrete class. It is invoked by the framework when a client requests the value of a parameter from this instance of the driver.
vme is a CVMUSB
object that can be used to perform simple VME operations
or execute CVMUSBReadoutList objects
created by this method.
parameter is the name of a parameter
supported by the driver. The parameter names that are supported by a driver are
up to the driver and hardware specific. If the
client requests a parameter that is not supoprted an
error should be returned.
The return value of this method is a
std::string. On successful
completion this should be the value OK.
On failure, this should be a string that begins with
the word ERROR and, after some whitespace
provides a human readable message describing the error.
virtual = 0 void clone(const CControlHardware& rhs);
This must be implemented by concrete subclasses. It is a
virtual copy constructor in the sense that the state of the
rhs object must be copied to the state
of this
virtual void addMonitorList(CVMUSBReadoutList& vmeList);
This method need only be implemented by drivers for
devies that require continuous monitoring.
vmeList is a reference for
a CVMUSBReadoutList to which this
call must add appropriate operations to obtain the
data fromt he device that needs to be monitored.
See also processMonitorList and
getMonitoredData
virtual void* processMonitorList(void* pData, size_t remaining);
Called for each execution of the monitor list built up
via addMonitorList.
pData points to the data
for this device from that list and
remaining is the number of bytes
of data remaining in that buffer.
The method must return a pointer to the first byte in
the buffer pointed to by pData
beyond the data returned by this driver's monitor list.
virtual std::string getMonitoredData();
Called to return the most recently received data from the driver's monitor list. The data are encoded as a string that must begin with the word OK. normally the remainder of the string is whitespace separated followed by a well formed Tcl list containing the data from the monitor list.
If the device does not use monitor lists the return value should be ERROR