\documentstyle[a4wide,11pt]{article}
\title{Event Format [Sorting + Storage]}
\author{John Cresswell}
\date{Edition 1.0\\February 1991}
 
\begin{document}
 
\begin{titlepage}
{
 
\hoffset=1truein
\hsize=5.25truein
\vsize=10.25truein
\font\small=cmssbx10 at 14.4truept
\font\medium=cmssbx10 at 17.28truept
\font\large=cmssbx10 at 20.74truept
\hrule height 0pt
\parindent=0pt
%\parskip=0pt
\hskip 3.9truein
\large
EDOC073\par
\vskip .5truein
\large
EUROGAM PROJECT\par
\vskip 1.5truein
\hrule height 2pt
\vskip 20pt
\large
NSF DATA ACQUISITION SYSTEM\par
\vskip .5truein
Event Format [Sorting + Storage]\par
\vskip 20pt
\hrule height 2pt
\vskip 1truein
\medium
Edition 1.0\par
\vskip 5pt
February 1991\par
\vfill
\medium
Nuclear Structure Software Support Group\par
\vskip 5pt
Liverpool University\par
\vskip .5truein
 
}
\end{titlepage}
 
\maketitle
 
\setlength{\parskip}{1ex}
\setlength{\parindent}{0em}
\section{Introduction}
 
{\em The format described in this document has been agreed
at the software meeting in Strasbourg 16-18 January 1991}
 
The event data format described in this document differs from the format
of the data stream output from the data acquisition electronics.
The changes have been made basically for two reasons.
The separation of data items into sub-events associated with each
Readout Controller is an artificial
division made necessary by features of the electronics and not the data
itself. Therefore there is no separation within events related to readout
methodology.
Secondly, significant space savings can be achieved by re-formatting
associated sets of parameters into the group format as described below.
 
This document describes the event format as written to magnetic tape
storage and hence of interest to the experimenter.
The data format output from the Eurogam Readout Controllers will not be
visible to the experimenter.
 
\section{Data Formats}
 
The basic unit of data is the 32bit word consisting of a 16bit
data value, a 14bit data address and a 2bit word type.
The defined data word format types are summarised in the final section
of this document.
 
The 2bit word type field is not fully allocated.
Unused values (``10'' and most of ``11'')
are reserved and
should not be used.
 
There may be many events in an event block.
The length of an event block is variable and terminated by
the end block token.
In practice, the end block token
should be augmented by some separate indication of the total block
length (e.g. as returned by file read).
Both indications should be used during event unpacking
to ensure that corrupted data does not result in chaining past the
end of the block.
 
The grouped data word format is defined primarily for compactness.
Groups of 1 or 2 items occupy the same space as simple words, but
space savings occur for 3 items and more.
The philosophy of groups is explained more fully in the next section.
 
\section{Parameter Groupings}
 
It has been noted that most modern detector systems consist of
many similar detectors with several related parameters repeated for each
detector.
This natural grouping of related parameters can be exploited
to make the user interface more understandable.
 
Each group maps onto a software record or structure.
This makes it easy to process the information from a particular
detector.
With this scheme all parameters related to a particular detector
are kept together.
This allows access to individual parameters within a record, but
also allows whole records to be accessed
and moved around efficiently by using pointers.
 
Each data parameter has a unique 14bit address which is allocated
when the data acquisition is setup.
In order to make the processing of the data words easier,
it has been decided to logically divide the address into two parts
(an 8bit group number and a 6bit item).
This subdivision is somewhat arbitary, but allows the group number
to be extracted easily as a byte.
The item numbers within a group are sequential starting from zero.
 
The main point to note is that whether event parameters are kept as
simple variables or as groups,
then each parameter still has a unique 14bit address.
If a group with several items is defined, then each item within the
group has a particular 14bit address which  cannot also be allocated
to another simple variable or another group item.
Similarly, there cannot be more than one group with the same group number.
 
Since the item field is in the most significant 6 bits of the address,
then the resultant addresses of items in a group will not be consecutive.
However, when viewed as a hexadecimal number the address is
trivially decoded into detector number and parameter offset.
 
Group 255 is defined as the system or trigger group.
If present, it will normally be positioned immediately following
the event header token.
Others group numbers are freely available to be allocated as and when
necessary for particular acquisition sub-systems (Ge/BGO,RMS,FIFI,...).
 
This ordering of parameters into associated groups should
make event processing easier to accomplish. Several of the operations
to be applied to each event will be group oriented. For example,
the sum energy calculation will include the same words from each of
the Ge groups. Also, a typical operation may be to filter on all
Ge TDC words ... again the same operation performed on the same 
word from each group.
 
\newpage
\section{Event Format Summary}
 
There are four basic format word variants.
For each event there is a unique separator word called the Start Event token.
This is followed by an optional number of simple and group formatted data
words.
A data block will consist of one or more such events terminated by the
End Block Token. Events will not be split across block boundaries.
 
All numeric values are given in hexadecimal.
\vspace{0.5in}
 
1) Start Event Token ...
 
\begin{center}
\makebox[1.5in]{\rule[-0.2cm]{0cm}{0.4cm}Field size
}\makebox[0.2in]{\rule[-0.2cm]{0cm}{0.4cm}2
}\makebox[0.6in]{\rule[-0.2cm]{0cm}{0.4cm}6
}\makebox[0.8in]{\rule[-0.2cm]{0cm}{0.4cm}8
}\makebox[1.6in]{\rule[-0.2cm]{0cm}{0.4cm}16}
 
\makebox[1.5in]{\rule[-0.2cm]{0cm}{0.6cm}
}\framebox[0.2in]{\rule[-0.2cm]{0cm}{0.6cm}
{11}}\framebox[0.6in]{\rule[-0.2cm]{0cm}{0.6cm}3f
}\framebox[0.8in]{\rule[-0.2cm]{0cm}{0.6cm}ff
}\framebox[1.6in]{\rule[-0.2cm]{0cm}{0.6cm}ELen}
 
\end{center}
\vspace{0.25in}
2) Simple Data Word Format ...
 
\begin{center}
\makebox[1.5in]{\rule[-0.2cm]{0cm}{0.4cm}Field size
}\makebox[0.2in]{\rule[-0.2cm]{0cm}{0.4cm}2
}\makebox[1.4in]{\rule[-0.2cm]{0cm}{0.4cm}14
}\makebox[1.6in]{\rule[-0.2cm]{0cm}{0.4cm}16}
 
\makebox[1.5in]{\rule[-0.2cm]{0cm}{0.6cm}
}\framebox[0.2in]{\rule[-0.2cm]{0cm}{0.6cm}
{00}}\framebox[1.4in]{\rule[-0.2cm]{0cm}{0.6cm}
Address}\framebox[1.6in]{\rule[-0.2cm]{0cm}{0.6cm}Data}
 
\end{center}
\vspace{0.25in}
3) Group Data Word Format ...
 
\begin{center}
\makebox[1.5in]{\rule[-0.2cm]{0cm}{0.4cm}Field size
}\makebox[0.2in]{\rule[-0.2cm]{0cm}{0.4cm}2
}\makebox[0.6in]{\rule[-0.2cm]{0cm}{0.4cm}6
}\makebox[0.8in]{\rule[-0.2cm]{0cm}{0.4cm}8
}\makebox[1.6in]{\rule[-0.2cm]{0cm}{0.4cm}16}
 
\makebox[1.5in]{\rule[-0.2cm]{0cm}{0.6cm}
}\framebox[0.2in]{\rule[-0.2cm]{0cm}{0.6cm}
{01}}\framebox[0.6in]{\rule[-0.2cm]{0cm}{0.6cm}
ic}\framebox[0.8in]{\rule[-0.2cm]{0cm}{0.6cm}g
}\framebox[1.6in]{\rule[-0.2cm]{0cm}{0.6cm}Data1}
 
\makebox[1.5in]{\rule[-0.2cm]{0cm}{0.6cm}+ optional word(s)
}\framebox[1.6in]{\rule[-0.2cm]{0cm}{0.6cm}
Data2}\framebox[1.6in]{\rule[-0.2cm]{0cm}{0.6cm}Data3}
 
\end{center}
\vspace{0.25in}
 
4) End Block Token ...
 
\begin{center}
\makebox[1.5in]{\rule[-0.2cm]{0cm}{0.4cm}Field size
}\makebox[0.2in]{\rule[-0.2cm]{0cm}{0.4cm}2
}\makebox[0.6in]{\rule[-0.2cm]{0cm}{0.4cm}6
}\makebox[0.8in]{\rule[-0.2cm]{0cm}{0.4cm}8
}\makebox[1.6in]{\rule[-0.2cm]{0cm}{0.4cm}16}
 
\makebox[1.5in]{\rule[-0.2cm]{0cm}{0.6cm}
}\framebox[0.2in]{\rule[-0.2cm]{0cm}{0.6cm}
{11}}\framebox[0.6in]{\rule[-0.2cm]{0cm}{0.6cm}3f
}\framebox[0.8in]{\rule[-0.2cm]{0cm}{0.6cm}ff
}\framebox[1.6in]{\rule[-0.2cm]{0cm}{0.6cm}0000}
 
\end{center}
\vspace{0.25in}
 
\newpage
\begin{verbatim}
where ...
 
ELen    =   Total event length including header in bytes
i       =   Item number (0-3F)
g       =   Group number (0-FF)
ic      =   Item count in group format. This is the number of data words
            following the 16bit header.
            If the number of data words is even, then a zero padding word
            forces 32bit alignment.
Address =   14bit parameter identifier
Data    =   Upto 16bit data value (unused high order bits zeroed)
 
\end{verbatim}
 
\end{document}