SOFTWARE DESIGN REVIEW OF MAY 1993 AND DOCUMENTATION STATUS L. D'Addario 12 June 1993 I. SUMMARY OF THE SOFTWARE DESIGN REVIEW A comprehensive review of the software design of the Green Bank OVLBI Earth Station was held in May 1993, including a meeting on May 13 that was attended by JPL representatives and by NRAO staff from outside the project. The review included both the real-time and offline software components, as well as all external interfaces. Not all of the design was complete, with the main omissions being in the offline software for output data; the latter has not yet been given much attention, in view of the obvious need to give higher priority to input data processing and real-time control. A large amount of progress had occurred since the limited internal review of December 1992 (see OVLBI-ES Memo No. 37) and since the Critical Design Review of October 1992 (see "Report on the Detailed Design Phase," 29 Oct 1992). The top level design of both offline programs for input data processing (the orbit data converter and the schedule converter) is now complete, and some algorithms have been prototyped. The structure of the real-time control software is now clear, with all internal data structures designed and each of the major components (schedule dispatcher, monitor/checker, antenna control, MCB communication, and timing) existing in at least a prototype form. The precise ways in which the VLBA code can be reused have been decided, and methods of code control have been adopted. The details of the current design have been described in a series of design documents, the current versions of which are attached to this memo. Further information about our system of documentation is given in section II, below. The agenda of the May 13 meeting is given in Appendix A, and a list of attendees is given in Appendix B. Most of the discussion during the meeting concerned clarifications of small details of the design. There were a few major points made on general issues: (a) There is concern about the continued lack of precise definition of some external interfaces, including the global schedule (input) file and the correlator timing corrections (output) file. The overall design attempts to isolate these definitions as much as possible, so that work on most of the system can proceed, but we are getting close to the point where final definitions will be needed. [Ulvestad] (b) We have not shown convincingly that the project can be completed on schedule with the available manpower, which seems lean compared with other software projects of similar scope. [Petrie] (c) It would be helpful to have quantitative measures for gauging progress, such as a count of new C functions required and completed. [Petrie] I want to thank Ron Heald of the NRAO staff in Socorro for spending several days in Green Bank including this meeting, resulting in valuable advise about the use of the VLBA code and the establishment of more organized methods of code sharing; and Ken Sowinski, also of NRAO in Socorro, for providing written comments on the design documents. I also thank Bob Petrie and Jim Ulvestad of JPL for attending and providing useful comments. II. DOCUMENTATION SYSTEM Here I want to summarize the existing and planned documentation of the OVLBI ES software, and to provide information on its availability outside the OVLBI group in Green Bank. Some of this information applies to hardware design documentation also. There are several levels of documentation being maintained during development, as described below. In addition, a set of Technical Manuals will be produced at the end of the project to describe the "as built" system and provide for its maintenance. The ongoing documents have the following characteristics: A. OVLBI-ES Memo Series. This series consists of informal, unrefereed contributions from anyone on subjects related to the design of earth stations for orbiting VLBI. Each contribution is distributed to a world-wide mailing list of those who have requested to be on it. Contributions from outside NRAO are accepted, and the contents need not be specific to the Green Bank station. The Green Bank staff attempts to include in this series discussions of those aspects of our design that are likely to be of interest to people outside our group. Generally, these memos are *not* definitive descriptions of design decisions and may include tentative results. Each contribution is numbered and indexed. A separate mailing list is maintained for the index only; this is intended for those who want to be kept aware of results and who may request copies of certain issues, but who do not need every one. Finally, the current index and most of the memos themselves are available over the Internet by anonymous ftp; this is done by running the ftp program on your own computer and connecting to sadira.gb.nrao.edu (192.33.116.115) with username "anonymous" and any password. You should then change directory to "ovlbi/memoseries" and get the file README for further instructions. B. Design Documents. This is a more formal series of documents which *do* represent definitive design decisions. They are specific to the Green Bank OVLBI Earth Station. At present they cover only software designs, but some hardware designs may be included in the future. Although they describe a definite design as of their issue dates, they are subject to change during development. For this reason and because of their specialized nature, they are not automatically distributed outside our group. Interested persons may request copies by sending e-mail to the responsible development team member or to me (ldaddari@nrao.edu). In addition, we intend to make copies available by anonymous ftp to sadira (as above) in ftp directory "ovlbi/doc." At the end of development, the final versions of these documents will be incorporated into the Technical Manuals. C. Technical Notes. This is a very informal memo series of mostly internal technical information that we want to have recorded for reference. It may consist of laboratory notes, test results, memoranda of discussions on technical issues, and planning papers. Again, these documents will not be automatically distributed outside the Green Bank group, but copies will be sent to interested persons upon request. However, the items will be numbered and indexed, and the index will be available by anonymous ftp (as above) in ftp directory "ovlbi/notes." The text of some memos may also be available there, but it is not likely to be as complete as the other on-line document sets. D. Source Code. The most definitive documentation of the software is contained in the code itself, in the form of commentary. All of the code is accessible over the Internet, but making it available by anonymous ftp is considered too much of a maintenance burden for now; besides, making significant use of it would require more computer privileges than we are willing to grant anonymously. Anyone outside NRAO who would like access to these files can be given an individual user account on the Green Bank computers. APPENDIX A: Meeting Agenda GREEN BANK OVLBI EARTH STATION SOFTWARE DESIGN REVIEW, 6 MAY 1993 AGENDA 0830-0930 Design Overview D'Addario 1. Top level requirements 2. Separation into real-time and non-real-time components 3. External interfaces (non-real-time components) 4. Real time control system 4.1 Operating system and environment 4.2 Hardware configuration 4.3 Top level data flow; internal data structures 4.4 Operator interface 4.5 Re-use of VLBA code 5. General issues: code control; schedule; current status 0930-1030 Input Data Processing 1. Orbit geometry calculations Meinfelder 2. Schedule conversion (off line) Langston 3. Command dispatcher (real time) Meinfelder/Langston 1030-1100 (Coffee Break) 1100-1200 Real Time Control System -- Part I 1. Initialization Varney 1.1 Normal cold start 1.2 Emergency shutdown and automatic restart 2. Timekeeping and task synchronization Varney 3. Control functions that run as separate tasks 3.1 Orbit geometry data handling task D'Addario 3.2 Antenna pointing control task D'Addario 3.3 Two-way timing control task D'Addario 1200-1300 (Lunch Break) 1300-1430 Real Time Control System -- Part II 4. Control functions that run as Dispatcher subroutines 3.1 Tape Formatter and Recorder control Varney 3.2 Front ends and downconverters control Varney 3.3 Two-way timing system setup D'Addario 3.4 Demodulator and Decoder setup Varney/Escoffier 5. Monitoring, checking, and logging task Varney 1430-1500 Output Data Processing 1. Status File (near real time) Varney 2. Timing Corrections File Langston 3. Doppler File Langston 4. Log Files D'Addario 1500-1530 (Coffee Break) 1530-1630 Questions and Discussion 1630-1730 Software Demonstrations (at 45 foot antenna) APPENDIX B: MEETING ATTENDEES Dave Burgess, NRAO Mike Balister, NRAO (Charlottesville) Larry D'Addario, NRAO Ron Heald, NRAO (Socorro) Glen Langston, NRAO Edmond Meinfelder, NRAO Bob Petrie, JPL Bill Shillue, NRAO Jim Ulvestad, JPL Doug Varney, NRAO APPENDIX C: LIST OF CURRENT SOFTWARE DESIGN DOCUMENTS Author(s) Title --------- ----------------------------------------- D'Addario "Software Overview" Langston "Off-line Scheduling Software" Varney "Initialize Function" Langston "Real-Time Command Dispatcher" Varney "Monitor and Check Task" D'Addario "Log Writer Task" D'Addario "Geometry Task" D'Addario "Pointing Task" D'Addario "Two-Way Timing Control Task" Varney, D'Addario "Status Task" Escoffier "Interface Protocol Between Decoder and Station Computer" (Copies of all of these documents can be found in directory ~ovlbi/doc or ~ftp/ovlbi/doc on the Green Bank network.)