GeN RAW DATA STRUCTURE
R. Michaels, Jefferson Lab, e-mail: rom@jlab.org, updated Mar 4, 2006
The raw data structure recorded in the GeN DAQ datastream will be described. This includes the following data: 1) Event data recorded with each accepted trigger (fastbus and VME data from the two spectrometers and from the BPM and raster); 2) scalers; 3) EPICS information; and 4) "special events" which are inserted once or infrequently during a run, such as prescale information and detector map.
These data are decoded by the Podd Analyzer classes developed for GeN, see also GeN Analyzer documentation. I won't go into that here, but suffice it to say you need an up-to-date database with correct crate map and detector maps.
I will not describe the various other datastreams in Hall A, such as Moller polarimeter, e-P energy measurement, Compton Polarimeter, etc.
[TOP]
The best detailed reference on the CODA format was the old manual for CODA version 1.4, see appendix E. I have saved this postscript file coda1.4.ps. I will give a simplified summary here. The data come in the form of an array of 32-bit words, in the case of event data, or character data, in the case of some of the special events. In general, the first part of the event structure is "header" information, indicating how long the event is, what the event type is, etc. The most important header and other identifying data words are:
| Location in Buffer | Content | Description |
| 1st word | event length | loop from J=1 to J=evbuffer(1)+1 in Fortran
to access data = evbuffer(J) |
| ishft( evbuffer(2), -16 ) | event type | Types 1-12 are triggers that don't overlap in
time. Event 5 are coincidences, or any trigger overlap within 10 nsec. Other types are prestart, go, end, etc. Types >128 are "special events". |
| evbuffer(4) in event type 17 | run number | The run number, which is normally in the filename also. |
| evbuffer(5) | event number | The event number, uniquely assigned by CODA |
After the header, the data are organized in banks corresponding to each ROC. A ROC is a "readout controller", and it means a crate of fastbus or VME. We have several ROCs in our DAQ event stream listed in the table below. Different CODA configs may exist with different mixtures of crates.
GeN DAQ CODA Configrations
GeN All crates
test* As of this writing, several test configs
with subset of crates.
| ROC | Description | IP Address | Portserver |
| TS1 (ROC28 in datastream) | Trig. Super. and BPM/raster | bbts1 | genps2 port 5 |
| ROC3 | Drift chamber crate 1 | hallasfi3 | genps2 port 3 |
| ROC4 | Drift chamber crate 2 | hallasfi4 | genps2 port 4 |
| ROC22 | BB Fastbus crate | bbsfi1 | genps2 port 6 |
| ROC23 | BB VME crate (also scalers) | bbvme1 | genps2 port 7 |
| ROC24 | Big Hand Fastbus | gensfi1 | genps1 port 7 |
| ROC25 | Big Hand VME (F1-TDC) | genvme1 | genps1 port 6 |
do 150 i = 1,MAXROC
c n1 = pointer to first word of ROC
if(i.eq.1) then
n1 = evbuffer(3) + 4
else
n1 = n1roc(irn(i-1))+lenroc(irn(i-1))+1
endif
c irn = ROC number obtained from CODA
irn(i) = ishft(iand(evbuffer(n1+1),'ff0000'x),-16)
if(irn(i).le.0.or.irn(i).gt.maxroc) then
write(6,*) 'fatal error in decoding'
stop
endif
c Store pointers and lengths
if(i.eq.1) then
n1roc(irn(1)) = n1
lenroc(irn(1)) = evbuffer(n1)
lentot = n1 + evbuffer(n1)
else
n1roc(irn(i)) = n1roc(irn(i-1))+lenroc(irn(i-1))+1
lenroc(irn(i)) = evbuffer(n1roc(irn(i)))
lentot = lentot + lenroc(irn(i)) + 1
endif
if(lentot.ge.len-1) goto 200
150 end do
200 numroc = i
[TOP]
To read CODA files with primitve code, try the CODA classes (C++ classes for CODA interface). This and the hana decoder have been integrated into the new Podd analyzer so you probably don't have to worry about it.
[TOP]
Each crate adds some ``event flag'' data, which are extra words that don't come from a module. The set of flags that exist may change over time. At present (Feb 1, 2006) here they are:
The following data are kept for each crate. They allow
to check the synchronization of the crates. The data will
be parsed by GenDecData class, which provides "misc data".
The data appear somewhere (see below) after the header
fabc000N where N = number of words that follows.
1. Local software counter (resets every 20K events)
2. CODA Event number
3. CODA Event type
4. Event count (at present undefined except for BB crates).
5. vxWorks system time (crude clock 16.7 msec least count)
6. 105 kHz clock time (fine clock 10 usec least count)
ROC3, BBSFI1 & GENSFI1 have this structure
header: fabc0008 Then right after the header:
1. timeout counter
2. datascan
next 6 are synch data 1-6 (see above)
BBVME1, GENVME1, BBDCVME* & Trigger-Supervisor (ROC28)
all the same:
header: fabc0007 Then right after the header:
1. - 6. (Synch)
7. TIR
Then there is a flag showing the buffering mode
0xfaaa0001 -- Header (0x means hex format)
0xfabb0000 -- If you see this, data are unbuffered.
0xfafbbf00+synchFlag -- If you see this the data are buffered.
If synchFlag !=0 then it was a synch event.
[TOP]
Scalers count raw hits on phototubes, as well as important quantities like charge and triggers which are used to normalize the experiment. See also this scaler schematic . Scalers appear in the raw data as event type 140 (so-called "scaler events") as well as in the BBVME1 data periodically (typ. every 200 events, or at synch events). In addition, the scalers are displayed online using the "xscaler" code, and the meaning of the channels is evident from the scaler configuration file "scaler.map" which that code uses. To run "xscaler", login to adaql4 (or 5,6..) as "adaq" account and type "xscaler" and do what it says. Also, scalers are processed by ~a-onl/scripts/halla_scaler_process.tcl for convenient halog display at end-of-run.
Note, to run the analyzer you also need the "scaler.map" file. Usage within the analyzer is explained at hallaweb.jlab.org/equipment/daq/THaScaler.html
Structure of raw data: The headers are of the form "0xb0dN00XY" for GeN scalers, and other headers if you ever use the HRS (it's explained in the standard DAQ pages). Here, N is the "software slot" and XY encodes the number of scalers channels in the lowest 6 bits (16 or 32 channels). The software slot is closely related to the physical slot, but there is one complication. The 1st physical slot (on the far left) is the helicity-gated scaler. These data are sorted by helicity on-the-fly and packaged into two virtual scalers corresponding to slot 0 and 1. The next slot (2) is the normalization scaler not gated by helicity. Subsequent physical slots correspond to software slots 3,4,5... etc. The helicity gated scalers are FIFO scalers run in G0 helicity mode, see also www.jlab.org/~rom/g0helicity.html. The helicity scalers appear in the data stream in event type 140 already sorted by helicity (the sorting is done online) but also in raw form; see the section below on BigBite scalers.
| Location in Buffer | Physical Slot in Crate (Left to Right) | 16 or 32 Chan | Header (see notes above) | Scaler Model | USAGE |
| 1 | 1 | 32 | 0xb0d00020 (software slot 0) | SIS3801 (FIFO) | Normalization scaler gated by PLUS helicity (see b0d2 scaler) |
| 2 | 1 (yes, same unit) | 32 | 0xb0d10020 (software slot 1) | SIS3801 (FIFO) | Normalization scaler gated by MINUS helicity (see b0d2 scaler) |
| 3 | 2 (2nd physical slot) | 32 | 0xb0d20020 (software slot 2) | SIS3800 | Normalization scaler NOT gated by helicity. Channels are (1 is 1st) 1-9 = T1-T9; 12th=clock(105 kHz); 13th=L1A; 17-22 BCM u1,u3,u10,d1,d3,d10; maybe more later. |
| 4 | 3 | 32 | 0xb0d30020 (software slot 3) | SIS3800 | Nothing yet. |
| 5 | 4 | 32 | 0xb0d40020 (software slot 4) | SIS3800 | Nothing yet. |
| 5 | 4 | 32 | 0xb0d50020 (software slot 5) | SIS3800 | Nothing yet. |
| 6 | 5 | 32 | 0xb0d60020 (software slot 6) | SIS3800 | Nothing yet. |
| 7 | 6 | 32 | 0xb0d70020 (software slot 7) | SIS3800 | Nothing yet. |
| 8 | 7 | 32 | 0xb0d80020 (software slot 8) | SIS3800 | Nothing yet. |
The scalers are cleared at the beginning of a run, and read out finally at the end of the run. The timing of the gates, which enables the scalers to count, is such that the end-of-run scaler readout is done after gates are turned off, and then after this final readout the gates are re-enabled, so that scalers can count in between runs. The end-of-run scaler data are written automatically to a file on ~a-onl/scaler/scaler_history.dat. Routines exist for reading this file and pulling out the particular scaler channel.
Scaler data are also inserted into the data stream as an event type 140 typically every 8 seconds, but not synchronized to any other event. The capability to read scalers at 30 Hz with zero deadtime is also supported, and these data appear in BBVME1 (ROC23), see section below. An event type 100 is written at end of run which has same format as ROC23 which is the final scaler reading from ROC23.
[TOP]
The ROC23 data contains the normalization scaler data (gated by helicity and not) once per 200 events, or once per synch event (if we run in buffered mode). It also contains a full flushing of the ring buffer for a subset of channels (can't flush all 32 because of deadtime). This scheme allows us to run with the helicity delayed in G0 helicity mode. See also www.jlab.org/~rom/g0helicity.html. An event type 100 is written at end of run which has same format as ROC23 which is the final scaler reading from ROC23. Here is the format of ROC23 data. There is the usual stuff from QDCs and TDCs (unless someone drops them), then starting with the header 0xfb0b0002 is scaler data, e.g.0xfb0b0002 0xb0d00000 0x6c80910a 0x00115144 0x00023455The header b0d00000 denotes the helicity MINUS (bit = 0) scaler and b0d10000 the helicity PLUS (bit = 1) scaler, 32 channels each, the data has been summed for you. After these 64 channels you get 3 words corresponding to the number of readings in the FIFO for the MINUS, PLUS, and "BAD". where "BAD" means the online algorithm had trouble predicting it (usually means a cable fell out). Of course there should be zero bad readings. After these, you get the RING BUFFER data. This starts with 0xfb1b0090 where 0xfb1b0000 is a header and the lower bits (here 0x90 = 144) is the number of readings in the buffer. Subsequent readings are groups of 6 words corresponding to clock, qrt&helicity, trigger 3, upstream BCM with gain 3, L1A, and trigger 1. The qrt&helicity is encoded as follows: qrt = (data & 0x10)>>4 and hel = (data & 0x1). See also the code tscalroc23_main.C and tscalring23_main.C in hana_scaler. These data allows the user to check for at least those vital data that the online-summed data above are correct. After the ring buffer data, starting with header 0xb0d20000 is the 32 channels of non-helicity-gated normalization data.
(etc)
[TOP]
The trigger supervisor TS1 appears in the datastream as ROC28. The first word in the hexidecimal dump is a header 0xfadcb0b9 followed by the event type (2 here), then the TIR data (an I/O register) containing helicity, gate, and QRT info as decoded by THaHelicity. After that is an event counter (0x4cc4 here). Then we readout two ADCs, headers are 0xfadc1182 and 0xfadd1182. These are related to the BPM/raster data. If the header 0xfb0b0020 appears (as here) it means the next 32 words are the scaler in that crate. Finally, 0xfabc0007 are the synch data (see section on Event Flags).Example of dump of ROC28
0xfadcb0b9 0x00000002 0x00000070 0x00004cc4 0xfadc1182 0x00000176
0x0000017d 0x0000019f 0x00000190 0x00000186 0x0000018b 0x0000019a
0x0000018f 0x00000001 0xfadd1182 0x00000117 0x00000115 0x0000012e
0x00000121 0x00000118 0x00000121 0x0000012a 0x00000119 0x00000001
0xfb0b0020 0x000019d5 0x00000000 0x00000000 0x00000000 0x00000000
0x00000000 0x00000000 0x00000000 0x00000000 0x00000000 0x00000000
0x00000000 0x00000000 0x00000000 0x00000000 0x00000000 0x00000000
0x00000000 0x00000000 0x00000000 0x00000000 0x00000000 0x00000000
0x00000000 0x00000000 0x00000000 0x00000000 0x00000000 0x00000000
0x00000000 0x00000000 0x00000000 0xfabc0007 0x00004cc4 0x00000007
0x00000002 0xffffffff 0x00dd70e3 0x000019d3 0x0000ef08 0xfaaa0001
[TOP]
Data from various EPICS databases are periodically inserted into the datastream, as well as placed in text files that are saved at the start-of-run and end-of-run. These text files are stored as, for example, ~a-onl/epics/runfiles/Start_of_Run_1047.epics, and End_of_Run_1047.epics where 1047 is the run number. These data are also written to the electronics log book HALOG. Each experiment is permitted to modify the script that controls this (ask me) but please let only ONE experienced, qualifed person modify the script (and it is probably good enough, too). Incidentally, no other dealing with DAQ should ever be modified without asking me. I leave things open but I must be informed.
The data which are inserted periodically include the beam current, position monitors, magnetic fields in our spectrometers, as well as some beamline elements, the beam energy, collimator positions, and several other things. Approximately every 30 seconds, a long list of information from the accelerator and from Hall A are inserted as event type 131. Approximately every 5 seconds a shorter list of information, for which rapid updates are desirable, are inserted as event type 131. The shorter list contain the BPMs near the target and the charge monitor data. The synchronization of the data relative to our datastream is good to perhaps 1 second.
Here is an fictitious example of the rapidly updated EPICS data which are inserted every approximately 5 seconds :
Tue Aug 27 12:59:43 EDT 2002
IPM1H04A.XPOS 0.352823
IPM1H04A.YPOS 0.430828
IPM1H04B.XPOS -0.130145
IPM1H04B.YPOS -0.48034
hac_bcm_average 5.29884
hac_bcm_dvm1_current 5.30776
hac_bcm_dvm2_current 5.28991
hac_unser_current 5.30134
There is some code in the C++ analyzer to pull out the data. See for example THaOutput. However, since the EPICS "event" data are characters they are viewable simply with grep. From a Linux box you can type "grep -a IPM1H0 e01012_1455.dat.0" on the data file.
[TOP]
Event types less than 15 are physics triggers of various types. There are also prestart, go, and end "events". Event types greater than 99 are "special events", which are not really "events" and not particularly "special" either -- they are data inserted into the CODA datastream which are useful to record with the event data. The following special events exist:
| Event Type | Format | Description |
| 100 | integer | Last scaler reading (same format as ROC23). |
| 120 | integer | Prescale registers (8 numbers read from TS) |
| 131 | character | EPICS Data (see section above) |
| 133 | character | Prescale Factors (decoded by Podd) |
| 140 | integer | Scaler Data (roc23 scalers every few seconds) |