LAT Configuration System Tool
(ConfigSystem)

The Configuration System Tool (ConfigSystem) is used to make LATC LPA (LAT Physics Acquisition) and LCI (LAT Charge Injection) configurations – starting from a concise XML representation of the configuration intent, and building that into a full LATC_XML and LCI_XML description of all the registers settings and the looping and iterations done in LCI runs. This tool is used to create new configurations for the LAT, or to modify existing configurations.

The MOOT system uses flight software tools to build the LATC_XML and LCI_XML into binary files, which are delivered to Flight Operations and used to define the LAT configuration during LPA and LCI data taking. These files are managed by the Flight Software file management system. While these processes are basically 'hidden' from the data analysts, MOOT is the tool used to obtain information about the LAT configuration.

To summarize, ConfigSystem is used to generate valid LATC_XML and LCI_XML files, and to load those files into MOOT so that they can be accessed by the Mission Planning tools, and by offline software. MOOT takes care of tracking configurations, as well as building and managing the flight software binary files needed to load those configurations.
(See ConfigSystem diagram.)

This section describes how to express the intent of a configuration, and how to use the available tools to build and store LATC_XML and LCI_XML files.

ConfigSystem

ConfigSystem converts concise "human-readable'' descriptions of the intent of the configuration into complete "full-blown" descriptions of all the register settings. In the process, it keeps track of:

• Intent in configuring "mode'' registers (generally all set to the same "broadcast'' value).

• Optimal values of timing registers (generally all set to the same "broadcast'' value).

• Calibrations to use in generating settings for threshold registers (generally have different values for each instance of the register).

• Threshold levels to use with calibrations, so that threshold settings may be expressed in terms of physically meaningful quantities, e.g., Energy, or Minimum-Ionizing Particle (MIP) equivalent.

• Loop structure and scan ranges when running LCI tests.

Precincts. In order to change different parts of the configuration asynchronously, the LATC configuration building process divides the LATC configuration into many groups or precincts, defined as a "best guess" for how LATC configurations will be changed, (i.e., any group of settings that are likely to be modified as a group make up a precinct, and each precinct can be managed independently).

LATC_XML Format

• LATC_XML groups LATC registers by hardware component. At each level, a hardware component has some registers, and controls other – lower-level – hardware components.

• Each hardware component and each register has its own xml node.

• For many hardware components, the LATC includes several instances of the component. In these cases LATC_XML allows configuration of a single instance by using the "ID'' attribute of the xml node for that component. Conversely "ID='BCAST''' can be used to configure all instances of that component.

• Many registers can be further broken into bit-fields.

• LATC_XML can be split into more that one file, but with several constraints. MOOT handles many of those constraints, so that they can be summarized in the next four points:
  • A broadcast value must be specified for every register that has more that one instance.

• The value for each singleton register must be specified exactly once.

• The broadcast value for any given instance of a register may be overridden exactly once.

• Broadcast settings and specific instance settings may not be mixed in a single file.

Hardware Hierarchy. (See Hierarchy of Hardware Components (and hence LATC_XML nodes).

Note: The task of generating configurations is complicated in that the ideal settings for many registers on a single hardware component may vary asynchronously.

LCI_XML Format

LCI_XML defines the data-taking sequence during charge injection runs. LCI runs often scan a series of register settings to map out the electronics response of the LAT. Therefore, the LCI syntax is designed to make it easy to specify loop structures.

Flight software provides a format for controlling LCI as reflected in a pseudo-example for an ACD LCI script.

Building LAT Configurations

Since ConfigSystem builds and manages both LATC_XML and LCI_XML in discrete sections some mechanism is needed to bundle together the sections into a coherent whole. On one side, this is handled explicitly by MOOT; however, it is also useful to provide an XML format to bundle the configurations. The XML syntax for doing this grouping is shown below:

  <LPA_XML>
      <!-- One Node per precinct -->
      <Precinct Name="ACD_Bias">
        <!-- One Node per parameter file -->
        <paramFile>FileKey_0</paramFile>
        <paramFile>FileKey_1</paramFile>
      </Precinct>
    </LPA_XML>  

The same syntax is used for grouping the parameter files needed for LCI scripts, except <LPA_XML>
is replaced with: <LCI_ACD>, <LCI_CAL>, or <LCI_TKR>. (See Configuration Builder GUI.)

And, in each case, there will be an extra precinct for the LCI instructions; respectively, these extra precincts are called: "ACD_LCI'', "CAL_LCI'', and "TKR_LCI'' .

Configuration Inputs

The process of building configurations is handled one precinct at a time. Associated with each precinct are:

• A vote file specifying the intent in configuring the precinct.

• Ancillary files such as calibrations or dead-channel masks which we use in generating the register settings.

• Output parameter files with the registers settings.

• In addition, some offline files may need to be generated, which are are not part of the LATC configuration, but are used by offline software.

Since the output parameter files are uniquely determined by the input vote and ancillary files, MOOT keeps track of the one-to-one mapping between a set of inputs and an set of outputs.

Note: The one-to-one aspect of the mapping only exists when the entire set of input and outputs is considered.

For example, the same input vote file used with different ancillary calibrations would produce different register settings. In addition, any precinct may – or may not – use any ancillary calibrations, or may even depend on more than one set of calibrations.

LPA vote Files

To build a LATC configuration every precinct must have vote file which specifies the intent behind the configuration. The vote file:

• Specifies how register configuration is built.

• Specifies the registers controlled by that precinct and to give default values for those registers.

• Selects any calibrations or other ancillary files needed to generate the configuration.

• Specifies any constants (such as a threshold level) needed to generate the configuration.

• Specifies the output LATC configuration files.

• Specifies any other output files that might be used by ground software tools.

The vote files all follow the same XML format. (See Example: Vote File.) Each of the six functions described above is treated by an XML node and its children.

Configuration Method and Comments

The "method'' xml node specifies how a precinct should go about building configurations. In general almost every precinct uses one of:

• NONE: is just used as a tag by the GUI tools when the method is unspecified.

• BCAST: requests that the default values be used for every channel.

• CALIB: requests that a calibration be applied. This will usually also require one or more constants to set things like the threshold level.

• SETTINGS: requests that an input file with the register settings be used. The precinct will just reformat those settings into valid LATC_XML.

In a small number of cases there may be more that one way to make the precinct settings from calibrations. In those cases the method tags are CALIB_TYPE, such as in the ACD_Veto precinct where CALIB_MIP and CALIB_PHA specify two different ways to build configurations from input calibrations.

Register default (broadcast) values

In every precinct, there is one node under <PREC_NAME-registers> for each type of LATC register managed by that precinct. These nodes serve the dual purpose of making it clear which precinct manages which registers and specifying a default (a.k.a. "broadcast'') value for those registers.
(See: LATC Register Types and Default Values.)

References to ancillary files

When precincts depend on ancillary files, there is one node under <PREC_NAME-anc> for each ancillary file needed by the precinct. Rather than referring directly to the ancillary file, the votes file refers to an alias, which in turn refers to the ancillary file. This system allows the version of the ancillary file to be updated by changing the alias, without having to change the vote file. Likewise, if several configurations refer to the same ancillary file by alias, updating the alias to point to a newer version of the ancillary will be picked up by all the configurations without the need for any further changes.

The XML syntax for ancillary file references is:

  <Ancillary_File_Type>Alias</Ancillary_File_Type>  

Configuration constants

Some precincts require numerical inputs such as the level at which to set trigger thresholds. The configuration system handles these inputs one-by-one as xml tags. It should be noted that there are only a small number of such inputs; primarily trigger discriminator levels in the CAL and ACD subsystems.

The XML format for numerical constants is:

  <Constant_Name>0.0</Constant_Name>  

Output parameters

Each precinct generates settings for one or more groups of on-instrument hardware registers. Technical considerations require register settings for each type of hardware to be handled separately. Therefore, each precinct will produce one output LATC_XML file for each hardware component which contains registers handled by that precinct. Also, if a precinct configures a hardware component with multiple instances, the precinct will generate a "broadcast'' LATC_XML file with the default settings for all instances of that hardware component.

  <latc_GRP_PREC_NAME/>  

PREC_NAME is a precinct name. Valid values of GRP are the various hardware component names: GEM, AEM, ARC, AFE, TEM, TIC, CCC, CRC, CFE, TCC, TRC, SPT, TFE, TDC. Also, "DFT'' is used to signify the broadcast or default settings and "LCI'' is used for the LCI instructions.

Offline files

In some case ConfigSystem generates files that can be used by the offline software as calibrations.

LCI vote Files

LCI configurations control charge injection runs. Most charge injection runs scan over a group of register settings; either to verify functionality, or to characterize the electronics performance of the LAT. Therefore, generating LCI configurations is primarily a matter of defining the structure of the loop iterations.

To construct an LCI run, specify:

• Type of LCI run, namely ACD, CAL, or TKR.

• Name of the analysis script used to process the run.

• Default values for the LCI parameters.

• Loop structure of the run.

To accomplish this, a compact xml syntax has been devised:

  <LCI_INTENT>
       <XXX_LCI>
        <script>ScriptName</script>
        <XXX_iterables>
          <!-- One node for each parameter not set to LATC values -->
        </XXX_iterables>
             <ci_dict/> One node for each charge injection dictionary we use.
                 <lci_loop>
          <!-- An XML tree which defines the loop structure and iteration ranges -->
        </lci_loop>
      </XXX_LCI>
    </LCI_INTENT>  

LCI parameters and iterables

LCI parameters and iterables are specified with a single XML tag. The syntax is:

  <iterable_name>value</iterable_name>  

Iterables are a special group of LCI parameters which can be iterated over in a single LCI configuration. This is an important distinction because it determines the structure of the output LCI_XML. However, the difference in the LCI_INTENT XML is minimal. The only real difference is the types of loops that are allowed for each.

Charge Injection Dictionaries

In certain scripts, to avoid iterating over the entire set of possible values, charge injection dictionaries are used to define which inner loop values to scan over for a given set of outer loop values.

Charge injection dictionaries are handled like any other ancillary files, and are always referenced to by alias; for example:

  <ci_dict dict_name='dict_name' dict_type='dict_type'
             dict_key='param_name' step_size='1'>alias</ci_dict>

LCI Loops

To define the LCI loop structure, construct an XML tree which gives the loop nesting order and describes the iteration structure of each loop. The loop nesting order is

      <lci_loop loop_id='ACD_read_range'>
         <!-- One node for each parameter which varies in this loop -->
          <listLoop param='ACD_read_range'>0:1</listLoop>
          <lci_loop loop_id='ACD_bias'>
            <!-- One node for each parameter which varies in this loop -->
            <rangeLoop param='ACD_bias'>0:7:1</rangeLoop>
            <lci_parameters number='100' period='200000' latc_delay='0'
                             delay='2' strobe='OFF' zero_suppress='OFF'/>
          </lci_loop>
         </lci_loop>  

Note: At any level of nesting any number, <lci_loop> node can be declared and will be executed in sequence.

For example, a single script may loop on <low_range_gain> with <high_range_gain> set to ``LATC'' and then perform a second loop with the roles reversed.

Loop iterations defines so far, include:

• <listLoop> loops over a colon-separated list of values. These values may be integers or may include special tags such as ``ON'', ``OFF'' or ``LATC''.

• <rangeLoop> loops over a specified range of values in even steps. We must specify the loop start, stop and step size values.

• <rangeDict> loops over a range of values taken from a charge injection dictionary.

The XML syntax for each of these loop iterations types is shown below:

  <listLoop param='param_name'>val0:val1:val2:val3</listLoop>
    <rangeLoop param='param_name'>start:stop:step</rangeLoop>
    <rangeDict param='param_name'>dictionay_name</rangeDict>  

LCI parameters can only be used in <listLoop> nodes; LCI iterables can be used in any type of loop (another way of saying that to loop over parameters, every value in the loop must be explicitly called out).

Ancillary Files

ConfigSystem handles about 20 different types of ancillary files which fall into four major classes:

• Calibrations: files generated by subsystem analysis which contain constants needed to calculate configuration settings.

• Settings: files generated by subsystem analysis which contain register settings.

• Masks: files which disable specific channels.

• Configurations: files which contain a complicated set of requests, such as per-channel threshold requests expressed in physical units. This also include "charge injection dictionaries'' which define the interesting ranges to scan over in charge injection scripts.

All the various types of ancillary files are described in the precincts by which they are used. See Ancillary File Types for a description of the XML syntax for each type of ancillary file.

Importing Ancillary Files into MOOT

In order for an ancillary file to by used by ConfigSystem it must first be imported into MOOT. Importing a file requires:

• The name and location of the file to be imported.

• The type of the file to be imported.

Ancillary file aliases

Ancillary files are referenced by alias rather than directly. Often, therefore, changing which version of a calibration in use is just a matter of manipulating the alias definitions in MOOT. (See Ancillary File Types.) (Also see Command Line Interfaces for syntax and ConfigSystem: Use Cases for examples.)

Inputs for LATC Level Configuration

Intent in building a LATC configuration is specified by providing a vote file for each precinct. As is the case for references in ConfigSystem, these are done by alias to provide an extra level of control to the user.

  <LAT_INTENT>
      <method>NORMAL</method>
      <!-- One vote per precinct, called out by alias -->
      <PREC_NAME-vote>Alias</PREC_NAME-vote>
    </LAT_INTENT>  

Products

ConfigSystem produces many intermediate outputs on the way to making a full LAT configuration. LAT configuration files sent up to the instrument are compiled binary files; hence, they are not ideally suited for human browsing. Furthermore, these files have information content identical to the input LATC_XML files, except they are grouped by hardware component instead of by precinct; it is therefore often easier to browse the parameter or vote files.

One of the jobs of MOOT is to keep track of the association between input vote and ancillary files and output parameter files Once vote and ancillary files are imported into MOOT they can not be changed. However, the vote files refer to the ancillary file by alias, and the alias can be changed. Therefore to specify a set of output parameter files for a precinct we need both the vote file and the set of ancillary files used to build those parameter files.

LATC parameter files

Each LATC precinct will produce one or more LATC_XML parameter files; in most cases, this will be one broadcast file and one file per group of hardware components with non-broadcast values. For the few singleton hardware components, we will not produce a broadcast file, only a hardware component file.

LCI parameter files

Each LCI precinct will produce one LCI_XML parameter file with the entire loop structure for the script.

LAT level configurations

In the long term this is handled by MOOT. However, it is useful to have an intermediate format to use for this purpose.

  <LPA_XML>
      <Precinct Name="PrecinctName">One node per precinct.
         <paramFile>one node per output paramter file.</paramFile>
      </Precinct>
    </LPA_XML>  

API for MOOT access

TBP