Table of Contents Previous Chapter ACIS

31.0 DEA Housekeeper (36-53221 02)

31.1 Purpose

The DEA Housekeeper function provides the capability to acquire the contents of a specific set of DEA registers at a prescribed interval rate.

31.2 Uses

  1. Start DEA Housekeeping

  2. Acquiring the selected DEA register values

  3. Stop DEA Housekeeping

31.3 Organization

Figure 148 illustrates the relationship between the classes used by the DEA Housekeeper.

FIGURE 148. DEA Housekeeping Class Relationships

The DEA Housekeeper uses the Executive and Protocols class categories.

DeaHousekeeper - This class is a subclass of Executive::Task. It is responsible for accumulating and delivering DEA Housekeeping data as specified in the referenced parameter block, from the receipt of a start command until receipt of a stop command.

Tf_Dea_Housekeeping - This class encapsulates the representation of a DeaHousekeeper telemetry packet. It is a subclass of Protocols::TlmForm.

Pblock - This class is responsible for manipulating the contents of a parameter block; extracting fields and verifying the block. It is a member of protocols class category.

PbDeaHouse - This class encapsulates the representation of a parameter block. It is a subclass of Protocols::Pblock.

DeaManager - This class is responsible for interaction with the DEAs, when requested to acquire specified housekeeping data. It is a member of Protocols class category.

PblDeaHouse - This class is responsible for loading, maintaining, and delivering the sets of parameter blocks. It is a subclass of Protocols::pBlockList.

TaskMonitor - This class (not shown) is a subclass of Executive::Task. It interrogates each thread in turn, verifying that it is functioning. Failure to respond will cause a watchdog reset.

notify and waitForEvent and requestEvent - These are functions of Executive::Task inherited by the DeaHousekeeper. They provide the connectivity between the clients request via the housekeeper public functions and the threads main process.

SystemClock - This class (not shown) provides the BEP tick count which is included in the telemetry Packet. It is a subclass of Executive.

The entire command which loads the DEA Housekeeping Parameter Block will be stored into the block.

The block will contain: a command packet header, a DEA housekeeping header, and a set of target identifiers. The command packet header consisting of: message length, packet identifier, and an op-Code. The DEA housekeeping header contains, the slot index, the parameter block identifier, the block CRC, and the data sampling rate. This is followed by a series of one word target identifiers which indicate the board and the register to interrogate for housekeeping data.

31.4 Scenario

The notify function communicates the client's request to the DEA Housekeeper thread. There are three states to control the next action; START, SAMPLE, and STOP. The start request will obtain a verified parameter block, set nextAct to START and notify the thread. When the idle thread receives the notification it will establish housekeeping according to the block delivered, set the state to SAMPLE, and proceed, continuing housekeeping, until notified of a change in state. If currently sampling, it will restart. A stop request will verify the current block, set the state to STOP, and notify the thread.

31.4.1 Use 1:: Start DEA Housekeeping

Figure 149 illustrates the initiation of the DEA housekeeping process.

  1. To begin a DEA housekeeping run, the client must provide the slot index from which the parameter block will be extracted for the run, and the command Id from the packet header which is to be echoed in the telemetry identifying the instigating agent for the action. Then it must engage this tasks public function startRun to start DEA housekeeping.

FIGURE 149. Start DEA Housekeeping

  1. When a client requests that a run be started, an instance of PBlock is created. startRun will acquire a copy of the designated block using PblDeaHouse::getBlock. After copying the block, getBlock performs a CRC check on the copy, returning BoolFalse if it can not deliver a valid copy. If a block is not delivered, startRun returns CMDRESULT_BAD_LOAD to the client and the request is not forwarded. The PBlock instance holds the copy.

  2. The current state of the thread is checked. Should the thread be executing a prior run request, a missed stop command is assumed. In that case the START state will cause a termination of the current run and initiation of the requested run. startRun will set the return argument to CMDRESULT_ALREADY. In this event, the last data-point in the current packet may reference the new parameter block. The client has the responsibility to convey this possibility. If the current state of the thread is stopped, the process will set the nextAct to START and set the return argument to CMDRESULT_OK. In either case, the startRun function will send a notify request to the thread before returning.

31.4.2 Use 2:: Acquiring DEA Housekeeping Data

Figure 150 illustrates the acquisition of the DEA housekeeping process.

  1. The main thread of this task, goTaskEntry, is initiated during BEP start-up. It consists of a forever loop in which the task idles in waitForCommand using the inherited waitForEvent while waiting to call TaskMonitor::respond to answer the TaskMonitor::query (neither shown) or to the notify sent by the startRun or stopRun public functions indicating that a request has been received and awaits proper action. Receipt of a startRun request causes the task to enter a loop in which it calls (or recalls) doHousekeeping whenever the START state is set (or reset).

  2. In doHousekeeping, the process sets nextAct to SAMPLE.

  3. The DEA header values, block Id and sample rate, are extracted from the parameter block using getBlockId and getSampleRate, and the item count is returned by getItemCount.

  4. It then enters a loop which it exits only when a new notify request is detected. It creates an instance of the DEA telemetry packet, Tf_Dea_Housekeeping. Then it enters waitGetPacket to obtain a packet buffer using the packet instance's waitForBuffer which it inherits through TlmForm. waitGetPacket. It will use requestEvent to check for a notify message. It will respond to a taskMonitor::query (not shown), and will return BoolFalse (no packet buffer) if notified of a new request from the DeaHousekeeper public functions startRun or stopRun. As the result of a new request, doHousekeeping will return to goTaskEntry. Obtaining the packet buffer, waitGetPacket returns BoolTrue.

  5. Getting the time reference from systemClock::currentTime (not shown), doHousekeeping will install the time and the command and block Ids into the DEA Header of the packet using functions provided by the packet instance. They are: put_timer_Tick, put_Command_Id, and put_Parameter_Id.

  6. The function drops into a loop in which it obtains the target indicators; the board index, and the register index. They are extracted from the parameter block using get_Board_Id, and get_Query_Id respectively.

  7. It uses the deaManager::queryDea to obtain the targeted register value, providing a default value if there is no response. The loop is cycled for itemCount times.

FIGURE 150. Acquisition of Housekeeping Data

  1. It then uses the packet instance function append_Entries to load the target Identifiers, boardIndex and queryIndex, and the register response value into the packet.

  2. The process then tests the state, exiting the loop if it is not still SAMPLE, else it uses waitForInterval to check for notifications from the TaskMonitor or from this tasks public functions using the inherited function requestEvent. It then waits the requisite interval, sampleRate, before processing the next data point.

  3. Having completed the data set, or having been told to stop (or re-start), thus truncating the data set, Tf_Dea_Housekeeping will forward the packet using the inherited function post.

31.4.3 Use 3:: Stop DEA Housekeeping

Figure 151 illustrates the termination of the DEA housekeeping process.

  1. The stop run request is handled by the stopRun public function called by the client. It does not require arguments.

  2. It will use checkCRC to verify the current parameter block returning CMDRESULT_BAD_CRC on failure. If the thread is not processing data, the interface assumes that it is stopped and will return CMDRESULT_ALREADY, else it will return CMDRESULT_OK.

  3. Regardless of the outcome of these checks, the interface will notify the thread to stop the run. If goTaskEntry is waiting for a command, it will receive the notification from the stopRun function. The stop run request is ignored by goTaskEntry, since, if one is received, the process is already stopped, and no action is required.

FIGURE 151. Stop DEA Housekeeping

  1. If housekeeping data is being collected, doHousekeeping will receive the request, and act upon it in the course of its processing. While obtaining a packet buffer, it uses waitGetPacket which uses requestEvent to check pending notifications from TaskMonitor::query and from the public functions startRun and stopRun. Receiving a notification from either public function will cause a return without a buffer. Without a packet to finalize, dohousekeeping will return.

  2. doHousekeeping will also respond to notifications after the acquisition of each data value using waitForInterval, which uses requestEvent to check pending notifications as above. Receiving a notification from either public function will cause a return without delaying for the sampleRate interval.

  3. doHousekeeping will terminate the run and deliver the packet using post.

31.5 Class DeaHousekeeper

Documentation:
The DEA Housekeeper is responsible for modulated acquisition and periodic telemetry of engineering information from the DEA subsystem. It is started and stopped by command.
Export Control:
Public
Cardinality:
1

Hierarchy:

Superclasses: 

Task

Public Uses: 

PblDeaHouse

Implementation Uses: 

DeaManager

Public Interface:

Operations: 

DeaHousekeeper()
goTaskEntry()
startRun()
stopRun()

Protected Interface:

Has-A Relationships: 





unsigned cmdGndId: The value the ground uses to identify a command. It is echoed in packets generated in response to the command.

unsigned sampleRate: Initially holds the number of seconds which should elapse between requests for housekeeping data. It is multiplied by TICKS_PER_SECOND to be used by sleep(). 




Operations:

doHousekeeping()
waitForCommand()
waitForInterval()
waitGetPacket()



Private Interface:

Has-A Relationships:





PbDeaHouse deaPBlock: An instance of a DEA parameter block. 

KeeperAction nextAct: This instance variable conveys the action requested by the client, from the public binding function to the housekeeper. It will reflect the pending state of the housekeeper; START, STOP, or SAMPLE (continue). 

Tf_Dea_Housekeeping tPkt: An instance of a DEA telemetry packet. 



Concurrency:





Active





Persistence:





Persistent 









 31.5.1   DeaHousekeeper()


Public member of:





DeaHousekeeper





Arguments:

unsigned taskId



Documentation:





The identity of this task is contained in taskId. This constructor initializes instance variables. 





Concurrency:





Sequential







 31.5.2   goTaskEntry()


Public member of:





DeaHousekeeper





Return Class:





void





Documentation:





This function is the main entry point of the task.





Semantics:





This thread is idle unless commanded to start data acquisition according to parameters stored in a designated block. A start run notification will initiate housekeeping by calling doHousekeeping. Housekeeping data will continue to be obtained until the housekeeper is commanded to stop. A stop notification received by this function is ignored: because it is stopped.





Concurrency:





Synchronous 









 31.5.3   startRun()


Public member of:





DeaHousekeeper





Return Class:





CmdResult





Arguments:

unsigned slotIndex
unsigned cmdGndId



Documentation:





This function acquires and verifies the designated block (CRC check) and instructs the DEA Housekeeper task to start acquiring and sending information from the DEA. slotIndex is the index (acis location) of the DEA Housekeeping parameter block to use for the run. cmdGndId is the ground designation of the command sent to instigate this action. It is included in response telemetry





Semantics:





This function will create an instance of a parameter block then extract a copy of the designated block using pblDeaHouse::getBlock. A faulty attempt to acquire the block, or a bad CRC check of the block, will cause a return with state CMDRESULT_BAD_LOAD. The request is not forwarded. With a valid parameter block, the threads state is tested, if it is running, the return state is set to CMDRESULT_ALREADY, but if it is stopped, the return state set to CMDRESULT_OK. The pending-action state variable, nextAct, is set to START. The function will use notify to inform the thread of the request before returning.





Concurrency:





Synchronous









 31.5.4   stopRun()


Public member of:





DeaHousekeeper





Return Class:





CmdResult





Documentation:





This function instructs the DEA housekeeper to stop acquiring and sending information from the DEA. The last data obtained will be posted.





Semantics:





This function will check the current block CRC using deaPBlock::checkCrc and set the return state CMDRESULT_BAD_CRC if it is invalid. It will set the state CMDRESULT_ALREADY if processing state is stopped, otherwise it will set the state to CMDRESULT_OK. The pending-action state variable is set to STOP. The thread will be informed using notify.





Concurrency:





Synchronous









 31.5.5   doHousekeeping()


Protected member of:





DeaHousekeeper





Return Class:





void





Documentation:





This function periodically acquires and telemeters DEA housekeeping values. The parameter block to use was loaded by the public startRun function. This function runs until commanded to stop. 





Semantics:





The pending-action state is set to SAMPLE. The parameter block entries for the science identifier, the count of housekeeping items, and the rate at which housekeeping data is acquired are obtained using getBlockId, getItemCount, and getSampleRate. The main process loop is entered and will be cycled until a stop run directive is detected. A Tf_Dea_Housekeeping packet instance is passed to waitGetPacket to be associated with a packet buffer. It also will check for new commands and for queries from the TaskMonitor. If a new request is detected, the loop will be terminated and this function will return. The packet functions will be used to load data into the packet. currentTime is used to obtain the BEP tick count. The tick count, the command identity which was received from the client, and the science block identity are installed in the packet using put_Timer_Tick, put_Command_Id, and put_Parameter_Id. A housekeeping data loop is entered during which the target board and register indices will be extracted from the block using get_Board_Id and get_Query_Id. Then a response value from the target requested from deaManager::queryDea or a default value will be installed in the packet using append_Entries. waitForInterval is used to check for new commands and for queries from the TaskMonitor. If a new request is detected, the loop will be terminated. When the housekeeping requests have been fulfilled, or the run terminated with a partially filled packet, this function will access post to forwarded the packet for transmission. 





Concurrency:





Guarded 









 31.5.6   waitForCommand()


Protected member of:





DeaHousekeeper





Return Class:





void





Documentation:





This function waits until the task is commanded to start (or to stop) acquiring housekeeping values while responding to TaskMonitor::query.





Semantics:





This function consists of a loop in which it waits; using waitForEvent for notification of a TaskMonitor::query which initiates TaskMonitor::respond, or a request from one of its public functions which allows it to leave the loop and return. 





Concurrency:





Guarded 







 31.5.7   waitForInterval()


Protected member of:





DeaHousekeeper





Return Class:





void





Documentation:





This function waits for sampleRate seconds. It is used to space out engineering value acquisitions while responding to queries from the TaskMonitor or for a command from the housekeeping public functions.





Semantics:





This function uses requestEvent to determine if the TaskMonitor has interrogated this process or if a public function has sent a notify to this process of a received command. If so, it uses TaskMonitor::respond to answer the TaskMonitor or returns so its caller may address the command. With no pending directive, it will sleep for the designated interval, and return. 





Concurrency:





Guarded 









 31.5.8   waitGetPacket()


Private member of:





DeaHousekeeper





Return Class:





Boolean





Arguments:

TlmForm & pkt



Documentation:





This function waits until a packet buffer becomes available while checking for TaskMonitor or DeaHousekeeper notifications. The buffer, in due course, will contain the data of the packet instance pkt.





Semantics:





This function checks for the TaskMonitor::query or the DeaHousekeeper::startRun or DeaHousekeeper::stopRun notifications. It will respond to queries, and return BoolFalse (no packet buffer) if a new housekeeping request is received. It then waits for a fresh packet buffer for a timed duration using waitForBuffer. On failure to obtain a packet in that time, it loops to check and to wait again. When a packet buffer is obtained, it will return BoolTrue. 





Concurrency:





Guarded






Table of Contents
Next Chapter