Table of Contents
Previous Chapter
Table of Contents
Previous Chapter
The FEP IO Library is a set of functions, executing in the FEP, which provide an interface to the front end hardware. Clients may use these functions to direct the FEP without having to know low level hardware details.
The FEP IO Library provides the following features:
Figure 186 illustrates the interfaces to the FEP provided by the IO Library.
FIGURE 186. FEP IO Library Interface Diagram
The FEP IO Library provides access functions to various areas of the FEP and BEP hardware.
The following paragraphs describe the basic function performed by the FEP, and which library functions should be used in a given scenario. In general, the functions prefaced by FIO (upper case) should be adequate for any task required by the science processing. All function prefaced with a lower case (fio) are used at the directive of the BEP.
Transferring data across the interface uses a portion of the shared memory which has been configured as a ring buffer, consisting of a series of 32-long word blocks. The function FIOappendBlock() writes the specified data block to the ring buffer. This function does not return until the operation is completed, or until a command arrives at the BEP to FEP Command Mailbox.It is possible for the buffer to be full, so a wait may be required until the BEP has emptied more of the buffer. While waiting for space in the buffer, this function calls FIOtouchWatchdog(). If the BEP is too slow in clearing the buffer, science processing may be affected. The function fioRbStatus() returns the status of the ring buffer and the available number of blocks. The library users do not need to call this routine before calling FIOappendBlock().
The FEP has little independent action; therefore, there is a command protocol for directing the FEP. A portion of the shared memory is set aside for a mailbox. The function FIOgetNextCmd()polls the command mailbox to look for pending commands and performs the required actions. The functions fioPollMBox(), fioGetCmd(), and FIOwriteCmdReply()are used by FIOgetNextCmd()to handle the command interface. If the command is directed to the science processing, it returns that information to the calling function.
The Mongoose DMA may be used to transfer data between the D-cache and general purpose memory, or between two general memory locations. The function FIOdmaTransfer()initiates the transfer. The function FIOdmaDone()indicates when the transfer has completed.
The I-cache requires special access through read/write registers. The functions fioReadIcache()and fioWriteIcache() should be used to for any access to the I-cache. For completeness, the functions fioReadMem()and fioWriteMem()are available for accessing the D-cache. There are also several functions available to read and/or write some of the FEP hardware registers and access the addresses of the various portions of hybrid memory, this includes the capability for directly executing a function located in the memory.
The watchdog timer must be reset frequently. If the timer reaches zero, it assumes the data processing is hung and resets the FEP. The function FIOtouchWatchdog()should be called within a TBD interval to reset the timer.
See the ACIS Software Preliminary Design Specification (FEP IO Library), (#36-02402) for further details on this interface.
Communication between the BEP and the FEP is accomplished via two mailboxes, one for BEP initiated commands and their corresponding responses, the other for FEP initiated requests and their corresponding replies. The mailboxes are located in a section of shared memory between the BEP and the FEP. It is necessary to have some handshaking to ensure proper delivery and receipt of messages.
The first field contains the mailbox state, the second contains the message. The actual message is divided into further sub-fields: the length of the following message, the type field, which indicates the kind of message, and any additional arguments required. Replies are written into the same structure as the initial command or request. (NOTE: See "fio.h" for a formal definition of this structure, and the definition of SIZE).
Communication originating in the BEP is usually a command directive to the FEP. There are two general types of commands, diagnostic and science. Diagnostic commands require information regarding the state of the FEP and are handled by the IO library. All science commands are forwarded to the science process.
The transfer sequence is as follows: the BEP writes a command to the mailbox and changes the state to NEW_MESSAGE. The FEP has been polling the mailbox (FIOgetNextCmd()) and takes the appropriate action when a command is received. In all cases, a response must be written to the command by the recipient (FIOwriteCmdReply()). This function will write the response and set the mailbox state to REPLY_RDY. The BEP reads the response and sets the mailbox state to NO_MESSAGE in preparation for the next exchange.
The following is a list of the commands that the FEP responds to. All other commands are forwarded to the science process.
This command accepts a source I-cache address and count of words to be read, in the format specified by Table 30 . If the parameters are within valid ranges, the data are read from I-Cache and stored back in the mailbox in the format specified by Table 31 . If the parameters are invalid, the action taken by the FEP is TBD.
TABLE 30. Read I-Cache command format
------------------------------------------------------------------------------ Argument Field Units Values Description------------------------------------------------------------------------------ len Argument 32 bit 2 Number of command argu count unsigned ments + type type Command enum CMD_READ_ICACHE Execute Read I-Cache com type mand args[0] Address 32 bit 0x80080000 - Source address in I-cache to unsigned 0x800ffffe read data from. args[1] Length 32 bit 0 -127 Number of words to be read. unsigned May not cross I-cache boundary ------------------------------------------------------------------------------
TABLE 31. Read I-Cache command response
----------------------------------------------------------------------------- Argument Field Units Values Description----------------------------------------------------------------------------- len Argument 32 bit 0 - 127 Number of words in argu count unsigned ments field + type type Command enum CMD_READ_ICACHE Indicates which command type has been executed args[0 .. N] Data 32 bit Data values read from I- unsigned cache. -----------------------------------------------------------------------------
This command accepts a destination address, count of words to be written, and data, in the format specified by Table 32 . If the parameters are within valid ranges, the data are written into I-Cache. The command response is detailed in Table 33 . If the parameters are invalid, the action taken by the FEP is TBD.
TABLE 32. Write I-Cache command format
------------------------------------------------------------------------------------ Argument Field Units Values Description------------------------------------------------------------------------------------ len Argument 32 bit 0 - 127 Number of command argu count unsigned ments + type type Command enum CMD_WRITE_ICACHE Execute Write I-Cache com type mand args[0] Address 32 bit 0x80080000 - Destination address in I-cache unsigned 0x800ffffe to write data too. args[1.. N] Data 32 bit Data values to write to I- unsigned cache. ------------------------------------------------------------------------------------
TABLE 33. Write I-Cache command response
------------------------------------------------------------------------------ Argument Field Units Values Description------------------------------------------------------------------------------ len Argument 32 bit 1 Number of command argu count unsigned ments + type type Command enum CMD_WRITE_ICACHE Indicates which command has type been executed ------------------------------------------------------------------------------
This command accepts a source address and count of words to be read, in the format specified by Table 34 . If the parameters are within valid ranges, the data are read from D-cache or general memory and stored back in the mailbox in the format specified by Table 35 . If the parameters are invalid, the action taken by the FEP is TBD.
TABLE 34. Read memory command format
------------------------------------------------------------------------------------- Argument Field Units Values Description------------------------------------------------------------------------------------- len Argument 32 bit 2 Number of command argu count unsigned ments + type type Command enum CMD_READ_MEM Execute read memory com type mand args[0] Address 32 bit 0x80000000 - 0x8007fffc Source address in memory to unsigned 0xa0000000 - 0xfffffffc read data from. args[1] Length 32 bit 0 - 127 Number of words to be read. unsigned May not memory boundaries -------------------------------------------------------------------------------------
TABLE 35. Read memory command response
------------------------------------------------------------------------------ Argument Field Units Values Description------------------------------------------------------------------------------ len Argument 32 bit 0 - 127 Number of words in argu count unsigned ments field + type type Command enum CMD_READ_MEM Indicates which command has type been executed args[0 .. N] Data 32 bit Data values read from mem unsigned ory ------------------------------------------------------------------------------
This command accepts a destination address, count of words to be written, and data, in the format specified by Table 36 . If the parameters are within valid ranges, the data are written into memory. The command response is detailed in Table 37 . If the parameters are not valid, the action taken by the FEP is TBD.
TABLE 36. Write memory command format
----------------------------------------------------------------------------------------- Argument Field Units Values Description----------------------------------------------------------------------------------------- len Argument 32 bit 0 - 127 Number of command argu count unsigned ments + type type Command enum CMD_WRITE_MEM Execute write memory com type mand args[0] Address 32 bit 0x80000000 - 0x8007fffc Destination address in write unsigned 0xa0000000 - 0xfffffffc data to. args[1.. N] Data 32 bit Data values to write to unsigned memory. -----------------------------------------------------------------------------------------
TABLE 37. Write memory command response
----------------------------------------------------------------------- Argument Field Units Values Description----------------------------------------------------------------------- len Argument 32 bit 1 Number of command argu count unsigned ments + type type Command enum CMD_WRITE_MEM Indicates which command type has been executed. -----------------------------------------------------------------------
This command accepts the address of a function and a list of the functions arguments, in the format specified by Table 38 . The function is called with the indicated arguments. the return value of the function is stored back in the mailbox in the format specified by Table 39 .
TABLE 38. Execute memory command format
-------------------------------------------------------------------------------- Argument Field Units Values Description-------------------------------------------------------------------------------- len Argument 32 bit 0 - 20 Number of command argu count unsigned ments + type type Command enum CMD_EXECUTE_MEM Execute "execute memory" type command args[0] Address 32 bit Pointer to function to be unsigned called. args[1..20] Arguments 32 bit Arguments for function call. unsigned --------------------------------------------------------------------------------
TABLE 39. Execute memory command response
---------------------------------------------------------------------------- Argument Field Units Values Description---------------------------------------------------------------------------- len Argument 32 bit 2 Number of words in argu count unsigned ments field + type type Command enum CMD_EXECUTE_MEM Indicates which command type has been executed. args[0] Data 32 bit Return value from function unsigned call. ----------------------------------------------------------------------------
The following are the function definitions for the FEP IO Library. There are several access functions that will just return an address pointer, a hardware register value, or a constant. Most of these will be implemented as macros or in-line functions, defined in the file fep.h. See the DPA Hardware Specification & System Description #36-02104, section TBD, for more detailed information.
The functions defined in Section 39.6.1 through Section 39.6.19 are interface functions to read and write the FEP hardware registers. These are defined as in-line functions in the include file fep.h.
Return a pointer to the start of the bias map. The address points to a pre-defined array of 1024 x 1024 16-bit pixels, and begins on a 4-byte boundary in non-cache memory.
unsigned *biasrec unsigned cnt
Retrieve the Bias Configuration information stored in I-Cache. cnt words are read from the I-cache address specified by the constant BIAS_CONFIG_SAVE and stored in the buffer indicated by biasrec.
unsigned *biasrec unsigned cnt
Write cnt words of bias configuration data specified by biasrec into I-cache. The location in I-cache is specified by the constant BIAS_CONFIG_SAVE.
Return a pointer to the location of the bias parity plane previously specified by a call to fioSetSegAllocReg().
Return the row index of the CCD where processing should begin, not necessarily the first row. The first row has index 0.
unsigned row_index
Set the index row of the CCD where processing should begin. The first row has index 0.
Return a pointer to the start of the Image map. The address points to a pre-defined array of 1024 x 1024 16-bit pixels, and begins on a 4-byte boundary in non-cache memory.
Return an index to the last row written in the image map. The first map has index 0.
Return the count of CCD rows.
unsigned count
Set the number of CCD rows.
Return the Image Map row index at which the hardware should begin loading the image into non-cache memory. The first row has index 0.
unsigned row_index
Set the index row of the Image Map where we should begin loading the image. The first row has index 0.
unsigned regnum
Return the contents of the indicated register (0 - 3).
unsigned regnum short value
Set the indicated offset register (0 - 3) to the value specified.
Return a pointer to the start of the overclock buffer previously specified by a call to fioSetSegAllocReg().
unsigned regnum
Return the contents of the indicated threshold register (0 - 3).
unsigned regnum short thresholdval
Set the indicated threshold register (0 - 3) to the value specified. In order to support updating the threshold register values synchronously with the advent of the next exposure, this function stores the passed thresholdval into a holding variable. When the Beginning of Frame interrupt occurs, the interrupt handling routine will copy the contents of the holding variable into the actual threshold register.
NOTE: This scheme requires that the interrupt handler is capable of copying the holding variables into the threshold registers within one pixel clock of the Beginning of Frame interrupt (~10µseconds).
Return the value of the T-Plane crossings counter.
Return a pointer to the start of the T-Plane, previously specified by a call to fioSetSegAllocReg().
unsigned *ptr unsigned wordcnt
Copy wordcnt words (32 bit values) pointed to by ptr to the block at the end of the ring buffer. wordcnt must be less than or equal to 32. Although wordcnt may be less than 32 words, the written block will always consume 32-words of ring-buffer space. This function does not return until the action is completed, or un til a command is received at by the Command Mailbox. There may be delays if the ring buffer is full. Data values must be aligned on long word boundaries. While waiting for room the function maintains the watchdog timer using FIOtouch Watchdog(), and polls the status of the Command Mailbox using fioPollM Box(). If the block is successfully appended to the ring buffer, the function returns TRUE. If a command arrives while waiting for room in the ring buffer, the function aborts, and returns FALSE. Using FIOgetNextCmd(),the caller must then read and process the received command. NOTE: Interrupts to the BEP on writes to an empty ring-buffer have been replaced by having the BEP poll the ring-buffers for data.
This function returns TRUE if the most recent DMA transfer has completed. It re turns FALSE if the transfer is not complete.
unsigned * src unsigned * dest unsigned wordcnt
This function requires a mongoose processor to be tested, it can not be tested on a development workstation.
Transfer wordcnt words indicated by src across the DMA interface to location indicated by dest. This operation can only be used between D-cache and memo ry, and memory to memory. If src and dest both point to D-cache, a panic will be generated.
unsigned *expnum unsigned *timestamp
This function requires a mongoose processor to be tested, it can not be tested on a development workstation.
Return information about the current exposure, i.e., the exposure number and the timestamp of the exposure. Interrupts will be masked while this function executes. The interrupts will be disabled for less than ~5mseconds.
COMMAND *cmd
Returns TRUE if a new science command has arrived, in which case, structure cmd contains the science command. Returns FALSE, and leaves cmd unchanged, if there are no new science commands. If the command is diagnostic in nature, this functions does the necessary processing before returning. Refer to the file "fio.h" for a list of possible diagnostic command types. All diagnostic command types are negative in value. Non-diagnostic command types, which are not defined in "fio.h", must have a value greater than 0.
This function initializes the various hardware registers in the FEP. The ring buffer is initialized by the BEP. Refer to the DPA Hardware Specification & System De scription for a detailed accounting of the registers and initialization information.
This function requires actual ACIS hardware to be tested, it can not be tested on a development workstation.
This function resets the watchdog timer to prevent a hardware reset.
COMMAND * cmdreply
unsigned mask
This function requires actual ACIS hardware to be tested, it can not be tested on a development workstation.
This function clears the bits in the FEP Control Register indicated by the mask. It does not affect any of the other bits in the control register. The constants for setting particular bits are defined in the enum CtlRegMask in fio.h.
unsigned mask
This function requires actual ACIS hardware to be tested, it can not be tested on a development workstation.
This function clears the bits in the FEP Image Control Register indicated by the mask. It does not affect any of the other bits in the register. The constants for set ting particular bits are defined in the enum ImgCtlRegMask in fio.h.
COMMAND * cptr
This function does not check if the command is current. Use fioPollMBox()to check the status of the command.
Get a command from the BEP. The command is returned in the area indicated by cptr.
This function requires actual ACIS hardware to be tested, it can not be tested on a development workstation.
This function returns the value of the status register.
This function requires actual ACIS hardware to be tested, it can not be tested on a development workstation.
This function returns the value of the Image Status register.
MBOXstate *mbox MBOXstate state
Returns TRUE if the MBOXstate of the mailbox matches state in the argument list. Returns FALSE otherwise. Mailbox state variables are defined in "fio.h".
unsigned *available
RB_FULL - Ring buffer is full, do not append more data RB_EMPTY - Ring buffer is empty RB_NOT_FULL - Ring buffer is not full and not empty, check available to see if there is enough room to append more data. RB_ERROR - There is an internal error in the ring buffer
unsigned * src unsigned * dest unsigned wordcnt
This function requires a mongoose processor to be tested, it can not be tested on a development workstation.
This function reads wordcnt 32-bit words from the I-cache, starting at src, into the buffer indicated by dest.
unsigned * src unsigned * dest unsigned wordcnt
This function reads wordcnt 32-bit words starting at src in D-cache or general memory into the buffer indicated by dest.
unsigned mask
This function sets the bits in the Control register indicated by mask. It does not affect any of the other bits in the register. The constants for setting particular bits are defined in the enum CtrlRegMask in the file fio.h.
unsigned mask
This function sets the bits in the Image Control register indicated by mask. It does not affect any of the other bits in the register. The constants for setting particular bits are defined in the enum ImgCtrlRegMask in the file fio.h.
unsigned pplane unsigned tplane unsigned oclk
This function sets the bits in the Bulk Memory Segment Allocation register. It is used to designate where in bulk memory the parity plane, threshold plane, and overclock buffer are located. It does not affect any of the other bits in the register. pplane, tplane, and oclk specify which segment to use for the parity plane, threshold plane, and overclock memory, respectively.Each must be unique and may range from 0 to 15. Each increment selects a 128Kbyte block within bulk memory, where 0 corresponds to the first block within bulk memory. The constants used for setting particular bits are defined by the enum SEGALLOC in fio.h.
unsigned * src unsigned * dest unsigned wordcnt
This function requires a mongoose processor to be tested, it can not be tested on a development workstation.
This function writes wordcnt 32-bit words starting at src into the I-cache start ing at dest.
unsigned * src unsigned * dest unsigned wordcnt
This function writes wordcnt 32-bit words starting at src, into the D-cache or general memory starting at dest.
unsigned mask
This function requires actual ACIS hardware to be tested, it can not be tested on a development workstation.
This function sets the bits in the Pulse register indicated by mask. It does not affect any of the other bits in the register. The constants for setting particular bits are by the enum PulseRegMask in fio.h.
unsigned mask
This function requires actual ACIS hardware to be tested, it can not be tested on a development workstation.
This function sets the bits in the Image Pulse register indicated by mask. It does not affect any of the other bits in the register. The constants for setting particular bits are by the enum ImgPulseRegMask in fio.h.
Next Chapter