Table of Contents Previous Chapter ACIS

43.0 FEP Continuously Clocked Modes (36-53225 01)

43.1 Purpose

The fepSciCClk module, executing in the FEP, implements continuously clocked science processing, comprising either raw mode or event detection mode. It is called from fepCtl with a single argument, fp, a pointer to the fepParm structure. Before invoking fepSciCClk, the FEP must be commanded to (a) load a continuous clocking FEPparmBlock into fp->tp, and (b) perform a continuous clocking bias calibration.

43.2 Uses

The fepSciCClk function operates in one of the following modes, according to the value of fp->tp.type:

  1. Identify and report 1x3 candidate X-ray events to the BEP

  2. Report values of raw pixels and overclocks to the BEP

    FIGURE 178. fepSciCClk subroutines and their calling hierarchy

43.3 Organization

All interactions with the BEP and with FEP hardware are made through fepio library functions described in Section 38.0. The data structures that are passed between FEP and BEP are defined in that document and in Section 4.10. fepSciCClk makes use of the following functions which call each other in the manner shown in Figure :

43.4 Global Variables

The following FEPparm fields, defined in fepCtl.h and invariably addressed by 
the fp pointer parameter, are used by all continuously clocked modes:
bepCmd
latest command received from BEP
br
bias calibration parameters
bias0[4]
average nodal overclocks for first bias frame
biassum
sum of the 4 bias0 values
colshft
bit shift to transform column index to node index
ex
current
FEPexpRec record
bias0[4]
copy of fp->br.bias0 array
dOclk[4]
overclock changes for each output node
expnum
current "exposure" (i.e. VSYNC frame pulse) number
timestamp
microsecond timer value at start of expnum
exend
current FEPexpEndRec record
expnum
current "exposure" (i.e. VSYNC frame pulse) number
parityerrs
number of corrected parity errors in the frame
thresholds
number of threshold crossings in the frame
flags
flag bits used:
FP_SUSPEND
BEP has sent BEP_FEP_CMD_SUSPEND
FP_TERMINATE
BEP has sent BEP_FEP_CMD_STOP
image
pointer to start of current 512-row frame
lastcol
index of last frame column
nextexpnum
the next frame index that the FEP is to process
quadrants
the number of DEA output nodes being sampled
tp
frame parameter block
ncols
number of CCD columns per output node
noclk
number of overclocks per output node
nrows
number of CCD rows between frame markers
quadcode
output node clocking mode
thresh[4]
threshold values for each output node
type
processing mode, either FEP_CCLK_PARM_1x3 or FEP_CCLK_PARM_RAW.

43.5 Scenarios

The following paragraphs describe the basic functions performed in continuously clocked mode. All Continuous Clocking modes wait until an image frame (a block of DEA output pixels delimited by VSYNC flags, typically comprising 512 image rows) is processed and copied to the ring buffer before commanding the hardware thresholder to read the next frame, thereby ensuring that no partial frames are generated.

43.5.1 Use 1: Report 1x3 Events

43.5.2 Use 2: Report Raw Pixels

  • This mode is characterized by fp->tp.type == FEP_CCLK_PARM_RAW. It begins in an identical manner to the event-finding modes described in the previous sections, except that fepSciCClk calls FEPsciCClkRaw to process each 512-row frame.

  • FEPsciCClkRaw copies each row of pixels, and up to 30 overclocks from each DEA output node, to a FEPeventRecRaw record and thence to the ring buffer.

43.6 Specification


This section describes the functions that are local to the fepSciCClk unit. The only external is fepSciCClk itself which is called from fepCtl. The FEPparm structure is defined in fepCtl.h, along with several pixel access macros. The interface to the FEP I/O library is described in Section 38.0, and data and messages exchanged between FEP and BEP are described in Section 4.10.

43.6.1 fepSciCClk()

#include fepCtl.h
Scope: Science
Return type: void
Arguments
FEPparm *fp
Description:
fepSciCClk is called from fepCtl with a single argument: the pointer fp to 
the fepParm structure. It is responsible for all FEP actions associated with a 
timed exposure science run, except for bias calibration. In particular, it controls the 
double-buffering of input data---the image map is split logically into two 512-row 
buffers and the FEP hardware is told to write into one while the software is pro
cessing the other. fepSciCClk performs the following actions:
i)  Calls FEPsciCClkInit to validate the BEP's parameter block, fp->tp, 
for the current mode, to verify that pixel biases have been computed, and to 
initialize mode-dependent variables. If FEPsciCClkInit returns 
FEP_CMD_NOERR, fepSciTimed calls fepAckCmd and continues. Oth
erwise, it calls fepNackCmd to pass the fepCmdRetCode error code to 
the BEP, indicating that the command has failed, and fepSciCClk then re
turns to fepCtl. Error codes are defined in fepBep.h (see Section 4.10).
ii)  Calls fepEnableNextFrame to enable the hardware to read the first 512 
rows of image pixels into the image buffer.
iii)  Loops over frames of 512 rows of image pixels.
iv)
Enters a loop (see the upper half of Figure ), calling FIOgetExpInfo until the exposure numbered fp->nextexpnum is encountered (or exceeded). During this loop, calls are made to FIOgetNextCmd to handle any incoming BEP commands, and to FIOtouchWatchdog to prevent the Watchdog Timer from expiring while waiting for that particular frame.
fp->flags is inspected: if the FP_TERMINATE bit is set, fepSciCClk returns immediately---the science run is over; if the FP_SUSPEND bit is set, fepSciCClk loops until the BEP sends it a BEP_FEP_CMD_RESUME command.
v)
Calls FIOsetImageMapRowStart and fepEnableNextFrame to enable the hardware to read the next 512 rows into the other half of the image buffer.
vi)
Calls either FEPsciCClkEvent or FEPsciCClkRaw (according to the value of fp->tp.type) to process the 512 rows that were read by the hardware prior to step v).
vii)
Branches back to step iii), above. The loop over input frames continues until FIOgetNextCmd receives a BEP_FEP_CMD_STOP command from the BEP, which sets the FP_TERMINATE bit in fp->flags. fepSciCClk will finish processing the current frame before returning to fepCtl.

43.6.2 FEPsciCClkInit()

#include fepCtl.h
Scope: Science
Return type: fepCmdRetCode
Arguments
FEPparm *fp
Description:
This function is called from fepSciCClk to verify the contents of the 
FEPparmBlock, fp->tp, and to check whether a bias calibration has been per
formed. It also performs any necessary mode-dependent initialization. The follow
ing fp->tp and fp->br fields are checked:

----------------------------------------------------
            Tests               Error code returned   
           Applied               if the test fails    
----------------------------------------------------
    quadcode &OE; fepQuadCode     FEP_CMD_ERR_QUAD_CODE  
    0 < nrows  CCLK_NROWS     FEP_CMD_ERR_NROWS      
  0 < ncols, and ncols even    FEP_CMD_ERR_NCOLS      
quadrants * ncols  MAX_NCOLS   FEP_CMD_ERR_NCOLS      
      noclk  MAX_NOCLK        FEP_CMD_ERR_NOCLK      
            (fig)                                     
                               FEP_CMD_ERR_NO_BIAS    
----------------------------------------------------
If an error is detected, FEPsciCClkInit returns the appropriate fepCmdRet Code value, as defined in fepBep.h (see Section 4.10); otherwise it returns FEP_CMD_NOERR.

43.6.3 FEPsciCClkEvent()

#include fepCtl.h
Scope: Science
Return type: void
Arguments
FEPparm *fp
Description:
This function is called from fepSciCClk to process a single continuously 
clocked frame. It initializes the following row pointers to the addresses of data 
structures used by the hardware thresholder:
pTPlane
points to first data bit in T-plane buffer
pOclk
points to start of overclock buffer
fp->image
points to start of first data row in image buffer
and these pointers will be advanced from row to row. Note that, in step with the double buffering, pTPlane and fp->image will alternately point to the start and to the middle of their respective buffers. The four oSum[] overclock accumu lators (one per DEA output node) are zeroed. FEPsciCClkEvent then loops over CCD pixel rows. Once per row, it calls FIOgetNextCmd to see whether the BEP is trying to command the FEP. A re turned value of TRUE signals that a science command has been received (utility commands will be executed within FIOgetNextCmd and will return FALSE), and a call will be made to fepHandleCmd to process it. NOTE: only one call is made to FIOgetNextCmd per input row. The function then processes the row data. It adds the overclocks to the oSum ac cumulators, and then examines the T-plane, 32 bits at a time, until a non-zero value is found---indicating that the hardware detected a threshold crossing or bias map parity error. Because the 12-bit pixel and bias values must be loaded in pairs, the 32 T-plane mask bits are tested two at a time---if an even-offset bit has been set, FEPsciCClkEvenPixel is called; otherwise FEPsciCClkOddPixel is called. After processing the image row, FEPsciCClkEvent increments the row point ers. After the last row of the frame, the oSum overclock accumulators are normal ized and used to derive thresholds for the next exposure, which are communicated to the hardware by calls to FIOsetThresholdRegister for each DEA output node.

43.6.4 FEPsciCClkEvenPixel()

#include fepCtl.h
Scope: Science
Return type: void
Arguments
unsigned irow
unsigned icol
FEPparm *fp
Description:
This function is called from FEPsciCClkEvent for every bit set in the T-plane 
whose bit offset is even. The associated pixel is located in row irow, column 
icol, and fp->image points to the first pair of pixels in that row. The corre
sponding pair of bias values are to be found in fp->image[BIAS_OFFSET].
FEPsciCClkEvenPixel first loads the 32-bit pixel and bias fields that contain 
the central pixel. Since the FEP is a little-endian processor, and the central pixel is 
stored in the lower address pair of bytes, pixel and bias will be loaded into the least-
significant 16 bits of each 32-bit variable. (The most significant 16 bits of these 
variables will contain the pixel and bias for row irow and column icol+1.)
The pair of bias values is now validated---the bias parity flags (bits 15 and 31) are 
tested to determine whether a parity error has occurred in either of those locations 
in the bias map. If so, a call is made to FEPsciCClkFixBias to handle the 
problem, and the corrected 32-bit bias pair is written back to the bias map. Unlike 
the situation in timed exposure mode, when the software is merely able to report 
the damaged pixel, in continuous clocking mode the value can actually be repaired 
since each row of the bias map should be identical. Therefore, once the bias value 
has been updated, FEPsciCClkEvenPixel continues execution with the cor
rected value. 
Next, a test is made to determine whether this central pixel lies on the left- or right-
hand edge of the CCD, or if its bias value is PIXEL_BAD (indicating that the pixel 
is a member of the bad-pixel list). In any of these situations, the pixel is ignored.

The 12-bit value of the central pixel is saved in ev.p[1] of a local 
FEPeventRec1x3 structure, and the corresponding 12-bit bias value in 
ev.b[1]. To assist in later FEPsciCClkPixTest calls, the variable val is set 
equal to the difference between the center pixel value and its bias values, as dis
cussed in Section 43.6.6.
The center pixel is now compared to those lying to its left and right, using 
FEPsciCClkPixTest, which also saves the pixel and bias values in the appro
priate elements of the ev.p and ev.b arrays. If a test fails, i.e. if the central pixel 
isn't a local maximum, the function returns. When testing the pixel lying to the left, 
val must be adjusted for any change in average overclock if the two pixels were 
generated by different CCD output nodes. This change is simply the difference be
tween the corresponding node values in the fp->ex.dOclk[] array.
If the pixels on either side of the central pixel survive the FEPsciCClkPixTest 
criteria, the 1x3 pixel and bias arrays in the ev structure will have been loaded. 
FEPtestEvenPixel then calls fepAppendRingBuf to write the 
FEPeventRec1x3 record to the FEP-BEP ring buffer.


43.6.5 FEPsciCClkOddPixel()

#include fepCtl.h
Scope: Science
Return type: void
Arguments
unsigned irow
unsigned icol
FEPparm *fp
Description:
This function is called from FEPsciCClkEvent for every bit set in the T-plane 
whose bit offset is odd. The associated pixel is located in row irow, column 
icol, and fp->image points to the first pair of pixels in that row. The corre
sponding pair of bias values are to be found in fp->image[BIAS_OFFSET].
FEPsciCClkOddPixel first loads the 32-bit pixel and bias fields that contain 
the central pixel. Since the FEP is a little-endian processor, and the central pixel is 
stored in the upper address pair of bytes, pixel and bias will be loaded into the 
most-significant 16 bits of each 32-bit variable. (The least significant 16 bits of 
these variables will contain the pixel and bias for row irow and column icol1.)
The pair of bias values is now validated---the bias parity flags (bits 15 and 31) are 
tested to determine whether a parity error has occurred in either of those locations 
in the bias map. If so, a call is made to FEPsciCClkFixBias to handle the 
problem, the corrected 32-bit bias pair is written back to the bias map. Unlike the 
situation in timed exposure mode, when the software is merely able to report the 
damaged pixel, in continuous clocking mode the value can actually be repaired 
since each row of the bias map should be identical. Therefore, once the bias value 
has been updated, FEPsciCClkOddPixel continues execution with the cor
rected value. 
Next, a test is made to determine whether this central pixel lies on the left- or right-
hand edge of the CCD, or if its bias value is PIXEL_BAD (indicating that the pixel 
is a member of the bad-pixel list). In any of these situations, the pixel is ignored.

The 12-bit value of the central pixel is saved in ev.p[1] of a local 
FEPeventRec1x3 structure, and the corresponding 12-bit bias value in 
ev.b[1]. To assist in later FEPsciCClkPixTest calls, the variable val is set 
equal to the difference between the center pixel value and its bias value, as dis
cussed in Section 43.6.6.
The center pixel is now compared to those lying to its left and right, using 
FEPsciCClkPixTest, which also saves the pixel and bias values in the appro
priate elements of the ev.p and ev.b arrays. If a test fails, i.e. if the central pixel 
isn't a local maximum, the function returns. When testing the pixel lying to the 
right, val must be adjusted for any change in average overclock if the two pixels 
were generated by different CCD output nodes. This change is simply the differ
ence between the corresponding node values in the fp->ex.dOclk[] array.
If the pixels on either side of the central pixel survive the FEPsciCClkPixTest 
criteria, the 1x3 pixel and bias arrays in the ev structure will have been loaded. 
FEPsciCClkOddPixel then calls fepAppendRingBuf to write the 
FEPeventRec1x3 record to the FEP-BEP ring buffer.

43.6.6 FEPsciCClkPixTest

#include fepCtl.h
Scope: Science
Return type: unsigned
Arguments
FEPeventRec1x3 *ev
unsigned dcol
unsigned val
unsigned pixel
unsigned code
unsigned bias
Description:
This is an inline function that is used several times within the 
FEPsciCClkEvenPixel and FEPsciCClkOddPixel functions. It masks 
the 12 low-order bits of pixel and bias and stores them in p[dcol] and 
b[dcol] in the ev structure. It then compares the value of (pixel - bias) 
against val.
FEPsciCClkPixTest evaluates to TRUE when the value of the pixel at dcol 
is inconsistent with a legal event, or FALSE when it isn't. Illegal events are those 
for which the corresponding bias value is PIXEL_BAD, i.e . when the correspond
ing pixel is a member of the bad column list, or those that pass the test defined by 
the mode parameter, which is either LE ("less-than-or-equal"), in which an illegal 
pixel satisfies
val <= (pixel - bias)
or LT ("less than"), when an illegal pixel satisfies
val < (pixel - bias)
dcol must be in the range 0-2; the "center" pixel has dcol=1; dcol=0 refers 
to the column before the center pixel, dcol=2 to the column after. Constants 
PIXEL_MASK, and PIXEL_BAD are defined within fepCtl.h, and val and ev are 
local variables.


43.6.7 FEPsciCClkFixBias()

#include fepCtl.h
Scope: Science
Return type: unsigned
Arguments
unsigned bias
unsigned irow
unsigned icol
FEPparm *fp
Description:
This function is called from FEPsciCClkEvenPixel or FEPsciCClkOd
dPixel, when a parity error is detected in either or both of the halves of a 32-bit 
bias word. Each corrupted 12-bit value is replaced by the first non-corrupted val
ue in the same column icol of the bias map, and FEPsciTimedError is called 
(twice if both 12-bit values are bad) to reset the appropriate bits in the Bias Parity 
Plane and T-plane. It then calls fepAppendRingBuf to send a message of type 
FEP_ERROR_REC to the BEP containing irow, icol, the uncorrected bias 
value, and the current exposure number in fp->ex.expnum. Finally, 
FEPsciCClkFixBias returns the fixed-up 32-bit bias word to the caller, 
which has the responsibility for saving it back in the appropriate location in the 
bias map. NOTE: since bias represents a pair of values, icol must necessarily 
be even.


43.6.8 FEPsciCClkError()

#include fepCtl.h
Scope: Science
Return type: void
Arguments
unsigned val
unsigned irow
unsigned icol
FEPparm *fp
Description:
This function is called from FEPsciCClkFixBias when a parity error is detect
ed in row irow, column icol of the bias map. It computes the parity of the 12-
bit bias value, val, and resets the relevant bit in the Bias Parity Plane, turns off the 
corresponding bit in the T-plane, and increments the bias error counter, 

fp->exend.parityerrs.


43.6.9 FEPsciCClkRaw()

#include fepCtl.h
Scope: Science
Return type: void
Arguments
FEPparm *fp
Description:
This function is called from fepSciCClk to process a single raw CCD frame. It 
initializes the following pointers to the addresses of data structures used by the 
hardware thresholder:
pOclk
points to start of overclock buffer
fp->image
points to start of first data row in image buffer
and these pointers will be advanced from row to row. Note that, in step with the double buffering, fp->image will alternately point to the start and to the middle of the image buffer. FEPsciCClkRaw then loops over CCD pixel rows. Once per row, it calls FIOgetNextCmd to see whether the BEP is trying to command the FEP. A re turned value of TRUE signals that a science command has been received (utility commands will be executed within FIOgetNextCmd and will return FALSE), and a call will be made to fepHandleCmd to process it. NOTE: only one call is made to FIOgetNextCmd per incoming pixel row. The function then processes the row data, copying the raw pixels and overclocks to a FEPeventRecRaw structure and then calling fepAppendRingBuf to copy it to the ring buffer.
 

Footnotes

(1)
The distinction made between even and odd pixels is purely for programming efficiency. As a consequence of the FEP hardware architecture, it must access pixel and bias values in pairs.

Table of Contents Next Chapter