ACIS Users Guide -- Memory Loads

ACIS Users Guide, Rev. A

3.7 Memory Loads

The ACIS software provides three mechanisms for loading code and/or data into the instrument. The first method uses the "Load from Uplink" feature, mentioned in Section 3.1.4. The second method is to load patches into the instrument, which when the instrument is warm-booted, overwrite sections of code and/or data copied from ROM into RAM. The third method is to use one of the "Write Memory" commands to directly write into the various memory types on the system. The following sections describe these second and third methods.

NOTE: In general, patching and writing to RAM on ACIS can crash the software. The loads for these writes are intended to be built by the ACIS software maintenance team.

3.7.1 Patching the software

ACIS maintains a set of patch nodes in the top of its instruction cache. When the instrument is warm-booted (see Section 3.1.3.3), code and data are copied from ROM into the instrument RAM, and items specified in the patch nodes are then written on top of the copied code and data.

3.7.1.1 Loading the Patches

Description

The user loads patch nodes into the instrument using "Load Patch" commands. Each node specifies a 16-bit identifier (which must not be 0xffff, see Section 3.7.1.3), the destination address to write to when the instrument is warm-booted, and an array of up to 125 32-bit words to write. The instrument determines the number of words in the array from the command packet length. If a patch requires more than 125 words, more than 1 patch node must be used to perform the write.

Commands

Command to add a patch

addPatch: CMDOP_ADD_PATCH
{
  patchId      = id of patch   - This uniquely identifies the 
                                 patch node (note: within the 
                                 instrument no more than 1 patch node 
                                 can have the same id at a time)
  writeAddress = address       - This specifies where to write 
                                 the data to upon warm-boot
  writeData[]  = data          - This is the array of 32-bit data 
                                 words to write
}

For example, a command to cause the software version number to be changed to 0x4321 upon the next warm-boot, assuming for this example that the address of the version number variable is 0x8001fdf0, is:

addPatch: CMDOP_ADD_PATCH
{
  patchId      = 0
  writeAddress = 0x8001fdf0
  writeData[]  =
  {
    0x4321
  }
}

Science Telemetry

Command Echo of a successful "Add Patch" command:
commandEcho: TTAG_CMD_ECHO
{
  arrival        = time command arrived (BEP 10Hz Ticks)
  result         = CMDRESULT_OK (other values indicate an error)

  addPatch: CMDOP_ADD_PATCH
  {
    patchId      = id of patch      
    writeAddress = address to patch
    writeData[]  = data to write
  }
}
If an error is encountered, such as the patchId already being used by a patch node loaded earlier, the Command Echo "result" field will contain CMDRESULT_BAD_ARGUMENT, and the patch will not be stored in the list.

Warnings

Bad patches can crash the instrument software
Since patches can write anything, anywhere, it is possible that a patch may cause the instrument to crash upon a warm-reboot. If this happens, when the instrument re-boots, it will detect that it was reset due to the watchdog timer and will not reapply the patches to the load copied from ROM (see Section 3.1.3.4 ).
No checks for full patch list
In order to allow the maintainer to work around unforeseen problems, the instrument software does not check to see if an added patch node overwrites any code or tables in the instruction cache. It is the maintainer's responsibility to predict where the nodes will go, and to ensure that they do not overwrite any existing tables and/or code.
Patches are lost upon power-on boot or cold-boot
Upon a power-cycle or cold-boot (see Section 3.1.3.1 and Section 3.1.3.2), the on- board patch list is reset to an empty state (NOTE: On a cold-boot, there is a "back- door" recovery strategy. If you know the where the end of the patch list is, and what the checksum value is (see Section 3.6.2.4), you can "Write BEP" the end-of-list pointer and checksum fields to recover the list. This trick won't work for the power-cycle case, however, because the memory contents will decay once the power is removed from the BEP).
Adding a patch may hide a corrupted list
The checksum for the patch list is only checked when the instrument is re-booted. Whenever a patch node is added to the instrument, the checksum is re-computed and stored. If the patch list is in a corrupt state prior to adding a new patch to the list, the adding of the patch will hide the corruption by re-computing the checksum and storing it.

3.7.1.2 Installing the Patches (Warm Boot)

Description

Once the patch nodes have been loaded into ACIS, they are installed whenever the instrument performs a warn re-boot. The patches are applied in the order in which they were loaded into the instrument. Section 3.1.3.3 describes the overall se quence of steps performed during an warm boot of the instrument, including the resulting command sequence and telemetry indicators

Warnings

See Section 3.1.3.3 Warnings
Watchdog re-boots will not re-install the patches
If the instrument watchdog resets, due to a fatal error, or some lockup causing a watch dog time-out, the instrument will perform a Watchdog Reset (see Section 3.1.3.4). This reset will reload code and data from ROM, but will not reapply the patch nodes. The patch nodes themselves, however, will remain in RAM, and will be re-applied upon the next commanded warm re-boot.

3.7.1.3 Removing Patches

Description

ACIS provides two mechanisms to reset the patch list, and one mechanism to re move single patch nodes from the list. To remove one or more patch node from the list, the user issues a "Remove Patches" command, specifying a list of Patch Iden tifiers to remove. When the instrument receives this command, it locates and re moves all nodes which contain a Patch Identifier which matches one of those in the list. The removal process compacts the patch list, releasing memory space at the end (low-memory) of the list.

There are two mechanisms which will remove all of the patches in the list. As men tioned earlier, a power-cycle or cold re-boot of the instrument will empty the con tents of the patch list (see Section 3.1.3.1 and Section 3.1.3.2). The user can also reset the entire patch list by issuing a "Remove Patches" command, and specifying 0xffff as the Patch Identifier. This will cause the instrument to reset the contents of the entire patch list.

Commands

To remove a set of patches from the list:
removePatches: CMDOP_REMOVE_PATCH
{
  patchIds[] = array of patch ids to remove
}
To remove all patches in the list:
removePatches: CMDOP_REMOVE_PATCH
{
  patchIds[] = 0xffff            - Reset the entire list
}
NOTE: If any of items in the patchIds[] array is 0xffff, the entire list will be removed.

NOTE: To remove the effect of the patches from the code and data in RAM, the BEP must be reset.

Science Telemetry

Command Echo of a "Remove Patches" command
commandEcho: TTAG_CMD_ECHO
{
  arrival      = time command arrived (BEP 10Hz Ticks)
  result       = CMDRESULT_OK (other values indicate an error)

  addPatch: CMDOP_REMOVE_PATCH
  {
    patchIds[] = array of patch ids.
  }
}
If there an error is encountered, e.g. if the specified patchId is not currently present in the stored patchlist, the Command Echo "result" field will contain CMDRESULT_BAD_ARGUMENT. The instrument, however, will continue to remove the remaining patchIds specified in the command.

Warnings

A warm-boot is required to remove the effect of a patch
Once patches are removed from the patch list, they will no longer be applied when the instrument performs a warm-boot. However, the effect of any patches installed by the last warm-boot will remain in RAM until the BEP is reset.
Removing a patch may hide a corrupted list
The checksum for the patch list is only checked when the instrument is re-booted. Whenever a patch node is removed from the instrument, the checksum is re-computed and stored. If the patch list is in a corrupt state prior to removing a patch from the list, the removal of the patch will hide the corruption by re-computing the checksum and storing it.

3.7.1.4 Dumping the Patch List

See Section 3.6.2.4

3.7.2 Writing to BEP Memory

Description

The patches described in the preceding section will only overwrite BEP memory after a successful warm boot. By contrast, ACIS also provides for instantaneous memory writes to the BEP using the Memory Server task. The ACIS maintainer can write to any location in the BEP address space using a "Write BEP" command packet. The command packet specifies which location to write to, and an array of up to 125 32-bit data words to write. The instrument determines the number of data words using the command packet length. The destination address must be aligned to a 32-bit word location (i.e. evenly divisible by 4).

Upon receipt of the command, the Memory Server task will copy the supplied data words to the specified location.

NOTE: If data is written to storage used by the instrument for code or data, the next reset of the instrument will overwrite the written area with the code and/or data from ROM.

The constraints for memory writes are the same as those for memory reads:
The start address must be aligned to a 32-bit word boundary (i.e. evenly divisible by 4)
If not, the command will be rejected, with a CMDRESULT_ARGUMENT in the Command Echo "result" field.

The region being read must not cross an Instruction Cache address boundary
These addresses are: 0x80080000 and 0x800fffff. If the region crosses one of these boundaries, the command will be rejected, with a CMDRESULT_ARGUMENT in the Command Echo "result" field.
If the region is in a FEP shared memory area, the associated FEP must be powered on
The FEP shared memory regions are:
FEP 0    - 0xa8000000 0xa8ffffff
FEP 1    - 0xa9000000 0xa9ffffff
FEP 2    - 0xaa000000 0xaaffffff
FEP 3    - 0xab000000 0xabffffff
FEP 4    - 0xac000000 0xacffffff
FEP 5    - 0xad000000 0xadffffff
If the FEP does not have power, a BEP Bus Error Exception will be raised and will cause a Fatal Error and subsequent BEP re-boot.

Commands

Command to write a block of BEP memory
writeBep: CMDOP_WRITE_BEP
{
  writeAddress   = start   - First location to write to
  writeData[]    =         - array of data words to write
}
If an error is encountered, such as specifying an invalid address, the Command Echo "result" field will contain CMDRESULT_BAD_ARGUMENT, and the memory will not be over-written.

If the Memory Server task is in the process of executing an earlier write or execute command, the Command Echo "result" field will contain CMDRESULT_BUSY, and the new data will not be written.

If the Memory Server task is in the process of performing an earlier memory read or dump, the Command Echo "result" field will contain CMDRESULT_CLOBBERED, the read operation will be aborted, and the new data will be written.

Warnings

Writes of the wrong data to the wrong locations can crash the software
It is assumed that the maintainers know what they're writing and why.
BEP hardware is memory mapped
Write BEP commands can write to BEP hardware registers.
Aborts earlier read
If, when the command is received, the Memory Server task is executing an earlier read command, such as a dump of the Huffman Tables, the earlier read will be aborted, possibly causing incomplete information to be telemetered. The write will then commence.
Written data may be lost upon next re-boot
Unless the writes are being used to modify the patch list, any data written to areas overwritten by the ROM load, or initialized and used by the running software, will be lost upon the next re-boot of the instrument.
Fatal Errors due to writes to un-powered FEP shared memory
Attempts to write to shared memory regions belonging to FEPs which do not have power will result in a BEP Bus Error exception, Fatal Error Message and BEP re-boot.

3.7.3 Writing to FEP Memory

Description

The ACIS maintainer initiates memory writes to a FEP using a "Write FEP" command packet, which specifies which FEP to write to, the starting location to write, and an array of up to 125 32-bit words to write. The instrument determines the number of words to write using the command packet length.

ACIS implements user-initiated memory writes to the FEP using the Memory Server task. If the write is to the FEP's shared memory, the writes are made directly by the BEP into that memory. If, however, the locations are not directly accessible by the BEP (e.g. within the FEP's I-cache or D-cache), the BEP will collaborate with the software running on the FEP to perform the write.

The constraints for memory writes are the same as those for memory reads:

The start address must be aligned to a 32-bit word boundary (i.e. evenly divisible by 4)

If not, the command will be rejected, with a CMDRESULT_ARGUMENT in the Command Echo "result" field.

The region being written to must not cross an Instruction Cache address boundary

These addresses are: 0x80080000 and 0x800fffff. If the region crosses one of these boundaries, the command will be rejected, with a CMDRESULT_ARGUMENT in the Command Echo "result" field.

The FEP must be powered when the write command is received

Attempts to write to a FEP when the BEP knows that it is not powered will cause the write to be rejected. The Command Echo result field will be set to CMDRESULT_BOARD_OFF.

The FEP must remain powered during the write

Attempts to write to a FEP's memory when the FEP is not powered may cause the write to abort, or possibly cause a BEP Bus Error Exception, which will subsequently cause a Fatal Error and BEP re-boot.

Commands

Command to write a block of FEP memory

writeFep: CMDOP_WRITE_FEP
{
  fepId        = FEP_0..FEP_5     - Specifies which FEP to write to
  writeAddress = start            - First location to write to
  writeData[]  =                  - array of data words to write
}

Science Telemetry

Command Echo of a successful "Write FEP" command:
commandEcho: TTAG_CMD_ECHO
{
  arrival        = time command arrived (BEP 10Hz Ticks)
  result         = CMDRESULT_OK (other values indicate an error)

  writeFep: CMDOP_WRITE_FEP
  {
    fepId        = FEP to write to
    writeAddress = address to write
    writeData[]  = data to write
  }
}
If an error is encountered, such as specifying an invalid address, the Command Echo "result" field will contain CMDRESULT_BAD_ARGUMENT, and the patch will not be stored in the list.

If the Memory Server task is in the process of executing an earlier write or execute command, the Command Echo "result" field will contain CMDRESULT_BUSY, and the new data will not be written.

If the Memory Server task is in the process of performing an earlier memory read or dump, the Command Echo "result" field will contain CMDRESULT_CLOBBERED, the read operation will be aborted, and the new data will be written.

If the BEP knows that the FEP is not powered at the time of the request, the Command Echo "result" result field will contain CMDRESULT_BOARD_OFF and the new data will not be written.

Warnings

Writes of the wrong data to the wrong locations can crash the FEP software
It is assumed that the maintainers know what they're writing and why.
FEP hardware is memory mapped
Write FEP commands can write to FEP hardware registers.
Aborts earlier read
If, when the command is received, the Memory Server task is executing an earlier read command, such as a dump of the Huffman Tables, the earlier read will be aborted, possibly causing incomplete information to be telemetered. The write will then commence.
Written data may be lost upon next re-boot of the FEP
Any data written to areas overwritten by the FEP program load, or initialized and used by the running software, will be lost upon the next re-boot of the FEP.
Fatal Errors due to writes to un-powered FEP shared memory
Attempts to write to shared memory regions belonging to FEPs which do not have power may result in a BEP Bus Error exception, Fatal Error Message and BEP re-boot.

3.7.4 Writing to DEA Sequencer Memory

Description

Although it is not recommended, the maintainer can initiate writes to DEA video board SRAM and PRAM using "Write SRAM" and "Write PRAM" commands, respectively, specifying the index of the CCD associated with that video board (see Section 3.3.4 ), the starting SRAM or PRAM index to write to, and a number of 16-bit data words to write. The ACIS software determines the number of words to write using the command packet length. The following constraints apply:

The selected Video Board must be powered

Attempts to write to a Video Board when the board is not powered will cause the write to be rejected. The Command Echo result field will be set to CMDRESULT_BOARD_OFF (see Warnings concerning DEA power)

The sequencers must be idle

If a science run is in progress when a write is requested, or starts while a write request is active, the write will be aborted. NOTE: It is STRONGLY recommended that one does NOT perform a direct SRAM or PRAM write during the setup stage of a science run, since the Science task may also be loading SRAM and PRAM (NOTE: once the sequencers are running, the hardware prevents reads and writes to the sequencer RAM). There is little risk to the hardware, however, since the ACIS on-board Sequence Checker will verify that contents of the SRAM and PRAM cannot hurt the hardware.

Commands

Command to write a block of SRAM memory

writeSram: CMDOP_WRITE_SRAM
{
  ccdId        = I0..S5   - Specifies the CCD Video Board
  writeIndex   = start    - First SRAM location to write to
  writeData[]  =          - array of 16-bit data words to write
}

Command to write a block of PRAM memory

writePram: CMDOP_WRITE_PRAM
{
  ccdId        = I0..S5   - Specifies the CCD Video Board
  writeIndex   = start    - First PRAM location to write to
  writeData[]  =          - array of 16-bit data words to write
}

Science Telemetry

Command Echo of a generic SRAM write request:
commandEcho: TTAG_CMD_ECHO
{
  arrival       = time command arrived (BEP 10Hz Ticks)
  result        = CMDRESULT_OK (other values indicate an error)

  writeSram: CMDOP_WRITE_SRAM
  {
    ccdId       = specified Video Board
    writeIndex  = specified start index
    writeData[] = array of 16-bit words to write
  }
}
Command Echo of a generic PRAM read request:
commandEcho: TTAG_CMD_ECHO
{
  arrival       = time command arrived (BEP 10Hz Ticks)
  result        = CMDRESULT_OK (other values indicate an error)

  readPram: CMDOP_WRITE_PRAM
  {
    ccdId       = specified Video Board
    writeIndex  = specified start index
    writeData[] = array of 16-bit words to write
  }
}
If the write interrupts an earlier on-going read, the Command Echo "result" field will contain CMDRESULT_CLOBBERED.

If the write attempts to interrupt a Write-Memory or Execute-Memory activity, the read is not performed. In this case, the Command Echo "result" field will contain CMDRESULT_BUSY.

If an attempt is made to write to a Video Board whose power is off, the command will be rejected and the Command Echo "result" field will contain CMDRESULT_BOARD_OFF.

Warnings

Don't use this to load science sequencer code
The ACIS science software is designed to re-load the SRAM and PRAM for each video board at the start of each science run. If a literal load of SRAM or PRAM is required for a run, the science parameter blocks provide a mechanism to reference the content of these loads (see ACIS IP&CL Software Structure Definitions, MIT-CSR 36-53204.0204, the deaLoadOverride field of the loadTeBlock and loadCcBlock definitions).
Aborts earlier read
If, when the command is received, the Memory Server task is executing an earlier read command, such as a dump of the Huffman Tables, the earlier read will be aborted, possibly causing incomplete information to be telemetered. The write will then commence.
Written data may be lost upon the setup for the next science run
During the setup stage for each science run, the ACIS software resets all of the video boards and re-loads their SRAM and PRAM with the code to use for the run. This may overwrite areas written to by earlier Write SRAM and Write PRAM commands.
Written data may be lost upon next power-cycle of the video board
Any data written into the video boards will be lost when power is removed from the board.
DEA power must remain on
>The ACIS software recognizes that a video board has power if it successfully sends the command to power the board. If the DEA is off when the command is issued, the resulting error will prevent the software from flagging the video board as powered. If, however, the DEA is powered off after successfully powering on video boards, the ACIS software continue to think that the video boards have power. Under these conditions, ACIS will accept and acknowledge the request to write to the video board with a CMDRESULT_OK, but will subsequently encounter an error when attempts to execute the write. This error will be indicated in Software Housekeeping as a SWSTAT_DEABOARD_ERROR report.

James E. Francis

Last modified: Wed Jan 12 10:54:53 EST