Table of Contents Previous Chapter

30.0 System Configuration Classes (36-53238 01)

30.1 Purpose

The purpose of the System Configuration classes is to manage the suite of software-controllable hardware settings within the instrument.

30.2 Uses

The following lists the use of the System Configuration Classes:

1. Update settings within the system's table
   

2. Update DEA and FEP power selections
   

3. Load updated settings into the DEA hardware
   

4. Power off the DEA if the radiation monitor is asserted
   

5. Re-enable DEA power once the radiation monitor de-asserts
   

30.3 Organization

Figure 131 illustrates the class relationships used by the System Configuration Classes. These class include the SysConfigTable class, which maintains the current list of settings, the SystemConfiguration class, which is a task which reloads settings into the hardware and monitors the radiation flag, and the RadCallback class, which the SystemConfiguration class uses to obtain control during Radiation Monitor interrupts.

FIGURE 131. System Configuration Class Relationships

SysConfigTable- This class represents the collection of system configuration parameters within the instrument. It provides a function which modifies an entry in the table (changeEntry), and provides a function which returns the address and length of the table for purposes of dumping the table to telemetry (getTableInfo). This class provides services used by the SystemConfiguration class to get the desired power settings for each of the DEA and FEP boards (getDeaPowerEnable, getFepPowerEnable), and to fetch a desired DEA register setting from the table (getDeaSetting).

SystemConfiguration- This class is a subclass of Executive::Task, and is responsible for maintaining the hardware configuration settings and reacting to the radiation monitor. This class provides a main task entry function (goTaskEntry) and a public function used to inform it when the radiation monitor is asserted (radiationAsserted).

RadCallback- This class is a subclass of Devices::DevCallback, and is used by the SystemConfiguration class to obtain control when the radiation monitor interrupt occurs. This class provides a single function which is invoked by the RadDevice's interrupt handler (invoke).

Task- This class is supplied by the Executive class category. It represents and controls an active running task. The SystemConfiguration class inherits from this class, and uses the class's functions to relinquish control for a period of time (sleep), and to detect queries from the TaskMonitor (requestEvent).

RadDevice- This class is supplied by the Devices class category and is a subclass of IntrDevice. It is responsible for providing access to the radiation monitor flag (isAsserted) and handle radiation monitor interrupts.

IntrGuard- This class is supplied by the Devices class category and is responsible for disabling and re-enabling interrupts.

TaskMonitor- This class is supplied by the Executive class category, and is responsible for periodically polling each task in the instrument. When polled, the SystemConfiguration task responds using this classes member function (respond).

DeaManager- This class is supplied by the Protocols class category, and is responsible for arbitrating access to the DEA hardware interface. The SystemConfiguration class uses this class to disable power to the DEA boards (powerOff), to query the current power state of the boards (hasPower), to enable power to the boards (powerOn), and to write to the board control and D/A registers (setRegister).

FepManager- This class is supplied by the Protocols class category, and is responsible for managing access to the Front End Processors. The SystemConfiguration class uses this class to query the current power state of each of the FEPs (hasPower), to disable power to a FEP (powerOff), and to power on a FEP and load a default program (loadRunProgram).

ScienceManager- This class is supplied by the Science class category, and is responsible for managing overall science processing. The SystemConfiguration class uses this class to detect when a science run is complete (isIdle), and to abort a run in-progress and inhibit further runs (inhibit).

IntrDevice- This class is supplied by the Device class category, and is used by the SystemConfiguration class to install the Radiation Monitor's interrupt callback.

DevCallback- This class is supplied by the Device class category and is responsible for defining the common interface to all interrupt callback classes.

30.4 Scenarios

30.4.1 Overall SystemConfiguration task operation

The SystemConfiguration task consists of a main polling loop, contained within goTaskEntry(), and uses an interrupt callback, RadCallback, to determine when the radiation monitor is asserted. Interrupt processing is needed to detect cases when the radiation monitor is asserted for times shorter than the polling period of the task, and would otherwise be missed if the polling loop alone was used to detect monitor assertions.

Figure 132 illustrates the main operations performed on each iteration of this loop, and the interactions with the Radiation Monitor interrupt.

FIGURE 132. SystemConfiguration task polling loop

1. During system initialization, the system start-up routines invoke the constructor for the systemConfiguration object. This constructor initializes the state of the object, and installs the radCallback object as the interrupt callback for the radiation monitor device, using radDevice.installCallback().
   

2. Once all of the system objects have been initialized, and the executive is started, the executive starts the systemConfiguration task using systemConfiguration.goTaskEntry(). The task function goTaskEntry() then enters its infinite polling loop.
   

3. At the top of its loop, goTaskEntry() calls sleep() to allow other tasks to run.
   

4. It then checks for, and responds to queries from the taskMonitor, and checks the current state of the radiation monitor using checkMonitors().
   

5. Meanwhile, assume that the radiation monitor is asserted. This causes an interrupt on the Back End Processor. The interrupt results in the intrController object invoking the handler for the monitor, using radDevice.handleInterrupt().
   

6. radDevice.handleInterrupt() clears the interrupt cause, and invokes the installed callback, using radCallback.invoke().
   

7. radCallback.invoke(), in turn, tells the systemConfiguration object that the monitor triggered, using systemConfiguration.radiationAsserted().
   

8. The task then detects the assertion of the monitor, and tells science to end its current run and delay the start of any subsequent runs until the radiation condition subsides, by passing BoolTrue to scienceManager.inhibit().
   

9. The task then shuts off power to all of the DEA's CCD-controller boards, using powerOffDea().
   

10. If the radiation monitor is not asserted, the task's polling loop checks to see if science is in the middle of a run, using scienceManager.isIdle().
    

11. If science is idle, the task then updates any changes to the power settings or DEA register settings using updateDeaPower(), updateFepPower() and updateSettings(), respectively.
    

30.4.2 Use 1: Update settings within the system's table

To modify an entry in the system configuration table, the client passes the entry index and value to sysConfigTable.changeEntry(), which then modifies the indexed value and sets the corresponding changed flag to BoolTrue. Later, the systemConfiguration task will pick up the modification, and adjust the corresponding DEA hardware setting or power selection as described in the subsequent scenarios.

30.4.3 Use 2: Update DEA and FEP power selections

Figure 133 illustrates the case where the SystemConfiguration updates the DEA power settings.

FIGURE 133. Update DEA Power Settings

1. The main polling loop of the systemConfiguration task determines that the radiation monitor is off and science idle. It takes the opportunity to update any DEA power settings which have changed by calling updateDeaPower().
   

2. updateDeaPower() consists of two loops. The first loop powers off any DEA boards which have been disabled. The second loop then powers on and re-loads the settings of any boards which have been enabled. At top of each loop iteration, updateDeaPower() calls checkMonitors() to ensure that the taskMonitor and radiation monitors are responded to in a timely fashion.
   

3. checkMonitors() first checks to see if a query from the taskMonitor is outstanding, using the inherited function, Task::requestEvent().
   

4. If a query is pending, checkMonitors() replies to the query using taskMonitor.respond().
   

5. checkMonitors() then checks to see if the radiation monitor is active by calling isRadiationOn() (not shown). isRadiationOn() then calls radDevice.isAsserted() to test the hardware radiation monitor flag. If the flag is asserted, then checkMonitors() returns, indicating that the current update operation should be aborted. If the radiation monitor is inactive, then the current operation may proceed. Assume for the remainder of the scenario that the monitor is inactive.
   

6. updateDeaPower() then obtains the desired power setting for a DEA board using sysConfigTable.getDeaPowerEnable().
   

7. updateDeaPower() then compares this with the current power state of the board, as indicated by deaManager.hasPower().
   

8. If the configuration indicates that the board should be off, but it is on, updateDeaPower() shuts off power to the board using deaManager.powerOff().
   

9. Once all of the boards which should be off have been disabled, updateDeaPower() checks for boards which should be turned on. If a board's power is off when it should be on, updateDeaPower() enables power to the board using deaManager.powerOn().
   

10. Whenever a board is powered on, updateDeaPower() then calls reloadSettings(), to load all of the desired register settings into the newly powered-on board.
    

11. reloadSettings() gets the desired register setting for the board using sysConfigTable.getDeaSetting().
    

12. reloadSettings() the loads the value into the board using deaManager.setRegister().
    

The scenario for powering FEPs is similar to the above scenario except that the there are no settings to load, the desired power settings are obtained using sysConfigTable.getFepPowerEnable(), and the queries and power control functions (hasPower, powerOff, powerOn) are issued to the fepManager, rather than the deaManager. Since changes in FEP power are driven by power-consumption and thermal concerns, power settings to the FEPs are always updated, regardless of the state of the radiation monitor or the state of science processing.

30.4.4 Use 3: Load updated settings into the DEA hardware

Figure 134 illustrates the steps used by the SystemConfiguration class to update modified register settings in the DEA boards.

FIGURE 134. Load updated DEA settings

1. The systemConfiguration's polling loop calls updateSettings() to update any DEA register values which have changed. updateSettings() enters two nested loops. The outer loop iterates through each DEA board, and the inner loop iterates over each board register.
   

2. Meanwhile, a client object may make changes to the collection of settings using sysConfigTable.changeEntry(). If a change is made to a setting prior to it being processed by updateSettings(), it will be loaded into the hardware on this invocation of updateSettings(). If, however, a change is made after it has been passed over by updateSettings(), it won't be loaded into the DEA until the next iteration of the systemConfiguration task's polling loop.
   

3. At the start of each iteration of the inner board register loop, updateSettings() calls checkMonitors() to respond to queries from the taskMonitor, and to check if the radiation monitor has been asserted. If the radiation monitor has been asserted, updateSettings() aborts its update process and returns to its caller. If not, it proceeds to update the next register setting.
   

4. updateSettings() obtains the desired value for a given DEA board's register, whether or not is used by the hardware, and whether or not the desired setting has changed since the last update, using sysConfigTable.getDeaSetting().
   

5. If the register setting is used, and has changed, updateSettings() loads the value into the DEA board using deaManager.setRegister().
   

30.4.5 Use 4: Power off the DEA if the radiation monitor is asserted

Figure 135 illustrates the steps used by the SystemConfiguration class to shutdown the DEA when the radiation monitor has been asserted.

FIGURE 135. DEA shutdown due to radiation monitor assertion

1. When the systemConfiguration task's polling loop detects that the radiation monitor has gone off, it instructs the scienceManager to stop its current run, and delay the onset of any subsequent runs, by passing BoolTrue to scienceManager.inhibit().
   

2. It then shuts off power to all of the DEA's CCD-controller boards using powerOffDea().
   

3. powerOffDea() iterates through each board. At top of each iteration, powerOffDea() calls checkMonitors() to respond to any queries from the taskMonitor. Since it already knows that the radiation monitor has been asserted, powerOffDea() ignores the return value from checkMonitors().
   

4. powerOffDea() then shuts off power to each DEA CCD-controller using deaManager.powerOff().
   

30.4.6 Use 5: Re-enable DEA power once the radiation monitor de-asserts

Once the radiation monitor subsides for a long enough period of time, the systemConfiguration's polling loop calls updateDeaPower() and updateSettings() to power on all of the required DEA boards and re-load their settings (see Section 30.4.3 and Section 30.4.4).

30.5 Class SysConfigTable

Documentation:

This class acts as a repository for the system configuration settings.

Export Control:

Public

Cardinality:

n

Hierarchy:

Superclasses:

none

Public Interface:

Operations:

changeEntry()
getDeaPowerEnable()
getDeaSetting()
getFepPowerEnable()
getTableInfo()

Protected Interface:

Operations:

getSetting()

Private Interface:

Has-A Relationships:

Boolean inuseMap[256]: This is an array of in-use flags indicating whether a particular DEA CCD-controller board register is used by the hardware or not. The array is indexed by register index. If an entry is BoolFalse, then the corresponding setting is not used by the system. If an entry is BoolTrue, then the setting entry is valid.

Boolean settingChanged[2560]: This is an array of flags which indicate which values have been changed since the last read. BoolFalse indicates that the value hasn't changed since the last query, and BoolTrue indicates that the value has changed. (TBD: use bit-field)

unsigned short setting[2560]: This is the array of configuration setting values.

Concurrency:

Guarded

Persistence:

Persistent

30.5.1 changeEntry()

Public member of:

SysConfigTable

void

Arguments:

unsigned item
unsigned value

This function modifies the configuration entry, setting the entry indicated by item to the passed value.

Concurrency:

Synchronous

30.5.2 getDeaPowerEnable()

Public member of:

SysConfigTable

Boolean

Arguments:

DeaBoardId boardid

This function returns whether or not the DEA board, indicated by boardid, is configured to be powered on. If the board should not be powered on, this function returns BoolFalse. If the board should be powered on when the radiation monitor is not active, the function returns BoolTrue.

Concurrency:

Synchronous

30.5.3 getDeaSetting()

Public member of:

SysConfigTable

Boolean

Arguments:

DeaBoardId boardid
unsigned regid
unsigned short& value
Boolean& changed

This function reads the desired setting for the DEA board register. The board is indicated by boardid, and the register setting is indexed by regid. The function returns the desired setting in the value and resets the changed flag corresponding to the entry. If the value has changed since the last call, the function sets changed to BoolTrue. If the value hasn't changed since the last time it was fetched, changed contains BoolFalse. If the register is not used by the DEA hardware, the function returns BoolFalse. If it is a valid hardware register, it returns BoolTrue. (NOE: This scheme is to allow for late changes to the DEA register settings without impacting the software design).

Concurrency:

Synchronous

30.5.4 getFepPowerEnable()

Public member of:

SysConfigTable

Boolean

Arguments:

FepId fepid

This function indicates whether or not the FEP, indicated by fepid, should be powered on. If the function returns BoolFalse, the FEP should be off. If the function returns BoolTrue, the FEP should be powered on and have code loaded and running.

Concurrency:

Synchronous

30.5.5 getSetting()

Protected member of:

SysConfigTable

void

Arguments:

unsigned item
unsigned short& value
Boolean& changed

This function reads and resets the changed flag for the indicated item. The fetched item is returned in value. If the value has changed since the last time it was fetched, the function sets changed to BoolTrue, otherwise, changed contains BoolFalse.

Concurrency:

Synchronous

30.5.6 getTableInfo()

Public member of:

SysConfigTable

void

Arguments:

const unsigned*& addr
unsigned& wordcnt

This function returns the address and word length of the system configuration table. Upon return, addr points to the start of the system configuration table, and wordcnt contains the number of 32-bit words in the table.

Concurrency:

Synchronous

30.6 Class SystemConfiguration

Documentation:

This class manages the system configuration of the instrument. It is responsible for monitoring the radiation flag, maintaining the power settings to the DEA and FEP, and updating DEA register settings.

Export Control:

Public

Cardinality:

n

Hierarchy:

Superclasses:

Task

Implementation Uses:

SysConfigTable
RadDevice
TaskMonitor
FepManager
DeaManager
ScienceManager
IntrGuard

Public Interface:

Operations:

SystemConfiguration()
goTaskEntry()
radiationAsserted()

Protected Interface:

Operations:

checkMonitors()
enableScience()
isRadiationOn()
powerOffDea()
reloadSettings()
updateDeaPower()
updateFepPower()
updateSettings()

Private Interface:

Has-A Relationships:

const unsigned radiationBaseCnt: This contains the number of polling iterations needed to ensure that the radiation monitor is off.

const unsigned pollSleep: This contains the number of ticks the task should sleep on each iteration.

Boolean radiationAssertFlag: This flag indicates that the radiation monitor has been asserted. It is set by calls to radiationAsserted() and is cleared when the task's polling loop disables power to the DEA boards.

unsigned radiationPollCnt: This is the current number of polling iterations remaining to ensure that the radiation monitor is off.

Concurrency:

Active

Persistence:

Persistent

30.6.1 SystemConfiguration()

Public member of:

SystemConfiguration

Arguments:

unsigned taskid

This is the constructor of the system configuration class. taskid is the RTX task id to use for the task. This function's initializers first initialize the parent Task. It then initializes its instance variables.

Concurrency:

Sequential

30.6.2 checkMonitors()

Protected member of:

SystemConfiguration

Boolean

This function polls the radiation monitor and the task monitor. If the task monitor is querying the task, the function responds to the query. If the radiation monitor has been off for long enough, the function returns BoolFalse. If the monitor is on, or was de-asserted too recently, the function returns BoolTrue.

Concurrency:

Synchronous

30.6.3 enableScience()

Protected member of:

SystemConfiguration

void

This function enables science activities if the radiation monitor is not active.

Concurrency:

Synchronous

30.6.4 goTaskEntry()

Public member of:

SystemConfiguration

void

This is the main loop of the system configuration task. This loop sleeps for pollSleep timer ticks. It then processes taskMonitor queries, changes to the radiation monitor flag, and updates any changed power or board settings, if allowed by the radiation monitor and science.

Concurrency:

Synchronous

30.6.5 isRadiationOn()

Protected member of:

SystemConfiguration

Boolean

This function polls the radiation monitor. If the monitor is asserted, or if the system is waiting for it to remain de-asserted for the required period, the function returns BoolTrue. If the monitor has been off for long enough, the function returns BoolFalse.

Concurrency:

Synchronous

30.6.6 powerOffDea()

Protected member of:

SystemConfiguration

void

This function shuts down power to all of the DEA's CCD-controller boards.

Concurrency:

Synchronous

30.6.7 radiationAsserted()

Public member of:

SystemConfiguration

void

This function informs the class that the radiation monitor has been asserted. This function may be called by an interrupt callback.

Concurrency:

Synchronous

30.6.8 reloadSettings()

Protected member of:

SystemConfiguration

Boolean

Arguments:

DeaBoardId boardid

This function reloads all settings to the DEA board indicated by boardid. If it completes, the function returns BoolTrue. If the operation is aborted by the radiation monitor, it returns BoolFalse.

Concurrency:

Synchronous

30.6.9 updateDeaPower()

Protected member of:

SystemConfiguration

Boolean

This function tests DEA power, first shutting down all boards which should be turned off, and then powering on and re-loading settings to boards which should be powered on. This function returns BoolTrue if successful, and BoolFalse if it was aborted by the radiation monitor.

Concurrency:

Synchronous

30.6.10 updateFepPower()

Protected member of:

SystemConfiguration

Boolean

This function updates the power settings of the FEPs. It first powers down all FEPs which should be off, and then powers on and runs the default FEP program on all FEPs which should be powered on. This function returns BoolTrue if it completes, and BoolFalse if it was aborted by the radiation monitor.

Concurrency:

Synchronous

30.6.11 updateSettings()

Protected member of:

SystemConfiguration

Boolean

This function updates any settings which have changed in any of the powered DEA boards. It returns BoolTrue if it completes, and BoolFalse if it is aborted by the radiation monitor.

Concurrency:

Synchronous

30.7 Class RadCallback

Documentation:

This is the interrupt callback used by the System Configuration to detect when the radiation monitor is asserted.

Export Control:

Public

Cardinality:

n

Hierarchy:

Superclasses:

DevCallback

Implementation Uses:

SystemConfiguration

Public Interface:

Operations:

invoke()

Concurrency:

Synchronous

Persistence:

Persistent

30.7.1 invoke()

Public member of:

RadCallback

void

Arguments:

IntrDevice* device

This function is invoked by the Radiation Monitor interrupt handler. It tells the System Configuration task that the monitor was asserted using systemConfiguration.radiationAsserted().

Concurrency:

Synchronous

Table of Contents Next Chapter