GSFC/NGIMS-FSW-12 Functional Requirements for CONTOUR/NGIMS CDS Low-Level Interface Flight Software PRELIMINARY Prepared By: Michael Paulkovich, Lead Software Engineer for Paul Mahaffy, Hasso Niemann, Co-Investigators NASA/GSFC Code 915 Laboratory for Planetary Atmospheres April 20, 2000 Rev 0.32 INTRODUCTION 1 Overview 1 Conventions 2 1. OPERATIONAL CONSTRAINTS 3 1.1 Application Program Interface 3 1.1.1 Function Calls and Parameters 3 1.1.2 Interrupts 3 2. SOFTWARE REQUIREMENTS 3 2.1 CDS Inputs 3 2.1.1 S/C Messages 4 2.1.2 NGIMS TCs 4 2.1.3 Common Telecommand Verification 8 2.2 CDS Outputs 8 2.2.1 Transmit TM 8 2.2.2 Transmit NPTM 8 3. DESIGN CONSIDERATIONS 9 3.1 Mutex Protocol 9 3.2 Data Dictionary 10 3.2.1 Constants 10 3.2.2 Variables 10 INTRODUCTION This document specifies the operational, environmental and functional requirements for the CDS Low-Level Interface (CDSLL) software for CONTOUR/NGIMS. Overview The NGIMS Flight Computer (FC) is a Marconi 1750A. The flight software is primarily Tartan Ada. There is 64 KW primary RAM, and 64 KW "IORAM," which is RAM that is I/O mapped and will be used for TC and TM buffers. Access to this IORAM will most likely be implemented via special functions in 1750 assembler, called by the CDSLL software. Primarily, the CDSLL software will handle the idiosyncrasies of the 1553 card and related protocol, buffering incoming messages for NGIMS high-level software to handle, and accepting outgoing messages (TM) from high-level software and outputting those messages to the 1553 interface. On the NGIMS FC, access to 1553 memory is performed via special functions that will likely be implemented in 1750 assembly and called by the CDSLL software. The CDSLL software must be self-contained and run within its own context; that is, it can't depend on any supervisory Run-Time Exec (RTE), Real-Time Operating System, or external heap or stack. The CDSLL will be called both during bootstrap operations (executing 1750 assembly code) and after boot-up (executing Ada code under the Tartan RTE). Any computer language and compiler may be chosen for the implementation as long as it satisfies the conditions and constraints set forth in this document. General requirements for coding standards include use of industry-standard and common-sense Style standards, plus: - avoidance of complex language constructs; - allocation of parametric, adaptive and tuning/calibration constants to one area of memory (AMB - adaptive memory block); - copious inclusion of comments, especially function "preambles"; - one-to-one correspondence of variable names to data names in this document (where possible). Acronyms CDS Command Data System C&UT Code & Unit Test DAC Digital-to-Analog Converter DFD Data Flow Diagram EM Engineering Model FC Flight Computer FIFO First in, First out FM Flight Model FSW Flight Software GSE Ground Support Equipment H/SIT Hardware/Software Integration Testing IP Integration Period MET Mission Elapsed Time NGIMS Neutral Gas and Ion Mass Spectrometer NPTM Non-Packetized Telemetry PROM Programmable Read-Only Memory QP Quadrupole RAM Random Access Memory ROM Read-Only Memory SC Stored Command S/C Spacecraft SCM Spacecraft Mode SDD Software Design Document SIS Software Interface Specification SW Software TC Telecommand TM Telemetry uP Micro-Processor uSeq Microsequencer Conventions Use of "Boolean." The term "Boolean" when referring to a signal type means that the data is binary (has two states). Boolean signals may take on only one of two values, but they need not be "True" and "False". They may be, for instance, On and Off, Open and Closed, Up or Down, High or Low, 1 or 0, etc. The term "toggle" used as a verb shall mean changing the value of a Boolean signal. The term "SET" shall mean the TRUE or NON-ZERO state of a boolean signal; the term "CLEAR" shall mean the FALSE or ZERO state. Signal Names. Signal (or data) names are usually shown in italics. Signal names in this document are prefixed with a one- or two-letter identifier in lower case (and followed in upper-case and with the rest of the signal name) that describes the data type, and (in the case of 2-letter identifiers) may infer certain software requirements: First identifier Description k - constant Signal has fixed value. This includes data that may be altered by AMB or patch load. v - variable Signal is formulated dynamically by software. Second identifier Description a - AMB Indicates the data must be included in the AMB table (see section 12). Signal is always a constant. (none) A two-letter prefix indicates the data is not required to reside in AMB. Parenthesis at the end of a signal name signifies that the signal is an array or pipe. This nomenclature is not intended to impose requirements on the actual data type of implementation. For instance, specification in this document of a constant may be best implemented with a variable type. When names of "external" variable signals are used (signals specified in other documents), the name in the other document is used prefixed by "v" and any spaces or odd characters are removed; sometimes the signal name is shortened. Example: vAppProcID = Application/Process ID (CCSDS). Telecommands. Telecommands (TCs), including messages from the S/C such as Time and Mode, are identified by a unique mnemonic enclosed in braces; e.g.: {MET} - the S/C message, Mission Elapsed Time. Optional Sections. When a section number or requirement number is followed by "(O)", the specified processing is optional; that is, desired but not required. Such processing shall be implemented schedule permitting. Requirement Numbering. Specific software requirements that must be implemented and verified are preceded by a "CLL-xx" designation ("CDS Low-Level"), e.g. "CLL-01" is requirement number one. 1. Operational Constraints This section specifies software operation constraints and considerations that influence decisions regarding software design, implementation, and computer language. 1.1 Application Program Interface 1.1.1 Function Calls and Parameters All CDSLL functions will be completely passive, playing a "server" role. Either the NGIMS bootstrap, or the NGIMS "Flight" (Ada) software will provide glueware and call the proper CDSLL function when required (e.g. upon 1553 message interrupts or to send TM). CDSLL need not save any registers. Any data passed in or out of CDSLL functions will be done via known addresses in RAM or IORAM. 1.1.2 Interrupts The NGIMS software (bootstrap and Ada) will handle all 1553 interrupts, set up the data inputs to CDSLL, save registers, and call the proper CDSLL function. 2. Software Requirements 2.1 CDS Inputs This section describes CDSLL processing requirements for CDS messages to NGIMS. 2.1.1 S/C Messages 2.1.1.1 MET The Mission Elapsed Time (MET) is received on 1553 sub-address R4 and must be read, validated, and distributed (made available to other software sections). CLL-01 The {MET} message shall be read from the 1553 Interface when it is made available to the FC and make it available to other software sections. The following two requirements are not in the scope of CDSLL, but in external processing: CLL-02 If the format of any of the fields within the {MET} command are erroneous [or time marches backward?], the most recent {MET} shall be discarded and software shall set vMETErrorLatch=TRUE, and vMETError=TRUE. CLL-03 If more than kaMetIntervalTol elapses between receipt of {MET} messages, software shall set vMETErrorLatch=TRUE, and vMETError=TRUE. CLL-04 kaMetIntervalTol = 4 s TBC Notes: Housekeeping for the vMETError signal is performed outside of CDSLL. Once set, the vMETErrorLatch remains set forever. 2.1.1.2 SCM TBS - Handling of the {SCM} (Spacecraft Mode) message will be similar to MET. 2.1.1.3 TZero TBS - Handling of the {TZero} (Time to closest approach) message will be similar to MET. 2.1.1.4 LOS TBS - Handling of the {LOS} (Line-of-Sight angle) message will be similar to MET. 2.1.2 NGIMS TCs NGIMS telecommands are received on 1553 sub-address R1 and must be read, validated, and distributed. 2.1.2.1 Standard TCs This section describes the requirement for processing standard (non-ALF) NGIMS TCs. The general format for Telecommands is as follows: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 vVC n/a vChecksum sp vSC vOpCode vDataWord1 vDataWord2+ (number of words dependent upon OpCode & Data Word 1 vSerialNumber vVC =Validate Command vSC = Stored Command = 0 for TCs Only the vVC, vOpCode and vChecksum fields are used directly by CDSLL. Refer to GSFC/NGIMS-FSW-05, "Contour/NGIMS Commanding" for details on commands. CLL-05 TCs shall be read from the 1553 Interface in sub-address R1 as specified in the CONTOUR 1553 Bus Specification. For each NGIMS TC received: CLL-06 If vVC (Validate Command) is SET, then: if the vChecksum field is not equal to the sum of all bits SET in all data words and the vSerialNumber word (modulo vChecksum'max arithmetic), the command shall be deemed INVALID. CLL-07 When a NGIMS command passes all validity checks, the Validate Command bit vVC shall be set = TRUE. CLL-08 When a command fails any validity check, the Validate Command bit vVC shall be set = FALSE. The Validate Command field thus serves dual purpose: At the GSE, is an indication that checksum validation shall not be performed by FSW After validation of all criteria, SET indicates command was deemed valid. 2.1.2.1.1 Telecommand Queuing CLL-09 A telecommand FIFO pipe, vTCFIFO(), shall be maintained to hold TCs, and which shall hold a number of records, each of which consists of: a command length field vCmdLength (values 0-63); a command valid field vCmdValid (1 bit); and a variable-length field vCommand( ) for the command itself (size 3-63 words) CLL-010 A method for external heterogeneous software to examine the FIFO and remove commands shall be provided, which may consist merely of making the FIFO end pointer vTcFifoLast and the array itself manually accessible by the external software. The vCmdValid may be implemented using a spare or otherwise unused common bit in the command block vCommand( ). CLL-011 The vTCFIFO() buffer shall be capable of holding up to kaTCFIFOWordMax words. CLL-012 kaTCFIFOWordMax = 640 The value for kaTCFIFOWordMax was determined by 8 TCs per major frame, max size 64 words each, plus two "pad" or "previously queued" TCs. CLL-013 Telecommand lengths vTCFIFO().vCmdLength shall be determined as follows: CLL-014 for Variable Length command {Patch}, software shall compute vCmdLength : vCmdLength = vLength field of the Patch TC CLL-015 For the {RAMDump}, {IORAMDump}, and {RawIO} commands, vCmdLength = 4 CLL-016 For the {EEPROMDump} command: vCmdLength = 5 CLL-017 for all other (valid) commands, software shall set the vTCFIFO().vCmdLength field to 3. CLL-018 The number of words vCmdLength of the command shall be pushed into the vTCFIFO() pipe in the vCommand( ) field. CLL-019 All reads and writes from the vTCFIFO() pipe shall use Mutex protocol, adjust pipe buffer metadata (pointers) appropriately, and release the Mutex. CLL-020 In all cases (pass or fail), the command shall be placed into the vTCFIFO() pipe. (See also §2.1.2.1.3, "TC Invalid.") CLL-021 If the event the command failed any check, only the first three words shall be stored in vTCFIFO(). CLL-022 Before placing any command in the buffer vTCFIFO(): CLL-023 if adding the command would have caused overflow, the command shall be discarded, and the vTCOverflow signal shall be SET. CLL-024 if it would not have caused overflow, the vTCOverflow signal shall be CLEARED and the command added. 2.1.2.1.2 TC Valid CLL-025 If all of the above tests (§10.1.3.2) pass, the command shall be placed into the vTCFIFO pipe with Mutex protocol, set vCmdValid, metadata set properly (as 10.1.3.3), pipe buffer pointer(s) appropriately, and release the Mutex. 2.1.2.1.3 TC Invalid CLL-026 If any of the above tests (§10.1.3.2) fail, the command shall still be placed into the vTCFIFO pipe with Mutex protocol, clear vCmdValid, adjust pipe buffer pointer(s) appropriately, and release the Mutex. CLL-027 For such invalid TCs, the number of words in the command may be erroneous; so a maximum of kaTCMaxLen words shall be taken from the interface and placed on the pipe. CLL-028 kaTCMaxLen = 64 TBC 2.1.2.1.4 TC Distribution CLL-029 TCs shall remain on the vTCFIFO( ) for retrieval by Command Distributor (SRD §1.2). 2.1.2.1.5 TC Ack in NPTM CLL-030 Each time a NGIMS TC is received, regardless of type (ALFs included) and regardless of validity, the vTCToggle signal shall be toggled. 2.1.2.1.6 CDS Bus Errors CLL-031 When any CDS or 1553 error occurs, the vCDSError signal shall be SET. 2.1.2.2 ALFs Application/Process ID (vAppProcID) values above 480 are used to indicate ALF word. CLL-032 For any NGIMS command where ( 480 < vAppProcID < 483 ), CDSLL shall simply pass the command to the ALF software section. 2.1.3 Common Telecommand Verification For all NGIMS telecommands, the CCSDS header shall be validated: CLL-033 If any of the following is not true, the command shall be deemed INVALID and processed as in 2.1.2.1.3: vVersionNumber = 0002 (TBC) vType = 1 (indicates TC) vSecHdrFlag = 0 vAppProcID = 48016 .. 4FF16 vGrouping = 112 vCcsdsLength = 6410 (TBC) 2.2 CDS Outputs This section describes CDSLL processing requirements for NGIMS telemetry. 2.2.1 Transmit TM TM packets are collected by the S/C from sub-address T1. Each packet is 122 words long. Software sections external to CDSLL will formulate TM packets and place them in in a FIFO buffer vTM( ) in IORAM memory using Mutex protocol, and make buffer pointers available to the Transmit TM function. The Transmit TM function will be invoked during bus quiet time as specified in the CONTOUR 1553 Bus Specification. CLL-034 When the Transmit TM function will be invoked, CDSLL shall take up to kaMaxPktXfer packets from vTM( ) and place it at sub-address T1. CLL-035 kaMaxPktXfer = 9 TBC -- Florence? 2.2.2 Transmit NPTM The 8-words of NPTM (Non-packetized Telemetry) are collected from sub-address T12 at the rate of 1 Hz with no CDS synchronization (NGIMS does not know when NPTM is collected) (TBC). Software sections external to CDSLL will formulate NPTM and then call a CDSLL function to place the NPTM block in T12. CLL-036 When the Transmit NPTM function is invoked, CDSLL shall take the 8-word vNPTM( ) block and place it at sub-address T12. 3. Design Considerations 3.1 Mutex Protocol If no built-in mutual exclusion mechanisms exist (for example, due to the heterogeneous nature of the compiler/language environment), a simple Mutex handshake can be implemented via a Locked Flag. The example below implements Mutex exclusion for two users (e.g., CDSLL writer of the TC FIFO, and the Ada reader of the FIFO), without using any RTE, built-in semaphores, or timing services. This example could be used to interface an assembly program to an Ada program. Note that if an atomic Test-and-Set mechanism is available, the interrupt disable/enable may not be needed. Manual mutex example -- Mutex data: type LockedByType is ( Nobody, Writer, Reader ); -- one of two users can access the resource LockedBy : LockedByType := Nobody ; MyLockId : LockedByType := Writer ; -- kMutexWaitMax : Integer := TBD ; -- determine experimentally; use float if needed -- in Writer: vMutexWaitCtr : Integer ; . . . vMutexWaitCtr := 0 ; DisableInterrupts ; if LockedBy = Nobody then LockedBy := MyLockId ; EnableInterrupts ; Access_Shared_Resource ; LockedBy := Nobody ; else while vMutexWaitCtr < kMutexWaitMax loop EnableInterrupts ; vMutexWaitCtr := ~+1 ; DisableInterrupts ; if LockedBy = Nobody then LockedBy := MyLockId ; EnableInterrupts ; break ; end if ; end loop ; -- see if it timed out: if LockedBy /= MyLockId then -- Mutex timeout, report error TBD ; else Access_Shared_Resource ; LockedBy := Nobody ; end if ; 3.2 Data Dictionary 3.2.1 Constants Signal type description kaMaxPktXfer int Maximum number of packets to take from vTM( ) each time the Transmit TM function is invoked kaTCFIFOWordMax int Number of words the vTCFIFO() buffer must be capable of holding kaTCMaxLen int For invalid commands, the maximum words taken from the interface and placed on the pipe 3.2.2 Variables Signal type description vAppProcID int See CCSDS document vCDSError boolean Set by CDSLL when CDS or 1553 error detected vChecksum int Checksum for telecommands vCmdLength int Computed number of words for telecommands as function of OpCode vCmdValid boolean Set by CDSLL - 1=valid, 0=invalid vCommand( ) word array Telecommand contents vGrouping int See CCSDS document vLength int Number of words in a patch command vCcsdsLength int See CCSDS document vMETError boolean Set by CDSLL when MET error detected vMETErrorLatch boolean Set by CDSLL when MET error detected vNPTM( ) word array Input to CDSLL - non-packetized telemetry array (8 words) vSecHdrFlag int See CCSDS document vSerialNumber int Serial number, last word of every TC (used in CDSLL only for checksum computation) vTCFIFO() TC array FIFO pipe containing received telecommands waiting to be fetched by other NGIMS software sections vTcFifoLast int Pointer to last command in vTCFIFO() vTCOverflow boolean Set by CDSLL when vTCFIFO() would have overflowed vTCToggle boolean Set by CDSLL each time a NGIMS TC is received vTM( ) word array Packetized telemetry FIFO pipe, input to CDSLL vType boolean See CCSDS document vVC boolean "Validate Command" - feature allows manual creation of TCs with no software tool to compute Serial Number. vVersionNumber int See CCSDS document INDEX { {EEPROMDump} · 6 {IORAMDump} · 5 {LOS} · 4 {MET} · 3 {Patch} · 5 {RAMDump} · 5 {RawIO} · 5 {SCM} · 4 {TZero} · 4 A Acknowledges · 7 ALFs · 7 B Bus Errors · 7 C CCSDS header validation · 7 D Distribution of TCs · 7 I Interrupts · 3 Invalid TCs · 6 K kaMaxPktXfer · 8 kaMetIntervalTol · 3 kaTCFIFOWordMax · 5 kaTCMaxLen · 6 M MET · 3 Mutex protocol · 6 N Non-packetized telemetry · 7, 8 NPTM · See Non-packetized telemetry. See Non-packetized telemetry T Telecommand queuing · 5 Telemetry packets · 8 V Valid TCs · 6 Validate Command · See vVC vAppProcID · 7 vCcsdsLength · 7 vCDSError · 7 vChecksum · 4, 5 vCmdLength · 5, 6 vCmdLength, in TC pipe · 5, 6 vCmdValid · 5, 6 vCommand( ) · 5, 6 vGrouping · 7 vLength, of Patch TC · 5 vMETError · 3, 4 vMETErrorLatch · 3, 4 vNPTM( ) · 8, 9 vSecHdrFlag · 7 vSerialNumber · 5 vTCFIFO() · 5, 6, 7, 9 vTcFifoLast · 5 vTCOverflow · 6 vTCToggle · 7 vTM( ) · 8 vType · 7 vVC · 4, 5 vVersionNumber · 7 GSFC/NGIMS-FSW-12 GSFC/NGIMS-FSW-12 Page 6