2.4. Event packets and larger systems.

2.4.1. What are packets

As you have seen, the production readout framework places no restriction on the format of the body of a buffer. Conventions have been adopted, however. These conventions are useful for larger systems. Especially systems which glue data together from more than one independent detector system.

The convention adopted at the NSCl for event bodies is that they should be composed of one or more packets. A packet is a chunk of data inside an event that has a word count, a uniquely assigned Identifying word, and a body. The word count includes itself and the identifying word.

Daniel Bazin at the NSCL serves as an authority for assigning packet ids for long lived devices (<bazin@nscl.msu.edu>). He maintains a list of the currently assigned packet ids (also known as tags) at: http://groups.nscl.msu.edu/userinfo/daq/nscltags.html.

Dividing a buffer up into packets has several advantages.

• Packets provide a predictable structure on the buffer which makes it easier to write analysis software.

• Each packet's readout and its corresponding SpecTcl unpacker can be maintained indepdendently of other packets, making it easy to compose the software of an experiment from existing modules.

• Packets document the contents of a buffer.

• Packet bodies can in turn have a sub-packet structure to provide whatever depth of structure is desired/required to organize the data.

2.4.2. Modifying the example to use packets.

We will modify our sample readout code to create the data within a packet. This would allow our event segment to be easily used with other event segments that follow the same convention, without any confusion about where the data from one segment ends and another begins.

class CDocumentedPacket      
{ 
public:
  CDocumentedPacket (unsigned short nTag,
		     const STD(string)&  rName,
		     const STD(string)&  rDescription,
		     const STD(string)&  rVersion); 
  unsigned short* Begin (unsigned short* rPointer)  ;
  unsigned short* End (unsigned short* rBuffer)  ;
  
};


                    

#ifndef __CMYEVENTSEGMENT_H
#define __CMYEVENTSEGMENT_H

#include <CEventSegment.h>                    

#include <string>                          // 


class CAENcard;
class CDocumentedPacket;                   // 

class CMyEventSegment : public CEventSegment  
{
private:                                      
  int        m_nSlot;
  int        m_nPedestal;
  CAENcard*  m_pModule;  
  CDocumentedPacket* m_pPacket;               // 
public:
  CMyEventSegment(int nSlot, int nPedestal, 
		  int id,    STD(string) name); // 
  ~CMyEventSegment();

                                             
  virtual void         Initialize();         
  virtual unsigned short*       Read(unsigned short* rBuffer);
  virtual void         Clear();
  virtual unsigned int MaxSize() {return 0;} 
  
};
#endif

                    

#include <CDocumentedPacket.h>         // 
. . .
CMyEventSegment::CMyEventSegment(int nSlot, int nPedestal,
				 int id,    string name) :
  m_nSlot(nSlot),
  m_nPedestal(nPedestal),
  m_pModule(new CAENcard(nSlot)),
  m_pPacket(0)                             // 
{
  // Be very unhappy if the module is not a
  // V775:

  int type = m_pModule->cardType();
  if (type != 775) {
    char errorMessage[100];
    delete m_pModule;
    sprintf(errorMessage, "Module in slot %d was is a %d should have been a 775\n",
	    m_nSlot, type);
    throw string(errorMessage);
  }
  m_pPacket = new CDocumentedPacket(id, name,    // 
				    string("CAEN V775 event data"),
				    string("1.0"));
}

                    

CMyEventSegment::~CMyEventSegment()
{
  delete m_pModule;
  delete m_pPacket;                            // <----- Added this line.
}

                    

unsigned short*
CMyEventSegment::Read(unsigned short* rBuffer)
{
  int bytesRead = 0;

  for (int i = 0; i < dataPresentTimeout; i++) {
    if(m_pModule->dataPresent()) {
      rBuffer = m_pPacket->Begin(rBuffer);          // 
      bytesRead = m_pModule->readEvent(rBuffer);
      rBuffer += bytesRead/sizeof(short);              // 
      rBuffer = m_pPacket->End(rBuffer);            // 
      break;
    }
  }

  return rBuffer;
}

                    

2.4.3. Effect on the data structure.

Lets see what all this does to our buffer structure. Start bufdump as before. This time, before starting a run, connect to the online system, set up the filter to accept both event buffers and packet-types buffers. The packet-types buffers are emitted at the beginning of a run, and describe the documented packets created by the readout segments.

Tell bufdump to get the next buffer, and only now start the run with your new packetizing event source. Bufdump should immediately dump something like the following:

Packet Type definitions buffer containing 1 packet descriptions
Name      Id         Description                Version   Instantiated
Detector1 0x8100     CAEN V775 event data         1.0     Mon May  8 07:26:33 2006
            

This is a formatted dump of the packet description buffer. Note that the name, Id, description and version match our parameters to the CDocumentedPacket constructor. Furthermore, the packet documentation describes when the CDocumentedPacket was created.

Now click the next buffer button again, to look at an event buffer. The first few events might look like:

Event Data buffer with 441 events
Event: 0  Size: 9 :
   Packet id 0x8100 : CAEN V775 event data Body size: 6 body:
0x5200 0x0100 0x5000 0x4467 0x5413 0xec97

Event: 1  Size: 9 :
   Packet id 0x8100 : CAEN V775 event data Body size: 6 body:
0x5200 0x0100 0x5000 0x4468 0x5413 0xec98

Event: 2  Size: 9 :
   Packet id 0x8100 : CAEN V775 event data Body size: 6 body:
0x5200 0x0100 0x5000 0x4467 0x5413 0xecdd

            

Some legacy software produces packets without using the CDocumentedPacket class. bufdump therefore reads in a packet definition file that describes the set of packet ids that have been allocated at the NSCL. The bufdump online help and the reference information later in this book describe how to incorporate additional packet definitions to bufdump as well as how to program plugins which know how to format the body of packets in an application specific way.