69.5. The slow controls subsystem

69.5.2.1. Driver requirements

A Slow controls device driver is a class that is derived from the CControlHardware abstract base class. In this section I will briefly go over the mandatory and optional requirements of a driver class as well as providing an annotated sample (if silly) driver.

The CControlHardware class is an abstract base class. This means it has some virtual methods that are not implemented and must be implemented by derived classes. In addition the name of the object being created (Module command's name) is maintained by the base class.

These constraints mean that a control driver class must implement the following member functions.

In addition to the mandatory methods above, you can implement several optional methods if required.

Let's look at the code for a rather silly user written driver a piece at a time. The driver is not going to interact with any hardware. What it will do is provide the configuration options -anint which will hold an integer, -astring which holds an arbitraty string, and -alist which holds a list of integers. The Set and Get operations will modify and retrieve these options. The driver won't support monitor lists.

#include <CControlHardware.h>
#include <CControlModule.h>
#include <CVMUSB.h>
#include <CVMUSBReadoutList.h>
	      

class CUserDriver : public CControlHardware
{

public:
  CUserDriver();
  virtual void onAttach(CControlModule& configuration);
  virtual std::string Update(CVMUSB& vme);
  virtual std::string Set(CVMUSB& vme, 
			  std::string parameter, 
			  std::string value);
  virtual std::string Get(CVMUSB& vme, 
			  std::string parameter);
  virtual void clone(const CControlHardware& rhs);

};
	      

CUserDriver::CUserDriver() :
  CControlHardware()
{}
	      

void
CUserDriver::onAttach(CControlModule& configuration)
{
  m_pConfig = &configuration;	       
  m_pConfig->addIntegerParameter("-anint", 0);
  m_pConfig->addParameter("-astring", NULL, NULL, ""); 
  m_pConfig->addIntListParameter("-alist", 16);

}
	      

std::string
CUserDriver::Update(CVMUSB& vme)
{
  return "OK";
}
	      

std::string
CUserDriver::Set(CVMUSB& vme,    
                 std::string parameter,           
                 std::string value)
{
  try {
    m_pConfig->configure(parameter, value);   
    return "OK";
  }
  catch (std::string msg) {	// configure reports errors via std::string exceptions.
    std::string status = "ERROR - ";
    status += msg;
    return status;                              
  }
}
	      

std::string
CUserDriver::Get(CVMUSB& vme, std::string parameter) 
{
  try {
    return m_pConfig->cget(parameter);                
  }
  catch (std::string msg) {
    std::string retval = "ERROR - ";                    
    retval += msg;
    return msg;
  }
}
		

void
CUserDriver::clone(const CControlHardware& rhs)
{
  CControlHardware* pRhs = const_cast<CControlHardware*>(&rhs);
  m_pConfig = new CControlModule(*(pRhs->getConfiguration()));
}
		

#include <CModuleCreator.h>                             
#include <CControlHardware.h>
   

class CUserDriverCreator : public CModuleCreator             
{
public:
  virtual std::unique_ptr<CControlHardware>
    operator()();                           
};

std::unique_ptr<CControlHardware>
CUserDriverCreator::operator()()
{
  return std::unique_ptr<CControlHardware>(emasc 
        new CUserDriver()                               
    );                               
}
	      

#include <CModuleFactory.h>                          
#include <tcl.h>

extern "C" {                                               
  int Userdriver_Init(Tcl_Interp* pInterp)                 
  {
    CModuleFactory* pFact = CModuleFactory::instance();    
    pFact->addCreator(
        "mydriver",
        std::unique_ptr<CModuleCreator>(new CUserDriverCreator)); 

    return TCL_OK;                                         
  }
  
}
	      

load [file join [file dirname [info script]] libMyDriver.so]
Module create testModule mydriver
Module config testModule -anint 1234
	      

69.5.3.1. Initialize

The full implementation of the Initialize is shown below:

    method Initialize vme {
    
    }
	  

The Initialize does nothing for our driver. For a real driver the options might be queried to find the base address of the hardware as well as other static configuration options. The vme argument, which is a Swig wrapped CVUSB object would then be used to perform the VME transactions needed to initialize the device.

In the event of an error while executing this method, the wrapper will pull the result of the command as a string, and throw it as a std::string exception. This is the accepted way for drivers to indicate errors in their Initialize methods

69.5.3.2. The update method

The Update method servesthe same function in a Tcl driver as in a C++ driver. In our case the implementationis

    method Update vme {
        return "OK"
    }
            

The vme is a SWIG encapsulated CVMUSB object that, in a real driver, would be used to perform VME operations or execute lists created via CVMUSBReadoutList objects created and filled in by this method.

The return string of OK indicates a normal completion. Tcl methods have two mechanisms to return errors. Returning a string that begins with ERROR - and concludes with an error message, or simply executing the error with an error message argument. The wrapper will map error returns into an ERROR - string return with the value of the string passed t the error command appended to the end of the error return string.

69.5.3.3. The Set method

As with the C++ driver, the Set method is used to process client requests to change a device parameter. The Tcl version of this method is:

    method Set {vme parameter value} {
        $self configure $parameter $value
        return "OK"
    }
            

The parameters passed into this are the same as those passed into a C++ driver's set, however the vme parameter is a swig wrapped CVMUSB object.

By using the configure method rather than just directly writing to the options array we force the call of any -configuremethod code that may do validations and throw errors.

The return of OK indicates successful completion, an error will be converted by the wrapper into a return string of the form ERROR - intepreter error result string. This allows errors from the configurmethod, including specifying an invalid option name as well as failures in validation by the -configuremethod code to be naturally mapped back to proper error returns.

In a real driver, the vme parameter will be used to perform VME operations. In addition you can choose to explicitly return an error string, or use the error command to report failures.

69.5.3.4. The Get method

As with the C++ driver this is called to fetch the value of a driver parameter. Our toy driver fetches configuration parameters rather than hardware parameters.

    method Get {vme parameter} {
        if {[array names options $parameter] eq ""} {
            error "Invalid parameter name: $parameter"
        }
        return $options($parameter)
    }
            

Our driver ensures the value of parameter really is an option name and then returns the option value from the options array. By doing the check for array names options $parameter we can produce a more meaningful error message than would be produced if we just let return $options($parameter) error.

Instead of the error command we could have just as easily done a return "ERROR - Invalid parameter name: $parameter"

A real driver would use the vme parameter, which is a Swig wrapped CVMUSB object to fetch the value of the parameter from the hardware.

69.5.3.5. The addMonitorList method

Since we are not using monitor lists, this method is trivial:

    method addMonitorList vmeList {
    }
	  

The vmeList is a CVMEReadoutList that is wrapped by Swig. A driver that uses monitor lists would add operations to the list as needed to retrieve the data being monitored from the device.

69.5.3.6. The processMonitorList method

processMonitorList is called with the data read by the monitor list marshalled into a Tcl list of bytes (string representation). The method is expected to process what it needs from the front of the list and return a count of the number of bytes processed. Since we are not using monitor lists, our implementation is:

    method processMonitorList data {
        return 0
    }
	  

69.5.3.7. The getMonitoredData method

If using a monitor list, this method typically returns the data last processed by processMonitorList with OK - prepended to indicate a successful completion. As usual an error or script errors will result in a return of ERROR - with the result string appended.

Since we are not using a monitor list, it's appropriate for us to return an error condition:

    method getMonitoredData {} {
        error "This driver has no monitored data"
    }
          

69.5.3.8. Validating the command options

The only thing left to do is write the option validation methods _validInd and _validIntList.

	Note
	Snit does not have method visibility control, that is all methods are public. By convention, methods that are not intended to be called by a client are given names that start with a _. Therefore these methods should be considered private.

    method _validInt {optname value} {
        if {[string is integer -strict $value]} {                  
	    set options($optname) $value                           
        } else {
            error "$optname must be configured with an integer was given '$value'" 
        }
    }
    method _validIntList {optname value} {
        if {![info complete $value]} {                            
            error "$optname must be given an integer list and '$value' isn't one"
        }

	set elements [llength $value]
        if {$elements != 16} {                                    
	    error "$optname must be given an integer list 16 '$value" as $elements"
	}
	
	foreach item $value {                                     
            if {![string is integer -strict $item]} {             
	       error "$optname list elements must be integer but '$item' in '$value' is not"
            }
        }
	set options($optname) $value                              
    }
	  

69.5.3.9. Using a Tcl control driver

To use a Tcl control driver you must:

1. Incorporate the driver into your controlconfig.tcl script either using the source or package require command.

2. Create an instance of your driver if needed. In the case of our toy driver, this means a command like: Mydriver aninstance to create a command ensemble named aninstance

3. If necessary configure our driver instance.

4. Wrap your driver with the tcl module type:

   Module create  atcldriver tcl
   Module config atcldriver -ensemble aninstance
   	      

The key point is that the -ensemble for a tcl module provides the base name of the command ensemble that Tcl driver wraps.