13.5. Extending the generator with loadable C++ generators

13.5.2.1. onAttach - define the configurable options

onAttach is called when the driver is being associated with its configuration object. The configuration object is passed in by reference, but the caller retains ownership, so you shouild not delete this object. Normally, you will need to save a pointer to that object, however.

THe configuration object is an instance of XXUSB::CConfigurableObject This class has methods both for defining configuration options and interrogating their current values. The configuration maintained by XXUSB::CConfigurableObject consists of a set of keywords (called options), and associated values. A value proposed for an option can be validated by a validation function. Many standard validators are supplied with XXUSB::CConfigurableObject as well as convenience methods to use them transparently. By convention, option names, begin with a - to make them look like Tk options. This is not enforced by XXUSB::CConfigurableObject.

The work of onAttach is to define thd configuration options the driver needs. A minimal option might be the base address of the specific device the driver is generating code for (by convention this is -base). Let's pull apart the sample driver's implementation. See the sample driver's comments for onAttache

void
SampleDriver::onAttach(XXUSB::CConfigurableObject& configuration) {
    m_pConfiguration = &configuration;                        

    m_pConfiguration->addIntegerParameter("-marker", 0);          


    m_pConfiguration->addIntegerParameter("-resetloc");           
    m_pConfiguration->addIntegerParameter("-resetvalue", 0, 0xffff, 0xaaaa); 

    m_pConfiguration->addBooleanParameter("-writeendrun", false);  
    m_pConfiguration->addIntegerParameter("-endrunloc");
    m_pConfiguration->addIntegerParameter("-endrunvalue", 0, 0xffff, 0xbbbb);
}

                

Before picking apart onAttach a bit about the operations the driver will generate. For readout, the driver will generate a fixed marker. For initialization, the driver will generate a 16 bit write to some VME location that can be specified. For finalization (as the run ends), the driver will optionally generate a 16 bit write to another VME location.

The numbers in the list below refer to the number in the example above.

13.5.2.2. Initialize - generating operations to set-up the device

Initialize is called after the configuration script has been completely executed. It is only called if the configuration script executed without errors. This method generates operations that will be performed as a run is starting to setup the device for data taking. Normally this invovle querying the configuration and performing operations on the controller parameter passed in.

While the CVMUSB class in the mvlcgenerate framework is intended to be much like the class with the same name in the VMUSBReadout application, the main thing to keep in mind is that your driver cannot actually talk to hardware. It can only generate operations that will be memorized and regurgitated when it comes time to generate initialization operation lists.

This has the following implications, if you are porting drivers from VMUSBReadout:

• You cannot interrogate the device (by performing reads). This may require additional options to be defined. For example, when porting the driver for the CAEN V785, V775, V792, modules, the VMUSBReadout driver asked each module for its model number and generated code specific to the module type, ADC, QDC, or TDC, this is not possible with mvlcgenerate, so an additional option -type was added that has an enumerated vavlue (adc, qdc, or tdc) that drives module type specific code generatikon in mvlcgenerate.

• Bit more subtle is that delays must be pushed into the set of generated operations. In many drivers, initialization requires some delay. For example, a general module reset may require a delay before the module can accpet additional configuration. In VMUSBReadout modules, this was often done via calls to sleep or usleep. In mvlcgenerate, this will simply delay code generation rather than actually supplying the run-time delay required. Instead you must add a run-time delay using the CVMUSB delay method.

• While using CVMUSBReadoutList to generate list of operations is supported for compatibility with existing VMUSBReadout drivers, the CVMUSB::executeList methods, just append the operations in the list to the list of VME operations it is memorizing. This method will never generate an error and it will always claim to have read 0 bytes of data.

In our SampleDriver none of this is relevant, but it is important to keep these points in mind for actual drivers. Let's have a look at the SampleDriver::Initialize code:

void
SampleDriver::Initialize(CVMUSB& controller) {
    uint32_t addr = m_pConfiguration->getIntegerParameter("-resetloc");
    uint32_t value = m_pConfiguration->getIntegerParameter("-resetvalue");

    controller.vmeWrite16(addr, CVMUSBReadoutList::a32UserData, value);
}
                

This code is relatively straightforward, The value sof the two integer configuration parameters, -restloc -resetvalue are fetched from the configuration object and used in a call to the CVMUSB vmewrite16 to add a 16 bit VME write to the list of initialization opertaions. CVMUSBReadoutList::a23UserData specifies a VME bus address modifier that specifies the VME address space associated with the address. A discussion of VME address modifiers is beyond the scope of this documentation. See: https://www.vita.com/page-1855177 for a description of address modifiers and what they do.

13.5.2.3. AddReadoutList - Generating operations to read the device

The AddReadoutList requires that you generate the list of operations that will be executed when the device is read out. In the case of our sample driver, we're just going to add a maker to the list. When coding this, or porting drivers from the VMUSBReadout, remember once more that you are not actually able to perform operations on the device itself. You can only add operations that will be added to the list of operations that will read the device. All read operations added to that list, will insert data into the event buffer.

AddReadoutList gets a reference to a CVMUSBReadoutList which is intended to implement the operations that the class of the same name implmeents for the VMUSBReadout framework. Where there is a mismatch in how these operations are implemented between the MVLC and the VMUSB, the proper MVLC readout list code is generated to perform the requested operation. For example, block reads where the transfer count comes from a field ina preceding read generate the appropriate accumluator load, shift and mask and accumulator driven block read.

Here is the addReadoutList for our sample driver:

void
SampleDriver::addReadoutList(CVMUSBReadoutList& list) {
    uint32_t markerValue = m_pConfiguration->getIntegerParameter("-marker");
    list.addMarker(markerValue);
}
                

The only thing of note here is that the markers generated by the MVLC are 32 bit markers, while those generated by the VMUSB are 16 bit markers.

13.5.2.4. onEndRun - shutting down the device

onEndOfRun is called to give the driver an opportunity to perform operations as a data taking run ends. Normally, these operations disable the device and clear any buffered data.

void
SampleDriver::onEndRun(CVMUSB& controller) {
    if (m_pConfiguration->getBoolParameter("-writeendrun")) {
        uint32_t addr = m_pConfiguration->getIntegerParameter("-endrunloc");
        uint32_t value = m_pConfiguration->getIntegerParameter("-endrunvalue");
        controller.vmeWrite16(addr, CVMUSBReadoutList::a32UserData, value);
    }
}

                

Notice how we use the -writendrun to conditionalize the write. Everything else should, by now be pretty clear.

13.5.3.1. mvlcgenerate SampleDriverCommand construction/destruction

Let's have a look at the constructor of the SampleDriverCommand:

SampleDriverCommand::SampleDriverCommand(
    CTCLInterpreter& interp, TCLConfigParser& parser) :
    DeviceCommand(interp, "example", parser)
{}

                

In our case, the base class contructor does all the work. We passed the interpreter, a command name: example and the configuration parser on to it. The Configuration parser (TCLConfigPaser) is the object that accumulates the configuration by processing the configuration script. Some drivers and driver commands, may require access to this object. For example, the caenchain object must generate objects that can validate that the modules in their chains actually exist and are C785 modules. The parser, includes factilities for finding modules or, alternatively, determining that modules don't exist.

The destructor, in our case, is empty. If your command allocates any dynamic memory, of course the destructor must delete it.

13.5.3.2. createDevice - creating a device instance

The createDevice is respsonsible for creating a new, dynamically allocated, driver instance (SampleDriver in our case), and binding it into a CReadoutModule. Remember, a device instance, consists of a driver instance and a configuration. These are packaged together in a CReadoutModule object.

For simple devices, the boilerplate below can be modified to create and return an appropriate CReaodutModule. Note that once returned, ownership of the module and associated device pass to the caller.

CReadoutModule*
SampleDriverCommand::createDevice(std::string name) {
    CReadoutModule* result = new CReadoutModule;
    result->SetDriver(new SampleDriver);

    return result;
}

                    

Once a CRedoutModule is created its driver can be allocated and associated using the SetDriver method. The CReadoutModule is then returned to the caller, in our case, the code executing the example create name example. The name is the name of the device instance being created. In most cases, the driver instance doesn't need this.