Table of Contents Previous Chapter ACIS

7.0 Command Management

7.1 Overview

This section describes the preliminary design of the ACIS Back End command processing software. This section first describes the discrete command flags interpreted by the software. It then describes the serial digital command packets interpreted by the software. This section then describes the overall command reception, execution, logging, and echoing participants and scenarios.

Figure 8 lists the ACIS commands according to the features listed in the ACIS Science Instrument Software Requirements Specification. All hardware discrete commands are preceded with "Discrete-." The remaining commands are delivered as Command Packets.

FIGURE 8. Commands Grouped by System Feature

7.2 Discrete Commands

The ACIS instrument software is directly affected by the following discrete commands to the ACIS hardware:

The format of these commands is defined in the ACIS DPA Hardware Specification and System Description.

7.2.1 Reset Command

When the DPA hardware receives a reset command, it restarts the Back End Processor. The Back End Processor then executes the instructions located at its Reset Vector, contained in the Back End's Boot ROM. This code then branches to the main Boot ROM code, which then loads and executes code from either the Command Interface or from the BEP Software ROM.

If the "Boot Mode Modifier" flag is asserted, the Boot ROM loads and executes code from a "Start Load From Uplink" command and possibly a series of "Continue Load From Uplink" commands (if the load didn't fit within the initial "Start Load From Uplink" command) provided via the Command Interface.

If the "Boot Mode Modifier" flag is de-asserted, the Boot ROM loads and executes code from the Back End Processor's Software ROM. The physical interface and software layout of this ROM is TBD.

7.2.2 Set Boot Mode Modifier

When the DPA hardware receives a "Set Boot Mode Modifier" hardware command, it asserts the "Boot Mode Modifier Bit" in a TBD software-readable status register. Upon reset, the Back End's Boot ROM reads this bit, and proceeds to load and execute code from the Command Interface.

7.2.3 Clear Boot Mode Modifier

When the DPA hardware receives a "Clear Boot Mode Modifier" hardware command, it de-asserts the "Boot Mode Modifier Bit" in a TBD software-readable status register. Upon reset, the Back End's Boot ROM reads this bit, and proceeds to load and execute code from the Back End's Software ROM.

7.2.4 Set Radiation Monitor Flag

When the ACIS hardware receives a "Set Radiation Monitor Flag" command, it asserts a Radiation Monitor bit in a TBD software-readable status register and (TBD) causes an interrupt. When the Back End software reads the status register and tests the bit, it proceeds to command the DEA to disable power to the CCDs. It then proceeds to poll the bit. Once the bit is cleared, via "Clear Radiation Monitor Flag," and remains cleared for a period of time, the Back End software issues another command to the DEA to re-enable power to the CCDs.

7.2.5 Clear Radiation Monitor Flag

When the ACIS hardware receives a "Clear Radiation Monitor Flag" command, it de-asserts the Radiation Monitor bit in a TBD software-readable status register. This command only has an effect on the software if the Radiation Monitor was previously asserted (see Section 7.2.4).

7.3 Command Packets

7.3.1 Command Packet Definitions - Class "Command Packet Buffer"

The Back End software receives all serial digital commands in the form of Command Packets. All Command Packets consist of a series of 16-bit words, and have the form shown in Table 20.

TABLE 20. Command Packet Format

Word #        Field       Values             Description                                             
0             Length      3 - 256            This field indicates the total number of 16-bit words   
                                             in the Command Packet, including the "Length"           
1             Packet      0 - 65,535         This field contains a number, assigned by the           
              Identifier                     packet's originator, which is used by the software      
                                             when referring to the command in telemetry.             
2             Opcode      1 -TBD,            This field instructs the Back End software to perform   
                          The values 0 and   an action, and identifies the format of the remainder   
                          65535 are          of the packet.                                          
                          reserved for test                                                          
3 - "Length"  Data        Depends on         The remainder of the packet contains the data man       
                          Opcode             dated by the "Opcode."                                  

The Back End software encapsulates this representation in a module or class known as a "Command Packet Buffer." Access to the fields of a command packet buffer are provided using functions as listed in Table 21. Some of these functions may be implemented "in-line" for speed.

TABLE 21. `Command Packet Buffer'Operations

Operation                   Inputs  Outputs                                                   
Get Packet Buffer Address   none    The address of the packet's buffer. This buffer will be   
                                    large enough to contain the largest packet size.          
Get Packet Word Count       none    The total length of the packet in 16-bit words            
Get Packet Sequence Number  none    The contents of the packet's identifier field             
Get Packet Opcode           none    The contents of the packet's Opcode field                 
Get Packet Data Length      none    The length, in 16-bit words, of the data portion of the   
Get Address of Packet Data  none    The address of the "data" portion of the packet           
Test for Valid Packet       none    Sanity checks the packet's Length and Opcode fields.      
                                    The operation returns an error condition if either is     
                                    out of range.                                             

7.4 Command Reception and Execution

7.4.1 Overview

Figure 9 illustrates the overall command processing scenario.

FIGURE 9. Command Processing Overview

7.4.2 Command Processing Management - Class "Command Manager"

The Back End software manages all command execution using a "Command Manager" class. During its initialization, the "Command Manager" class installs its own callback function in the "Command Device" using the "Install Command Callback" feature of the device (see Table 6, "`Command Device' Operations," on page 32). When a command packet arrives, the device's interrupt handler calls this installed callback function. The callback then acquires the device status. If a packet has arrived, the callback function obtains a Command Packet Buffer and reads the Command Packet from the device into the buffer. If the callback was invoked due to a change in the Radiation Monitor status, it synthesizes an internal command packet, containing an internal opcode representing a Radiation Monitor command. The callback then enqueues the address of the Command Packet Buffer onto the "Command Manager's" command queue. Once the callback returns and the interrupt handler returns, the Command Manager is scheduled. The task then reads the packet address from its queue, and proceeds to handle the command.

When handling a command, the Command Manager first opens an entry in the "Command Log." When in verbose mode, the "Command Log" is also responsible for "echoing" the command to the telemetry stream. Once the log is open, the Command Manager invokes the "Command Handler" operation specified for the packet's Opcode. The "Command Handler" then checks the validity of the command's data and proceeds to perform the requested operation. Once the "Command Handler" returns, the Command Manager closes the command's log entry and releases the "Command Packet."

The Command Manager provides the public operations shown in Table 22.

TABLE 22. `Command Manager'Operations

Function                             Inputs                                    Outputs        
Initialize                           Address of "Command Device" to use for    none           
(This operation must be invoked      input.                                                   
before starting the RTX scheduler)   Address of "Command Log" to use for                      
                                     command logging and echoing.                             
                                     Address of a fixed length collection of                  
                                     "Command Handlers"                                       
Command Manager's Main Task          none                                      never returns  
Function (invoked by RTX scheduler)                                                           

7.4.3 Command Execution - Class "Command Handler"

All of the Opcode-specific operations concerning a command are handled by "Command Handlers." All "Command Handlers" are invoked as part of the "Command Manager" task. All "Command Handlers" provide the operations listed in Table 23.

TABLE 23. `Command Handler'Operations

Function        Inputs                         Outputs                          
Initialize      none                           none                             
Handle Command  Address of a "Command Packet"  Result of the command execution  

7.4.4 Command Logs - Class "Command Log"

Whenever the "Command Manager" is about to execute a command, it tells the "Command Log" to open an entry for the command, passing the address of the "Command Packet" about to be executed. Once the "Command Handler" has finished with the command, the "Command Manager" instructs the log to close the open entry.

When an entry is opened, the "Command Log" copies the identification information from the passed "Command Packet" into the entry. If the system is in "Verbose Mode," the Command Log attempts to echo the "Command Packet" to the telemetry system. It then returns to its caller.

When commanded to close the entry, the "Command Log" records the disposition of the command in the log's entry, and then marks the entry as closed.

The Command Log provides the operations shown in Table 24.

TABLE 24. `Command Log'Operations

Function              Inputs                                       Outputs                            
Initialize            none                                         Registers "Command Han             
(This must be                                                      dlers" for Set Verbose Mode,       
invoked before start                                               Set Terse Mode, and Dump           
ing the RTX sched                                                  Command Log (TBD) with             
uler)                                                              the "Command Manager"              
Open Entry            Address of a "Command Packet"                none                               
Close Entry           Address of the open "Command Packet"         none                               
                      and the execution disposition code for the                                      
Set Verbose Mode      none                                         none                               
Set Terse Mode        none                                         none                               
Telemeter Log         TBD                                          Posts a telemetry packet con       
                                                                   taining a list of Command          
                                                                   entries added since the last log   
                                                                   was sent                           

Table of Contents Next Chapter