Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Data Structures | File List | Namespace Members | Data Fields | Globals | Related Pages

eventHandler.h

00001 /************************************************************************************
00002  *  the event manager control structure:   Set of basic variables within the event
00003  *                                         manager. Many of these registers are set
00004  *    asynchronously by the DMA ISR, and thus should only be monitored within other
00005  *    routines unless there are special reasons to do so (like a frame buffer overflow).
00006  *    The fixed parameters FRAME_SIZE and FRAMES_PER_BLOCK define the structure of
00007  *    the frame sets. The frame size is the size of frame transfers from the router;
00008  *    this is now fixed. While the # of frames per block can be changed if appropriate
00009  *    adjustments are made to the burst buffer lengths, doing so would require extensive
00010  *    changes to other areas as well (such as the event queue structure and the frame
00011  *    set registers. It would also defeat the word-boundary design of these registers,
00012  *    making them harder to access & much harder to monitor.
00013  *
00014  *    Fields:
00015  *
00016  *     running:      Indicates whether the event manager is running or not.
00017  *     isrState:     The current state of the ISR (NEWEVENT, DATA, or SLOWDATA).
00018  *     eventFrameCount:  The number of frames in the current event.
00019  *     format:       The event data format (TRAP_FMT_NORMAL or TRAP_FMT_ERROR).
00020  *
00021  *     i/xFrameCount: The number of currently occupied (valid) frames in the internal
00022  *                    and external frame buffers.
00023  *     i/xFrameRelease: When frames are released after the event has been processed,
00024  *                      these variables tell the ISR (the next time it runs) how many
00025  *                      frames to release from the frame buffers.
00026  *
00027  *     update:    Indicates to the non-ISR frame updating code that the ISR ran while
00028  *                it was still occupied releasing an event's frames, and that it should
00029  *                subtract the values used by the ISR from the frame release variables.
00030  *                This prevents conflicts between the ISR & the rest of the code.
00031  *     i/xFrameUpdate: If the ISR runs while non-ISR code was busy releasing frames, it
00032  *                     places the values it actually used in updating the buffer frame
00033  *                     counts, and will expect that the non-ISR code will modify the
00034  *                     frame-release counts accordingly, so that the next time it runs
00035  *                     the correct variables are used.
00036  *
00037  *     cf:   Points to the internal buffer frame in which the next data from the router
00038  *           will be placed. 
00039  *     xcf:  After a frame arrives, if all internal frames are currently full with valid
00040  *           data, xcf point to the frame inside the external burst buffer, to which the
00041  *           frame will be transferred. The internal buffer frame is then left unused, so
00042  *           that it can receive the next frame.  
00043  *     releaseFrames:  Indicates whether the event manager should release frames for
00044  *                     re-use as soon as the last pending operation has finished with
00045  *        them. If data processing is frame-based and incoming events arrive frequently,
00046  *        or events can be very large (histogramming), this helps to avoid buffer
00047  *        overflows.  
00048  *     permitBackPressure: Used by the master DSP to set the router control bit which
00049  *                         allows it to apply back-pressure to the EFB, typically done
00050  *                         in calibration mode. It is sent on to the slaves as a flag.
00051  *
00052  *     headerError: Flag indicating a serious error. If set, the DMA ISR expected a
00053  *                  header but found other data instead. The event manager will halt.
00054  *
00055  *     overflow:    If all frames in the internal & external frame buffers are occupied,
00056  *                  and a new frame arrives, the ISR will enter an overflow state. When
00057  *       this occurs, it will dump any more frames which arrive while it is in overflow.
00058  *       Exit from the overflow state is only possible when all the frames in external
00059  *       memory have been processed. 
00060  *     endOverflow: Flag which signals the ISR that it can resume normal processing.
00061  *     framesLost:  Countains the total number of frames which were discarded while the
00062  *                  ISR was in overflow.
00063  *
00064  *     sLink:      Indicates that the router is in sLink mode. (Trap matching is
00065  *                 overridden; data is passed on to DSPs using only the modulus &
00066  *       remainder formula). In this case trap 0's function ID (input to eventTrapSetup)
00067  *       is used to indicate the tasks which should process the trapped events. 
00068  *     dataMode:   Indicates that the router is set in data mode instead of event mode.
00069  *                 Frames cannot be counted on to always begin on a frame boundary, and
00070  *                 the router does not send data until it has accumulated 0x100 words.
00071  *     autoFlush:  Diagnostic bit which instructs the event manager to automatically
00072  *                 flush the frame buffers once they fill up, even if the frames are
00073  *                 not yet processed.
00074  *     trapStray:   Flag indicating whether or not "stray" events (see below) are
00075  *                  marked for trapping on the iteration past the limit, or are
00076  *                  removed.
00077  *
00078  *     strayCount:  The number of stray events seen so far. Should be small and get
00079  *                  incremented infrequently, so this wraps at 256.
00080  *     nTrailerWords: Indicates the number of words in the event trailer (depends on
00081  *                    the event format).
00082  *
00083  *     asmGuard:    Protection for the assembly language routines which use the C
00084  *                  structures (the routines check the value of this word & exit if
00085  *                  an unexpected value is found).
00086  *     buffPtr[2]:  Pointers to the start of the internal & external frame buffers
00087  *     buffLen[2]:  The length of the internal & external frame buffers.
00088  *
00089  *     lastFrameWordPtr:  
00090  *                  Points to the last word of the current frame.  If this is the
00091  *                  last frame, its content will be the END OF BLOCK marker
00092  *                  generated by the Router. "The Router generates an end of block
00093  *                  word that is located in the last location of the last frame of
00094  *                  a trapped event.  the word contains trap information that is
00095  *                  required by the DSP for processing."  In particular this
00096  *                  word flags events containing errors such that the actual
00097  *                  event trailer need not be processed.  PWP 03/11/2005
00098  *
00099  *     queuePtr:    Pointer to the start of the event queue.
00100  *
00101  *     trapParams[2]:   A set of six variables in a structure, indicating what is
00102  *                      being done with the router's two trap registers:
00103  *
00104  *       config:  The configuration of the trap, ie. what sort of events is it
00105  *                trapping, if any. Types can be TRAP_CFG_(ATLAS,TIM, or ROD)_EVT,
00106  *         or TRAP_CFG_IDLE for none. If only one trap is used, it must be trap #0.
00107  *
00108  *       match:   The 8 bit event ID which triggers the trap, if the remainder in
00109  *                the modulus/remainder register agrees with the current remainder.
00110  *
00111  *       exclusionFlag:  If set, the trap will match anything *but* what is set in
00112  *                       the trap match register. Currently not implemented.
00113  *
00114  *       function:  The function(s) of this trap, ie. what task(s) will handle it.
00115  *                  The functions are additive and are defined in primParams.h
00116  *
00117  *       modulus/remainder: Determine the frequency of event trapping inside the
00118  *                          router. If an event matches the trap's match, then it
00119  *          will be sent on to the SDSP if (# matches)%(modulus) == remainder.
00120  *          Note that the router VHDL requires that the 1st event passed on have
00121  *          a remainder of 1.
00122  *
00123  *     nEventsTot:   The total number of events which have been collected since
00124  *                   initialization.
00125  *     frameCount: The number of times the ISR has been called.
00126  *     nOverflowEvents:   The number of events which have been lost in overflow.
00127  *     eventLimit: The number of events to collect. 0 means continue until stopped.
00128  *
00129  *     conflict:  The number of times the frame release code has been interrupted
00130  *                by the ISR.
00131  *     noConflict:  The number of times the frame release code has run without any
00132  *                  conflict. 
00133  *     reserveDataLen: The size of data (in words)  inside the event manager's
00134  *                     reserve buffer. Once here, the data cannot be taken out. It
00135  *       is for stray event observation only. The reserve buffer cannot hold large
00136  *       events (>32k); these are discarded.
00137  *     reserveDataPtr: Pointer to the current writing frame in the reserve data
00138  *                     buffer. This 32 frame buffer in external memory wraps like
00139  *       the other two, and will over-write any data in it if necessary. 
00140  *
00141  * ----------------------------------------------------------------------------------
00142  *  the event queue:  organizes the trapped events. Event Manager routines transfer
00143  *                    events to and from different sub-queues within the event queue,
00144  *    deleting an event when it has no more operations pending, and freeing up its
00145  *    frames for re-filling. This sub-structure of the event queue contains the
00146  *    actual event data. To avoid any possible conflicts between the asynchronous ISR
00147  *    and the routines which manage the queue, the queue is structured as a FIFO. The
00148  *    routines have control over reading from and pointing of the front end of the
00149  *    pipe, while the ISR controls writing to the back end.
00150  *
00151  *    EvtData Fields (8 words per event):
00152  *
00153  *     data1: Packed data word containing the starting frame and # of frames in both
00154  *            the internal & external frame buffers. Fields are defined below.
00155  *     data2: Packed data word containing the event length and flags which indicate
00156  *            if the event contains errors and which tasks will process it.
00157  *     data3: Packed data word containing the frame numbers of the last two event
00158  *            frames, for easy access to the end of the event.
00159  *
00160  *     unpacked data. To be removed:
00161  *     i/xStartFrame, i/xFrameCount, error, length.
00162  *     startFrame:   The frame in which the event begins. This is not necessarily
00163  *                   constant, but could move if an overflow occurs. The starting frame
00164  *       is in the burst buffer if startFrame= [0,31]; startFrame= [32,63] indicates
00165  *       the first external burst buffer, etc. (up to 7)
00166  *
00167  *     nFrames:      The number of frames in the event.
00168  *
00169  *     flags:       Four event flags: bit 0== contiguous, bit 1= wrapped, bit 2= not
00170  *                  contained within one frame set (32 frames or 32K), bit 7= exception
00171  *       frame release flag. Contiguous means that the event's frames are all in
00172  *       ascending order in one or two groups (nice). Wrapped means that the event
00173  *       arrived at the end of burst memory in the 31st frame. The DMA engine then
00174  *       resets, so if free frames are available in the beginning of the buffer, the
00175  *       next frames will go there. If an event is wrapped and finds enough space at
00176  *       the beginning of the buffer to complete there, it is also marked as contiguous.
00177  *       If the high bit is set, then the closing operation of the event has requested
00178  *       that the event manager clean up the frames (if release_frames is set, see
00179  *       above.) 
00180  *
00181  *     id:           The internal id number assigned to the event, as shown in the
00182  *                   frameSummary registers.
00183  *
00184  *     nErrors:      Count of the number of errors inside the event; obtained from 
00185  *                   the event fragment trailer.
00186  *
00187  *     routerError:   Indicates a router error.
00188  *
00189  * not used:
00190  *     type:         The type of the trapped event, as given by either fragment header
00191  *                   word 7 for ATLAS events, or a field in word 8 for ROD & TIM events.
00192  *
00193  *
00194  *     operations:   The scheduled operations for the trapped event; one bit per
00195  *                   operation. The bits are the same as are given for the queue
00196  *                   constants below. (Q_HISTOGRAM, etc.) 
00197  *
00198  *     opsPending:   The pending operations for the trapped event; one bit per
00199  *                   operation.
00200 
00201 
00202  *    EvtQueue Fields:
00203  *
00204  *     nEvents:         The total number of events in the queue.
00205  *     readPtr:         Points to the queue start (current output of the pipe). 
00206  *     writePtr:        Points to the queue end (current input to the pipe). 
00207  *
00208  *     EvtData eventData[0x100]: The queue's event data structure array.
00209  *
00210  *  Douglas Ferguson
00211  ************************************************************************************/
00212 #ifndef EVENT_MANAGER_STRUCT
00213 #define EVENT_MANAGER_STRUCT
00214 
00215 #include "memoryPartitions.h"
00216 #include "router.h"
00217 #if (defined(I_AM_SLAVE_DSP)&&(defined(REV_B)||defined(REV_C)))
00218     #include <csl_dma.h>
00219 #endif
00220 
00221 //Event Manager structures & defined constants
00222 #define FRAME_SIZE        0x100    /* in words */
00223 #define FRAMES_PER_BLOCK  32       /* 1 block == 1 event set */
00224 
00225 #if (defined(REV_E))
00226     #define EDMA_BURST_ID  4    //The CIPR/CIER IDs of the burst DMA interrupt.
00227 #endif
00228 
00229 
00230 struct EvtMgrCtrl {
00231     UINT8 running, isrState, eventFrameCount, format,
00232           iFrameCnt, xFrameCnt, iFrameMax, xFrameMax,
00233           headerError, overflow, xMinIdx, xMaxIdx, 
00234           sLink, dataMode,  releaseFrames, permitBackPressure,
00235           autoFlush, trapStray, strayCount, nTrailerWords,
00236           pin4MaskDown, iFrameThres, cf, xcf,
00237           intOnly, unused[3];
00238     
00239     /* Important to keep the locations of the following pointers relative to the start
00240        of the structure fixed (they are used in assemby language, which does not know
00241        about C structure specifics, and can only be give a pointer to the start of the
00242        structure). */
00243     UINT32 asmGuard, *buffPtr[2], buffLen[2], *lastFrameWordPtr;
00244     
00245     UINT32 *queuePtr;
00246     RouterTrapParams trapParams[2];
00247     UINT32 nEventsTot, frameCount, nOverflowEvents, nOverflowFrames,
00248            eventLimit, reserveDataLen, reserveDataPtr, unused1[3];
00249 }; 
00250 
00251 
00252 struct EventData {
00253     UINT32  data1, data2, data3;
00254     UINT8   iStartFrame, iFrameCnt, xStartFrame, xFrameCnt, error, unused;
00255     UINT16  length;
00256 
00257     UINT8   startFrame, nFrames, flags, id;
00258     UINT32  nErrors, routerError;
00259 };
00260 
00261 /* Data1 definition. Each field is 8 bits wide: */
00262 #define EVT_MGR_IFRAME_O  24
00263 #define EVT_MGR_IFCNT_O   16
00264 #define EVT_MGR_XFRAME_O  8
00265 #define EVT_MGR_XFCNT_O   0
00266 
00267 /* Data2 definition: */
00268 #define EVT_MGR_OVERFLOW_O    31
00269 #define EVT_MGR_EVT_ERR_O     30
00270 #define EVT_MGR_HEADER_ERR_O  29
00271 #define EVT_MGR_TRAILER_ERR_O 28
00272 #define EVT_MGR_DATA_ERR_O    27
00273 #define EVT_MGR_LINK_ERR_O    26
00274 
00275 /* The trapping mask is used by the task manager to decide whether a given task
00276    will process this event or not. It contains 1 bit per potential task */
00277 #define EVT_MGR_TRAP_O        16
00278 #define EVT_MGR_TRAPMASK    0x001f0000
00279 
00280 #define  EVT_MGR_TRAP_FXN_HISTOGRAM   0
00281 #define  EVT_MGR_TRAP_FXN_TRAP        1
00282 #define  EVT_MGR_TRAP_FXN_OCCUPANCY   2
00283 #define  EVT_MGR_TRAP_FXN_ERRORCNT    3
00284 #define  EVT_MGR_TRAP_FXN_RESYNCH     4
00285 
00286 #define EVT_MGR_EVTLEN_O      0
00287 #define EVT_MGR_EVTLEN_W      16
00288 
00289 /* Data3 definition. Data3 has 2 8-bit fields that contain the last two event frames
00290    in an event. The last frame= current frame buffer frame when event ends; the
00291    previous frame is gotten from the stored value of data3 before it is updated. */
00292 #define EVT_MGR_CFRAME_O      24
00293 #define EVT_MGR_LFRAME_O      16
00294 
00295 struct EventQueue {
00296     UINT8  nEvents, readPtr, writePtr, unused;
00297     struct EventData eventData[0x100];
00298 }; 
00299 
00300 #define OBSERVATION_STRAY_MASK  0x40
00301 
00302 #if defined(I_AM_SLAVE_DSP)
00303 //Inlined event manager functions:
00304 extern far struct EvtMgrCtrl evtMgrCtrl;
00305 
00306 #if   (defined(REV_B)||defined(REV_C))
00307     extern DMA_Handle hBurstDataDmaCh;      
00308     extern DMA_Config burstDmaConfig;
00309 #endif
00310 
00311 static inline void eventManager(void);
00312 static inline void setDmaRegs(UINT8 frame);
00313 /************************************************************************************
00314  * eventManager
00315  *
00316  *  synopsis: After the tasks have finished processing the events, the event
00317  *            manager handles frame release & other cleanup tasks. The routine is
00318  *            written as an inlined routine to avoid the overhead of a function
00319  *            call. 
00320  *
00321  *  author: Douglas Ferguson
00322  ************************************************************************************/
00323 static inline void eventManager() {
00324 
00325 }
00326 
00327 /************************************************************************************
00328  * setDmaRegs
00329  *
00330  *  synopsis: Rev. B and C RODs use a 32 frame DMA transfer with pin 4 interrupts
00331  *            at the beginning of each frame, and a reload from 2 global reload
00332  *    registers at the end of the whole transfer, which reload the DMA registers.
00333  *    After transferring a frame, the frame counter and destination pointer of the
00334  *    DMA engine have automatically decremented (by 1 frame) & incremented (to the
00335  *    starting address of the next frame); if the DMA counters must be manually set,
00336  *    we must be careful to set the number of remaining frames to transfer correctly.
00337  *    For a Rev. E ROD (using EDMA), it is different: interrupts are only possible
00338  *    after a transfer has completed, so we must use single frame transfers. The
00339  *    element count will reload from the EDMA channel's reload register (which assumes
00340  *    the function of the global count reload register). The destination address will
00341  *    not increment automatically to the start of the next frame, nor will it wrap,
00342  *    so these functions are accomplished manually. 
00343  *
00344  *  author: Douglas Ferguson
00345  ************************************************************************************/
00346 static inline void setDmaRegs(UINT8 frame) {
00347     #if (defined(REV_B)||defined(REV_C))
00348         /* Transfer counter: number of frames and number of elements per frame */
00349         burstDmaConfig.src= ROUTER_FIFO_ADDR;
00350         burstDmaConfig.dst= (BURST_BFR_BASE +(frame<<10));
00351 
00352         burstDmaConfig.xfrcnt= DMA_XFRCNT_RMK((FRAMES_PER_BLOCK-frame), FRAME_SIZE);
00353         DMA_config(hBurstDataDmaCh, &burstDmaConfig);
00354 
00355     #elif (defined(REV_E))
00356             /* Set the source of the frame transfer (EDMA evt 4) directly, for speed.
00357                The EDMA event is linked to channel 4. See the EDMA chapter in the
00358                TMS320C6000 Peripherals Reference Guide for more details. */
00359             *((UINT32 *) 0x01a0006c)= BURST_BFR_BASE +(frame<<10);
00360     #endif
00361     return;
00362 }
00363 
00364 #endif  /* SDSP */
00365 #endif  /* Multiple inclusion protection. */

Generated on Thu Dec 15 21:14:26 2005 for SCT DAQ/DCS Software - C++ by doxygen 1.3.5