ࡱ > ' ) " # $ % & M 2 bjbj== W W |z O ^ l X N @ 4 R R R h PS T T
W X X X |Z " ^ < _ l n n n n n n $ r z` xZ |Z z` z` c X X c c c z` R X X l c z` l c $ c h "" PL : * X T h)) 5 R ` : j v 8 4 0 m * ) a ) * c LAT Flight Software
TITLE \* MERGEFORMAT LATC Users' GuideType:Users GuideVersion: COMMENTS \* MERGEFORMAT V6-0-0Author: AUTHOR \* MERGEFORMAT J. SwainCreated: CREATEDATE \@ "d MMMM yyyy" \* MERGEFORMAT 2 March 2005Updated: SAVEDATE \@ "d MMMM yyyy" \* MERGEFORMAT 15 March 2005Printed: PRINTDATE \@ "d MMMM yyyy" \* MERGEFORMAT 30 April 2004
This document provides an introduction to the LAT configuration package, LATC.
Contents
TOC \o "1-6" \h \z HYPERLINK \l "_Toc97524614" 0 Introduction PAGEREF _Toc97524614 \h 2
HYPERLINK \l "_Toc97524615" 0.0 Intended Audience PAGEREF _Toc97524615 \h 2
HYPERLINK \l "_Toc97524616" 0.1 References PAGEREF _Toc97524616 \h 2
HYPERLINK \l "_Toc97524617" 0.2 Glossary PAGEREF _Toc97524617 \h 2
HYPERLINK \l "_Toc97524618" 0.3 Request For Comments PAGEREF _Toc97524618 \h 2
HYPERLINK \l "_Toc97524619" 0.4 Overview PAGEREF _Toc97524619 \h 2
HYPERLINK \l "_Toc97524620" 0.5 LAT Registers PAGEREF _Toc97524620 \h 2
HYPERLINK \l "_Toc97524621" 0.6 LAT Components PAGEREF _Toc97524621 \h 3
HYPERLINK \l "_Toc97524622" 0.7 Names PAGEREF _Toc97524622 \h 4
HYPERLINK \l "_Toc97524623" 1 Example XML Files PAGEREF _Toc97524623 \h 4
HYPERLINK \l "_Toc97524624" 1.0 GEM PAGEREF _Toc97524624 \h 4
HYPERLINK \l "_Toc97524625" 1.1 AEM PAGEREF _Toc97524625 \h 8
HYPERLINK \l "_Toc97524626" 1.2 TEM PAGEREF _Toc97524626 \h 10
HYPERLINK \l "_Toc97524627" 2 Configuration Processing PAGEREF _Toc97524627 \h 14
HYPERLINK \l "_Toc97524628" 2.0 XML Interpretation PAGEREF _Toc97524628 \h 14
HYPERLINK \l "_Toc97524629" 2.1 Configuration Application PAGEREF _Toc97524629 \h 14
HYPERLINK \l "_Toc97524630" 2.2 Recording State PAGEREF _Toc97524630 \h 15
HYPERLINK \l "_Toc97524631" 2.3 XML Generation PAGEREF _Toc97524631 \h 16
Introduction
Intended Audience
This document is intended to provide guidance for users of the LAT configuration package LATC.
References
Glossary
Request For Comments
Please post corrections or questions as replies to the SNITZ release announcement for the relevant LATC version. Failing this, email jswain@slac.stanford.edu.
Overview
The LAT configuration is specified by one or more XML files setting the values for the registers or fields within registers of the LAT. This document will describe the XML tags used by LATC and give examples of configuration files before going to describe how to feed these files into XML.
LAT Registers
For the purposes of this document, the registers of the LAT can be divided into four categories
Read-only. There are various statistics registers or ADC interface registers of the LAT that are read-only. These registers cannot be set by LATC and their state is not recorded by LATC.
One-time write. There are several registers of the LAT that have one, and only one, correct setting. For example, the various timeouts and delays of the TEM, EBM, TCC and CCC. These registers are configured by FSW during start-up and are not modified or recorded by LATC.
Process driven. Some registers are implicitly set when a command is issued to the LAT. For example, the CRU registers, the PDU registers and the address registers of the various LATp nodes are set when a command is sent to the LAT instructing it to power a node and add it to the LAT command and response fabric. Other registers in this category might be the charge injection DACs that are used during calibration. These registers are not modified or recorded by LATC.
Everything else. The remaining registers can be used to enable and disable portions of the detector, or configure the trigger. These registers
LATC is concerned only with the last group of registers.
LAT Components
LATC can be used to configure the following LATC components (with multiplicities indicated in parentheses and indentation intended to indicate hierarchy).
GEM. Global trigger Electronics Module. (1)
TAM. Trigger Accept Message generator (1)
ROI. Region Of Interest. (1)
TIE. Trigger Input Enable. (1)
WIN. Window. (1)
SCH. Scheduler. (1)
AEM. ACD Electronics Module. (1)
ARC. ACD Readout Controller. (12)
AFE. ACD Front End. (216, 18 per ARC)
TEM. Tower Electronics Module. (16)
TIC. Trigger Interface Controller. (16, 1 per TEM)
CCC. Calorimeter Cable Controller. (64, 4 per TEM)
CRC. Calorimeter Cable Controller. (256, 4 per CCC)
CFE. Calorimeter Front End. (3072, 12 per CFE)
TCC. Tracker Cable Controller. (128, 8 per TEM)
TRC. Tracker Readout Controller. (1152, 9 per TCC)
SPT. Layer Split. (576, 36 per TEM)
TFE. Tracker Front End. (13824, 24 per SPT)
Note that some components, such as the CRU and PDU have no registers that are configured by LATC. The registers and fields that LATC configures on each component are listed in the appendix to this document.
Names
As far as possible, the names of the XML tags used by LATC match the names of the components, registers and fields as given in the various design documents. Unfortunately, XML tags must be unique while there are several reoccurring register names and several register fields with the same name as the register. Prepending the component name to register name to give unique register names, and shortening field names where necessary resolves this problem.
For example, the CONFIGURATION register of the AEM becomes aem_configuration and the TRG_ENABLE field of the TRG_ENABLE register becomes enable.
Example XML Files
The LATC package contains a document type definition specifying the layout of the LATC XML files. This DTD is included at the end of this document.
GEM
The LAT Global Trigger Electronics module actually contains six components. The GEM component of LATC holds the common controller registers (such as the ADDRESS). The other five components are represented as children of the GEM in the hierarchy. Within each component there are one or more registers that can be configured through LATC. Some, but not all, of these registers are further divided up into field that can be individually configured through LATC.
A simple GEM configuration is given below.
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0x0fff
0x0fff
0x0fff
0x0fff
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0xffff
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0x5
Most of this configuration is concerned with setting the various registers of the GEM to zero, but once it is understood that these values can simply be changed for any other acceptable value the example is sufficient for demonstrating the layout of the XML file.
No expertise in XML should be required to understand the GEM configuration presented above. Lines 0, 1, 2, 3 and 129 are standard XML header information specifying the version of XML being used, the types of tags that can be included in this file and marking the start and end of the document.
The next start tag, simply indicates the start of the GEM configuration information. The other two possibilities are and . The GEM tag contains five pairs of start and end tags, one for each sub-component of the GEM. In turn each of these contains one or more register elements.
The TAM, for example, contains sixteen registers, engines 0 to 15. These are represented in the XML by the tags , where N is 0, 1, , f. Each register has at least one field, the register field, which spans the entire register. Note that no attempt to format the user input for MBZ or read-only fields is made. This configuration file specifies most of the engine registers directly using the register field so the single number between the register tags (for engines 0, 2, , f) is the value that should be written into the register after the configuration has been applied. Engine 1 is treated differently. Rather than describing the register with a single number, this XML file describes each of the registers eight true fields individually.
The other GEM sub-components are similarly described. Note, however, that not all registers have field definitions. None of the TIE or SCH registers can be split, simply because the register only has a single field that uses the full width of the register.
AEM
The ACD configuration is different in several respects to the GEM configuration. First, the hierarchy is more complex. The ACD contains twelve ARC, represented as subcomponents of the AEM. Each of these ARC have eighteen AFE associated with them. The AEM, ARC and AFE all have registers associated with them, some of which are subdivided into fields.
A simple AEM configuration is given below.
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
0x0
The AEM start tag, register and field definitions are similar to those shown in the GEM example above. The differences lie in the start tags of the ARC and AFE. Each has an attribute, ID, with an associated value. The ID specifies which of the ARC or AFE the subsequent configuration refers to. The ID value of 255 is special, and indicates that the default configuration for the component is being specified. So the first ARC configuration and the first AFE configuration are both describing portions of the default configuration. The second ARC configuration refers to ARC 0, and the second AFE configuration refers to AFE 3 of that ARC.
TEM
The TEM component combines the features of the AEM and GEM. The TEM start tag takes an ID attribute and the TEM component contains a single TIC subcomponent. The calorimeter hierarchy follows along the same lines as the ACD, with the addition of a cable controller. The tracker hierarchy is more complicated. The TFE can be controlled from either TRC on a tracker layer. Thus the CC-RC-FE hierarchy breaks down. The alternative has TFE as subcomponents of the fictitious SPT (split) component. The SPT component itself has to fake registers that indicate how many TFE are controlled by the high end TRC and how many by the low end TRC. LATC uses this information to configure the TRC and TFE correctly, and then to route TFE configuration commands through the correct TRC.
A simple TEM configuration is given below.
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
Configuration Processing
XML Interpretation
Once the desired configuration has been expressed in XML files a parser must be used to generate the binary configuration files used by LATC on the target system, the LAT or a test stand. The parser is trivial to invoke.
latc_parser file0.xml file1.xml filen.xml uniqueID
The XML files of the configuration are simply supplied as command line arguments. The final argument, uniqueID, is the first of a monotonically increasing sequence of file IDs.
This command will produce a variable number of output files. There will definitely be a file called uniqueID. This is a text file called the configuration master file. It contains the names of all the binary configuration files generated by the parser. Different binary files can be mixed and match by editing the configuration master file. There will also be three files uniqueID+1 uniqueID+2, uniqueID+3. These files contain the default data set, the GEM configuration and the AEM configuration respectively. Since the GEM and the AEM are singletons, their configuration is specified by the default data, so the latter two files are in fact orthogonal subsets of the first. These are provided to allow more flexibility to LATC users; the GEM or AEM configuration can be updated without having to reenter the TEM, and ACD default configuration.
There may or may not be additional binary configuration files depending on the contents of the original XML file. The example files given in the previous section would result in the full complement of a binary file for each LAT component.
Configuration Application
In the flight environment the resulting configuration would be used during physics acquisition or calibration and the name of the configuration master would be passed as an argument to the command initiating such actions. In a test environment the configuration operation will be initiated by user software. In this case the simplest way to configure that LAT would be
#include LATC/latc.h
LATC_map* excluded = LATC_newMap();
LATC* latc = LATC_newByFile(uniqueID, excluded);
In most cases the latc and excluded structures can be immediately freed using the MBA_free function.
#include PBS/MBA.h
MBA_free(latc);
MBA_free(excluded);
The excluded structure is used to indicate portions of the LAT that should not be configured at this time, perhaps because they do not exist in the test stand environment. In the example above, no bits of the map are set and thus the whole LAT will be configured. A pair of functions is provided for setting and clearing the bits of the map.
#include LATC/latc.h
#include LATC/lrd.h
LATC_map* map = LATC_newMap();
LATC_addr addr = { {0, 0, 0, 0} };
latcType type = LATC_lookupType(TEM);
LATC_setBit(map, type, &addr);
addr.tem.to = 1;
addr.tem.cc = 2;
addr.tem.rc = 1;
type = LATC_lookupType(CRC);
LATC_setBit (map, type, &addr);
LATC_clearBit(map, type, &addr);
In addition to a pointer to the map being manipulated, the set and clear functions also need to be given an identifier for the component and its address. The numerical ID is found from the text string identifying the component by the function LATC_lookupType. The LATCaddr structure is actually a union of structures, and is defined in LATC/lrd.h. In the example given above the address is first initialed to zero, and used to set the bit of the map corresponding to TEM 0, and them it is reset so the second set command will set the bit of the map corresponding to CRC 1 of CCC 2 on TEM 1.
Recording State
The reverse operation, constructing a configuration by interrogating the LAT and writing that configuration to disk, can also be performed.
#include LATC/latc.h
#include LATC/lrd.h
LATC_map* excluded = LATC_newMap();
LATC* latc = LATC_newByLAT(excluded);
LATC_writeFile(latc, uniqueID);
As with configuration application, a map of components is supplied as an argument to the interrogation function. It is somewhat more important in this case, since attempting to read large sections of the LAT that are not present will force LATC to wait for all those reads to time out, which can take a significant period of time. The second argument to LATC_writeFile is a four-character identifier that will be used to create the filenames for the configuration. The output of this command will be a configuration master file and a variable number of configuration binary files, depending on the portions of the LAT that have been excluded form interrogation.
XML Generation
The final step is to generate an XML description of the recorded state. The writer is trivial to invoke and takes a single argument, the name of the configuration master file.
latc_writer uniqueID
The writer will generate (very large) XML file containing the configuration for each component that was not excluded in the call the LATC_newByLAT. No attempt is made to generate a default configuration, so even if each TEM has the same configuration, there will still be sixteen separate entries in the XML file.
For the purposes of this document clear-on-write registers are considered read-only.
SPT is a logical construct that does not correspond to a physical device. Setting the SPT sets the MODE registers of the TFE and the COUNT registers of the TRC.
All the fields are defined to be parsed character elements so reuse of a field name is not a problem, provided each name appears only once in the LATC DTD.
LATC XML files can be checked for correctness and validity with xmllint --noblanks --valid
None of these registers are modified by LATC at the time of writing.
This example is available in the FSW CVS repository, in the LATC package, file sdf/gem.xml
The latc.dtd file is the Document Type Definition for this XML file. It lists the tags that are valid of this type of XML file and describes the acceptable hierarchy.
XML uses start tags and end tags to bound elements.
I dont like this. I think it would be more natural for the whole register to be specified by the absence of a field tag, but I had problems getting the parser to work that way, and ran out of testing time. This might change in a later release (although I will have to keep the register field forever to ensure bw compatibility).
This example is available in the FSW CVS repository, in the LATC package, file sdf/gem.xml
This example is available in the FSW CVS repository, in the LATC package, file sdf/tem.xml
For this to work correctly the DFT configuration filename should appear before the GEM or AEM in the configuration master file, but it is a general operating principle that the default configuration filename should be the first file in the configuration master.
The obvious question here is how do I know what is each file? The answer is, you dont. This is an outstanding issue to be resolved by the integration of LATC and FMX. In the meantime, you can always learn to read the hex dump of the configuration binary files(.
This explains the double braces in the initialization statement for LATCaddr.
Tables TITLE \* MERGEFORMAT LATC Users' Guide
PAGE 9 Version COMMENTS \* MERGEFORMAT V5-0-1
Tables TITLE \* MERGEFORMAT LATC Users' Guide
TITLE \* MERGEFORMAT LATC Users' Guide Tables
PAGE 16 COMMENTS \* MERGEFORMAT V5-0-1
COMMENTS \* MERGEFORMAT V5-0-1 PAGE i
0 1 B C E G H [ \ e f 1 2 ? @ A B K L w x ½¶¶¶½¶¶½¶¶½¶¶½¶¶½
6>*]aJH j 6>*U]aJH CJ mH nH u
j CJ UOJ QJ CJ CJ0
j CJ0 UCJ KH OJ QJ aJ 6CJ0 OJ QJ ]^J 56CJ<