5.3. Writing device support software

5.3.1. The driver onAttach method

Each driver instance has a configuration database attached to it when it is created. The configuration database holds configuration parameter definitions and their current values. The framework takes care of managing the values for you, however you must define the set of configuration parameters supported by your driver.

The template driver's code is (comments removed for brevity:

void
CTemplateDriver::onAttach(CReadoutModule& configuration)
{
  m_pConfiguration = &configuration;                    
  m_pConfiguration->addIntegerParameter("-slot", 1, 23, 1); 

  m_pConfiguration->addIntegerParameter("-value"); // default is 0. 
}
                

Normally the onAttach method is simply defining the set of configuration parameters it needs to know how to initialize and read the device it manages. Configuration parameters are named items (by convention the names start with the dash character) and are strongly typed. Integer, real, string, enumerated, and boolean simple parameters are supported. In addtion collection (Tcl lists) are supported.

Parameter values can have constraints placed on them (the range of -slot parameter values e.g.) which are checked by the configuration subsystem without any intervention by you. Several pre-defined constraint checkers are available, as are convenience functions for defining configuration parameters. You can also define custom constraint checkers and register them with the configuration subsystem.

See CConfigurableObject(3ccusb) for detailed information about how to define configuration parameters.

5.3.2. The driver Initialize method

The Initialize method of each device instance that has been put in a stack is called after the configuration file is processed prior to loading the stack and prior to turning on data taking mode in the CC-USB.

Typically in Initialize you must:

1. Fetch the configuration parameters you need to know how to initialize the device and prepare it for data taking.

2. Issue method calls to the controller CCCUSB object passed in to the method. Note that if your device requires a lot of initialization, you can speed up that process by creating CCCUSBReadoutList objects, which are lists of instructions, using its methods to create a list of operatinos and then asking the controller to execute that list.

For detailed information about the methods supported by the CCCUSB and CCCUSBReadoutList, see CCCUSB(3ccusb) and CCCUSBReadoutList(3ccusb)

The template driver provides the following code (most comments removed for brevity).

void
CTemplateDriver::Initialize(CCCUSB& controller)
{

  int slot = m_pConfiguration->getIntegerParameter("-slot"); 

  /* MODIFY ME HERE */
                                                             
  /* END MODIFICATIONS */

}


                

5.3.3. The driver addReadoutList method

addReadoutList is called as a run is being intialized. This method is expected to contribute items to the CCCUSBRedoutList that will be loaded into either a scaler or event stack. Usuall this is done by fetching the set of configuration parameters that are required to know how to read the device and then invoking appropriate methods on the list parameter to add CAMAC operations to the stack.

The template driver implements a marker 'device'. The marker device ignores its -slot configuration parameter (a production quality marker driver would probably not define a -slot parameter). It adds an instrution to the list that inserts a literal value into the event. The value inserted is determined by the -value parameter.

Here's the sample driver code for the addReadoutList method:

void
CTemplateDriver::addReadoutList(CCCUSBReadoutList& list)
{
  int slot = m_pConfiguration->getIntegerParameter("-slot");
  
  /* MODIFY ME HERE */
  
  int value = m_pConfiguration->getIntegerParameter("-value");  
  list.addMarker(value);        // This is a longword marker.   

  /* END MODIFICATIONS */
}

                

5.3.4. Initializing the driver with the framework.

The Tcl load command searches the shared object for a specific function entry point that it will call to initialize the library. The initialization function must follow the correct naming conventions or Tcl will complain about not being able to find the library's initialization function.

The initialization entry point must be the name of the resulting library with the lib prefix stripped off and the first letter capitalized suffixed by _Init. Thus if you are building libmydriver.so, the initialation function must be called Mydriver_Init.

The template driver provides the following code:

extern "C" {                                    
  int Templatedriver_Init(Tcl_Interp* pInterp)  
  {
    Tcl_PkgProvide(pInterp, "Templatedriver", "1.0"); 
 
    CUserCommand::addDriver("changeme", new CTemplateDriver); 

    return TCL_OK;                               

  }
}