Level 1.5 Calorimeter Trigger Tool Calling --------------------------------------------- Rev. 9-NOV-1993 Local DSP Tools =============== Local DSP Tools have only two entry points. One entry point is used for normal event processing and the other entry point is used only once right after the tool is loaded to ask the tool to verify its parameters and to do any special setup that it may require. Tool/Term Parameter checking and Initialization entry point ----------------------------------------------------------- Just after the Tool is loaded it is called so that it can verify its parameters in the parameter block and so that it can do any special setup processing that may be necessary. Note that it may be called multiple times, i.e. for all the Terms this Tool evaluates. Call Local_Tool_N_Param_check ( Pointer_to_Parameters, Pointer_to_Term_Specific_Memory ) Pointer_to_Parameters is the actual address of the beginning of the first parameter in the set of parameters that this tool is to use to do its part to evaluate this L15 CT Term for all subsequent events (i.e. it is the address of a Term Local Tool Entry in the Parameter Block). Pointer_to_Parameters is not the base address of the whole parameter block. Pointer_to_Term_Specific_Memory is the actual address of the beginning of a memory region that the Local DSP Frame Code is offering to the Tool for this Term. The Tool is expected to answer back to the Local DSP Frame Code (cf. below) how much memory it will use, starting at this address. This memory section will be reserved for the evaluation of this Term by this Tool. The Tool may fill some of this block of memory with quantities derived from the parameters specific to this Term/Tool. The Tool may reserve additional memory for any temporary variable that will be necessary during its work in the evaluation of this Term during event processing, or for any status or counter variables. Note that this section of memory is captured by the Local DSP Frame Code during Mark and Pass Events. For this reason, the Tool should chose this memory region for any variable that may be useful for monitoring or debugging the Tool operation. After being called the tool checks this term entry in the parameter block and verifies that: - This Term Entry in the parameter block belongs to this Tool Number, - that the proper number of parameters appear in the term entry - and that all data contained in this entry is within range and consistency checks that are built into this part of the Tool code. After the Tool has made these checks it may also perform any one time initialization that is necessary to be ready for the subsequent event analysis. The Tool then returns 3 Longwords, including a status which indicates either that everything is "OK" or else some kind of error code (e.g. This Parameter Block Entry is not of my Tool Number, incorrect number of parameters, or parameter out of range, or I was not able to initialize). The 1st Longword will be examined by the Local DSP Frame Code to determine if the initialization was successful. In the case the initialization failed, the 1st and second Longwords will be made available to TCC. TCC will decode these error codes, return an error status to COOR on the initialization request, and send a formated error message to the D0 Alarm System. 1st longword 0:7 error code 0 : ok 1 : tool ID mismatch 2 : incorrect number of parameters 3 : parameter out of range 4 thru 20 : reserved for other initialization error codes 8:15 Reserved 16:23 Term Number 24:31 Which Parameter is found bad (if error code = 3) or number of parameters expected (if error code = 2) 2nd Longword 0:31 Tool Number Found (if error code = 1) Number of parameters found (if error code = 2) Parameter Value (if error code = 3) 3rd Longword 0:31 Tool Number of the Tool checking Parameters The 3rd Longword describes the length of the section of memory that the Local Tool needs for variables that need to be private for this Term/Tool and/or that the Tool wants to be included in the Debug Section of every Mark and Pass Event. For Mark and Pass events, the Local DSP Frame Code will arrange to capture this section of memory and include it in the Debug Section of the event readout returned by this Local DSP. This Debug Section is captured AFTER all the candidates have been processed. 3rd Longword Length of the Debug Section, i.e. number of words reserved by this Tool starting at Pointer_to_Term_Specific_Memory. Candidate Tower Confirmation entry point (For normal event processing) ---------------------------------------- For a given event processed by the L1.5 CalTrig Crate, this entry point will be called zero, one or several times during the Local DSP Processing of the event. This entry point is called for every Candidate Trigger Tower that the Local DSP Frame Code found for the term being evaluated by this Tool. A Trigger Tower is a Candidate when its energy is greater than the Reference Set associated with this Term. The Reference Set is applied to the EM or Tot Et Energy of the Trigger Tower according to the trigger definition files submitted to COOR. Call Local_Tool_N_Confirm_Candidate ( Pointer_to_Parameters, Pointer_to_Term_Specific_Memory, Eta_Ring, 1_Dimension_Eta_Phi_Address ) Pointer_to_Parameters is the actual address of the beginning of the set of parameters that this tool is to use to do its part to evaluate this L15 CT Term for this event (i.e. it is the address of Term Local Tool Entry in the Parameter Block). Pointer_to_Parameters is not the base address of the whole parameter block. Pointer_to_Term_Specific_Memory is the actual address of the beginning of a memory region agreed upon with the Local DSP Frame Code during the Term/Tool initialization phase. This memory is reserved for the evaluation of this Term by this Tool. The Tool may have filled some of this block of memory with quantities derived from the parameters specific to this Term/Tool. The Tool may use this memory for any temporary variable necessary during its work in the evaluation of this Term, or for any status or counter variables. Note that this section of memory is captured by the Local DSP Frame Code during Mark and Pass Events. For this reason, the Tool should chose this memory region for any variable that may be useful for monitoring or debugging the Tool operation. Eta_Ring is the Eta index of the Trigger Tower (signed integer -20..-1, 1..20) This parameter is mainly (only) used to correct for the eta dependency in the zero energy offset of any computed energy quantity. 1_Dimension_Eta_Phi_Address is the one dimensional eta,phi address of the Trigger Tower that was above the Reference Set value and thus caused the Local DSP Tool to wake up. Eta is the faster index. During normal event processing the local DSP tool returns 3 longwords of information. These are: 1st Longword Error Code, Pass/Fail 0:7 Error Code 0 : ok 21 : Local Tool Internal Memory overflow 22 thru 40 : reserved for other Local Tool error codes 8:15 Candidate Pass/Fail 0 : Pass FF : Fail 16:31 Reserved, set to zero for now 2nd Longword Object Type, Object Energy 3rd Longword Information Specific to the Tool The Pass/Fail information is used to control whether or not the candidate is made into an entry in the List of Identified Objects as a result of this call to a Local DSP Tool. In the case the Tool "Passes" the call, the 2nd and 3rd longwords returned by the Tool become the 2nd and 3rd longwords in the entry in a List of Identified Objects. The 2nd longword has: a 1 byte Object Type, a 2 byte Object Energy, and 1 byte reserved. 0:7 Object Type Code 8:15 Reserved 16:31 Object Energy (units 1/4 GeV per count) The third longword entry will contain Tool specific information, probably two 16 bit integers Notes about Local DSP Tools --------------------------- 1) There is no call to initialize the Local DSP Tools between events or between multiple calls (at different Trigger Tower addresses) to the same Local DSP Tool for a given event. 2) The Local Frame Code makes no attempt at preventing or rejecting duplicate entries issued from adjacent trigger tower candidates. An EM Tool might achieve this rejection by requiring that none of the towers in its 8 closest neighbors has a greater energy deposit. 3) Some work should be done to understand the impact on the rates, and acceptance of the Tool in the presence of Hot Towers (under the various types of hot towers). One should understand if the tool algorithm can safely operate with a Reference Set isolating the hot tower, or if the tower needs to be excluded and forced to read as zero energy for both the L1 and L1.5 Calorimeter Trigger Systems. 4) The Zero Energy Response (offset) of a Trigger Tower in the Level 1.5 Calorimeter Trigger depends on its eta index. Thus the DSP implementation of the Local Algorithm needs to receive as argument the eta_ring of the candidate tower. All Energy sums (1x1, 3x3, 5x5) need to be corrected using an offset that only depends on the Eta Index of the Candidate Trigger Tower. 5) All Energy Quantities returned by a Local Tool need to be offset corrected by the Local Tool before they are returned to the Local DSP Frame Code. 6) The energies in the Local DSP memory are organized in 2 blocks, one for Trigger Tower Et Data from each rack serviced by this Local DSP Node. Each block is further divided in 2 sections. One section contains the Trigger Tower EM Et data for a single rack (i.e. 4 etas by 32 phis), and the other section contains the Trigger Tower Total Et data for a single rack. The energies of the four etas for the first phi value appear first in memory in each block, followed by the energies of the four etas at the next phi and so on. The energies are byte-packed in increasing eta values, with the low eta in the low byte. Nothing can be done to avoid having 2 separate blocks of etas. A given Local DSP sees the data for only 8 consecutive etas (except for end effects at +/- 17:20 that only get 4 etas) and is only responsible for the candidates in the center 4 etas. The one dimension index is 1_Dimension_Eta_Phi_Address = cst_1 + TT_Phi for the lower 4 etas, and 1_Dimension_Eta_Phi_Address = cst_2 + TT_Phi for the upper 4 etas. with eta_ring identifying the byte in the Longword addressed. 7) It is currently believed that a Local Tool would not need the Phi index of the candidate tower, and that phi-wrapping can be solved with a different method. One doesn't need to know the phi value to make any of the 3x3 or 5x5 sums. All this data is accessible by fixed offset (which is speed efficient). However, because of the eta splitting in two blocks, one might need to make a special code section for each eta ring. The best approach for solving the "phi-wrap" problem is to use the 'C40 circular addressing mode which is designed to address exactly this problem (creation of a circular buffer in memory). Therefore the trigger tower energies at phi = 1,2 and 31,32 WILL NOT be explicitly duplicated in memory. If we end up really needing phi, bit 0:4 (or something like that) of 1_Dimension_Eta_Phi_Address will encode (TT_phi-1), or some other method will be available. 8) For Mark and Pass events, the Local DSP Frame Code will still place the failed candidate towers in the list of identified objects, flagging it accordingly. For this reason, the Local Tool should make its best effort to return all the information possible even when it fails a candidate. This information may be incomplete, but should at least include the quantity that made the Tool reject the Tower. 9) In the block of memory identified by the Local DSP Tools as needed in the debug section of Mark and Pass Events, the tool may chose to place - any derived constant or table it judges appropriate - any intermediate result - any status, counter or other variable required for Monitoring 10) The same Local Tool may be called for several Terms with different Term Parameters. This means it cannot place quantities derived from the parameters in a section of memory that it would overwrite in a subsequent call for a different Term. Such variables have to be placed in the section of memory at Pointer_to_Term_Specific_Memory. Global DSP Tools ================ Global DSP Tools have four entry points. Three entry points are used for normal event processing, and one entry point is used only once right after the tool is loaded to ask the tool to verify its parameters and to do any special setup that it may require. During Normal Event Processing, the Global DSP Frame Code scans all the Local DSP's lists of "Identified Objects". For each filled entry located the Global DSP Frame Code calls a first entry point of the appropriate Global Tool for each Term that needs to be evaluated. The Global Tool may then reject, process, count, register, or simply remember the pointer to the entry. During each such call, the Global Tool may place zero, one or more entries in the Global DSP "Accepted Object" List. A macro or a frame code service routine will be provided to actually insert an entry in the Entry list. After the Global DSP Frame Code is done scanning all the Local DSP's list, it calls a second entry point of the appropriate Global Tool of each Term that needs to be evaluated. The Global Tool is then required to return its Pass/Fail answer for the Term it is evaluating and is also required to place any last additional entries it cares to include in the Global DSP "Accepted Object" List. After the processing of all the Terms is finished, and before the processing of the next event, the Global DSP Frame Code will call a third entry point of the appropriate Global Tool of each Term that HAS BEEN evaluated. The Global Tool may then perform any initialization necessary between events. Tool/Term Parameter checking and Initialization entry point ----------------------------------------------------------- This Entry point has the same definition and the same expectations as for the Local Tools. This includes the protocol between the Global DSP Frame section and the Global Tool to reserve a section of memory private to this Term/Tool. Call Global_Tool_N_Param_check ( Pointer_to_Parameters, Pointer_to_Term_Specific_Memory ) An additional requirement for Global Tools is that the Tool should have already take during this phase any event initialization action necessary. The reson being that no call to the End of Event Initialization entry point will be made by the Global DSP Frame Code before the Tool is called with the first entry of the first event. Confirmed Object Registration entry point (For normal event processing) ----------------------------------------- For a given event processed by the L1.5 CalTrig Crate, this entry point will be called zero, one or several times during the Global DSP Processing of the event. This Entry point is only called for the Terms that need to be evaluated by this Tool. This entry point is called for every filled Entry that the Global DSP Frame Code found in the List of Identified objects from the 11 Local DSP's. Every entry found is passed to all the appropriate Global Tools to evaluate the Terms needed. Every entry is passed to all the elligible tools, independently of which Term, which Local Tool generated this entry and which type of object it is. Call Global_Tool_N_Register_Object ( Pointer_to_Parameters, Pointer_to_Term_Specific_Memory, Pointer_to_Entry ) Pointer_to_Parameters is the actual address of the beginning of the set of parameters that this tool is to use to do its part to evaluate this L15 CT Term for this event (i.e. it is the address of a Term Global Tool Entry in the Parameter Block). Pointer_to_Parameters is not the base address of the whole parameter block. Pointer_to_Term_Specific_Memory is the actual address of the beginning of a memory region agreed upon with the Global DSP Frame Code during the Term/Tool initialization phase. This memory is reserved for the evaluation of this Term by this Tool. The Tool may have filled some of this block of memory with quantities derived from the parameters specific to this Term/Tool. The Tool may write in this section of memory any temporary variable necessary during its work in the evaluation of this Term, or any status or counter variables. The Tool may use this memory region to remember the pointer to the current object and thus be able to access this object again later. Note that this section of memory is captured by the Global DSP Frame Code during Mark and Pass Events. For this reason, the Tool should chose this memory region for any variable that may be useful for monitoring or debugging the Tool operation. Pointer_to_Entry is the address of one entry that this Global Tool needs to examine. It is the address of one of the entries in a List of identified objects from one of the 11 Local DSP's. Pointer_to_Entry is not the base address of a list of objects. During this processing phase the global DSP tool returns 1 longword of information, which is an error code. Longword Error Code 0:7 Error Code 0 : ok 41 : Local Tool Internal Memory overflow 42 thru 60 : reserved for other Global Tool registering error codes 8:31 Reserved, set to zero for now It is the responsibility of the Global Tool to check the Entry passed. The Global Tool may chose to pre-filter the Entry on the basis of its originating Term Number or Object Type. During this phase of processing, the Global Tool may chose to reject or accept the proposed entry, and write zero, one or more entries in the Global DSP Accepted Objects List. Depending on the Global DSP algorithm, the tool might only be able to register the entry, remember its pointer but need to wait for further entries before coming to any conclusion. Term Pass/Fail entry point (For normal event processing) -------------------------- For a given event processed by the L1.5 CalTrig Crate, this entry point will be called once during the Global DSP Processing of the event. This Entry point is only called for the Terms that need to be evaluated by this Tool. This Entry point will be called after all Local DSP Enties in the List of Identified Objects have been exhausted. Call Global_Tool_N_Term_Answer ( Pointer_to_Parameters, Pointer_to_Term_Specific_Memory ) Pointer_to_Parameters is the actual address of the beginning of the set of parameters that this tool is to use to do its part to evaluate this L15 CT Term for this event (i.e. it is the address of a Term Global Tool Entry in the Parameter Block). Pointer_to_Parameters is not the base address of the whole parameter block. Pointer_to_Term_Specific_Memory is the actual address of the beginning of a memory region agreed upon with the Global DSP Frame Code during the Term/Tool initialization phase. This memory is reserved for the evaluation of this Term by this Tool. The Tool may have filled some of this block of memory with quantities derived from the parameters specific to this Term/Tool. The Tool may retrieve from this memory any temporary variable written earlier and necessary during its work in the evaluation of this Term, or for any status or counter variables. The Tool may have placed a series of pointers to the interesting entries registered earlier, and is now able to go back and examine them in more details, or combined and compare them. Note that this section of memory is captured by the Global DSP Frame Code during Mark and Pass Events. For this reason, the Tool should chose this memory region for any variable that may be useful for monitoring or debugging the Tool operation. During this processing phase the global DSP tool returns 1 longword of information, which includes an error code and the Pass/Fail Answer for the Term being evaluated. Longword Error Code, Pass/Fail 0:7 Error Code 0 : ok 61 : Global Tool Internal Memory overflow 62 thru 80 : reserved for other Global Tool Answer error codes 8:15 Term Pass/Fail 0 : Pass FF : Fail 16:31 Reserved, set to zero for now During this phase of processing, the Global Tool needs to make its final decision for the processing of this Term for this event. It also needs to write any last entries it wants to register in the Global DSP Accepted Objects List. End of Event entry point (For normal event processing) ------------------------ For a given event processed by the L1.5 CalTrig Crate, this entry point will be called only once and after the Global DSP Processing of the event is finished, that is after all entries have been exhausted and after the final pass/fail entry point has been called. This Entry point is only called for the Terms that were evaluated by this Tool for this event. Call Global_Tool_N_End_Event ( Pointer_to_Parameters, Pointer_to_Term_Specific_Memory ) Pointer_to_Parameters is the actual address of the beginning of the set of parameters that this tool is to use to do its part to evaluate this L15 CT Term for this event (i.e. it is the address of a Term Global Tool Entry in the Parameter Block). Pointer_to_Parameters is not the base address of the whole parameter block. Pointer_to_Term_Specific_Memory is the actual address of the beginning of a memory region agreed upon with the Global DSP Frame Code during the Term/Tool initialization phase. This memory is reserved for the evaluation of this Term by this Tool. The Tool may need to clear/reset any temporary variable that it had used during its work in the evaluation of this Term. The Tool may need to clear the list of pointers to the objects it may have registered earlier. During this processing phase the global DSP tool returns 1 longword of information, which includes an error code. Longword Error Code 0:7 Error Code 0 : ok 81 : Global Tool Initialization error 82 thru 100 : reserved for other Global Tool Initialization error codes 8:31 Reserved, set to zero for now During this between event initialization phase the global DSP tool should get ready to process the next event. Notes about Global DSP Tools --------------------------- 1) Depending on the Global Tool and the configuration, the Global Algorithm may need to use the output of several Term Local Tools. This is the motivation for passing all entries without any filtering (except failed entries for Mark and Pass events) to all Global Tools. It is then the responsibility of the Global Tool to select the input candidates on the basis of their originating Term Number or Object ID. 2) The Global Tool sees the output from all Local Tools, but do not see the output of any other Global Tool. 3) The Global Frame Code makes no attempt at preventing or rejecting duplicate entries before invoking a Global Tool. 4) All Energy Quantities included in Local DSP Lists of Identified Objects have been corrected by the Local Tools for Zero Energy offset. 5) For Mark and Pass events, the Global DSP may still chose to place some of the failed entries in the Global DSP Lists of Accepted objects. A macro or call to a frame code service will be provided to actually insert an entry in the Entry list, appropriately flagged as Mark and Pass additional Entry. 6) For Mark and Pass events, the Global DSP Frame Code will capture the section of memory described during the call to the Tool/Term Parameter checking and initialization entry point. The memory will be captured after the Call to the Pass/Fail Entry point, and before the call to the End of Event entry point.