\documentclass[11pt]{article}
\usepackage{a4}
\usepackage{graphicx}

\oddsidemargin=0pt           % No extra space wasted after first inch.
\evensidemargin=0pt          % Ditto (for two-sided output).
\topmargin=0pt               % Same for top of page.
\headheight=0pt              % Don't waste any space on unused headers.
\headsep=0pt
\textwidth=16cm              % Effectively controls the right margin.
\textheight=24cm

\begin{document}
\title{\bf CALICE DAQ User and Reference Manual}
\input pdd.tex

\maketitle

%\begin{abstract}
%Blah blah...
%\end{abstract}

\newpage
\tableofcontents

\newpage
\section{Introduction}
For most users (doing analysis directly from the raw data or working
on the LCIO conversion) then the section on offline use is most useful.


\section{Basic concepts}
The DAQ hardware is mainly based around the CALICE Readout Card
(CRC, pronounced ``Kirk'').


The data are based on the concept of records, which are generalised
events. Each record indicates an occurance (a ``transition'')
within the DAQ system.
Each process within the DAQ can add data to the record (but not
remove anything). The data within the record are organised into
subrecords, each of which has a well-defined structure. The records
are manipulated as contiguous chunks of memory with regard to being
copied, transported, etc.

The code is intended to be light-weight and transportable (meaning to
different sites). Having said that, 
it is written in C++ and is only intended to work with Linux.
%(although there are some Windows extensions for legacy systems).
The only external code needed is ROOT (for both online and offline
applications) and HAL and a HAL-supported VME driver
(for online only). These can be included as
soft links into the directory structure, allowing them to be 
installed wherever convenient on the computer being used.


\subsection{Records}
Each record contains a short header with the most basic information
which is then (optionally) followed in memory 
by an arbitrary amount of data. The header contains just the time and
type
of the event and the number of bytes of data following, for which zero
(i.e. no data) is valid. The
organisation of the following data is not defined by the record classes
at all; it can be any structure desired. Because the header size and
length of the following data are known, the records can be
manipulated easily without any further knowledge. Hence, the I/O and
transport classes for records do not need to depend on the data
structure within the record.

The internal record structure actually used for CALICE
involves subrecords, which are well-defined
chunks of data inserted into the record. Each subrecord starts with
a subheader, which contains
an identifier (to indicate the data contents) and the number of bytes 
of the data in the subrecord. This allows many manipulations of the
subrecords to be done without knowledge of the data contained in the
subrecord. However, to actually use the subrecords, then the identifier
must be checked to ensure the data are as expected. This is done by
associating each identifier used with a data storage class which defines
the actual subrecord data structure for that identifier. Hence, a list
of identifiers for each class must be maintained and whenever a class
is modified in a non-backwards compatible way, a new identifier must
be assigned to the new class.

These data storage classes
must lie completely within the contiguous data of the subrecord and
this puts limitations on the classes used. They must contain all their
data within the object or contiguously following the object, which
means no pointers can be used. In addition, although inheritance can
be used, no virtual functions are possible. To manipulate these storage
objects, an inserter or accessor class is used to add or read the
objects, respectively. 


\subsection{Online and dataflow}
The records are used for two purposes in the online system; to store
and carry data within the online and also to indicate transitions of the
online system. Effectively all data needed to control the online system is 
sent through the records. In particular, configuration data to set up
the hardware is written into the record before being copied to the
hardware itself. These data are also read back from the hardware
into the record, to allow a comparison and check of the configuration.

The hardware of the system consists of
two 9U VME crates, each containing six or seven
CRCs as well as a VME crate controller and other readout modules for the
beam line tracking and particle ID.
The VME controllers used
are SBS 620 PCI-VME bridge sets.
The VME readout is based on the HAL system and this supports the SBS
cards. The PCI cards are used in several standard multi-CPU PCs which 
are linked via a network switch.


\subsection{Offline analysis}
The actual ``final'' analysis of the data will not be done from the
raw data as written out by the DAQ but from a reduced dataset. This
will be in LCIO format and will only contain calorimeter channels which
are above a threshold. Their values will be calibrated and pedestal
subtracted in these files.

Hence, the meaning of ``offline'' here is therefore the process needed to
take the raw data files (defined in terms of records) and do any
analysis which requires the raw data. The most obvious case is the
actual job which does the data reduction to the LCIO dataset. Other
cases are the calculation of the calibration constants (pedestals,
gains, etc) used in the LCIO conversion job. However,
it is possible calibration run analysis may also be done from the raw
data as will all quick checks of data quality. These are the tasks
which are covered by the concept of offline here.

\subsection{Conventions}
All C++ header files are .hh, all main programs are .cc.

The subdetectors have abbreviations
emc, ahc, dhc, trg, slw, bml for ECAL, AHCAL, DHCAL, trigger, slow
controls and beam line, respectively.

\section{Hardware}
\subsection{CRC overview}
The CRC is a (substantially modified) adaptation of the CMS
silicon tracker readout board, the Front End Driver (FED).
However, the whole of the front section of the board was
redesigned for CALICE use and the firmware for the FPGAs
has also been modified. An overview of the CRC is shown in
figure~\ref{fig:ReadoutOverview}.
%
\begin{figure}
\begin{center}
\includegraphics[width=8cm]{ReadoutOverview.eps}
\caption{Overview of CRC}
\label{fig:ReadoutOverview}
\end{center}
\end{figure}
%

The CRC contains ten Xlinix Virtex-II FPGAs, running
three firmware designs. The board
is mainly controlled by the Back End (BE) FPGA. This
communicates with the VME controller via the VME FPGA
and with the Very Front End (VFE) electronics via the
Front End (FE) FPGAs. Each CRC has one VME, one BE and
eight FE FPGAs; all the FE FPGAs run the same firmware.

There are two data paths via VME into the CRC. One
is a serial I/O link, which is used for configuration
and slow data readout; this has both read and write
access. The second path is a read-only fast data
path, the ``Vlink'', which allows VME block transfers.

The BE distributes configuration data and the trigger
to the FEs and collects readout data from the FEs.
These data are stored in a 8MByte Quad Data Rate (QDR)
memory on the CRC. The contents of this memory are the
only data which can be read via the Vlink.

\subsubsection{ADCs and DACs}
The main function of the CRCs is to digitise the
analogue data stored in the VFE electronics. The analogue
level is stored using a sample-and-hold and then subsequently
clocked out on a multiplexed line to the CRC. These analogue
levels are input to six dual ADCs per FE and the digitised
data are buffered in the FE before being transfered later to
the BE.

The ADCs used are Texas Instruments ADS8361 500\,kHz, 16 bit devices. 
Each physical
component contains two ADCs, each of which has two inputs;
one is used for the VFE analogue signal and the other for
a direct input from the on-board DACs. Which of these
two inputs is to be digitised
is controlled by the FE and configurable via software.

The DACs used are Analog Devices AD5541 16 bit devices. There are two
DACs per FE, one for each connector.


\subsubsection{Trigger distribution}
The trigger is handled through a standard CRC. The trigger LVDS
input signals are input via the pins on the VME J2 connector.
The logic and control of the trigger in implemented in the BE firmware
in all CRCs. However, only one CRC is used to control the trigger in
a run, usually one in slot 12.
Following a trigger decision, the trigger is output to
the J0 connector via two 1-to-10 fanouts. 
The outputs from one of the
fanout are then distributed via a custom J0 backplane
to the other CRCs with the same crate. The outputs from the second
fanout are picked off the custom backplane with a cable which 
plugs into a J0 connector (aqgain, usually slot 12)
in the second crate on the inner side
of the crate. This then mimics a CRC sitting in that slot in the
second crate, so the distribution to the CRCs within the second crate 
is then done using an identical custom J0 backplane.


\subsubsection{VFE acquisition sequence}
The signal timing sequence to drive the data acquisition sequence
for the VFE electronics is shown in figure~\ref{fig:VfePcbSignals}.
%
\begin{figure}
\begin{center}
\includegraphics[width=12cm]{VfePcbSignals.eps}
\caption{VFE acquisition sequence}
\label{fig:VfePcbSignals}
\end{center}
\end{figure}
%
This sequence is run through for every trigger.
All the signals are LVDS except OUTPUTs and VCALIBs, which are analogue.

\subsubsection{Connector signals}
The signals on the connector XXX.

DIAGRAM OF CONNECTOR AND PIN NUMBERING

TABLE OF CONNECTOR PINS FROM INTERFACE DOC


\subsubsection{FE acquisition sequence}
In addition to the VFE signals, the FE needs to generate
the signals needed within the CRC with the correct timing.
These signals consist of the ADC control and the
FE-to-BE data transfer signals.

The digitised ADC values are stored in a FIFO implemented within
the FE FPGA. These data are transfered to the BE and subsequently
to the QDR memory after the FE sequence is complete.

\subsubsection{FE-to-BE data transfer}
The FE-to-BE data transfer starts a fixed (software configurable)
time delay after the trigger falling edge.
The transfer involves three data packets before the data themselves
are sent.
The FE initiates the first packet, the FrameSyncOut,
and this consists of one leading bit
followed by 80 bits of data; these are currently fixed to the
values 0x0102030405060708090a. When all FEs are seen by the BE,
it replies with the ReadoutSyncIn command simultaneously to all
FEs. The FEs then reply with the ReadoutSyncOut; this need to
arrive at the BE simultaneously from all FEs and so this is also
timed from the trigger falling edge, again configurably in software.
Following the ReadoutSyncOut with a configurable delay, the FE then 
sends the data themselves, which the BE receives and stores in the
QDR memory.

\subsubsection{BE, VME access, serial I/O and Vlink}
The main data transfer method off the CRC is the Vlink. This reads
the data stored in the QDR memory through VME. The BE assembles the
data for the first event in the QDR and pushes it to the VME FPGA.
This is then readable directly through VME in sveral buffers. Once
each buffer is read and flushed, the BE can transfer the next buffer
until the event is complete. At this point, the BE starts on the
next event in the QDR. Tis Vlink transfer allows VME block transfers

All other read, and all write, access to the CRC is via the serial
I/O link, which is much slower.

\subsubsection{Monitoring data}
NS LM82 and power shutdown. AD ADM1025A.

\subsection{CRC hardware setup}
\subsubsection{Jumper array}
The CRC can handle several types of VFE electronics by setting
jumpers in the large jumper array immediately behind the FE
connectors. The ECAL VFE electronics has three types; full, left
and right, while the AHCAL VFE electronics has two; left and right.
In addition, the CRC is designed to accomodate a fully-digital interface
to another system if this is ever required.

REQUIREMENTS FOR FULL, LEFT AND RIGHT.

Link array has 15 connections; 12 ADCs, 2 DACs and 1 detection.

See figure~\ref{fig:linkArray}.
%
\begin{figure}
\begin{center}
\includegraphics[width=12cm]{linkArray.eps}
\caption{Link array settings, views from the top (component) side
of the CRC with the FE connectors to the left.}
\label{fig:linkArray}
\end{center}
\end{figure}
%
Link array and VFE types, plus readback

VCALIB shared if full, two separate VCALIBs if left and right?


\subsubsection{CompactFlash card}
Location of reset button

Xilinx SystemACE

Reload procedure and power up issues

How to make a new CompactFlash card

\subsubsection{EPROM}
Each CRC has a non-volatile EPROM which can contain long-term data.
This is a Xicor X24165 2k$\times 8$ bit memory device which can be
locked to be read-only using a jumper on the CRC.

This is used to store the CRC unique serial number. 

Serial number convention.

Location of write jumper; diagram and photo?

\subsubsection{CRC LED indicators}

\subsection{CRC software configuration}
\subsubsection{FE sequence timing}
\subsubsection{VFE enables}
\subsubsection{BE}
\subsubsection{AHCAL VFE shift registers}

\subsection{CRC trigger}
Note that the trigger busy is implemented by holding it high.

\subsubsection{BE-Trg}
\subsubsection{CRC trigger fanout}
\subsubsection{Backplane trigger distribution}

\subsection{Other hardware}
\subsubsection{Overview}
DIAGRAM OF PCs AND SWITCH

PC internally numbered 
icalice00 (Central), icalice01 (ECAL), icalice02 (HCAL) 
and icalice03 (Monitoring). Externally at DESY, these are
flccalice00, flccalice01, flchcaldaq03 and flcANA???


\subsubsection{SBS}
Jumpers

\subsubsection{TDC}
LeCroy LC1176.


\section{Online structure}
\subsection{State machine}
\subsection{Records as transitions}
\subsection{Data groups}
\subsubsection{Run, R/O}
\subsubsection{Configuration, R/W}
\subsubsection{Event, R/O}
\subsubsection{Trigger control}
\subsection{XxxConfiguration and XxxReadout}
\subsection{Other code}
\subsubsection{HAL}
\subsubsection{SBS}
\subsubsection{ROOT}

\section{Offline structure}
There are generally two ways to use the raw data files offline.
One uses the minimal amount of DAQ software and requires the
overall infrastructure to be supplied by the user; for example,
this is the system used for the LCIO conversion. This minimal
software is contained in the ``records'' package and only this
is needed.

The second method is to work within the DAQ offline structure
as a DAQ ``user'', for which not only the records package but
also the ``daquser'' package are needed. In addition, the
correct directory structure needs to be used.

Both methods are described below. The use of the records package for
the first method is identical for both, so this is decribed first.

\subsection{Use of the records package}
\subsubsection{Records as data containers}

\subsubsection{Accessing the basic record header information}
The code for handling records is in {\tt records/inc/rcd}.
Normally, a record is handled within some specific 
array of memory, defined by the {\tt RcdArena} class.
This inherits from the record class {\tt RcdRecord}.

The header of each record is encapsulated in a class 
{\tt RcdHeader}, from which {\tt RcdRecord} inherits,
and the information stored is accessed
though methods of this class. These are
\begin{itemize}
\item {\tt RcdHeader::recordTime()}: Returns a 
{\tt UtlTime}
object containing the timestamp for the record.
\item {\tt RcdHeader::recordType()}: Returns a 
{\tt RcdHeader::RecordType} enum value giving the type of
record; start of run, end of run, event, etc.
\end{itemize}
Both these items can be printed using the {\tt print} method, e.g.
\begin{verbatim}
  arena.RcdHeader::print(std::cout);
\end{verbatim}
Since all other manipulations of data are done through
subrecords, then the other methods of records are not
normally required.

\subsubsection{Reading and writing records}
To read a record from a file, then a {\tt RcdReader} object is
used. This is also found in  the subpackage {\tt records/inc/rcd}.
Both binary ({\tt .bin}) and ascii ({\tt .asc}) record files
can be handled. The {\tt RcdReader} object should be used to open,
read and close the record file as follows, for example for a binary
file called InputFile.bin:
\begin{verbatim}
  RcdArena arena;
  RcdReaderBin reader;
  assert(reader.open("InputFile"));  // ".bin" is appended

  while(reader.read(arena)) {
    // Use record
  }

  assert(reader.close());
\end{verbatim}
In a similar way, a {\tt RcdWriter} object can be used to write records 
to a file, again in either binary or ascii format. The method interface is
very similar to that for reading
\begin{verbatim}
  RcdArena arena;
  RcdReaderBin reader;
  RcdWriterBin writer;
  assert(reader.open("InputFile"));  // ".bin" is appended
  assert(writer.open("OutputFile")); // ".bin" is appended

  while(reader.read(arena)) {
    // Use record
    assert(writer.write(arena));
  }

  assert(reader.close());
  assert(writer.close());
\end{verbatim}


\subsubsection{Accessing subrecords within records}
The code for handling subrecords is in {\tt records/inc/sub}.
Only classes which have been registered in 
{\tt records/inc/sub/SubRecordTypes.hh}
can be used as subrecords and hence stored within records.
Therefore, this file by definition contains the definitive list
of subrecords.

To access a particular set of subrecords, then a subrecord
accessor {\tt SubAccessor} is used. This can return a 
{\tt std::vector} list of pointers to all the occurances
of any subrecord in a record. The code would look similar
to:
\begin{verbatim}
  SubAccessor accessor(arena);
  std::vector<const DaqRunStart*> v(accessor.access<DaqRunStart>());
\end{verbatim}
which gets a list of pointers to {\tt DaqRunStart} objects, for 
example.

\subsubsection{Fixing subrecords}
As the DAQ software develops, the subrecord classes will be modified,
not necessarily in a backwards-compatible way. To handle this, each
subrecord class has a version number and conversion constructors are
supplied to change older versions to the latest version, when possible.
The {\tt records/inc/fix} subpackage contains code to perform these
conversions on-the-fly and can be used as follows:
\begin{verbatim}
  FixAll fix;
  ...
  // For each record
  fix.fix(arena);
\end{verbatim}
The {\tt records/src} subdirectory contains one main program,
{\tt example.cc} which simply puts some of the above pieces together.
\begin{verbatim}
#include "RcdArena.hh"
#include "RcdReaderBin.hh"
#include "RcdReaderAsc.hh"
#include "RcdWriterBin.hh"
#include "FixAll.hh"

using namespace std;

int main(int argc, const char **argv) {
  if(argc<2 || argc>3) {
    cout << "Usage: " << argv[0] 
	 << " <input filename> [<output filename>]" << endl;
    return 1;
  }

  // Memory array for records
  RcdArena arena;

  // Record reader; bin or asc
  RcdReaderBin reader;
  //RcdReaderAsc reader;

  // Record writer if required
  RcdWriter *writer(0);
  if(argc==3) writer=new RcdWriterBin;

  // Fixers to repair data
  FixAll fixAll(4); // 4 prints up to and including configuration
  
  // Open files
  if(!reader.open(argv[1])) return 2;
  if(argc==3 && !writer->open(argv[2])) return 3;

  // Read records until end of file
  while(reader.read(arena)) {
    fixAll.fix(arena);
    if(argc==3) writer->write(arena);
  }

  // Close files
  if(!reader.close()) return 4;
  if(argc==3 && !writer->close()) return 5;

  return 0;
}
\end{verbatim}

\subsection{Use of the daquser package}


\subsubsection{User directory}
To use the software, the user needs to create a directory with a
specific structure. This has the following subdirectories:
\begin{itemize}
\item {\tt inc}: Contains user classes.
\item {\tt src}: Contains user main programs.
\item {\tt bin}: Contains the executables made from the {\tt src} code.
\end{itemize}
In addition, it needs either subdirectories, or more usually soft links,
as follows:
\begin{itemize}
\item {\tt records}: The above central software {\tt records} directory.
\item {\tt daquser}: The above central software {\tt daquser} directory.
\item {\tt data}: Contains the data directories (see below).
\end{itemize}



\subsubsection{bin/build, PATH, setenv}
Within the {\tt bin} subdirectory, a link should be created to the
{\tt daquser} scripts {\tt bin/build}
Then, {\tt build xxx} will compile and link the file {\tt xxx.cc}
and write the resulting executable to {\tt bin/xxx}.
The file {\tt xxx.cc} is searched for (in order) in {\tt src},
{\tt daquser/src} and finally {\tt records/src}.

It is convenient to
add {\tt ./bin} to the PATH to allow the {\tt bin/build} script to be
found automatically
{\tt setenv PATH $\{PATH\}:./bin}.
Also define the environmental variables {\tt ROOTSYS} (to the
top level ROOT directory, as usual) and
{\tt LD_LIBRARY_PATH} to pick up the ROOT libraries
{\tt setenv LD_LIBRARY_PATH $\{LD_LIBRARY_PATH}:\{$ROOTSYS\}/lib}.

\subsection{Data directories}
\subsubsection{dat}
\subsubsection{slw}
\subsubsection{log}


\subsubsection{How to access subrecords}

\subsection{Overview of subrecords}
\subsubsection{Run, R/O}
\subsubsection{Configuration, R/W}
\subsubsection{Event, R/O}
\subsubsection{Trigger control}

\newpage
\section*{Appendix A: Code organisation}
\addcontentsline{toc}{section}{Code organisation}
An overview of the three software packages is shown in figure~\ref{fig:swDaq}.
%
\begin{figure}[b]
\begin{center}
\includegraphics[width=12cm]{swDaq.eps}
\caption{Conceptual overview of the DAQ and external software packages.}
\label{fig:swDaq}
\end{center}
\end{figure}

\subsection{DAQ software}
The DAQ software is organised into three main directories:
\begin{itemize}
\item {\tt online}: This contains code which is only used in the
online, i.e. the actual DAQ process.
\item {\tt daquser}: This contains code which is used both online
and daquser,
during read back or analysis of the data.
\item {\tt records}: This contains code which needs to be used for
the LCIO conversion.
\end{itemize}
For daquser use, only the {\tt daquser} and {\tt records} directories
need to be installed although ROOT must also be available.
For online use, all three directories
need to be installed together with ROOT, HAL and the SBS VME driver.

The {\tt records} directory only contains subdirectories
{\tt inc}, {\tt src}, {\tt bin} and {\tt doc}. {\tt inc}
contains the classes. 
\begin{itemize}
\item {\tt inc}: Contains the classes arranged in further subdirectories.
\item {\tt src}: Contains the main programs.
\item {\tt bin}: Contains scripts to build executables from the {\tt src} code
and other useful scripts.
\end{itemize}

For the {\tt daquser} directory,
the subdirectories are:
\begin{itemize}
\item {\tt inc}: Contains the classes arranged in further subdirectories.
\item {\tt src}: Contains the main programs.
\item {\tt bin}: Contains scripts to build executables from the {\tt src} code
and other useful scripts.
\end{itemize}
The {\tt online} subdirectories are similar to the ones in {\tt daquser}
but have a fourth subdirectory, {\tt hal}, which contains the VME address
space map definition files for the VME modules used online.


\subsection{Records software}
An overview of the subpackages is shown in figure~\ref{fig:swRecords}.
%
\begin{figure}
\begin{center}
\includegraphics[width=12cm]{swRecords.eps}
\caption{Conceptual overview of the records subpackages.}
\label{fig:swRecords}
\end{center}
\end{figure}
%
No class is able to know about or use any class in a lower group.


The classes in the {\tt records/inc} subdirectory are organised into
two different groups. The first contains classes used to
manipulate data and the second contains classes to store and
handle the data of the subrecords. These are split into
subdirectories as follows; for the first group
\begin{itemize}
\item {\tt utl}: Contains utility classes.
\item {\tt rcd}: Contains the record structure and basic I/O classes.
\item {\tt sub}: Contains the subrecord organisation classes.
\item {\tt fix}: Contains the subrecord fixing code.
\end{itemize}
and for the second group
\begin{itemize}
\item {\tt daq}, {\tt crc}, {\tt emc}, 
{\tt ahc}, {\tt dhc}, {\tt trg}, {\tt slw}, {\tt bml}: 
Contains the subrecord
data storage classes; the generic CRC
data and the various subdetectors.
\end{itemize}

\subsubsection{Classes in {\tt inc/utl}}
The utility classes perform various commonly needed functions.
{\tt UtlPrintHex} prints values in decimal, hex and (optionally)
binary for debugging purposes.
{\tt UtlLocation} contains the crate, VME slot, component (and
an extra label) for any data.
{\tt UtlPack}
{\tt UtlTime}
{\tt UtlTimeDifference}

\subsubsection{Classes in {\tt inc/rcd}}
These classes 
\subsubsection{Classes in {\tt inc/sub}}
\subsubsection{Classes in {\tt inc/fix}}

DAQUSER

\subsubsection{Classes in {\tt inc/daq}}
\subsubsection{Classes in {\tt inc/crc}}
\subsubsection{Classes in {\tt inc/emc}}
\subsubsection{Classes in {\tt inc/ahc}}
\subsubsection{Classes in {\tt inc/dhc}}
\subsubsection{Classes in {\tt inc/trg}}
\subsubsection{Classes in {\tt inc/slw}}
\subsubsection{Classes in {\tt inc/blm}}



\subsubsection{Classes in {\tt inc/chk}}
\subsubsection{Classes in {\tt inc/hst}}
\subsubsection{Classes in {\tt inc/dsp}}
\subsubsection{Classes in {\tt inc/skt}}
\subsubsection{Classes in {\tt inc/shm}}

{\tt UtlAverage} 
{\tt UtlRollingAverage}
{\tt UtlArguments}

\subsection{Online software}
An overview of the subpackages is shown in figure~\ref{fig:swOnline}.
%
\begin{figure}
\begin{center}
\includegraphics[width=12cm]{swOnline.eps}
\caption{Conceptual overview of the online subpackages.}
\label{fig:swOnline}
\end{center}
\end{figure}
%
\begin{itemize}
\item {\tt hal}: Contains the code for 
\item {\tt dio}: Contains the code for data transport.
\item {\tt onl}: Contains the code for online use of the {\tt dio}
classes.
\item {\tt shm}, {\tt skt}: Contains classes to handle data for
shared memory and sockets, respectively.
\item 
{\tt sem}, {\tt sgn}, {\tt shm}, {\tt skt}, {\tt pip}: Contains
classes to allow the use of inter-process connunication, namely
semaphores, signals, shared memory, sockets and pipes, respectively.
\item {\tt vme}: Contains the generic VME classes.
\item {\tt emc}, {\tt ahc}, {\tt dhc}, {\tt trg}, {\tt slw}, {\tt bml}:
Contains the subdetector-specific online classes.
\item {\tt chk}, {\tt hst}, {\tt dsp}: Contains low level checking, 
histogramming and display classes for data analysis.
\end{itemize}

\subsubsection{Classes in {\tt inc/dio}}
\subsubsection{Classes in {\tt inc/onl}}
\subsubsection{Classes in {\tt inc/vme}}
\subsubsection{Main programs in {\tt src}}



For online use, the directory needs to have
\begin{itemize}
\item {\tt online}: The above central software {\tt online} directory.
\item {\tt sbs}: A soft link to the top of the SBS driver directory.
\item {\tt hal}: A soft link to the top of the HAL directory (online only).
\end{itemize}

\subsection{Offline software}
An overview of the subpackages is shown in figure~\ref{fig:swOffline}.
%
\begin{figure}
\begin{center}
\includegraphics[width=12cm]{swOffline.eps}
\caption{Conceptual overview of the offline subpackages.}
\label{fig:swOffline}
\end{center}
\end{figure}
%

\subsubsection{Classes in {\tt inc/cal}}
\subsubsection{Classes in {\tt inc/lco}}
\subsubsection{Main programs in {\tt src}}

\section*{Appendix B: State machine}
\addcontentsline{toc}{section}{Code organisation}

\subsection{Definitions and transitions of states}

The DAQ state machine is shown in figure~\ref{fig:StateMachine}.
%
\begin{figure}
\begin{center}
\includegraphics[width=10cm]{StateMachine.eps}
\caption{The DAQ state machine}
\label{fig:StateMachine}
\end{center}
\end{figure}
%

\begin{itemize}
\item State Dead: no DAQ program running
\begin{itemize}
\item Transition startUp to state Alive: default
\end{itemize}
   
\item State Alive: program initialised but no run in progress
\begin{itemize}
\item Transition runStart to state Running: default
\item Transition shutdown to state Dead: when finished number of runs or on
    user command
\end{itemize}

\item State Running: Run initialised
\begin{itemize}
\item Transition configurationStart to state Configured: default
\item Transition slowReadout to state Running: default if monitoring run
   - Read out all slow data.
     Ensure trigger timeout is off and send s/w central trigger.
     Flush all buffers and counters.
\item Transition runEnd to state Alive - on user command
   - Same as for RUNSTART
\end{itemize}

\item State Configured: All configuration data loaded.
 In this state, need to have
    - Trigger in BUSY state
    - All QDR buffers empty
    - All event counters cleared
\begin{itemize}
\item Transition acquisitionStart to state Armed: default if XXX run
\item Transition acquisitionStart to state Ready: default if YYY run
\item Transition slowReadout to state Configured: if more than minimum
time since last slowReadout
\item Transition configurationEnd to state Running
\end{itemize}

\item State Armed: Ready to take event data
\begin{itemize}
\item Transition event to state Armed: default
\item Transition acquisitionEnd to state Configured
\end{itemize}

\item State Ready: prepared for spill
\begin{itemize}
\item Transition spillStart to state Spilling
\item Transition spill to state Acquiring
\end{itemize}

\item State Spilling: taking triggers during spill
\begin{itemize}
\item Transition preEvent to state Spilling: default
   - Release central trigger busy.
     S/w trigger or poll for trigger.
     Read out pre-event data.
\item Transition spillEnd to state Acquiring
\end{itemize}

\item State Acquiring: taking data during spill
\begin{itemize}
\item Transition transferStart to state Transfering
\item Transition transfer to state Empty
\end{itemize}

\item State Transfering: reading out buffered data taken during spill
\begin{itemize}
\item Transition postEvent to state Transfering: default if not finished
all event data
\item Transition transferEnd to state Empty: when finished number
    of events
\end{itemize}

\item State Empty: finished data acquisition for a spill
\begin{itemize}
\item Transition acquisitionEnd to state Configured
\end{itemize}




\begin{itemize}

\item Transition CONFIGURATIONEND to state ALIVE - 
   - Readback all configuration data
\item Transition CONFIGURATIONSTOP to state ALIVE - when output file size too
    big, or user command
   - Readback all configuration data
\item Transition SLOWREADOUT to state CONFIGURED - occasionally
   - Read out all slow data.
     Ensure trigger timeout is off and send s/w central trigger.
     Flush all buffers and counters.
\end{itemize}
 * SM needs to know if finished events, file size, user command and time
    since last SLOWREADOUT





\item
State SETUP = 3
\begin{itemize}
\item Transition CONFIGURATIONSTART to state CONFIGURED - default
   - Write and readback configuration data.
     Ensure trigger timeout is off and send s/w central trigger.
     Flush all buffers and counters.
\item Transition RUNEND to state ALIVE - when finished number
    of configurations
   - Same as for RUNSTART plus VFE load/flush
\item Transition RUNSTOP to state ALIVE - when output file size too big, or on
    user command
   - Same as for RUNEND
\end{itemize}
 * SM needs to know if finished configs, file size and user command



\item
State TRIGGERED = 5
\begin{itemize}
\item Transition EVENT to state CONFIGURED - default
   - Read event data
\end{itemize}
\end{itemize}

\subsubsection{STATE MACHINE 2 = SPILL WITH PRE-EVENT AND EVENT}

\begin{itemize}
\item
State SETUP = 3
\begin{itemize}
\item Transition CONFIGURATIONSTART to state CONFIGURED - default
   - Write and readback configuration data
     Ensure trigger timeout is off and send s/w central trigger.
     Flush all buffers and counters.
\item Transition RUNEND to state ALIVE - when finished number
    of configurations
   - Same as for RUNSTART plus VFE load/flush
\item Transition RUNSTOP to state ALIVE - when output file size too big, or on
    user command
   - Same as for RUNEND
\end{itemize}
 * SM needs to know if finished configs, file size and user command

\item
State CONFIGURED = 4
 In this state, need to have
    - Trigger in BUSY state
    - All QDR buffers empty
    - All event counters cleared


\begin{itemize}
\item Transition STARTSPILL to state SPILLED - default
   - S/w spill or poll for spill
\item Transition CONFIGURATIONEND to state ALIVE - when finished number
    of spills or events
   - Readback all configuration data
\item Transition CONFIGURATIONSTOP to state ALIVE - when output file size too
    big, or user command
   - Readback all configuration data
\end{itemize}
 * SM needs to know if finished spills or events, file size and user command

\item
State SPILLED = 5
\begin{itemize}
\item Transition PREEVENT to state SPILLED - default
   - Release central trigger busy.
     S/w trigger or poll for trigger (must all osc or timeout)
     Read out pre-event data, inc spill and buffer status
\item Transition SPILLEND to state READQDR - after spill end, full buffer
    or finished number of events 
   - S/w unspill or poll for spill end
\item Transition SPILLSTOP to state READQDR - when output file size too
    big, or user command
   - Same as SPILLEND
\end{itemize}
 * SM needs to know if spill status, if finished events or full buffer, file
    size and user command

\item
State READQDR = 6
\begin{itemize}
\item Transition EVENT to state READQDR - if not finished events
   - Read event data
\item Transition SLOWREADOUT to state CONFIGURED - after last event
   - Read out all slow data
     Ensure trigger timeout is off and send s/w central trigger.
     Flush all buffers and counters.
\end{itemize}
 * SM needs to know if finished events
\end{itemize}


\subsubsection{STATE MACHINE 3 = SPILL WITH EVENT ONLY}

\begin{itemize}
\item
State SETUP = 3
\begin{itemize}
\item Transition CONFIGURATIONSTART to state CONFIGURED - default
   - Write and readback configuration data
     Ensure trigger timeout is off and send s/w central trigger.
     Flush all buffers and counters.
\item Transition RUNEND to state ALIVE - when finished number
    of configurations
   - Same as for RUNSTART plus VFE load/flush
\item Transition RUNSTOP to state ALIVE - when output file size too big, or
    on user command
   - Same as for RUNEND
\end{itemize}
 * SM needs to know if finished configs, file size and user command

\item
State CONFIGURED = 4
 In this state, need to have
    - Trigger in BUSY state
    - All QDR buffers empty
    - All event counters cleared



\begin{itemize}
\item Transition STARTSPILL to state SPILLED - default
   - Enable trigger timeout (and release if needed)
     S/w spill or poll for spill or number of events
\item Transition CONFIGURATIONEND to state ALIVE - when finished number
    of spills or events
   - Readback all configuration data
\item Transition CONFIGURATIONSTOP to state ALIVE - when output file size too
    big, or user command
   - Same as CONFIGURATIONEND
\end{itemize}
 * SM needs to know if finished spills or events, file size and user command

\item
State SPILLED = 5
\begin{itemize}
\item Transition SPILLEND to state READQDR - default
   - Multiple S/w trigger. 
     Poll for spill end, finished number of events, full QDR or
     user command. Or s/w unspill, poll for finished number of events, full
     QDR or user command. 
     Readout pre-evet data
     Unset trigger timeout.
\end{itemize}

\item
State READQDR = 6
\begin{itemize}
\item Transition EVENT to state READQDR - 
   - Read event data
\item Transition SLOWREADOUT to state CONFIGURED - after last event
   - Read out all slow data
     Ensure trigger timeout is off and send s/w central trigger.
     Flush all buffers and counters.
\end{itemize}
 * SM needs to know if finished events
\end{itemize}


\subsection{Definitions of transitions}

\begin{itemize}
\item
Transition startUp
\begin{itemize}
\item Initialise all CrcVmeDevices, reset (with care), load AHCAL VFE DAC
   settings (but not whenever the program is started)
\end{itemize}

\item
Transition shutdown
\begin{itemize}
\item Readback AHCAL VFE DAC settings (but not whenever the program is stopped)
\end{itemize}

\item
Transition runStart
\begin{itemize}
\item Readback Crc run info and slow run info. Read EMC stage (if not slow)
\item Set and readback slow control settings
\end{itemize}

\item
Transition runEnd
\begin{itemize}
\item Readback Crc run info and slow run info. Read EMC stage (if not slow)
\item Pptional VFE load/flush
\item Readback slow control settings
\end{itemize}

\item
Transition runStop (obsolete)
\begin{itemize}
\item Same as for runEnd
\end{itemize}

\item
Transition configurationStart
\begin{itemize}
  \item Write and readback configuration data.
     Ensure trigger timeout is off and send s/w central trigger.
     Flush all buffers and counters.
\end{itemize}

\item
Transition configurationEnd
\begin{itemize}
\item Readback all configuration data
\end{itemize}

\item
Transition configurationStop (obsolete)
\begin{itemize}
\item Same as configurationEnd
\end{itemize}

\item
Transition slowReadout
\begin{itemize}
  \item Read out all slow data.
\end{itemize}

\item
Transition acquisitionStart
\begin{itemize}
  \item 
\end{itemize}

\item
Transition acquisitionEnd
\begin{itemize}
\item 
\end{itemize}

\item
Transition spillStart
\begin{itemize}
  \item Enable trigger timeout (and release if needed) for SM3
     S/w spill or poll for spill, number of events, QDR full
\end{itemize}

\item
Transition spillEnd
\begin{itemize}
  \item Poll for spill end, finished number of events, full QDR or
     user command. Or s/w unspill, poll for finished number of events, full
     QDR or user command. 
  \item Multiple S/w trigger. 
     Poll for spill end, finished number of events, full QDR or
     user command. Or s/w unspill, poll for finished number of events, full
     QDR or user command. 
     Readout pre-event data?
     Unset trigger timeout for SM3
\end{itemize}

\item
Transition spill
\begin{itemize}
  \item Poll for spill end, finished number of events, full QDR or
     user command. Or s/w unspill, poll for finished number of events, full
     QDR or user command. 
     Poll for spill end, finished number of events, full QDR or
     user command. Or s/w unspill, poll for finished number of events, full
     QDR or user command. 
     S/w trigger or poll for trigger (must allow osc or timeout for SM2)
     Read out pre-event data, inc spill and buffer status
\end{itemize}

\item
Transition transferStart
\begin{itemize}
  \item 
\end{itemize}

\item
Transition transferEnd
\begin{itemize}
  \item 
\end{itemize}

\item
Transition transfer
\begin{itemize}
  \item Read all QDR buffer data
\end{itemize}

\item
Transition preEvent
\begin{itemize}
  \item Release central trigger busy.
     S/w trigger or poll for trigger (must allow osc or timeout for SM2)
     Read out pre-event data, inc spill and buffer status
\end{itemize}

\item
Transition postEvent
\begin{itemize}
  \item Read out one event from QDR buffers
\end{itemize}

\item
Transition event
\begin{itemize}
\item Same as preEvent and postEvent
\end{itemize}
\end{itemize}


\end{document}
