11.3. Creating the Readout program

11.3.1. Obtaining the Readout Skeleton

The readout skeleton is part of NSCLDAQ. For this example we are going to use the most recent version of NSCLDAQ-11.0 We are going to set up environment variables for that version of NSCLDAQ, make a directory called readout in our current working directory and copy the SBS skeleton into that directory:

. /usr/opt/daq/11.0/daqsetup                 # Define env variables
mkdir readout                                # make an empty directory.
cd readout                                  
cp $DAQROOT/skeletons/sbs/* .                # Copy the skeleton.
                

The Readout skeleton is a template that can be modified to build a functional readout program. In the next two section, we'll do just that.

11.3.2. Writing the Event segment

The Readout program responds to triggers (we'll get to triggers in the next section) by executing one or more event segments to read data from the hardware into an event buffer. You can register as many event segments as you want. Event segments allow you to organize the readout of your experiment into logical chunks. Often event segments will readout one of several detector subsystems that make up your experiment.

Event segments are C++ classes that are derived from the base class CEventSegment. The base class defines the interface between your event segment and the SBS readout framework. The base class provides reasonable default implementations for most of these interfaces so you only need to implement the interfaces your event segment needs.

We are going to implement:

• initialize - To set up the V775 for readout.

• read - to read an event.

See $DAQROOT/include/sbsreadout/CEventSegment.h and the online reference for CEventSegment in http://docs.nscl.msu.edu/daq for more information about the interface this class defines.

Here is a header that describes the class we are going to write:

#ifndef _V775EVENTSEGMENT_H                            
#define _V775EVENTSEGMENT_H

#include <CEventSegment.h>                       

class CAENcard;                                        



class CV775EventSegment : public CEventSegment        
{
private:
  CAENcard&   m_module;                          

public:
  CV775EventSegment(CAENcard& module);           
public:
  virtual void initialize();                         
  virtual size_t read(void* pBuffer, size_t maxwords);
};


#endif
                  
                

Let's look at the implementation. We're going to look at the following sections of the implementation file

• File heading #include directives etc.

• Constructor

• initialize

• read

#include "V775EventSegment.h"                  
#include <CAENcard.h>                    
#include <iostream>
#include <stdint.h>


static const unsigned  TDC_RANGE = 0x1e;       
static const unsigned  MAX_WORDS =
        34*sizeof(uint32_t)/sizeof(uint16_t);  
                

CV775EventSegment::CV775EventSegment(CAENcard& module) :
  m_module(module)
{}

                

The constructor only has to initialize the reference to the CAENcard object that is controlling our TDC.

void
CV775EventSegment::initialize()
{
  try {                                     
    m_module.commonStart();                 
    m_module.setRange(TDC_RANGE);           
    m_module.clearData();
  }
  catch (std::string msg) {                 
    std::cerr << "Unable to initialize TDC (V775)\n";
    std::cerr << msg <<std::endl;
    throw;
  }
}
                

size_t
CV775EventSegment::read(void* pBuffer, size_t maxWords)      
{
  if (MAX_WORDS <= maxWords) {                            
    size_t n = m_module.readEvent(pBuffer);                      
    m_module.clearData();
    return n/sizeof(uint16_t);
  } else {
    throw std::string(
        "CV775EventSegment::read - maxWords won't hold my worst case event" 
    );
  }
}

                

11.3.3. Writing the trigger

The event segment read methods are called in response to a trigger. But what is a trigger? In the SBS readout framework a trigger is anything we say it is. We supply, or use a trigger object that tells the readout framework when to do the readout.

Usually there is a hardware trigger that is some combination of external hardware and a trigger object that monitors that hardware to determine when the trigger occured. The external trigger hardware then interfaces with the VME crate via either a CAEN V262 I/O register or a CAEN V976 coincidecne register for example.

For our simple setup, the appropriate time to trigger a readout is when the V775 has data available. The CAENcard class has a method dataPresent that can report this condition. We will use that method as the basis for our trigger class.

In SBS Readout, trigger classes are derived from the CEventTrigger base class. As with the CEventSegment class, this class provides a set of defined interfaces between the readout framework and objects that can test for trigger conditions.

While there are initialization and tear down methods, our initialization is done by the event segment, so we only need to check for the trigger condition.

Here's the header for our trigger class MyTrigger:

#ifndef _MYTRIGGER_H
#define _MYTRIGGER_H

#include <CEventTrigger.h>

class CAENcard;

class MyTrigger : public CEventTrigger
{
private:
  CAENcard& m_module;
public:

  virtual bool operator()();
};

                

If you understood how we wrote the event segment this should be clear. The only new wrinkle is the use of operator(). This is the function call operator. When defined, it allows objects of a class to be dalled as if they were functions. Objects of this sort, functions that have state are often called functors.

The implementation is also simple:

#include "MyTrigger.h"
#include <CAENcard.h>


MyTrigger::MyTrigger(CAENcard& module) :
  m_module(module)
{}

bool
MyTrigger::operator()() {
  return m_module.dataPresent();
}
                    
                

The constructor saves a reference to the module and the function call operator returns the state of that module's data present. If an object of this class is established as a trigger, it will trigger a readout whenever thte module has data.

11.3.4. Hooking everything together.

In the last two sections we've written our event segment and trigger classes. In order to use them

• We must add an instance of our event segment to the Readout framework's top level event segment.

• We must declare an instance of our trigger as the event trigger.

These are done by editing the Skeleton.cpp file that you copied into your work directory for Readout.

At the top you will need to #include the headers for your new classes:

#include <config.h>
#include <Skeleton.h>
#include <CExperiment.h>
#include <TCLInterpreter.h>
#include <CTimedTrigger.h>

#include <CAENcard.h>              // Add this line.
#include "V775EventSegment.h"            // Add this line
#include "MyTrigger.h"                   // Add this line.
                    
                

The Skeleton.cpp method SetupReadout is where we will make the remainder of the changes. We're going have to:

• Create a long lived CAENcard object to communicate with our V775.

• Create and register a MyTrigger object to act as the event trigger, that uses the card we created.

• Create and register a V775EventSegment to readout the V775 card we created.

Here's what the SetupReadout method looks like when we're done modifying it:

static const uint32_t V775Base=0x11110000;                  

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

  CAENcard* pModule = new CAENcard(10, 0, false, V775Base);     
  
  pExperiment->EstablishTrigger(new MyTrigger(*pModule));       

  pExperiment->AddEventSegment(new CV775EventSegment(*pModule)); 


}
                    
                

11.3.5. Building and testing your Readout

When you copied the skeleton, you also copied in a starting point for a Makefile for your project. In this section we're going to modify that Makefile so that a build of your Readout program will compile your trigger and event segments and link them into the Readout.

The Makefile defines a symbol OBJECTS that is the list of objects that need to be built. It also defines rules for building C and C++ source files to an objet file in a way that allows access to the headers and libraries of NSCLDAQ. In many cases you just need to add the desired objects to the definition of OBJECTS:

...
#
#  This is a list of the objects that go into making the application
#  Make, in most cases will figure out how to build them:

OBJECTS=Skeleton.o V775EventSegment.o MyTrigger.o
...
                

Once you have made this modification to the Makefile just issue the make commnad to build your Readout program.

We're going to use the NSCLDAQ dumper pgoram to test our readout program. To do this, you may want to have a copy of the V775 manual handy so that you can make sense of the data that is read.

Assuming the electronics is set up as described in the block diagram and the base address of the V775 has been configured as described above, we should be able to take data from this system

First building and running your Readout interactively:

make
./Readout
%
                

In a second terminal window; setup the NSCLDAQ environment definitions as before and:

$DAQBIN/dumper
                

Now in the Readout window start a run let it run for a while and end the run.

begin
%  (wait a bit)
end
%
                

Let's look at some dumped events for the case where I had a stop input in to channel 0 of the TDC:

-----------------------------------------------------------
Event 16 bytes long
No body header
0008 0000 5200 0100 5001 41f3 5400 1555 

-----------------------------------------------------------
Event 16 bytes long
No body header
0008 0000 5200 0100 5001 41f3 5400 1556 

-----------------------------------------------------------
Event 16 bytes long
No body header
0008 0000 5200 0100 5001 41f3 5400 1557 

                

Before we pick this apart, I want to make a comment about word endianess. Endianess, in this context means that when you represent data that are larger than a byte there is a choice (usually made by the hardware) made to determine if the first bytes represent the low order bits (little endian), or the high order bits (big endian).

While the computers we run NSCLDAQ on (intel chips) are little endian, the VME bus is inherently big endian. This will be clear as we describe the meaning of the longwords in the data.

The SBS readout framework will prefix the data you read with a self-inclusive count of the number of 16 bit words in the event. Since this is generated by the SBS readout program running in the intel CPU, this 32 bit item is in little endian order (first the 0x0008 which are the low order bits then 0x0000 the high order bits). According to these data, the event 8 16 bit words in length.

The remainder of the data are as described in the V775 manual. The VME bus is inherently big endian, so the data have the high order bits first:

1. 0x52000100 is a header for virtual slot 10 which has a single channel worth of data.

2. 0x500141f3 is data for channel number 0 with the value 0x1f3 and the valid data bit set.

3. 0x54001557 is a trailer word for event number 0x1557 since the event count was zeroed (a the start of the run).