swscomp: Software Status Compiler

Contents

0.0: Invocation

swscomp [options] files

The default <prefix> is 'SWData'.

Without -A, four files are generated:

With -A, either <prefix> or <prefix>.tma is generated.

1.0: Motivation

There is a well-established convention in tmcalgo programs of using software status telemetry variables to control instrument operations. Unlike most telemetry variables, software status variables do not report the state of physical sensors. Instead, they are set under program or interactive control. Using this approach, it is possible to provide operators with very high-level control.

Setting up an instrument for this type of configuration involves:

  1. creating the tmcalgo code to implement the high-level functions (.tma)
  2. defining a telemetry variable to communicate the desired functionality (.tmc)
  3. setting up the necessary mechanisms for setting the variable (.tmc, .cmd)
  4. defining the encoding for this variable (.h)
  5. defining textual commands and mapping them to the variable's encoding (.cmd)
  6. creating a tmcalgo software status control partition to trigger the desired functions when the specified encoding is observed (.tma)

As you can see, many different input files are involved, but only the first item listed here involves truly original coding. Setting up and modifying all the other files has been a tedious process of duplicating the established convention. This is what motivated the effort to create a compiler to offload the busy work and centralize the necessary definitions. With swscomp the steps required now include:

  1. creating the tmcalgo code to implement the high-level functions (.tma)
  2. define mapping of command text to variable encoding and algorithm action. (.sws)

2.0: SWS Syntax

As you can see, the aim of the .sws file is to succinctly encapsulate selected syntaxes from several different languages into one file. There are three basic types of input lines:

2.1: Variable Definitions

SW_Variable: [ < ctype,tmtype > ] name [cmd_prefix]

This defines a variable with the specified name that can be set using the specified cmd_prefix. If the cmd_prefix is omitted, the variable's name is used instead. If the type specifications are omitted, the default is <unsigned char,UCHAR>. Both C and TMC type definitions are required because the variable will be used in both C and TMC contexts.

If no SW_Variable statement is found, the following default is used:

SW_Variable: <unisgned char,UCHAR> SWStat SW Status

It remains the responsibility of the programmer to ensure that appropriate type definitions are in place for the ctype and tmtype.

2.2: Value/Action Mappings

SWS_mnemonic value cmd_text : action

Value/Action Mappings cram a lot of details onto a single line (although the action portion can extend onto subsequent lines as well.) The easiest way to think of these lines is as a C case statement within the tmcalgo program. Everything before the colon is replaced with case SWS_mnemonic:, and everything after the colon gets copied directly. Subsequent lines that are not identified as one of the recognized sws syntax elements are also copied as part of this case statement body.

In addition to tmcalgo commands, this line includes information that goes into a header file (#define SWS_mnemonic value) and into a .cmd file ( : cmd_prefix cmd_text { $0 = value; } )

The following restrictions apply:

2.3: cmdgen definitions

Sometimes we need software status variables that serve a different purpose within the algorithm or need to communicate data that is not easily reduced to a fixed number of integer values. Since swscomp has already set up the interprocess communication required, it is handy to allow these other variable types to be supported, even though they don't have exactly the same implementation on the algorithm side.

Any line where the first non-space character is a colon is interpreted as a line from a cmdgen specification for the right hand side expansion for the value of the current SW_Variable. The basic structure is:

: cmd_text { $0 = value; }

but more complex cmdgen syntax is also possible. To specify a float value, for example:

: Set Point %f { $0 = $3; }

Note that the full command syntax will include the SW_Variable's cmd_prefix.

3.0: Build Rules

.sws files should be listed in the .spec file using the swsbase syntax:

swsbase = ToF.sws

In addition, .sws files also need to be listed explicitly as inputs to any algorithms that they reference.

Both specifications are required because although the command syntax definitions and the variable name and types definitions are global, it is entirely possible for an instrument to have more than one algorithm with independent functionality. This might be true for example when more than one physical instrument is controlled by a single processor.

A.0: Example

The following example is taken verbatim from the Wennberg Group's Time of Flight instrument:

SW_Variable: SWStat SW Status
  SWS_FLOWSTATE_OFF    1 Flow State Off: Validate Flows_OFF; break;
  SWS_TURBOS_ON       90 Turbo Pumps On:
    Validate TPA_On;
    Validate TPB_On;
    break;
  SWS_TURBOS_OFF      91 Turbo Pumps Off:
    Validate TPA_Off;
    Validate TPB_Off;
    break;
  SWS_PUMPS_ON        96 Pumps On: Validate pumps_on; break;
  SWS_PUMPS_OFF       97 Pumps Off: Validate pumps_off; break;
  SWS_INLET_PCTRL    100 Inlet Pressure Control: Validate Inlet_PControl; break;
  SWS_INLET_IDLE     101 Inlet Close: Validate Inlet_Close; break;
  SWS_INLET_LAB      102 Inlet Lab: Validate Inlet_Lab;  break;
  SWS_TOF_START      110 ToF Start: Validate ToF_start; break;
  SWS_TOF_STOP       111 ToF Stop: Validate ToF_stop; break;
  SWS_DATA_LOOP      115 Data loop start: Validate data_loop; break;
  SWS_DATA_STOP      116 Data loop stop: Validate data_idle; break;
  SWS_QUICK_SHUTDOWN 254 Shutdown Quick: Validate Quick_Shutdown; break;
  SWS_SHUTDOWN       255 Shutdown Full: Validate Shutdown; break;

SW_Variable: SWFlow SW Flow State
  : Transitioning { $0 = 0; }
  : Off { $0 = SWS_FLOWSTATE_OFF; }

SW_Variable: <float,SWStatf> InP_Pgain Inlet Pgain
  : %f (Enter Proportional Gain) { $0 = $1; }

SW_Variable: <float,SWStatf> InP_igain Inlet Igain
  : %f (Enter Integral Gain) { $0 = $1; }

SW_Variable: <signed short,V100torr_t> InPset Inlet Pressure Setpoint
  : %f (Enter Inlet Pressure Setpoint in mbar) { $0 = $1*32768/133.33; }

B.0: History

Return to Manuals Guide. Written by Norton T. Allen

last updated: Wed Aug 8 11:15 EDT 2012 webmaster@huarp.harvard.edu
Copyright 2012 by the President and Fellows of Harvard College