NOTES ON INTERNAL SOFTWARE DESIGN REVIEW MEETING OF 18 DECEMBER 1992 Larry R. D'Addario 6 January 1993 Attendees: Ed Meinfelder, Doug Varney, Larry D'Addario, Bill Shillue (part time), Dave Burgess -- Green Bank Ron Heald, Ken Sowinski -- Socorro, by telephone This was a very specialized review of certain critical software design work done since the overal project CDR on October 15, 1992. It included the design of most internal data structures, the station initialization code, the satellite geometry calculations, and the schedule dispatcher. The meeting followed fairly closely the agenda given in Appendix A. Most materials presented as handouts or viewgraphs are reproduced in Appendices B (Larry), C (Doug), D and E (Ed). (Appendices are included only with hard copies of this report.) Earlier drafts of these notes were reviewed by the participants. Comments and explanations added by them after the meeting are given in square brackets [...]. 1. Development Plan and Schedule -- Larry The overall structure of the control system was reviewed briefly, with reference to a block diagram of the environment (Fig. B-1) and the current top-level data flow diagram (B-2). The development plan was presented as a Gantt chart (B-3), leading to completion at the end of June 1993. It is expected that considerable testing, debugging, and revision will be needed in the second half of 1993. Work to be reviewed at this meeting is restricted to that scheduled to have been done since the CDR in October. [Ken -- For the project as a whole, June of 1993 seems optimistic, but possible if it is clear to all what is needed by that date. I think the first two action items (see below) must be resolved for this to be true.] 2. Internal Data Structures -- Doug A. Monitor-related data. Doug presented a design in which the monitor schedule, log schedule, checking limits, and monitor data are combined into a single structure rather than being separate. This structure is organized first by module, then by MCB address within a module, then by anomalies presently associated with a particular address (see vg1, vg5, and Figure C-1 in Appendix C). The following concerns were raised during discussion. (a) Ron - Does the monitoring/logging schedule need to be dynamically changeable? [Reply by Larry: Probably not on short time scales, but the whole thing will be kept in the Station Parameters File, so different schedules could be loaded for different purposes, e.g., test mode vs. normal mode.] (b) Ken - The plan to have the CHECK task and others access previously-acquired monitor data is like the VLA, but not like VLBA (which allows each task to communicate on the MCB independently). The plan to store monitor results as MCB data rather than in user units is also unlike the VLBA. (c) Larry - It is not clear how the checking limits can be made to depend on the current station state. Also, the design does not allow for interaction between the values at different MCB addresses. (It was not clear during the meeting whether any need for the latter exists, but the former is quite critical.) [Ken - Some examples of error checks that require examining more than one monitor point are: (1) For the VLA dewars, the quantity (He supply pressure - He return pressure) should be within certain limits. (2) Certain combinations of outdoor temperature and dewpoint are interesting enough for checker to warn about it, like DP=temp and temp.LE.0 deg C. (3) In VLA terms, you might be interested in some combination of Gated Total Power and Synch Detector voltages.] (d) [Ken -- The real issue here is discussed under E below: whether to use the VLBA code or not. The answer to this answers the first two action items and clearly sets what has to be done.] B. Station Parameters Straightforward structures were presented for the recorder parameters, pointing correction parameters, and certain geometric parameters like station coordinates and zones of avoidance. Discussion: (a) Ron - What utilities will be used to maintain the recorder parameters? VLBA station software keeps copy of structure in binary file, with a screen provided for loading, saving, editing. VLBA correlator keeps data in ASCII file, using text editor to maintain. [Doug - Our intention is to keep these in the same form as the VLBA, so that the VLBA screen can be used to maintain them.] C. Station State Doug presented a design in which the state consists of file position pointers for each of the two input files; an array of integers representing the software state; and a linked-list of MCB commands giving the last command sent to each valid address (vg3, Figure C-2). Discussion: (a) Larry - It is not clear what would be recorded in the "flags" array. (b) Larry - Which tasks will maintain this list? The DFD shows it being maintained by DISPATCHER and INITIALIZE only. It is important that the structure show the *desired* state of the station, which is not necessarily the actual state. (c) Larry - Some important information about the desired state may not be expressible as values sent via the MCB, e.g. the overall station mode, the orbit file in use, etc. These ought to be added to the structure. (d) Ed - The DISPATCHER should be able to specify the desired state at a higher level than MCB commands. (e) Ron - The design is not at all like the VLBA "observ" structure, so it cannot be substituted for the latter in VLBA "set*" and "get*" routines; thus, it seems that the latter routines must all be re-written. (f) [Ken - I almost wonder if it pays (in simplicity) to include the full state for each line of the schedule file? By "line" I mean a line in the ascii file representing the schedule. I am suggesting a schedule format that allows you to know the full station-state by examining one element in the schedule list. My impression is that it takes very little information to characterize the desired state of the station.] [Larry - I don't agree. The command ("schedule") file needs to be flexible enough to allow changing *parts* of the station, so we cannot specify the whole state on one line. Nevertheless, the point that the station state structure could be very simple may be valid.] D. Access Rules Doug plans that MONITOR will lock out access to the monitor structure during updates by use of a semaphore (vg6). LOG and STATUS will block on this semaphore, whereas CHECK will run only after being triggered by MONITOR. Discussion: (a) Ken - Is it really necessary to control access in this way? What harm will occur if, say, CHECK is running while MONITOR is updating a value? (b) Ken - If locking is needed, there are two other possible methods: task priorities and time slicing. In the latter, each task runs during an assigned interval so that access conflicts can't occur. (c) Larry - What about the station state structure? For it, an even more complicated specification is needed for exactly who can modify it. E. VLBA Code Affected Doug presented a list of VLBA data structures and the VLBA C-functions that depend on them (vg7). It appeared that nearly all of this VLBA code would not be used in the present design. The idea of the new design is to keep the executable code for monitoring and station state maintenance completely generic (i.e., it does the same thing for all modules and monitor points, and need not have detailed knowledge of how anything works) and therefore simple, with all necessary information about particular devices being kept in the data structures. Thus, although large amounts of VLBA code would not be used, the amount of new code required would be small. In spite of this, Doug pointed out that most of the VLBA functions could still be retained unchanged. [The idea here is that it would allow several important "screen" programs to be kept for operator interfaces, using the corresponding "get*" routines, even if the automatic system operates completely differently and independently.] Discussion: (a) Larry - The design is more clean and elegant than that used at the VLBA, but we have not really shown that the generic organization and processing will be flexible enough for all the hardware. (b) Ron - Although it is admitted that the VLBA approach is in some ways awkward, it has the advantage that it already exists and is working. (c) [Ken - I would suggest extending this so that MONITOR consists of a collection of chk*() calls. Then CHECK is a byproduct of MONITOR. The caller of the chk*() routines would then save the stuff returned in any structure you choose for use by LOG, STATUS, etc.] [Larry - CHECK could be a subprogram of MONITOR, as Doug has planned, but not the other way around, as Ken suggests. We want the flexibility to monitor and log things for which there is not presently a checking algorithm.] 3. Initialization Task Design -- Doug The design involves copying station geometrical parameters, recorder parameters, and pointing correction parameters from the Station Parameters file to the appropriate structures; then copying a list of MCB commands from the file to the station state structure; then sending those MCB commands from the station state structure to the hardware (vg2, vg2a). Discussion: (a) Larry - As noted earlier, it is not clear whether a set of MCB commands can properly express the desired station state, so it may also not be able to specify how to initialize the station. (b) Larry - There needs to be a provision for recovery after power failure. This needs a carefully crafted algorithm (see also discussion under Schedule Dispatcher, below). (c) [Larry - How do we know that the initialization was successful? How are errors reported?] (d) [Larry - Initialization of the addresses of MCB interfaces has been omitted.] 4. Schedule Dispatcher Design -- Ed The design is described in Appendix D. The schedule file [which should be called the "command file" in all our documentation from now on, to distinguish it from the externally-supplied schedule] is parsed according to a defined syntax, and then individual functions are called to implement each command. The design allows for macros to be defined and called, and for other command files to be referenced for inclusion. The main use of the latter would be for the definition of standard macros. The design includes provisions for special checks for restart procedures when it is first activated. Discussion: (a) There was considerable discussion of the procedures for restarting after a power failure. [Actually, this should be handled within the INITIALIZE task rather than here.] The plan (from the purple book) was to keep following the command file as long as UPS power to the computer is retained, even though other hardware is off; then to checkpoint the station state and file pointer just before computer power is lost. Upon restart, station state and file pointer are restored (if necessary), then the hardware is re-set into the specified state, then (if necessary) the command file contents are executed from the pointer to the present time. Ken - Why not forget the checkpointing, just redo everything from the beginning of file? Larry - Maybe, but BOF may not be the beginning of a run, so the state may not be well defined; it would be better to redo from the last RESET, which might be BOF or might not. We agreed to study this, and to implement whatever is simplest, with the goal of achieving automatic recovery without operator intervention. (b) Larry - Which commands are primitive and which are implemented as macros? In many cases, it could be done either way, but some things *must* be primitive, and it would be good to have a complete list of these. (c) Ron - This seems to combine the functions of "ldsked" and "newd" in the VLBA system. 5. Geometry Calculations -- Ed The design is described in Appendix E. Basically, a subset of the JPL NAIF/SPICELIB software package will be used to read and evaluate the satellite ephemeris file in real time. The satellite position and velocity will then be transformed to local coordinates of date using VLBA routines for precession, nutation and sidereal time, plus knowledge of the geographical station location. This is then transformed to the link delays and the pointing angles. Actually, the link delays are needed for two slightly different positions at any given earth station time, corresponding to the uplink and downlink, and these must be found iteratively. Tests show that two iterations are almost always enough, and that an accurate set of these calculations should take only a few milliseconds. Furthermore, cubic spline interpolation (in the two-way timing hardware) seems to be good enough that the precise calculations are needed only every 10 sec or so. For extracting the satellite ephemeris, the plan is to port a small portion of the JPL code from FORTRAN to C and to run it in real time under VxWorks. Discussion: (a) Ken -- Is it necessary to include corrections for polar motion? Is it necessary to include diurnal abberation? [I have looked into this a bit. The magnitude of polar motion is only 9 meters. If you are happy lumping this in to a general "station position error" than it need not be considered. The diurnal aberration correction is not needed to point the antenna. I think I have convinced myself that you do not need to consider this for the distance calculation, so it too is not needed.] (b) Ken -- The plan to port some of NAIF from an interactive to a real time environment, and from FORTRAN to C, seems similar to the VLBA correlator's use of CALC. It might be valuable to learn the details of how they did it. (c) Ken -- If the precise calculations are needed only every 5 to 10 sec, then perhaps they can be done off-line, avoiding the problem of porting SPICELIB to the real time system. [If these calculations are done in real time, then consider splitting them into two tasks: a slow one to run every 10 sec, and a fast one to run at 16Hz (?) for interpolation.] ACTION ITEMS: 1. Determine the additional effort required to implement code to support the newly designed data structures. Note that the present development plan assumes use of VLBA code for control of VLBA-type devices, including recorder and formatter. Exactly which VLBA code would need to be re-written? --Doug 2. Determine whether the Station State structure could be modeled after the VLBA "observ" structure, and if so whether it could be close enough to allow retaining of most hardware-specific VLBA code. --Doug 3. Create detailed plan for hardware initialization, including default states of everything. --Doug 4. Decide algorithm for restart after power failure. --Doug, Larry, Ed 5. Make a list of DISPATCHER commands that must be implemented as primitives. --Ed 6. Study the VLBA correlator's porting of CALC to a real-time environment, since there may be some useful parallels to our porting of a portion of NAIF/SPICELIB. --Ed, Larry 7. Determine whether polar motion and/or diurnal abberation needs to be included in the geometry calculations. --Larry