Data read by the L3 Script Runner Code
        from the L1 Trigger Framework Readout Crate
           for inclusion in the Event Header

Updated: 16-Jan-2001


General Readout structure:
--------------------------

Each L1FW card reads out a stream of 40x 16-bit words.

Each Card's stream of 16-bit words is sent over an optical
cable to a VTM Module plugged into the back of a VRB Card.
There are 4x Channels per VTM  Card and thus up to
4x L1 Framework Cards readout by each VRB Card.

The L1 Trigger Framework currently uses 9x VRB Cards
all in one Readout Crate including a VRB Controller Card
and a VBD Card.

The L1 Trigger Framework Readout Crate is Geographic Section #31.

Each VTM Channel feeds a pair of VRB Channels:
i.e. VTM Channel #0 feeds VRB Channels #0 and #1,
     VTM Channel #1 feeds VRB Channels #2 and #3,
     VTM Channel #2 feeds VRB Channels #4 and #5,
 and VTM Channel #3 feeds VRB Channels #6 and #7.

Each 16-bit word sent by a L1FW THE-Card is split into two bytes
with the Least Significant Byte going to the lower VRB Channel
and the Most Significant Byte going to the upper VRB Channel
of the corresponding VRB Channel Pair.

Before trying to access any of the L1 Framework Card data,
these arrays of 40x 16 bit words should be rebuilt.
One must watch for platform dependent Endian-ness issues.

The VRB and VBD header formats are described in their respective
documentations. Th section below summarizes the generic format of
a L1 Trigger Framework THE-Card readout.

Additional details are available in
www.pa.msu.edu/hep/d0/ftp/l1/framework/hsro/summary_of_fw_data_readout.txt

Generic THE-Card Readout Format:
--------------------------------

Word #0  : Header LSWord LSByte = THE-Card ID
                         MSByte = THE-Card Event Number
                                 (Not identical to SCL Event Number)
      1  : Header MSWord Reserved (Fpga Version Number Information)
      2  : Fpga #1 LSWord \ In most cases each pair forms a 32-bit Longword
      3  : Fpga #1 MSWord /
      4  : Fpga #2 LSWord \
      5  : Fpga #2 MSWord /
      6  : Fpga #3 LSWord \
      7  : Fpga #3 MSWord /
      8  : Fpga #4 LSWord \
      9  : Fpga #4 MSWord /
      10 : Fpga #5 LSWord \
      11 : Fpga #5 MSWord /
      12 : Fpga #6 LSWord \
      13 : Fpga #6 MSWord /
      14 : Fpga #7 LSWord \
      15 : Fpga #7 MSWord /
      16 : Fpga #8 LSWord \
      17 : Fpga #8 MSWord /
      18 : Fpga #9 LSWord \
      19 : Fpga #9 MSWord /
      20 : Fpga #10 LSWord \
      21 : Fpga #10 MSWord /
      22 : Fpga #11 LSWord \
      23 : Fpga #11 MSWord /
      24 : Fpga #12 LSWord \
      25 : Fpga #12 MSWord /
      26 : Fpga #13 LSWord \
      27 : Fpga #13 MSWord /
      28 : Fpga #14 LSWord \
      29 : Fpga #14 MSWord /
      30 : Fpga #15 LSWord \
      31 : Fpga #15 MSWord /
      32 : Fpga #16 LSWord \
      33 : Fpga #16 MSWord /
      34 : Board Support Fpga LSWord \ Reserved (Board Global IO)
      35 : Board Support Fpga MSWord /
      36 : Board Support Fpga LSWord \ Reserved (Board P5 IO)
      37 : Board Support Fpga MSWord /
      38 : Trailer LSWord Reserved (Fpga Version Number Information)
Word #39 : Trailer MSWord LSByte = THE-Card Event Number
                                  (should match Header's THE-Card Event Number)
                          MSByte = Reserved (Event Transfer Flags)

Sanity Checks:
--------------

Checking the sanity of the VBD-level structure is beyond the scope
of this document and is hopefully done before ScriptRunner is
handed the VRB data.

Some things the ScriptRunner could check before trusting
the online data:

  - Check that both VBD Channels of the targeted channel pair
  have 40 bytes of data each (which gives 40 words for the
  corresponding THE-Card).

  - Check that the content of the THE-Card ID field matches the
  targeted card.

  - Check that the two THE-Card Event Number bytes match
  (one from the Header and one from the Trailer, cf. above).

If any of the above tests fails, the data shouldn't be trusted.


The L1 Accept Number:
---------------------

    - Find the VRB in slot #18
      (which only uses 2x of its Channel pairs).

    - The L1FW Card with this information uses Channel Pair #2-3
      (i.e the 2nd channel pair on this VRB).

    - This is L1FW THE-Card ID= 0xD3

    - The L1 Accept Number will come from FPGA #1
      (with the LSWord coming first, i.e. little-endian format).


The Mask of Specific Trigger Fired:
----------------------------------

    - Find the VRB in slot #16
      (which only uses 3x of its Channel pairs).

    - The L1FW Card with this information uses Channel Pair #4-5
      (i.e the 3rd channel pair on this VRB).

    - This is L1FW THE-Card ID= 0xB0

    - The 128 bit mask will come from FPGA #12 thru 15
      (with the LSWord coming first, i.e. little-endian format).


The Luminosity Block Number a.k.a. Luminosity Index:
---------------------------

    - Find the VRB in slot #10
      (which only uses 3x of its Channel pairs).

    - The L1FW Card with this information uses Channel Pair #4-5
      (i.e the 3rd channel pair on this VRB).

    - This is L1FW THE-Card ID= 0x94

    - The 32 bit Luminosity Block Number will come from FPGA #4
      (with the LSWord coming first, i.e. little-endian format).