/* Version:
$Source: /var/www/hades-wiki.gsi.de/data/DaqSlowControl/MatchingUnitDataFormat.txt,v $
$Id: MatchingUnitDataFormat.txt,v 1.7 2006/01/23 13:28:19 MichaelTraxler Exp www-data $
*/


Matching Unit SubEvent Data Format
----------------------------------

Overview:
---------

----------------------------------------|
|       Standard MBS Subevent header    |
|---------------------------------------|
|       MU Data                         |
|---------------------------------------|
|       RICH Data                       |
|---------------------------------------|
|       Shower Data                     |
|---------------------------------------|
|       TOF Data                        |
|---------------------------------------|

At the begining of each block, there is a length-word of the following block,
sometimes as a single word, sometimes encoded.


For the prototype version of the Matching Unit all data
words delivered by the DAQ are 32-bit words, but the
contents is only 16-bit wide (MSW first).
This will be changed in the future, then only 32-bit words will exist.

Event in more detail:

Word:    Contents:          Description:
--------------------------------------------------

# MU Header , Standard MBS Subeventheader
1        length             Length of whole subevent in 8-bit words
2        0x1                to distinguish between little and big endian
3        MU ID              non-ambiguous Matching Unit ID. Set to 0x200 (512)
4        trigger tag        trigger tag of event
# The rest is MU Data

## Important change: all data taken from 31.08.2001 18:00 will have the following
## order of the following two words. This was switched before!
6        trigger code       lower 4 bits: trigger code of subevent
                            bits 4-7: trigger decision as described further down
                            bit 12 marks, if trigger condition is encoded
                            
5        MU-data length     MU-data length, length in 16-bit words, without
                            this length, minumum = 0 , data can end here
7        matching-data      see below for description
.
.


# Rich IPU "sub-event"
# (new, since nov00)
x+0      length             length of RICH-IPU-subevent in 32-bit words,
                            without this length

# min: 1, max: 6 RICH "sub-sub-events" of the following structure
# (same as nov00)

## for(i=1; i<= (1,2 ... or 6), i++) {
x+1      IPU header(MSW)    see below for description, length included
x+2      IPU header(LSW)    see below for description, length included
x+3      IPU data(MSW)      data is optional, but can be up to 42 long words per IPU, see below for description
x+4      IPU data(LSW)      see below for description
...
...

## }


# Shower IPU, exactly one subevent of this type
y+0      length (MSW)       length of shower IPU sub-sub-event
                            in 32-bit words, without this length
y+1      length (LSB)

## for(i=1; i<= 1..12, i++) {
y+2      length (MSB)       length of shower IPU-IPC-subevent in
y+3      length (LSB)       16-bit words including this length

y+4      header (MSW)       see below for description
y+5      header (LSW)

## for(i=1; i<= x, i++) {
y+6      hitpattern (MSW)   see below for description
y+7      hitpattern (LSW)
## }
..
..
z+0      trailer (MSW)      see below for description
z+1      trailer (LSW)
.
.
.
# } repeat previous x-times, except the overall-length .

##       TOF IPU

# (new, since nov00)
n+0      length             length of TOF-IPU-subevent in 32-bit words,
                            without this length
# min: 1, max: 3 TOF-sub-sub events of the following structure

## for(i=1; i<= (1,2, or 3), i++) {
n+1      length (MSW)           length of subevent in 32-bit-words,
                                without this length word
n+2      length (LSW)
n+3      register (MSW)         tag, code, additional information,
                                see below for details
n+4      register (LSW)
n+5      data (MSW)
n+6      data (LSW)
.
.
## data n-times
# next TOF event
# }
.
.

### End of MU Subevent


#################################################
#################################################

#######################
#   matching data
#######################

Due to the fact, that the matching unit is very flexible, we also have to use
a very flexible data format, because it will change many times in the future.
For example the MU-Event will be reduced substantially when debugging is over.
Therefore I suggest to introduce a "MU-Data-version-number":

mu_data:

0    version_number             this is a version number, which tells the unpacker
                                what to do with the data

old versions: 0x12  (from 31.08.2001 18:00)

current version number: 0x13  (from somewhere in November 2001)


1a   reduction value and        if this was a downscaled event, the reduction value
     original trigger decision  is stored here (in the lower bit 0 to 11):
                                1 means: 1:1 => only positive triggers
                                2 means: 1:2 => 1 positive, 1 negative (50%)

                                from bit 12 on it is the "trigger condition"
                                Bit 0:   downscaled event flag:  1 = downscaled, 0 = normal triggered
                                Bit 1-2: original trigger decision
                                         0 => negative
                                         1 => positive
                                         2 => positive, but stopped analyzing due to
                                              to many leptons (>=7) or dileptons (>=x)

*ATTENTION*: The num_of_hits_in_RICH and num_of_hits_in_SHOWER are *not* final numbers, only a lower 
limit for the MU, to find out very fast if it can trigger pos. without analysing the event.
In fact, they are just the number of data-words. For RICH the real number could be 4 times more, 
for shower I don't know exactly, but theoretically 16 times more (8 times is more likely!)
When no cut-condition was applied, then the MU unpacks the data correctly and will also write the
correct numbers in these variables.

1    num_of_hits_in_RICH        these words tells how many hits the different
                                IPUs found in the detectors
2    num_of_hits_in_SHOWER
3    num_of_hits_in_TOF

4    sector_hitpattern_RICH     bit-hitpattern, where every bit (0-5) describes
                                at least one hit in this sector (0-5)
5    sector_hitpattern_SHOWER
6    sector_hitpattern_TOF

7    num_of_leptons             number of leptons found in whole event
## for(i=0; i<num_of_leptons; i++) {
8    lepton (MSW)                       describes found lepton, theta, phi
                                        and momentum
9    lepton (LSW)
.
.
.
## }

x+10    num_of_di_leptons               number of di_leptons found in whole event
## for(i=0; i<num_of_Di-leptons; i++) {
x+11    lepton_numbers                  Byte 0: lepton number 1
                                        Byte 1: lepton number 2
x+12    dilepton (MSW)                  IEEE32 bit floating point invariant_mass_squared
x+13    dilepton (LSW)                  (arbitrary units)
.
.
.
## }


---------------
- lepton:
---------------


#### old format, before November 2001 beamtime
####bits:
####------------------------------------------------
####    31-24           20              19-8    7-0
####    momentum        electron flag   phi     theta
####------------------------------------------------
####
####theta:              0 => 0 degrees ,  255   => 90  degrees
####phi:                0 => 0 degrees ,  1535  => 360 degrees
####momentum:   0 => 0 units,     255   => 255 units
####electron_flag:      1 => electron,  0 => positron


## New Lepton structure, since November 2001

------------------------------------------------------------------------------------
31-24      23-22      21               20             19-12      11-4        3-0
momentum   reserved   electron flag    Detector Bit   META Nr.   RICH Nr.    sector
------------------------------------------------------------------------------------

momentum:       0 => 0 units,     255   => 255 units
electron_flag:  1 => electron,    0 => positron
Detector Bit:   0 => TOF
                1 => Shower


momentum: 255 units corresponds to 1 GeV/c momentum of the lepton. Every lepton above 1GeV/c is
          clipped to the 1Gev/c bin. All is dependent of the momentum-table from Manual Sanchez 
          generated with the kick-plane Ansatz. 
          Important issue: to get correct momenta, the magnetic_field current have to be 
                           set correctly, in the MU and in the analysis!

---------------
- dilepton:
---------------

bits:
------------------------------------------------
15-8            7-0
number_2        number_1
------------------------------------------------

number_1 and number_2:          Numbers of leptons which build lepton pair

#######################
#       RICH IPU
#######################
# Rich Header Format:

bits:
------------------------------------------------------------------------------------------
31-29  28-26            25-24   23-16               15-8                        7-0
010    Segment ID[2..0] 00      Trigger Tag[7..0]   Length of "sub-sub"-event   trigger code
                                                    in 32-bit words,
                                                    including header
------------------------------------------------------------------------------------------

# Rich Data Format:

bits:
------------------------------------------------------------------------------------------
31-28         27-24        23-16                  15-13   12-10         9-7  6-0
0001          FifoNr.      column pattern[7..0]   000     Segment ID    000  Row Number
------------------------------------------------------------------------------------------

The column (polar) coordinate where a ring was found is calculated by:
95- [(FifoNr.-1)*8 + (position of bit which is 1 in column pattern)]
Example: Fifo Nr. = 2, column_pattern = 0x04   =>  column = 95 - ((2-1)*8 + 2) = 95 - 18 = 77
So, for each bit which is set in the column pattern, one ring was found.

### changed before the aug04 beamtime, new IPU is shifting by 26
###    the row coordinate (azimuthal) is: Row Number - 23
the row coordinate (azimuthal) is: Row Number - 26

Annotation: One can non-ambiguously distinguish between data and header words of the rich by
the bit nr. 30.
if it is 1: => Header
if it is 0: => Data


##########################
#       Shower IPU
##########################

For every IPC (there are 12 IPCs) there will be one "sub-sub-sub"-event
which is described in the following.
----------
- header:
----------

bits:
-----------------------------------------------------------------------------
31-30   29-28           27-16                   15-8            7-0
FL_CTR  01 (fixed)      SubEvtBuilder-ID        RB Status Word  trigger tag
-----------------------------------------------------------------------------

SubEventBuilderID:
Sector 0:       Row 0-15 =>  300 in decimal (0x12c)
                Row 16-31 => 301
Sector 1:       Row 0-15 =>  302
                Row 16-31 => 303
.
.
.


-------
- data:
-------
bits:
-----------------------------------------------------------------------------
31-30    29-28    27-24   23-21      20-16      15-0
FL_CTR   10(fix)  res.    decoding   column     row pattern
-----------------------------------------------------------------------------

row pattern:    16-bit pattern (bit 0 => row 1,
                bit 15 => row 16, for each bit in the row
                a shower was found, row => polar angle)

column:         column coordinate, 0-31 (azimuthal)

decoding:       BIT0 => 1: at least one Bit was found in LSB of row pattern
                BIT0 => 0: no Bit was found in LSB of row pattern

                BIT1 => 1: at least one Bit was found in MSB of row pattern
                BIT1 => 0: no Bit was found in MSB of row pattern

                BIT2 => 1: more than one bit was found in MSB+LSB of row pattern
                BIT2 => 0: exactly one bit was found in MSB+LSB of row pattern

-----------
- trailer:
-----------

The trailer can be switched on and off by the Shower IPU.
From the beamtime nov02 on, it will be turned off.


bits:
-------------------------------------------------------------------
31-30    29-28    27-16   15-8         7-5              4-0
FL_CTR   11(fix)  res.    RevisionID   AnalysisMode     FrameCount
-------------------------------------------------------------------

FrameCount:     Number of 32 bit words written from IPC to LM
                without trailer: must be equal (IPC-subevent-length >> 1) - 2
                check for debugging

AnalysisMode:   BIT0 => 1: local maximum search enabled
                BIT1 => 1: cluster search is enabled
                BIT2 => 1: debug mode (should never be on)

#######################
#       TOF IPU
#######################

register format:
-------------------------------------------------------------
31 - 15   14    13      12      11-8            7-0
reserved  GEO   ID      veto    trigger code    trigger tag
-------------------------------------------------------------

GEO:
    1 => theta phi calculation is on
    0 => theta phi calculation is off

ID:
    1 => PID is on
    0 => PID is off


veto:
    1 => pileup marker
    0 => normal LVL2 decision, made by MU


data format:

bits:
------------------------------------------------------------------------------------------------
31-24           23-16                   15-8            7-6     5-4             3-0
time            phi angle               theta angle     res     PID             sector number
------------------------------------------------------------------------------------------------

PID:            00    TOF-cut disabled, all particles (should be matched)
                01    Lepton candidate                (should be matched)
                11    Other particles                 (no matching, only for offline analysis)
                10    reserved                        (no matching)
time:           time of flight in AU
sector number:  0..5
phi angle:      0 => -30 degrees, 255   => +30 degrees
theta angle:    0 =>   0 degrees, 255   => +90 degrees


###################################################
### Examples
###################################################


NEW!
A sample shower sub-sub-event (shown in 32-bit words)
Starts with length of subevent (0x1c) without this length
(4 IPCs sent data, same pattern, 4 hits in each IPC-sub-event)

0x0000001c 0x0000000e 0x512d1325 0x20020004
0x20080020 0x202e0200 0x20344000 0x70009225
0x0000000e 0x512e1325 0x20020004 0x20080020
0x202e0200 0x20344000 0x70009225 0x0000000e
0x512f1325 0x20020004 0x20080020 0x202e0200
0x20344000 0x70009225 0x0000000e 0x51301325
0x20020004 0x20080020 0x202e0200 0x20344000
0x70009225


#######################################
###
#######################################

## one event MU and Shower, 8 IPCs (Shower IPUs), 6 RICH IPUs, 3 TOF crate

0270  length of whole MU-event in bytes
0001
0200  MU-ID
00b0  trigger tag
0011  mu-subevent-length
0001  trigger code
0010  version number
0002  number of hits in RICH
0020  ..  SHOWER
0003  ..  TOF
0009  RICH-hit-pattern
007f  SHOWER-hit-pattern
0008  TOF-hit-pattern
0002  number of leptons found
1d00  MSB Lepton 0
297e  LSB Lepton 0
a703  MSB Lepton 1
d8f5
0001    nuber of DiLeptons found
0100  match Lepton number 0 and 1
45fc  invariant mass squared (MSB)
8b61  LSB
0008  RICH length
5cb0  RICH Sector 1
0201  (length 2)
1808
1c35
48b0  RICH sector 2
0101
4cb0  ..
0101
50b0
0201
1240
1066
54a0
0101
58b0
0101
0000 Shower Event length (MSB)
0030 (LSB)
0000 IPC 1 subevent length (MSB)
000e (LSB)
512d
13b0
2002
0004
2008
0020
202e
0200
2034
4000
7000
9225
0000 IPC 2
000e
512e
13b0
2002
0004
2008
0020
202e
0200
2034
4000
7000
9225
0000 IPC 3
000e
512f
13b0
2002
0004
2008
0020
202e
0200
2034
4000
7000
9225
0000 IPC 4
000e
5130
13b0
2002
0004
2008
0020
202e
0200
2034
4000
7000
9225
0000 IPC 5
000e
5131
13b0
2002
0004
2008
0020
202e
0200
2034
4000
7000
9225
0000 IPC 6
000e
5132
13b0
2002
0004
2008
0020
202e
0200
2034
4000
7000
9225
0000 IPC 7
0006
5133
13b0
7000
9221
0000
0006 IPC 8
5134
13b0
7000
9221
0009 TOF length
0000 TOF 1 subevent length (MSB)
0002 (LSB)
0000
01b0
005b
f403
0000 TOF 2 subevent length
0002
0000
01b0
005b
f403
0000 TOF 3 subevent length
0002
0000
01b0
005b
f403