Draft specification of Run IIb L1 Calorimeter Trigger Interface between TCC and TAB/GAB Software P.Laurens, H.Evans, M.Mulhearn. 4-Oct-2005 0. General ========== The TCC control code will interface to the TAB/GAB software by sharing the source code developped to test and control the hardware. 0.1. Enumerated type for Return Value -------------------------------------- This interface uses a dedicated enumerated data type for all functions to use as return values. This is common to all routines described in this document. enum EStatus { eOk = 0, /* Request filled, no problem*/ eBadParam = 1, /* Didn't like one of the parameters*/ eIoError = 2 /* Tried to do as requested, but couldn't program hardware*/ } ; The TAB/GAB software should verify that the parameters passed are within the expected boundaries. If an unexpected parameter is detected, the function should return the enumerated value "EBadParam". The TAB/GAB software should verify that the requested action was carried out successfully, e.g. by reading back all/some of the values programmed in registers. If an IO error is detected, the function should return the enumerated value "eIoError". When the TAB/GAB software has verify that the requested action was successfully performed, the function should return the enumerated value "eOk". I. Configuration and Initialization =================================== I.1. Firmware Configuration --------------------------- After power up, or for specific reasons, TCC can reload firmware in all TAB/GAB boards. To be described. Probably no new special code needed. Use the existing code. Any order dependence will need to be specified. I.2. Initialization ------------------- After power up and firmware configuration, or on an explicit request from COOR (e.g. before a new store), TCC will initialize the L1Cal system. Initialization is aimed at several goals: - Access all hardware registers and instore or restore functionality. - Access all resources, and verify (to best extent) that all functional aspects are operational (e.g. verify that all cards and FPGAs are accessible). - reset all logic that could have been previously become confused or stuck in an unknown state - forget any history of previous programming from COOR or any direct overriding by trigger experts or special tests carried out between stores. - reload all constants, and other non-run-dependent programmable resources (e.g. trigonometric tables) - program all run-dependent resources to a default, defined, clean slate, initial state which is known to and expected by COOR. - return a clear binary status to COOR to assert that the system is now operational and under COOR control. Any critical problem should be flagged to COOR as an initialization failure, and a L1Cal Expert will then need to be called. The detail of the error detected is not communicated to COOR. The detection of such failures should generate detailed error messages that will be captured in TCC's logfile. TCC may also separately send more detailed messages to the Significant Alarm System to specify the details and the extent of the problems (to be determined). Initialization is pictured to happen in (at least) two steps - The first step is a "hardware level" per-card initialization to reset logic, load operational values (e.g. delays) in whatever sequence of actions is necessary to say that the card is ok, and ready for programming. There may be a specific order the TAB/GAB cards need to be initialized in, to be defined here. Constants (e,g, trigonometry) may be loaded at this time, or as an explicit separate step. - The last step is a "functional level" initialization of all resources using the higher level resource functions described later in this document in order to bring the system to the defined initial state. Some/Most resources may get programmed twice this way, which is not a problem unless significant time is involved (several seconds). These two steps have a different emphasis. I.2.1 TAB Hardware Level Initialization EStatus Tab_Initialize ( unsigned long Tab_Module ) Return value: cf. EStatus definition Parameters: Tab_Module Module ID of TAB card unsigned integer allowed values = 0:7 I.2.2 GAB Hardware Level Initialization EStatus Gab_Initialize ( ) Return value: cf. EStatus definition Parameters: None II. COOR to TCC messages ======================== This chapter is a place holder so that the numbering of items in chapters III and IV matches the numbering of the COOR messages that this library of routines supports, as described in coor_to_l1caltcc_message_syntax.txt in http://www.pa.msu.edu/hep/d0/ftp/run2b/l1cal/tcc/coor/ III. TAB resources ================== III.1. Threshold Reference Sets ------------------------------- III.1.a. Jet Reference Sets EStatus Tab_Set_JetEtThresh ( unsigned long Tab_Module, unsigned long Tab_Chip, unsigned long Tab_Thresh_Num, unsigned long Set_AdcCount_Thresh ) Return value: cf. EStatus definition Parameters: Tab_Module Module ID of TAB card unsigned integer allowed values = 0:7 Tab_Chip Chip ID on TAB Card unsigned integer allowed values = 0:9 Tab_Thresh_Num Jet Threshold Number on TAB unsigned integer allowed values = 1:7 Set_AdcCount_Thresh Energy Threshold Value for Jet Object in units of ADC counts unsigned integer allowed values = 0:4095 Current limitations: None III.1.b. EM Reference Sets EStatus Tab_Set_EmEtThresh ( unsigned long Tab_Module, unsigned long Tab_Chip, unsigned long Tab_Thresh_Num, unsigned long Set_AdcCount_Thresh ) Return value: cf. EStatus definition Parameters: Tab_Module Module ID of TAB card unsigned integer allowed values = 0:7 Tab_Chip Chip ID on TAB Card unsigned integer allowed values = 0:9 Tab_Thresh_Num EM Threshold Number on TAB unsigned integer allowed values = 1:7 Set_AdcCount_Thresh Energy Threshold Value for EM Object in units of ADC counts unsigned integer allowed values = 0:4095 Current limitations: None III.1.c. Tau Reference Sets EStatus Tab_Set_TauEtThresh ( unsigned long Tab_Module, unsigned long Tab_Chip, unsigned long Tab_Thresh_Num, unsigned long Set_AdcCount_Thresh ) Return value: cf. EStatus definition Parameters: Tab_Module Module ID of TAB card unsigned integer allowed values = 0:7 Tab_Chip Chip ID on TAB Card unsigned integer allowed values = 0:9 Tab_Thresh_Num Tau Threshold Number on TAB unsigned integer allowed values = 1:7 Set_AdcCount_Thresh Energy Threshold Value for Tau Object in units of ADC counts unsigned integer allowed values = 0:4095 Current limitations: Until firmware exists routine defined, but no action, return Ok. III.2. Algorithm Parameters --------------------------- III.2.a. EM isolation Ratio EStatus Tab_Set_EmIsol ( unsigned long Tab_Module, unsigned long Tab_Chip, unsigned long Set_Exponent_Thresh, unsigned long Set_Enabled ) Return value: cf. EStatus definition Parameters: Tab_Module Module ID of TAB card unsigned integer allowed values = 0:7 Tab_Chip Chip ID on TAB Card unsigned integer allowed values = 0:9 Set_Exponent_Thresh Power of 2 exponent defining the Treshold unsigned integer allowed values = 0:3 Set_Enabled Specify whether EM Isolation cut is used unsigned integer allowed values 0 = Disabled 1 = Enabled Current limitations: None III.2.b. EM/HD fraction EStatus Tab_Set_EmHdFract ( unsigned long Tab_Module, unsigned long Tab_Chip, unsigned long Set_Exponent_Thresh, unsigned long Set_Enabled ) Return value: cf. EStatus definition Parameters: Tab_Module Module ID of TAB card unsigned integer allowed values = 0:7 Tab_Chip Chip ID on TAB Card unsigned integer allowed values = 0:9 Set_Exponent_Thresh unsigned integer allowed values = 0:3 Set_Enabled Specify whether EM/HD Fraction cut is used unsigned integer allowed values 0 = Disabled 1 = Enabled Current limitations: None IV. GAB resources ================== IV.1. Jet Object Count ----------------------- IV.1.a. Jet Count over full coverage EStatus Gab_Set_JetAllTerm ( unsigned long Rel_Term_Num, unsigned long Use_Thresh_Num, unsigned long Set_ObjCount_Thresh ) Return value: cf. EStatus definition Parameters: Rel_Term_Num Relative An/Or Term Number of this type sent by the GAB to L1 Framework unsigned integer allowed values = 0:15 Use_Thresh_Num Jet Threshold Number (as seen by GAB) from which Jet Objects will be counted unsigned integer allowed values = 1:6 Set_ObjCount_Thresh unsigned integer allowed values = 1:4 Current limitations: Set_ObjCount_Thresh ignored IV.1.b. Jet Count over Central Calorimeter coverage EStatus Gab_Set_JetCentralTerm ( unsigned long Rel_Term_Num, unsigned long Use_Thresh_Num, unsigned long Set_ObjCount_Thresh ) Return value: cf. EStatus definition Parameters: Rel_Term_Num Relative An/Or Term Number of this type sent by the GAB to L1 Framework unsigned integer allowed values = 0:3 Use_Thresh_Num Jet Threshold Number (as seen by GAB) from which Jet Objects will be counted unsigned integer allowed values = 1:6 Set_ObjCount_Thresh unsigned integer allowed values = 1:4 Current limitations: Set_ObjCount_Thresh ignored IV.2. EM Object Count ---------------------- IV.2.a. EM Count over full coverage EStatus Gab_Set_EmAllTerm ( unsigned long Rel_Term_Num, unsigned long Use_Thresh_Num, unsigned long Set_ObjCount_Thresh ) Return value: cf. EStatus definition Parameters: Rel_Term_Num Relative An/Or Term Number of this type sent by the GAB to L1 Framework unsigned integer allowed values = 0:11 Use_Thresh_Num EM Threshold Number (as seen by GAB) from which EM Objects will be counted unsigned integer allowed values = 1:6 Set_ObjCount_Thresh unsigned integer allowed values = 1:4 Current limitations: Rel_Term_Num allowed values = 0:7 Set_ObjCount_Thresh ignored IV.2.b. EM Count over Central Calorimeter coverage EStatus Gab_Set_EmCentralTerm ( unsigned long Rel_Term_Num, unsigned long Use_Thresh_Num, unsigned long Set_ObjCount_Thresh ) Return value: cf. EStatus definition Parameters: Rel_Term_Num Relative An/Or Term Number of this type sent by the GAB to L1 Framework unsigned integer allowed values = 0:3 Use_Thresh_Num EM Threshold Number (as seen by GAB) from which EM Objects will be counted unsigned integer allowed values = 1:6 Set_ObjCount_Thresh unsigned integer allowed values = 1:4 Current limitations: Rel_Term_Num allowed values = 0:1 Set_ObjCount_Thresh ignored IV.3. Tau Object Count ----------------------- IV.3.a. Tau Count over full coverage EStatus Gab_Set_TauAllTerm ( unsigned long Rel_Term_Num, unsigned long Use_Thresh_Num, unsigned long Set_ObjCount_Thresh ) Return value: cf. EStatus definition Parameters: Rel_Term_Num Relative An/Or Term Number of this type sent by the GAB to L1 Framework unsigned integer allowed values = 0:3 Use_Thresh_Num Tau Threshold Number (as seen by GAB) from which Tau Objects will be counted unsigned integer allowed values = 1:6 Set_ObjCount_Thresh unsigned integer allowed values = 1:2 Current limitations: Set_ObjCount_Thresh ignored IV.4. EM Isolated Object Count ------------------------------- IV.4.a. EM Isolated Count over full coverage EStatus Gab_Set_IsolEmAllTerm ( unsigned long Rel_Term_Num, unsigned long Use_Thresh_Num, unsigned long Set_ObjCount_Thresh ) Return value: cf. EStatus definition Parameters: Rel_Term_Num Relative An/Or Term Number of this type sent by the GAB to L1 Framework unsigned integer allowed values = 0:1 Use_Thresh_Num EM Threshold Number (as seen by GAB) from which Isolated EM Objects will be counted unsigned integer allowed values = 1:6 Set_ObjCount_Thresh unsigned integer allowed values = 1:2 Current limitations: Until firmware exists routine defined, but no action, return Ok. IV.4.b. EM Isolated Count over Central Calorimeter coverage EStatus Gab_Set_IsolEmCentralTerm ( unsigned long Rel_Term_Num, unsigned long Use_Thresh_Num, unsigned long Set_ObjCount_Thresh ) Return value: cf. EStatus definition Parameters: Rel_Term_Num Relative An/Or Term Number of this type sent by the GAB to L1 Framework unsigned integer allowed values = 0:1 Use_Thresh_Num EM Threshold Number (as seen by GAB) from which Isolated EM Objects will be counted unsigned integer allowed values = 1:6 Set_ObjCount_Thresh unsigned integer allowed values = 1:2 Current limitations: Until firmware exists routine defined, but no action, return Ok. IV.5. Missing Et Energy Cut ---------------------------- EStatus Gab_Set_MissEtTerm ( unsigned long Rel_Term_Num, unsigned long Set_AdcSquare_Thresh ) Return value: cf. EStatus definition Parameters: Rel_Term_Num Relative An/Or Term Number of this type sent by the GAB to L1 Framework unsigned integer allowed values = 0:3 Set_AdcSquare_Thresh unsigned integer allowed values = 0:8191 Current limitations: Nnone IV.6. Total Et Energy Cut ---------------------------- EStatus Gab_Set_TotEtTerm ( unsigned long Rel_Term_Num, unsigned long Set_AdcCount_Thresh ) Return value: cf. EStatus definition Parameters: Rel_Term_Num Relative An/Or Term Number of this type sent by the GAB to L1 Framework unsigned integer allowed values = 0:1 Set_AdcCount_Thresh unsigned integer allowed values = 0:8191 Current limitations: Nnone IV.6. Topological Acoplanar Jet Requirement ------------------------------------------- EStatus Gab_Set_AcoplanarJetTerm ( unsigned long Rel_Term_Num, unsigned long Use_Thresh_Num_a, unsigned long Use_Thresh_Num_v ) Return value: cf. EStatus definition Parameters: Rel_Term_Num Relative An/Or Term Number of this type sent by the GAB to L1 Framework unsigned integer allowed values = 0:1 Use_Thresh_Num_a Jet Threshold Number (as seen by GAB) from which a Primary jet Object will be picked unsigned integer allowed values = 1:6 Use_Thresh_Num_v Jet Threshold Number (as seen by GAB) from which the Primary Jet Object(s) will be compared to unsigned integer allowed values = 1:6 Current limitations: Use_Thresh_Num_v, ignored use Use_Thresh_Num_v = Use_Thresh_Num_a IV.7. Topological Back-to-Back EM Requirement --------------------------------------------- EStatus Gab_Set_BackToBackEmTerm ( unsigned long Rel_Term_Num, unsigned long Use_Thresh_Num ) Return value: cf. EStatus definition Parameters: Rel_Term_Num Relative An/Or Term Number of this type sent by the GAB to L1 Framework unsigned integer allowed values = 0:1 Use_Thresh_Num EM Threshold Number (as seen by GAB) from which at least one EM pair must be flagged as back to back unsigned integer allowed values = 1:6 Current limitations: Nnone V. Monitoring ============= To be defined VI. Alarms ========== To be defined