Author: Ron Fox, Sean Liddick

Date: March 3, 2016 (last modification).

Introduction

This page provides step by step instructions for the use of the DDAS readout program. Throughout this page we will use $prefix to mean the top level directory of the DDAS software installation directory. Thus if the installation directory is in

/usr/opt/ddas/1.0

Then

$prefix/share/spectcl

refers to the directory

/usr/opt/ddas/1.0/share/spectcl

Getting Started

To use the Readout program requires that you:

Obtain and modify the template crate directory for each DDAS PXI Crate you will use. Set up the Readout(s) you need as data sources for the ReadoutGUI. Set up the NSCL Event builder to build event data from the Readout program(s) you use.

Note: In order to maintain a consistent event structure, the event builder is used even when data only comes from a single PXI crate.

Obtaining and modifying the crate files.

For each PXI Crate you will use create a directory for its configuration files. By convention, the files are located in your home directory tree under the readout directory. The name of each crate directory is, again by convention, crate_n where n is a crate number you have chosen.

Once you have created a crate directory, you can copy a set of sample files from $prefix/share/readout/crate_1 into your crate directory.

This will create the files:

Filename	Contents
pxisys.ini	Crate slot to PCI resource map
cfgPixie16.txt	Defines what is in the crate
crate_1.set	Parameter setting files for the DSP algorithms.
modevtlen.txt	Event length for triggers from each module in cfgPixie16.txt

Note that Readout for the crate must be run with the current working directory set to the crate directory that has the configuration files it needs.

The crate configuration file.

This is a file that just contains the following information:

Crate Id.
Number of modules in the crate
Slot of first module
Slot of second module
       ...
Slot number of last module.
path to set file.

Example:
1
4
2
4
5
6
/user/0400x/readout/crate_1/crate_1.set

Crate id is one with four moudules in slots 2,4,5,6. settings file is /user/0400x/readout/crate_1/crate_1.set

It is possible to load a crate with a heterogeneous selection of Pixie-16 digitizers. You need not fill a crate with only 100 MSPS digitizers for example. You could fill it with 100 MSPS and 250 MSPS modules.

A full description of the cfgPixie16.txt file can be found at The cfgPixie16.txt format.

The module settings file.

This file is generated by nscope and contains he DPP settings that will be loaded into each module in the crate. At this time only nscope should be used to modify this binary file.

The Module Event Length Configuration File - modevtlen.txt

For each module described in cfgPixie16.txt provides the size of the event expected from the channels in that module. Be careful to compute the correct length of each event. If this number is incorrect, the data output from the DDAS Readout will be gibberish because the Readout program uses the modevtlen to chunk up the data it reads from the FIFO into events. If trace acquisition, energy summing, and qdc modes are not enabled in the module, then only the header will be outputted. This header is four 32-bit words long. Assuming that this is the case for the cfgPixie16.txt file above, your modevtlen.txt would look like this.

For example:

4
4
4
4
...

The four modules defined in the cfgPixie16.txt file above all provide event lengths of 4 longwords (i.e. 32-bit).

This gets a little more interesting if you have trace acquisition, energy summing, or qdc mode enabled. In those situation you have to compute the number of 32-bit words that will be outputted by each module. Here is how to compute it based on whether each feature is enabled (On) or disabled (Off) :

QDC	Energy Sums	Trace Acquisition	Event length (32-bit words)
Off	Off	Off	4
Off	On	Off	8
On	Off	Off	12
On	On	Off	16

If trace acquisition is enabled, then the the number of data words required to store the complete trace must be added to these event lengths. In general, the number of longwords required to store a trace is:

N_longwords = ceil( 0.5 * trace_length * frequency )

The factor of 1/2 arises because the ADCs in all DDAS supported modules have less than 16-bit resolution. That means that for every 32-bits, there are two samples. Here is an example calculation for a 100 MSPS digitizer. Assume that trace capture is enabled and that 2.3 us traces are going to be recorded. That means that there are 115 longwords stored for this trace. We then add to this the number of words in the rightmost column of the above table according to the features that were enabled. Let's assume that energy summing is enabled in addition to our trace capture. The value we would write in our modevtlen.txt would be 123. Now if I had the same scenario, but was using a 250 MSPS digitizer, then the corresponding modevtlen.txt entry would be 296. Note that we had to round up to account for the odd number of samples (575) in the trace.

Note: At the moment, there is no support for setting up channels within a single module to output different length events. If one channel in a module is set to acquire traces of length 1 us, then all other channels in the module must do the same. If you do not, then Readout will fail to create events with boundaries that are meaningful and the data will become gibberish very quickly.

The pxisys.ini

The `pxisys.ini' file contains a mapping between crate slot numbers and cPCI resoiurces. The sample file is suitable for use with the Wiener PXI crates that are used at the NSCL.

Other laboratories may need to modify this file to correctly assign a correspondence between PCI resources and PXI slots.

Setting up readoutgui event sources.

The NSCL ReadoutGUI can manage several event sources. Use the Data Source menu to set up data sources. Data sources are remembered from run to run of the GUI.

The DDAS Readout programs get run as SSHPipe programs. In the parameter prompter for SSH Pipe data sources fill in the fields as follows:

Field	Value
Host name	DNS name of the computer connected to the DDAS crate
Readout Program>	$prefix/bin/Readout
Working Directory	The appropriate crate directory e.g. /user/0400x/readout/crate_1
Command line options	See below set –ring, and –sourceid options

Each Readout is required to put data in a unique ring name and to have a unique source id. The source id identifies data from that crate within fragment of events put together by the event builder.

A reasonable set of conventions are:

Ring names like username_DDAS_crateno e.g. e0400x_DDAS_1 for crate number 1 for the user e0400x. Source id that matches the crate number.

Setting up the NSCL Event builder.

The NSCL Event builder set up is documented in detail the NSCLDAQ online documentation. This section will summarize the setup and provide a sample file for a single crate. The assumption is that we are following the conventions for ring names and ids described in the previous section.

Setting up the event builder involves creating or adding to a ReadoutCallouts.tcl Readout GUI extension file.

Here is an annotated example:

package require evbcallouts                                       ; #1

proc OnStart {} {
   EVBC::initialize -restart false -glombuild true -glomdt 10     ; #2
}

EVBC::registerRingSource \
        tcp://spdaq21/0400x_DDAS_1 \
        $prefix/lib/libddastimestampextractor.so \
        1 {Crate 1};                                                      #3

Includes the package that provides the API for the NSCL event builder.
When the system becomes ready, starts the event builder. The options ensure that the event builder is persistent, builds events from fragments and combines fragments within 10 timstamp ticks of an initial fragment into events.
Registers and event builder data source for a Readout running in spdaq21 following the ring name and source ids for crate 1.

For multi-crate systems the setup simply requires an additional EVBC::registerRingSource for each crate's readout program.

DDAS Readout Special features

Infinity clock synchronization mode

Synchronizing clocks can result in different card to card or even channel to channel time offsets. This is a problem for experiments that require precise timing. Those experiments need to synchronize only infrequently and only at known times. This form of synchronization was dubbed "infinity clock" because the clocks are allowed to continue to increment without reset.

The DDAS readout supports the infinity clock in two ways:

If the environment variable INFINITY_CLOCK is defined and has the value "YES" clock synchronization is only performed automatically as DDAS Readout initializes, otherwise clock synchronization/zeroing is performed at the beginning of each run. If DDAS Readout is given the command "ddas_sync" clocks will synchronize in response to that command.

Controlling the FIFO threshold for triggering readout

The DDAS Readout program is designed to poll the Pixie-16 digitizers until the data available in the FIFO is greater than a threshold. The threshold default is set in the XIA Pixie-16 API, but users can configure it themselves by setting the FIFO_THRESHOLD environment variable. When this variable is defined, its value is used in place of the default threshold. The value of the variable represents the number of 32-bit words required to be in the FIFO.

The Output Data Format

The format out of the DDAS Readout program can be read in more detail at Event Data Structure Produced by Readout.