66.2. Writing a driver

66.2.1. Obtaining the scripted reaodut skeleton

The scripted readout skeleton is located in skeletons/scriptedReadout/skel relative to the top level of the nscldaq installation. If, your installation of NSCLDAQ is at /usr/opt/nscldaq/11.0 for example, the following sequence of commands will create a new directory and copy the skeleton into that directory.

mkdir development
cd    development
cp /usr/opt/nscldaq/11.0/skeletons/scriptedReadout/skel/* .
                

In the remainder of this chapter we are gonig to assume your current working directory is a directory in which the skeleton has been added.

66.2.2. Writing a module and a module creator

Writing a module and module creator is the hard work of supporting a new device. The module class supports the module and the creator makes the new device known to the module command. To illustrate the basic techniques of writing modules and their creators without referring to any specific hardware, we are going to develop a 'module' that produces a counting pattern. You will be able to configure the number of words in the counting pattern, the starting value of the pattern and the direction of the count (ascending or descending).

The key features of a module clasa are:

• They are derived from CDigitizerModule

• They implement an Initialize That set up the module in accordance with the value of cofiguration options registered for the module at construction time. This initialization is performed once at the beginning of each bout of data taking (begin or resume).

• They implement a Prepare method which prepares the module for an event (both the first one and subsequent events after the first one). This method is called both at the start of data taking and after acquiring an event.

• They implement a Read method which places data from the device into the event buffer in response to a trigger.

• They implement a Clear method which clears any data buffered in the digitizer. This is called bouth at the start of a bout of data taking and after an event has been read. In all cases, Clear is called prior to Prepare

• They implement a getType method which returns a string documenting the type of module they are.

Note that any methods that are not required may be omitted since all methods are default in the base class to do nothing.

Armed with the knowledge above the class header is easy to write. Since we are not talking to hardware we can omit the Prepare and Clear methods:

#ifndef __COUNTERMODULE_H             
#define __COUNTERMODULE_H

#ifndef __CDIGITIZERMODULE_H
#include <CDigitizerModule.h%>  
#endif
class CCounterModule : public CDigitizerModule { 
    int  m_firstValue;
    int  m_length;                    
    int  m_increment;
    
public:
    CCounterModule(const std::string& rName, CTCLInterpreter& interp); 
    virtual ~CCounterModule();
    
    virtual void Initialize();        
    virtual int  Read(void* pBuffer);     
    virtual std::string getType() const{
       return std::string("counter");
    }
};
#endif
                

CCounterModule::~CCounterModule() {}
                    

CCounterModule::CCounterModule(const string& rName, CTCLInterpreter& rInterp) :
    CDigitizerModule(rName, rInterp)               
{
    AddIntParam("size", 10);                       
    AddIntParam("start", 1);
    AddIntParam("increment", 1);
}
                    

void
CCounterModule::Initialize()
{
    CIntConfigParam* pConfigItem;
    
    pConfigItem = (CIntConfigParam*)(*(Find("size"))); 
    m_length    = pConfigItem->getOptionValue();
    
    pConfigItem = (CIntConfigParam*)(*(Find("start")));
    m_firstValue = pConfigItem->getOptionValue();
    
    pConfigItem = (CIntConfigParam*)(*(Find("increment")));
    m_increment = pConfigItem->getOptionValue();
    
        
}
                    

int CCounterModule::Read(void* pEvent)
{
    uint16_t* p = reinterpret_cast<uint16_t*>(pEvent); 
    
    int value = m_firstValue;                                
    for (int i = 0; i < m_length; i++) {                 
        *p++ = value;                                        
        value += m_increment;
    }
    return m_length;                                         
}
                    

#ifndef __CMODULECREATOR_H     //CModuleCreator
#include <CModuleCreator.h>                                 
#endif
class CCounterCreator  : public CModuleCreator                    
{	
public:
  CCounterCreator ();                                             
  virtual ~CCAENV830Creator ( );


public:

   virtual   CReadableObject* Create (CTCLInterpreter& rInterp, 
				      CTCLResult& rResult,    
				      int nArgs, char** pArgs)   ;  
   virtual   std::string  Help ();                                

};

                    

CCounterCreator::CCounterCreator() :
   CModuleCreator("counter")
{}
                    

 CCounterCreator::Create(CTCLInterpreter& rInterp,
                       CTCLResult& rResult,                    
                       int nArgs, char** pArgs)
{

  CReadableObject* pModule = new CCounterModule(*pArgs, rInterp);  
  nArgs -= 2;                   // Get rid of module name and type. 
  pArgs += 2;

  // If there are any remaining args, configure the mdoule:

  if (nArgs) {
    int status = pModule->Configure(rInterp, rResult,              
                                    nArgs, pArgs);
    if (status != TCL_OK) {
      delete pModule;                                              
      pModule = (CReadableObject*)NULL;
    }

  }
  return pModule;                                                 
}
                    

66.2.3. Extending CScriptedSegment

Recall that the Readout framework itself organizes the hardware into event segments. Each event segment is normally responsible for some part of the detector system. Event segments are added to the readout program by initialization code in the skeleton software (which we will cover in the next section).

The scripted readout framework defines a special CScriptedSegment which which handles reading the configuration file creating the appropriate driver modules, configuring them and calling them in the appropriate order in response to a trigger. CScriptedSegment will need to be extended if you have added your own module drivers. Specifically, the segment will need to register creators for your new modules with the module command so that that command both knows about the new module and has a mechanism to create instancs of it.

This section will continue the example from the last section and show how to derive a new class from the CScriptedSegment that registeres the CCounterCreator. The next section will show how to modify Skeleton.cpp so that it uses your scripted event segment instead of the base class.

When adding scaler module support, the concept is identical however you will derive your class from CScriptedScalers wich is a CScaler class that operates in a manner similiar to CScriptedSegment.

As usual, we start by looking at the important featurs of the header for CMyScriptedSegement the new scripted segment we're going to write.

// CMyScriptedSegment.h

#ifndef __CEVENTSEGMENT_H
#include <CEventSegment.h>                   
#endif

class CMyScriptedSegment : public CScriptedSegment 
{
  virtual void addUserWrittenCreators();           
};
                

Now let's look at the key implementation features.

#include "CMyScriptedSegment.h"                   
#include "CCounterCreator.h"

void
CMyScriptedSegment::addUserWrittenCreators() {   
    addCreator(*(new CCounterCreator()));        
}
                

66.2.4. Modifying Skeleton.cpp

If you have worked with the SBS readout framework, you know that everything gets knit together in the Skeleton.cpp file. Continuing the example in the previous section, we're going to point out how to modify Skeleton.cpp so that your scripted event segment CMyScriptedSegment is used as the event segment rather than the normal CScritedSegment. Doing this ensures that your hardware configuration file can use addtional module types (such as the counter type) you have added to the system.

We are going to modify the Skeleton::SetupReadout method. If you were adding scaler modules you would make very similar modifications to the Skeleton::SetupScalers

The first thing you will need to do is add an #include "MyScriptedSegment.h" directive towards the top of the headers in Skeleton.cpp I like to add #include directives at the end of those that are already there.

Below is what them modified SetupReadout should look like. Comments have been removed for the sake of brevity. The code assumes you are using a V977 coincidence register at 0x11110000 of crate 0 as both the trigger and busy module.

Skeleton::SetupReadout(CExperiment* pExperiment)
{
  CReadoutMain::SetupReadout(pExperiment);

  pExperiment->EstablishTrigger(new CV977Trigger(0x11110000));  
  pExperiment->EstablishTrigger(new CV977Busy(0x11110000));
  
  pExperiment->AddEventSegment(new CMyScriptedSegment());       

}
                

66.2.5. Modifying the Makefile

In the previous several sections, we added several source files. Not counting headers:

In addition we modified Skeleton.cpp but that does not require any changes to the Makefile. As with most templated NSCL makefiles there is a Makefile definition OBJECTS which is the list of object files that must be built and linked into the readout framework.

This is a whitespace separated list. Initially it looks like

    OBJECTS=Skeleton.o
                        

    OBJECTS=Skeleton.o CCounterModule.o CCounterCreator.o CMyScriptedSegment.o